$Id: INSTALL 1284 2008-09-28 09:57:27Z tpgww $

REQUIREMENTS
~~~~~~~~~~~~

Gtk+ >= 2.6 (http://www.gtk.org)
gcc >= 3.2 (http://gcc.gnu.org)
shell commands - file >= 4, grep, sed

The crypt plugin can make use of [de]compressors liblzo, libz and/or libbz2 if they're
available, but will otherwise work without any [de]compression. Development files are
not needed.

Build-time options

emelFM2 can be built with with some relevant capabilities of later Gtk+ versions.

emelFM2 can be built with improved file alteration monitoring, using kernel-based mechansim (sofar only dnotify or inotify on linux) or FAM or gamin >= 0.1.0 (http://www.gnome.org/~veillard/gamin/index.html).

emelFM2 can be built with plugins that require some external libraries 
libgimpthumb >= 2.2 for the thumbnails plugin
libacl with more-or-less the full capability of the POSIX standard for ACL's for the ACL plugin

COMPILING
~~~~~~~~~

make
or
make OPTION=choice OPTION2=choice2 ....

The various make options are set out in file Makefile.config, and some
of them are further discussed here.

For new makers, any paramter specified in Makefile.config in this form:
 OPTION ?= choice
means that OPTION will be assiged the value choice unless OPTION is otherwise
specified by the user, as an argument to the make command, as shown in the
second example above.

You can of course edit Makefile.config if you want.


PREFIX=/<your-preferred-path>/emelfm2

NOTE: changing PREFIX affects the default location of the custom
icon files. The configuration file (typically ~/.emelfm2/config)
includes paths for custom icon files, so if you have previously
installed emelFM2 with a different PREFIX, the pre-existing config
file, even if it has the current version number, will include icon
paths which don't match the current PREFIX. The easiest solution for
"missing" icon files is to open the emelFM2 configuration dialog,
and click the "Default" button.

some relevant make options:

DOCS_VERSION=1
causes the default docs dir name to include the current emelFM2
version no. Some distros prefer this style.

HELPDOC=MY-HELP-DOC
changes the name of the main user-guide document from the
default (USAGE) to MY-HELP-DOC

CONFIGDOC=MY-CFG-DOC
changes the name of the configuration help document from the
default (CONFIGURATION) to MY-CFG-DOC

USE_LATEST=1
builds a few differences that are available in the build-time
gtk version, if that is later than 2.6

At most ONE of the following file-alteration-monitor processes
can be enabled. Each has advantages and constraints:

USE_FAM=1
builds code for file-change monitoring using FAM instead of
monitoring the m/ctimes of the parent dir. Requires FAM
development files and/or library, of course
Functionality a bit limited, but reasonably widely available

USE_GAMIN=1
builds code for file-change monitoring using gamin instead of
monitoring the m/ctimes of the parent dir. Requires gamin
development files and/or library.
Gamin is sort of FAM on steroids, with use of kernel mechanism
if one is available.
Gamin never reports access-time changes, seems never to report
some directories (e.g. ~/.Trash), its dnotify backend is
unreliable under heavy load, and its treatment of symlinks is
ambivalent
But gamin does support bsd's and ntfs partitions.
Source is available at www.gnome.org/~veillard/gamin/sources
NOTE don't use this if only FAM is available ! It will build
successfully, but crash when run !

USE_INOTIFY=1
builds code for directly interrogating linux kernel's inotify FAM
functionality. Implies a kernel with support for the inotify API
used in 2.6.13 (some 2.6.12's may have it too, at your distro's
pleasure. Existence of /proc/sys/fs/inotify/* is a good - but not
foolproof - indicator).
Should simply revert to polling if built with this, but the
capability is not actually present

USE_DNOTIFY=1
builds code for directly interrogating linux kernel's dnotify FAM
functionality. Implies a kernel with support for the dnotify - which
should be everything after 2.4.0
Should simply revert to polling if built with this, but the
capability is not actually present
Note that dnotify requires a monitored dir to be 'opened' and so
it must be mounted before displaying the dir, and cannot be
unmounted while displayed
WARNING - this option fared badly with one tester's smp kernel.
There were spurious processes generated, and spurious filelist
refreshing occurred. On investigation, this seems to have been
a problem with the particular kernel.

USE_KQUEUE=1
NOTE this option does not yet work. Code has been written, but
needs bsd'er(s) to perfect and test it. Volunteers welcome.
builds code for directly interrogating bsd kernel's kqueue FAM
functionality.
Should simply revert to polling if built with this, but the
capability is not actually present
Note that kqueue requires a monitored dir to be 'opened' and so
it must be mounted before displaying the dir, and cannot be
unmounted while displayed

FILES_UTF8ONLY=1
By default, emelFM2 will convert path/file name strings which are
encoded in something other than utf-8 (which includes ascii) for
internal use and interaction with glib/gtk. If you're sure that only
utf-8 or ascii will be needed, then setting this variable to 1 will omit
the conversions, resulting in slightly smaller and faster code.

NOTE: If your filesysten encodes path/file names in something
other than utf-8/ascii (e.g. with german umlauts), you should also
have:
1. set the environment variable
G_FILENAME_ENCODING=character set name (or a comma-separated
list of such names, and glib uses the first name in that list).
OR
2. set the environment variable G_BROKEN_FILENAMES=1. In that case,
glib assumes that the locale encoding is used for names.

To cancel the effect of G_BROKEN_FILENAMES you have to unset the
environment variable, setting it to 0 is not enough!

G_FILENAME_ENCODING takes priority over G_BROKEN_FILENAMES.

PANES_HORIZONTAL=1
causes the default file-pane layout to be top-to-bottom instead
of side-by-side

WITH_THUMBS = 1
enables a thumbnail viewer plugin. This uses libgimpthumb for managing
thumbnail-file cacheing in accord with freedesktop.org specification.
At least version 2.2 of that library is needed in order for the plugin
to load at runtime. Corresponding development files are needed for
building the plugin

WITH_TRACKER = 1
enables a tracker-UI plugin. This uses at least version 0.6 of that
application. No external library is involved, as the data is interrogated
via shell commands. Similarly, no development file is needed at build time
(these may change if tracker's API is updated).

WITH_ACL = 1
enables an Access-Control-List-management plugin. This uses libacl.
Not all operating systems (or more particularly their libraries used to
manage ACL's) support the same level of functionality. This plugin assumes
reasonably-full functionality, more-or-less the full capability of the
aborted POSIX standard for ACL's. Linux meets this requirement, others
will just have to experiment. Corresponding development files are needed
for building the plugin

UPDATE TRANSLATION FILES
~~~~~~~~~~~~~~~~~~~~~~~~

make i18n

INSTALLATION
~~~~~~~~~~~~

make install
or
make install PREFIX=/<path>/emelfm2

To process just the plugins

make install_plugins
or
make install_plugins PREFIX=/<path>/emelfm2

UNINSTALLATION
~~~~~~~~~~~~~~

make uninstall
or
make uninstall PREFIX=/<path>/emelfm2
or
make uninstall_plugins
or
make uninstall_plugins PREFIX=/<path>/emelfm2

API DOCUMENTATION
~~~~~~~~~~~~~~~~~

If you have doxygen installed,

make doc

will create or refresh a suite of html files, in docs/api/html in the source code tree.
