$Id: INSTALL 2434 2012-02-18 20:58:16Z tpgww $

NOTE: the content of this file is not always as fresh as the commentary in file
Makefile.config

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

Gtk+ >= 2.6 (http://www.gtk.org)
gcc >= 3.2 (http://gcc.gnu.org)
shell commands - grep, sed
libraries - libmagic is desirable, not not mandatory, at runtime.

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 (ATM only inotify on linux) or gamin >= 0.1.0 (http://www.gnome.org/~veillard/gamin/index.html).

emelFM2 can be built with plugins that require some external libraries
threadsafe modification of libgimpthumb
(http://emelfm2.net/attachment/wiki/OtherDownLoads/libgimpthumb-2.6.7.tar.bz2)
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 described, and set to their respective defaults,
in file Makefile.config. Some of them are further discussed here.
Makefile.config is often more up-to-date than this file.

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 ~/.config/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

WITH_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_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_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 may use external library for managing
thumbnail-file cacheing in accord with freedesktop.org specification (if set
WITH_THUMBLIB=1). A suitable library is available from
http://emelfm2.net/wiki/OtherDownLoads. 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.
