* single quoting for shell not to expand unexpanded variable in example

[fvwm.git] / INSTALL.fvwm

                                                                -*- text -*-
If you only need an information about all supported features skip to the
"Supported Features" and the following sections.

VMS users: ignore this file, and follow the instructions in vms/README
instead.

This file details only configuration options peculiar to FVWM.  Please
read the generic instructions in INSTALL first.


Important Note!
===============

The `configure' script keeps a cache of information it discovers, so
that subsequent invocations of `configure' will be faster.

However, if you update information on your system (such as install or
upgrade an optional library like Xpm, etc. [see below]) the cache may
contain outdated information; this can lead to confusing behavior during
subsequent `configure' invocations or builds.

If you're not familiar with how this works it might be safest to remove
the cache each time before running `configure'; you can either do a
simple:

  $ rm -f config.cache

Or you may feel more comfortable with a complete cleaning:

  $ make distclean


What gets installed, and where
==============================

* fvwm is installed into ${prefix}/bin
* a couple of utilities are also installed into ${prefix}/bin; this includes
  fvwm-config, fvwm-menu-*, fvwm-bug, fvwm-convert-*, fvwm-root, FvwmCommand
* all FvwmModule modules are installed into ${libexecdir}/fvwm/${VERSION}
* all manual pages are installed into ${mandir}/man1
* some configuration files are installed into ${datadir}/fvwm, for example,
  FvwmForm & FvwmScript configurations and others
* perl library is installed into ${datadir}/fvwm/perllib

where VERSION is the version string of FVWM, typically something like
"2.4.0".  No other files are installed.  There are sample fvwm/config
files which you may copy manually to ${datadir}/fvwm, see below.

Unless you used configure options,

* ${prefix}     is /usr/local
* ${bindir}     is ${prefix}/bin
* ${mandir}     is ${prefix}/man
* ${libexecdir} is ${prefix}/libexec
* ${datadir}    is ${prefix}/share
* ${sysconfdir} is ${prefix}/etc

Thus the default locations are: /usr/local/bin, /usr/local/man/man1,
/usr/local/libexec/fvwm/VERSION, and /usr/local/share/fvwm for the FVWM
executables, man pages, modules, and configuration files, respectively.

Note that by default, none of the executables are stripped when they're
installed.  If you'd like them to be, run `make install-strip' instead
of `make install'.  Note that due to a bug in the older versions of
autoconf/automake this may fail in some of the modules directories
trying to strip shell scripts.  We recommend that you run `make -k
install-strip', which will continue past the failures.


Configuration File
==================

