                                                                -*- text -*-
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.


New!
====

We are in the process of moving from the fvwm2 executable name to the
fvwm name.  This completes the process that was started in 2.1.0.

In this 2.4.8+ release we setup symbolic links from fvwm to fvwm2 and
from fvwm-root to xpmroot for the executables and the man pages.
In the 2.5.x it is vice versa, the main names are fvwm and fvwm-root,
but fvwm2 and xpmroot symlinks are supported for some time.

To disable these 4 symlinks, i.e. install only fvwm2 names, specify:

  % make install NEW_NAME_SYMLINKS=false

Distributions are encouraged to start to use "fvwm" as the executable.


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
==============================

* fvwm2 is installed into ${prefix}/bin
* a couple of utilities are also installed into ${prefix}/bin; this includes
  fvwm-config, fvwm-menu-*, FvwmCommand, fvwmbug, fvwm24_convert, xpmroot
* 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

where VERSION is the version string of FVWM, typically something like
"2.4.0".  No other files are installed.  There are sample system.fvwm2rc
files which you may copy manually to ${sysconfdir}/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 current versions of
autoconf/automake this will 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 location for the system-wide configuration (named
system.fvwm2rc) is /usr/local/etc/fvwm; this may be changed by changing the
prefix or setting sysconfdir explicitly.  This system-wide file is
read only if the user's ~/.fvwm2rc is not found.

Sample configuration files may be found in the sample.fvwm2rc
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 .fvwm2rc file, there are built-in
dialogs that can copy files from the configuration directory into the
users home directory to create the users starting .fvwm2rc.
See the fvwm2 man page under "INITIALIZATION".


C++
===

This section is irrelevant for the fvwm 2.3 and 2.4 series, there are no
modules using C++ anymore.  It is left for historical reasons.

FVWM proper does not need C++ to compile.  However, some modules are
written in C++, so configure probes for a C++ compiler by default, and
will build these modules only if a C++ compiler exists.  If configure
doesn't do the right thing, specify one or the other of these flags:

  --with-cxx=foo  to use "foo" for compiling C++ programs
  --without-cxx   to disable probing for a C++ compiler altogether


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


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

FVWM can optionally be compiled to use the following libraries: Xpm, rplay,
readline, LibStroke.  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.

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.

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 fvwm2 man page.

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 libfoo's headers

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

  xpm         X11/xpm.h
  readline    readline/readline.h
  rplay       rplay.h
  stroke      stroke.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.

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.

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-gnome-hints         disable GNOME window manager hints
  ~~~~~~~~~~~~~~~~~~~~~

By default, FVWM supports GNOME hints regarding windows, desks, pages
and more.  This turns this support off.  Note, you may turn it off
dynamically for all or individual windows by: Style * GNOMEIgnoreHints
Note that no additional libraries are needed for supporting GNOME hints.


  --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.


  --enable-multibyte            multibyte character support (experimental)
  ~~~~~~~~~~~~~~~~~~

FVWM has limited support for multibyte charsets.  It is fully experimental
and does not work in all places.  If you have access to a multibyte system
and want to extend this support, contact the fvwm-workers@fvwm.org list.

  --disable-compound-text       disable compound text conversion
  ~~~~~~~~~~~~~~~~~~~~~~~

International application may encode its window and icon name using a
special encoding (COMPOUND_TEXT) even with a non multibyte charset.
Basically, this happen if the window title contains non ASCII characters
(or only non ISO-8859-1 characters, this depends on the locale). By default,
FVWM converts these names into STRING encoded in the current locale. In the
pure ISO-8859-1 environment such conversion is rarely needed. Some shared
libraries are loaded at the FVWM startup when compound text is enabled.
This option disable this conversion. Note that --enable-multibyte causes to
ignore this option and you should try to use --enable-multibyte if you have
problems with the window titles.


  --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.


  --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.

