
          L i b e r ( a t o r )   /   O C a m l   F C P   /
  O C a m l   H i g h   L e v e l   F r e e n e t   I n t e r f a c e

                      V e r s i o n   2 . 0 . 2

by Travis Bemann <tabemann@wisc.edu>
and Eric Norige (aka "Edgar Friendly") <thelema314@bigfoot.com>

Liber(ator) is a powerful command line Freenet client written in
Objective Caml (OCaml) that facilitates both the easy request of files
from Freenet with the proper processing of control metadata and the
easy insertion of files, both single and multiple (in directory
trees), into Freenet, combined with mapfile generation and insertion
and date-based redirect target insertion.  Furthermore, it supports
easy date-based redirect insertion.

Liber, Ocaml FCP, and OCaml High Level Freenet Interface, which share
significant portions of their source code, are licensed under the GNU
Lesser General Public License, which is available in its full text in
the provided file named COPYING.  The motivation behind the decision
to license them under the LGPL rather than the GPL is to provide the
advantages of copyleft that are provided by the GPL while making it
easier for software written with licenses such as the BSD and X11
licenses to use portions of any of their collective source code or
OCaml FCP or OCaml High Level Freenet Interface as a whole.

Liber provides a user-configurable personal subspace, which must be
configured in the Liber configuration file; while the configuration
file is automatically generated when one runs Liber the first time for
a given user, in that user's home directory as ~/.liber, one must
invoke liber --generate-svk to generate an SVK key pair, and set the
setting subspace_private_key to the generated private key, in quotes,
and delimited from the setting name by an equals sign and arbitrary
whitespace.

In addition, Liber also provides al MIME type metadata generation from
file suffix facility.  A default set of file name suffix to MIME type
mappings is compiled into Liber itself, but to add new mappings or
override such default mappings a suffix to MIME type mapping file must
be installed and specified by one's Liber configuration file.
However, the Liber configuration file generation feature does not
provide a direct means to enable this feature, for Liber has no way of
knowing where the user expects the file containing the proper suffix
to MIME type conversions to be located, if one exists at all.
Therefore, one must manually create an entry in the Liber
configuration file to specify the location of such a file in the
proper format for one to add new suffix to MIME type mappings or
override default ones.


  B u i l d i n g   a n d   I n s t a l l a t i o n


Installation of binary tarballs for Liber, OCaml FCP, and OCaml High
Level Freenet Interface is simply carried out by

make install

within the directory from the expanded binary tarball as root.  Doing
so will not only install the liber binary, but also the liber
documentation (including the files README, COPYING, TODO, and
FREESITE-HOWTO), and the Ocaml FCP and OCaml High Level Freenet
Interface libraries and interfaces (both source and compiled) within
the OCaml library tree if it exists.  Note that the installation
prefix is /usr/local by default, and to be changed

make install PREFIX=<prefix>

has to be specified (without the angle brackets).

Note that the binary tarball Makefile may make use of GNU
make-specific features.  However, these features are used in such a
manner that they will not interfere with the installation of the Liber
binary and the OCaml FCP and OCaml High Level Freenet Interface
documentation if a version of make other than GNU make is used.

Building and installing Liber, OCaml FCP, and OCaml High Level Freenet
Interface from a source tarball or CVS tree requires having OCaml 3.x
or higher installed on one's computer.  To obtain the lastest version
of OCaml one should go to

http://caml.inria.fr/
OR
http://www.ocaml.org/

While Liber, OCaml FCP, and OCaml High Level Freenet Interface
themselves are not very platform-dependent in themselves due to
OCaml's emulation of UNIX system calls that perform functions that are
not actually specific to UNIX itself on non-UNIX platforms, even
though Liber does require the environment variable $HOME to be set to
be properly configured, they cannot be fully installed (even though
the binary for Liber can be installed) on machines not supported by
Findlib.  Also note that the Makefile does use some GNU make-specific
features, in particular the use of a hyphen and a space before a
command to indicate that make should continue even if the command
fails.  Therefore, one should use GNU make for building and or
installing Liber, OCaml FCP, and OCaml High Level Freenet Interface.

(Note that all the following command sequences should be executed in
the directory where the Liber/OCaml FCP/OCaml High Level Freenet
Interface sources are located, and that

make install

and any other installation commands require the current user to be
root and assume that the installation prefix is /usr/local.  To change
the installation prefix, change the line starting with PREFIX= to
PREFIX=<prefix>, where <prefix> is whatever one wants the installation
prefix to be.)

The standard method to build (using native compilation) and install
Liber, OCaml FCP, and OCaml High Level Freenet Interface is

make
make install

The method to build (using native compilation) and install just Liber
is

make liber.opt
make install

The method to build (using bytecode compilation) and install just
Liber is

make liber
make install

The method to build (using both native and bytecode compilation) and
install OCaml FCP and OCaml High Level Freenet Interface is

make lib
make install

Note that a file named liber_mimetypes containing suffix to MIME type
conversions for most standard file types that one is likely to
normally use is included in the distribution.  Note that this need not
be installed and pointed to by one's Liber configuration file,
as the mappings in this file as provided with the distribution (source
or binarh) are compiled at build-time into Liber at build-time;
however, this file or a file with the same format must be pointed to
by one's Liber configuration file if one is to add new suffix to MIME
type mappings or change default ones.  It can be placed wherever one
likes (but it is recommended that one place it in one's home directory
as .liber_mimetypes) as long as the configuration file field
suffix_mime_type_field is set to point to its absolute path. Doing so
will make it easy to use the suffix to MIME type conversion for file
insertion, so one doesn't need to write one's own suffix to MIME type
conversion file from scratch.


  M o d u l e s   a n d   C o m p o n e n t s


The backend of Liber, the OCaml High Level Freenet Interface, provides
the actual code that facilities high level requesting and inserting,
and is modularly separate from Liber, even though both the OCaml High
Level Freenet Interface and Liber share a number of modules.  These
modules are Fstream, Fieldset, Strutil, and Fcp, and any project that
uses the OCaml High Level Freenet Interface must include these modules.

OCaml FCP is the backend for the OCaml High Level Freenet Interface,
and implements the direct interface with a computer's local Freenet
node.  It is also self-contained and does not depend upon Liber(ator)
or the OCaml High Level Freenet Interface, but it does share the
module Strutil with Liber and the OCaml High Level Freenet Interface,
and any project that uses OCaml FCP must include this module.