FVWM configures itself at runtime by reading one or more configuration
files.  The default locations of the config file are ~/.fvwm/config and
/usr/local/share/fvwm/config (if the user's file is not found).  The
.fvwm2rc file names used in the past are supported too.

Sample configuration files may be found in the sample.fvwmrc
directory.  To avoid clobbering the current configuration, no
configuration file is installed by default.  You must copy it manually
the first time FVWM is installed.  But this is fully optional, FVWM
can run without any configuration file and has an ability to install some
configurations into the user home directory (precisely, FVWM_USERDIR).

Other system-wide configuration files are located in /usr/local/share/fvwm
(also called FVWM_DATADIR) that can be used directly from the configuration
directory.  See the FvwmForm man page for some examples.

For users starting fvwm without a fvwm/config or fvwm/.fvwm2rc file,
there are built-in dialogs that can copy files from the configuration
directory into the users home directory to create the users startup
file.  See the fvwm man page under "INITIALIZATION".


Bug Reports
===========

One of the installed scripts is fvwm-bug that allows users to send bug
reports to either the local address or the developer address or both.
The local email address defaults to the installer login, probably root.
To override this default, set $FVWM_BUGADDR before running ./configure.

There is also a web based bug reporting system, see the Home Page.


CPP
===

One of FVWM's modules, FvwmCpp, requires a C preprocessor program.  The
configuration will look in various common places for cpp.  If one is not
found, FvwmCpp will still compile but you'll need to invoke it with the
-cpppath option to tell it where to find cpp.  FvwmCpp will exit with an
error message if no path to cpp is known.

You can tell configure what cpp to use by setting the FVWM_CPP
environment variable before invoking configure:

  $ FVWM_CPP=/my/special/cpp ./configure


Supported Features
==================

FVWM has several compile time features that may be switched on and off
using ./configure. To query what your installed fvwm supports run one of:

  % fvwm-config --info
  % fvwm-config --supports

Please run './configure --help' to see a list of all option.
The sections below explain these options.

  Line shown by configure              Feature name  ./configure options
---------------------------------------------------------------------------
  With Asian bi-direct. text support?  bidi          --disable-bidi
  With Gettext Native Lang Support     gettext       --with-intl-*
  With GTK+ required for FvwmGtk?      gtk           --with-gtk-*
  With GDK image support in FvwmGtk?   gdk-imlib     --with-imlib-*
  With GNOME libs support in FvwmGtk?  gnome-libs    --with-gnome
  With PNG image support?              png           --with-png-*
  With ReadLine sup. in FvwmConsole?   readline      --with-readline-*
  With RPlay support in FvwmEvent?     rplay         --with-rpm-*
  With Shaped window support?          shape         --disable-shape
  With With Shared memory for XImage?  shm           --disable-shm
  With Session Management support?     sm            --disable-sm
  With Mouse strokes (gestures)?       stroke        --with-stroke-*
  With SVG image support?              rsvg          --disable-rsvg
  With Xinerama multi-head support?    xinerama      --disable-xinerama
  With Xft anti-alias font support?    xft           --enable-xft --with-xft-*
  With XPM image support?              xpm           --with-xpm-*
  With Xrender image support?          xrender       --disable-xrender
  Perl library directory:              perllib       --disable-perllib

None of these features are essential, but some are nice to have.
It is safe *not* to compile in the following features:
  bidi        (not needed if you don't plan to read Arabic and Hebrew)
  gnome-libs  (really not needed, used only in FvwmGtk for minor things)
  rplay       (really not needed, used only in FvwmEvent for internal sound)
  xinerama    (not needed if you or your users have only one monitor)


Optional libraries used by FVWM
===============================

FVWM can optionally be compiled to use the following libraries:

        xpm         (XPM image format)
        png         (PNG image format)
        rsvg        (SVG image format)
        rplay       (RPlay audio)
        readline    (Command line editing using readline)
        stroke      (Mouse strokes)
        intl        (Internationalization and localization using gettext)

By default, these are probed for, and used if found. If you want to use
any of them, install the library before configuring FVWM. It is possible
to explicitly tell configure to skip autoprobing of a given library and
disable it (see below).

Xpm allows the use of coloured icons.  See the Xpm web page at
http://www.inria.fr/koala/lehors/xpm.html for all the latest info and
links to source code.  You can also get the source code from
ftp://ftp.x.org/contrib/libraries/.  If you're having trouble building
with XPM even after reading this, try Question 2.4 in the FVWM FAQ.

Png allows to load coloured icons from files in PNG format. See the
libpng web page at http://www.libpng.org/pub/png/libpng.html for all the
latest info and links to source code. libpng is available as ANSI C source
code and requires the zlib library. The zlib package can be found at
http://www.gzip.org/zlib/

Librsvg allows rendering of SVG (scalable vector graphics) image files.
See the librsvg web page at http://librsvg.sourceforge.net/ for more
information and links to source code. Librsvg uses the Cairo library as
a rendering backend. Source code can be found at http://cairographics.org/

Rplay is used in one module (FvwmEvent) to play sounds without invoking
an external program.  This library appears to have been orphaned
in November, 1996.  The latest version is available at
http://rplay.doit.org/dist/.

Readline is used in one module (FvwmConsole) to allow fancy
command-line editing, a history buffer, etc.  It is GNU software, and
should be found on any GNU site, such as ftp://ftp.gnu.org/gnu/readline/.

To build with readline support, either termcap or ncurses library should
be found.  Use --with-termcap-library or --with-ncurses-library to specify
the path (directory or library file) to termcap or ncurses.  The first
valid library found is used.  It is possible to disable termcap or ncurses
autoprobing using --without-termcap-library or --without-ncurses-library.
Disabling both disables readline support, like --without-readline-library.

LibStroke allows interpretation by fvwm of mouse strokes (i.e., motions
of the mouse). For more informations see the  LibStroke web page at
http://www.etla.net/~willey/projects/libstroke/ and the fvwm man page.

Gettext is included in glibc, so it may be a part of your system.
Alternatively, there is GNU gettext package available at
http://www.gnu.org/software/gettext/.

If configure doesn't do the right thing, try one or more of the
following flags (examples assume library is named "foo"):

        --without-foo-library    to disable probing for libfoo
        --with-foo-library=FILE  to specify the library filename
        --with-foo-library=DIR   to specify directory containing libfoo
        --with-foo-includes=DIR  to specify include directory for headers

The desired include directory is the one in which the following header
may be found:

        xpm         X11/xpm.h
        png         png.h (zlib.h)
        readline    readline/readline.h
        rplay       rplay.h
        stroke      stroke.h
        intl        libintl.h

Only one version of the --with-foo-library flag may be specified.


Optional libraries used by FvwmGtk
==================================

FvwmGtk module requires GTK+ and optionally GDK-Imlib and GNOME libraries.
GDK-Imlib library that is a part of Imlib version 1 is used to have images.

Note, FVWM itself has an ability to support GNOME Window Manager hints
(which is enabled by default), this has nothing to do with GNOME library
support compiled into FvwmGtk (which is autoprobed and used if passed).

To disable autoprobing of GTK+, Imlib and GNOME libraries, use:

        --disable-gtktest --disable-imlibtest --without-gnome

This does not turn GTK+ and Imlib support off, instead, one part of the
checking, precisely compilation, is quietly considered to be passed.
To disable GTK+ and Imlib support even if the corresponding libraries
are installed, try this solution:

        --with-gtk-prefix=/no/dir --with-imlib-prefix=/no/dir

Run './configure --help' for more information about configure options.


Shared Libraries in Non-standard Places
=======================================

Note that at this time, autoconf and FVWM don't handle systems which
require a runtime library path separate from the link path very
gracefully.  If you have such a system (e.g., Solaris) and you have
installed the optional libraries in places not normally searched (e.g.,
not in /usr/lib, /lib or similar), you may need to specify the runtime
path separately; the above options won't add it for you.

A good way to do this is set the Makefile LDFLAGS variable before configure
runs to contain the -R option.  For example:

  $ LDFLAGS="-L/opt/xpm -R/opt/xpm" ./configure \
      --with-xpm-library=/opt/xpm/lib \
      --with-xpm-includes=/opt/xpm/include

In the future, FVWM's configuration may perform this step automatically.


Compile-time Options
====================

FVWM has several options selectable only at compile time.
These are intended to keep FVWM's memory footprint small, by compiling
in the code only if requested.

Each such option, say "foo", is selectable by an "--enable-foo" or a
"--disable-foo" switch.  By default, all of these options (except
debug messages) are enabled.  This is probably what you want -- unless
memory is *really* tight -- so normally none of these options are
used.

If option "foo" is enabled by default, the NON-default version of the
switch is shown in the list below, and vice-versa.  In other words,
the version of the switch that you are likely to use is the one
listed.


  --disable-package-subdirs     don't create subdirs for modules and data
  ~~~~~~~~~~~~~~~~~~~~~~~~~

Usually FVWM is installed to common places, like /usr or /usr/local/X11,
in this case it is essential to create the package subdirectories for
modules and data files.  Hovewer, if FVWM is installed to its own prefix,
like /opt/fvwm or /opt/fvwm-2.4, it's possible to disable them.

With --enable-package-subdirs (default):
  modules are installed into:    $libexecdir/fvwm/$VERSION
  data files are installed into: $datadir/fvwm
With --disable-package-subdirs:
  modules are installed into:    $libexecdir
  data files are installed into: $datadir

This option is good if you need a full control over exact directory names:
  $ ./configure --prefix=/tmp/fvwm --disable-package-subdirs \
      --libexecdir='${prefix}/modules' --datadir='${prefix}/data'

If you switch this option between builds, you need "make clean"!


  --enable-debug-msgs           enable debugging messages
  ~~~~~~~~~~~~~~~~~~~

If you would like to see lots of debug messages from FVWM, for
debugging purposes, enable this option.  When reporting bugs, please
do not send the debug output.  It is almost never useful in this
situation.


  --enable-command-log          enable command logging
  ~~~~~~~~~~~~~~~~~~~~

If you would like to see all commands executed and their times, enable
this option.  Remember, when using this, the command time offset is given
in the system ticks, and it only means anything for commands executed in
one batch; for example, after startup the command time offset may freely
reach hours.


  --disable-sm                  disable session management support
  ~~~~~~~~~~~~

FVWM has experimental session management support, which is autoconfigured
by searching for SM library, which is often shipped together with your
X libraries.  Note, the session management support is activated when FVWM
is run under a session manager like xsm or gnome-session.
This option disables session management support completely.


  --disable-xft                 disable anti-aliased text rendering
  ~~~~~~~~~~~~~

FVWM can use the Xft library (version 1 or 2) to perform anti-aliased
text rendering in any text drawn by fvwm and modules.  By default, Xft
library is probed and this support is enabled if Xft works. You need
XFree version >= 4.1 and freetype2 version >= 6.1.0 (aka version
2.0.6), but more recent versions are better. The FONT NAMES AND FONT
LOADING section of the fvwm manual page explains how to enable
anti-aliased rendering at runing time.  This option disables Xft
support completely.


  --disable-xrender             disable Xrender alpha-blend rendering
  ~~~~~~~~~~~~~~~~~

FVWM uses the Xrender library for alpha-blend rendering and tinting. This
library is contained in XFree version >= 4.0 and others recent X package.
This option disables Xrender support completely.


  --disable-rsvg                disable scalable vector graphics (SVG images)
  ~~~~~~~~~~~~~~
Fvwm can use the librsvg library to render SVG files into icons and
images. You need a librsvg version >= 2.13.91 that uses Cairo as the
rendering backend. This option disables SVG image loading support.


  --disable-shape               disable shape extensions
  ~~~~~~~~~~~~~~~

Shaped window extensions are enabled by default; this option will
disable them.  Shaped window extensions seem to increase the window
managers RSS by about 60 Kbytes.  They provide for leaving a title-bar
on the window without a border.  If you don't use shaped window
extension, you can either make your shaped windows undecorated, or
live with a border and backdrop around all your shaped windows
(oclock, xeyes).

If you normally use a shaped window (xeyes or oclock), you might as
well compile this extension in, since the memory cost is minimal in
this case (the shaped window shared libs will be loaded anyway).  If
you don't normally use shaped windows, you have to decide for yourself.

Note: if it is compiled in, run time detection is used to make sure
that the currently running X server supports it.


  --disable-bidi                disable bi-directional text support
  ~~~~~~~~~~~~~~

The bi-directional text support is used to properly handle right-to-left
languages, like Hebrew and Arabic.  By default, fribidi library is probed
and this support is enabled if fribidi works.  This option explicitly
disables the bi-directional text support.


  --with-fribidi-bindir         directory of fribidi-config if not in PATH
  ~~~~~~~~~~~~~~~~~~~~~

The location of fribidi libraries and headers (needed for Bidi support)
is determined using fribidi-config utility.  This option specifies a
directory where fribidi-config is installed if it is not in the $PATH.


  --disable-perllib             disable installing FVWM perl library
  ~~~~~~~~~~~~~~~~~

By default the FVWM perl library is installed together with all other
data files.  Perl library may be used to write FVWM modules in perl.
Currently the FvwmPerl module uses it.  This option disables installing
the FVWM perl library.


  --with-gnome                  no, yes or prefix for GNOME files (FvwmGtk only)
  ~~~~~~~~~~~~

FvwmGtk may be built as a GTK application or a GNOME application.
This is autodetected and if GNOME libs found, they are used in FvwmGtk.
You may also specify the location of GNOME headers and libs using
--with-gnome-includes and --with-gnome-libs, but this is usually never
needed, since all required info should be returned by gnome-config
if GNOME is properly installed.  In case the GNOME installation works
and you don't want to be dependant on GNOME, specify --without-gnome.


  --enable-xinerama-emulation   enable Xinerama emulation on one screen
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~

This option is only useful for developers.  Usually the Xinerama support
is only activated at run time when it is compiled in and X supports it
and X is run with Xinerama extension.  This option enables the Xinerama
emulation even when X does not support it or fvwm is run on one screen.
This divides the screen to 2 non equivalent parts and one black area.