Use the correct border hints to calculate screen width.
[fvwm.git] / INSTALL.fvwm
blob3f8dadcbeb5767e401c5247731dee1ebb8cf681e
1                                                                 -*- text -*-
2 If you only need an information about all supported features skip to the
3 "Supported Features" and the following sections.
5 VMS users: ignore this file, and follow the instructions in vms/README
6 instead.
8 This file details only configuration options peculiar to fvwm.  Please
9 read the generic instructions in INSTALL first.
12 Important Note!
13 ===============
15 The `configure' script keeps a cache of information it discovers, so
16 that subsequent invocations of `configure' will be faster.
18 However, if you update information on your system (such as install or
19 upgrade an optional library like Xpm, etc. [see below]) the cache may
20 contain outdated information; this can lead to confusing behavior during
21 subsequent `configure' invocations or builds.
23 If you're not familiar with how this works it might be safest to remove
24 the cache each time before running `configure'; you can either do a
25 simple:
27   $ rm -f config.cache
29 Or you may feel more comfortable with a complete cleaning:
31   $ make distclean
34 What gets installed, and where
35 ==============================
37 * fvwm is installed into ${prefix}/bin
38 * a couple of utilities are also installed into ${prefix}/bin; this includes
39   fvwm-config, fvwm-menu-*, fvwm-bug, fvwm-convert-*, fvwm-root, FvwmCommand
40 * all FvwmModule modules are installed into ${libexecdir}/fvwm/${VERSION}
41 * all manual pages are installed into ${mandir}/man1
42 * some configuration files are installed into ${datadir}/fvwm, for example,
43   FvwmForm & FvwmScript configurations and others
44 * perl library is installed into ${datadir}/fvwm/perllib
46 where VERSION is the version string of fvwm, typically something like
47 "2.4.0".  No other files are installed.  There are sample fvwm/config
48 files which you may copy manually to ${datadir}/fvwm, see below.
50 Unless you used configure options,
52 * ${prefix}     is /usr/local
53 * ${bindir}     is ${prefix}/bin
54 * ${mandir}     is ${prefix}/man
55 * ${libexecdir} is ${prefix}/libexec
56 * ${datadir}    is ${prefix}/share
57 * ${sysconfdir} is ${prefix}/etc
59 Thus the default locations are: /usr/local/bin, /usr/local/man/man1,
60 /usr/local/libexec/fvwm/VERSION, and /usr/local/share/fvwm for the fvwm
61 executables, man pages, modules, and configuration files, respectively.
63 Note that by default, none of the executables are stripped when they're
64 installed.  If you'd like them to be, run `make install-strip' instead
65 of `make install'.  Note that due to a bug in the older versions of
66 autoconf/automake this may fail in some of the modules directories
67 trying to strip shell scripts.  We recommend that you run `make -k
68 install-strip', which will continue past the failures.
71 Configuration File
72 ==================
74 Fvwm configures itself at runtime by reading one or more configuration
75 files.  The default locations of the config file are ~/.fvwm/config and
76 /usr/local/share/fvwm/config (if the user's file is not found).  The
77 .fvwm2rc file names used in the past are supported too.
79 Sample configuration files may be found in the sample.fvwmrc
80 directory.  To avoid clobbering the current configuration, no
81 configuration file is installed by default.  You must copy it manually
82 the first time fvwm is installed.  But this is fully optional, fvwm
83 can run without any configuration file and has an ability to install some
84 configurations into the user home directory (precisely, FVWM_USERDIR).
86 Other system-wide configuration files are located in /usr/local/share/fvwm
87 (also called FVWM_DATADIR) that can be used directly from the configuration
88 directory.  See the FvwmForm man page for some examples.
90 For users starting fvwm without a fvwm/config or fvwm/.fvwm2rc file,
91 there are built-in dialogs that can copy files from the configuration
92 directory into the users home directory to create the users startup
93 file.  See the fvwm man page under "INITIALIZATION".
96 Bug Reports
97 ===========
99 One of the installed scripts is fvwm-bug that allows users to send bug
100 reports to either the local address or the developer address or both.
101 The local email address defaults to the installer login, probably root.
102 To override this default, set $FVWM_BUGADDR before running ./configure.
104 There is also a web based bug reporting system, see the Home Page.
110 One of fvwm's modules, FvwmCpp, requires a C preprocessor program.  The
111 configuration will look in various common places for cpp.  If one is not
112 found, FvwmCpp will still compile but you'll need to invoke it with the
113 -cpppath option to tell it where to find cpp.  FvwmCpp will exit with an
114 error message if no path to cpp is known.
116 You can tell configure what cpp to use by setting the FVWM_CPP
117 environment variable before invoking configure:
119   $ FVWM_CPP=/my/special/cpp ./configure
122 Supported Features
123 ==================
125 Fvwm has several compile time features that may be switched on and off
126 using ./configure. To query what your installed fvwm supports run one of:
128   % fvwm-config --info
129   % fvwm-config --supports
131 Please run './configure --help' to see a list of all option.
132 The sections below explain these options.
134   Line shown by configure              Feature name  ./configure options
135 ---------------------------------------------------------------------------
136   With Asian bi-direct. text support?  bidi          --disable-bidi
137   With Gettext Native Lang Support     gettext       --with-intl-*
138   With GTK+ required for FvwmGtk?      gtk           --with-gtk-*
139   With GDK image support in FvwmGtk?   gdk-imlib     --with-imlib-*
140   With GNOME libs support in FvwmGtk?  gnome-libs    --with-gnome
141   With PNG image support?              png           --with-png-*
142   With ReadLine sup. in FvwmConsole?   readline      --with-readline-*
143   With RPlay support in FvwmEvent?     rplay         --with-rpm-*
144   With Shaped window support?          shape         --disable-shape
145   With With Shared memory for XImage?  shm           --disable-shm
146   With Session Management support?     sm            --disable-sm
147   With Mouse strokes (gestures)?       stroke        --with-stroke-*
148   With SVG image support?              rsvg          --disable-rsvg
149   With Xcursor support?                xcursor       --disable-xcursor
150   With Xinerama multi-head support?    xinerama      --disable-xinerama
151   With Xft anti-alias font support?    xft           --enable-xft --with-xft-*
152   With XPM image support?              xpm           --with-xpm-*
153   With Xrender image support?          xrender       --disable-xrender
154   Perl library directory:              perllib       --disable-perllib
156 None of these features are essential, but some are nice to have.
157 It is safe *not* to compile in the following features:
158   bidi        (not needed if you don't plan to read Arabic and Hebrew)
159   gnome-libs  (really not needed, used only in FvwmGtk for minor things)
160   rplay       (really not needed, used only in FvwmEvent for internal sound)
161   xinerama    (not needed if you or your users have only one monitor)
164 Optional libraries used by fvwm
165 ===============================
167 Fvwm can optionally be compiled to use the following libraries:
169         xpm         (XPM image format)
170         png         (PNG image format)
171         rsvg        (SVG image format)
172         rplay       (RPlay audio)
173         readline    (Command line editing using readline)
174         stroke      (Mouse strokes)
175         intl        (Internationalization and localization using gettext)
177 By default, these are probed for, and used if found. If you want to use
178 any of them, install the library before configuring fvwm. It is possible
179 to explicitly tell configure to skip autoprobing of a given library and
180 disable it (see below).
182 Xpm allows the use of coloured icons.  See the Xpm web page at
183 http://www.inria.fr/koala/lehors/xpm.html for all the latest info and
184 links to source code.  You can also get the source code from
185 ftp://ftp.x.org/contrib/libraries/.  If you're having trouble building
186 with XPM even after reading this, try Question 2.4 in the fvwm FAQ.
188 Png allows to load coloured icons from files in PNG format. See the
189 libpng web page at http://www.libpng.org/pub/png/libpng.html for all the
190 latest info and links to source code. libpng is available as ANSI C source
191 code and requires the zlib library. The zlib package can be found at
192 http://www.gzip.org/zlib/
194 Librsvg allows rendering of SVG (scalable vector graphics) image files.
195 See the librsvg web page at http://librsvg.sourceforge.net/ for more
196 information and links to source code. Librsvg uses the Cairo library as
197 a rendering backend. Source code can be found at http://cairographics.org/
199 Rplay is used in one module (FvwmEvent) to play sounds without invoking
200 an external program.  This library appears to have been orphaned
201 in November, 1996.  The latest version is available at
202 http://rplay.doit.org/dist/.
204 Readline is used in one module (FvwmConsole) to allow fancy
205 command-line editing, a history buffer, etc.  It is GNU software, and
206 should be found on any GNU site, such as ftp://ftp.gnu.org/gnu/readline/.
208 To build with readline support, either termcap or ncurses library should
209 be found.  Use --with-termcap-library or --with-ncurses-library to specify
210 the path (directory or library file) to termcap or ncurses.  The first
211 valid library found is used.  It is possible to disable termcap or ncurses
212 autoprobing using --without-termcap-library or --without-ncurses-library.
213 Disabling both disables readline support, like --without-readline-library.
215 LibStroke allows interpretation by fvwm of mouse strokes (i.e., motions
216 of the mouse). For more informations see the  LibStroke web page at
217 http://www.etla.net/~willey/projects/libstroke/ and the fvwm man page.
219 Gettext is included in glibc, so it may be a part of your system.
220 Alternatively, there is GNU gettext package available at
221 http://www.gnu.org/software/gettext/.
223 If configure doesn't do the right thing, try one or more of the
224 following flags (examples assume library is named "foo"):
226         --without-foo-library    to disable probing for libfoo
227         --with-foo-library=FILE  to specify the library filename
228         --with-foo-library=DIR   to specify directory containing libfoo
229         --with-foo-includes=DIR  to specify include directory for headers
231 The desired include directory is the one in which the following header
232 may be found:
234         xpm         X11/xpm.h
235         png         png.h (zlib.h)
236         readline    readline/readline.h
237         rplay       rplay.h
238         stroke      stroke.h
239         intl        libintl.h
241 Only one version of the --with-foo-library flag may be specified.
244 Optional libraries used by FvwmGtk
245 ==================================
247 FvwmGtk module requires GTK+ and optionally GDK-Imlib and GNOME libraries.
248 GDK-Imlib library that is a part of Imlib version 1 is used to have images.
250 Note, fvwm itself has an ability to support GNOME Window Manager hints
251 (which is enabled by default), this has nothing to do with GNOME library
252 support compiled into FvwmGtk (which is autoprobed and used if passed).
254 To disable autoprobing of GTK+, Imlib and GNOME libraries, use:
256         --disable-gtktest --disable-imlibtest --without-gnome
258 This does not turn GTK+ and Imlib support off, instead, one part of the
259 checking, precisely compilation, is quietly considered to be passed.
260 To disable GTK+ and Imlib support even if the corresponding libraries
261 are installed, try this solution:
263         --with-gtk-prefix=/no/dir --with-imlib-prefix=/no/dir
265 Run './configure --help' for more information about configure options.
268 Shared Libraries in Non-standard Places
269 =======================================
271 Note that at this time, autoconf and fvwm don't handle systems which
272 require a runtime library path separate from the link path very
273 gracefully.  If you have such a system (e.g., Solaris) and you have
274 installed the optional libraries in places not normally searched (e.g.,
275 not in /usr/lib, /lib or similar), you may need to specify the runtime
276 path separately; the above options won't add it for you.
278 A good way to do this is set the Makefile LDFLAGS variable before configure
279 runs to contain the -R option.  For example:
281   $ LDFLAGS="-L/opt/xpm -R/opt/xpm" ./configure \
282       --with-xpm-library=/opt/xpm/lib \
283       --with-xpm-includes=/opt/xpm/include
285 In the future, fvwm's configuration may perform this step automatically.
288 Compile-time Options
289 ====================
291 Fvwm has several options selectable only at compile time.
292 These are intended to keep fvwm's memory footprint small, by compiling
293 in the code only if requested.
295 Each such option, say "foo", is selectable by an "--enable-foo" or a
296 "--disable-foo" switch.  By default, all of these options (except
297 debug messages) are enabled.  This is probably what you want -- unless
298 memory is *really* tight -- so normally none of these options are
299 used.
301 If option "foo" is enabled by default, the NON-default version of the
302 switch is shown in the list below, and vice-versa.  In other words,
303 the version of the switch that you are likely to use is the one
304 listed.
307   --disable-package-subdirs     don't create subdirs for modules and data
308   ~~~~~~~~~~~~~~~~~~~~~~~~~
310 Usually fvwm is installed to common places, like /usr or /usr/local/X11,
311 in this case it is essential to create the package subdirectories for
312 modules and data files.  Hovewer, if fvwm is installed to its own prefix,
313 like /opt/fvwm or /opt/fvwm-2.4, it's possible to disable them.
315 With --enable-package-subdirs (default):
316   modules are installed into:    $libexecdir/fvwm/$VERSION
317   data files are installed into: $datadir/fvwm
318 With --disable-package-subdirs:
319   modules are installed into:    $libexecdir
320   data files are installed into: $datadir
322 This option is good if you need a full control over exact directory names:
323   $ ./configure --prefix=/tmp/fvwm --disable-package-subdirs \
324       --libexecdir='${prefix}/modules' --datadir='${prefix}/data'
326 If you switch this option between builds, you need "make clean"!
329   --enable-debug-msgs           enable debugging messages
330   ~~~~~~~~~~~~~~~~~~~
332 If you would like to see lots of debug messages from fvwm, for
333 debugging purposes, enable this option.  When reporting bugs, please
334 do not send the debug output.  It is almost never useful in this
335 situation.
338   --enable-command-log          enable command logging
339   ~~~~~~~~~~~~~~~~~~~~
341 If you would like to see all commands executed and their times, enable
342 this option.  Remember, when using this, the command time offset is given
343 in the system ticks, and it only means anything for commands executed in
344 one batch; for example, after startup the command time offset may freely
345 reach hours.
348   --disable-sm                  disable session management support
349   ~~~~~~~~~~~~
351 Fvwm has experimental session management support, which is autoconfigured
352 by searching for SM library, which is often shipped together with your
353 X libraries.  Note, the session management support is activated when fvwm
354 is run under a session manager like xsm or gnome-session.
355 This option disables session management support completely.
358   --disable-xft                 disable anti-aliased text rendering
359   ~~~~~~~~~~~~~
361 Fvwm can use the Xft library (version 1 or 2) to perform anti-aliased
362 text rendering in any text drawn by fvwm and modules.  By default, Xft
363 library is probed and this support is enabled if Xft works. You need
364 XFree version >= 4.1 and freetype2 version >= 6.1.0 (aka version
365 2.0.6), but more recent versions are better. The FONT NAMES AND FONT
366 LOADING section of the fvwm manual page explains how to enable
367 anti-aliased rendering at runing time.  This option disables Xft
368 support completely.
371   --disable-xrender             disable Xrender alpha-blend rendering
372   ~~~~~~~~~~~~~~~~~
374 Fvwm uses the Xrender library for alpha-blend rendering and tinting. This
375 library is contained in XFree version >= 4.0 and others recent X package.
376 This option disables Xrender support completely.
379   --disable-xcursor             disable Xcursor ARGB/animated cursor loading
380   ~~~~~~~~~~~~~~~~~
382 Fvwm can use the Xcursor library to load ARGB/animated mouse cursors. This
383 library is contained in XFree version >= 4.3 and others recent X packages.
384 This option disables Xcursor support.
387   --disable-rsvg                disable scalable vector graphics (SVG images)
388   ~~~~~~~~~~~~~~
389 Fvwm can use the librsvg library to render SVG files into icons and
390 images. You need a librsvg version >= 2.13.92 that uses Cairo as the
391 rendering backend. This option disables SVG image loading support.
394   --disable-shape               disable shape extensions
395   ~~~~~~~~~~~~~~~
397 Shaped window extensions are enabled by default; this option will
398 disable them.  Shaped window extensions seem to increase the window
399 managers RSS by about 60 Kbytes.  They provide for leaving a title-bar
400 on the window without a border.  If you don't use shaped window
401 extension, you can either make your shaped windows undecorated, or
402 live with a border and backdrop around all your shaped windows
403 (oclock, xeyes).
405 If you normally use a shaped window (xeyes or oclock), you might as
406 well compile this extension in, since the memory cost is minimal in
407 this case (the shaped window shared libs will be loaded anyway).  If
408 you don't normally use shaped windows, you have to decide for yourself.
410 Note: if it is compiled in, run time detection is used to make sure
411 that the currently running X server supports it.
414   --disable-bidi                disable bi-directional text support
415   ~~~~~~~~~~~~~~
417 The bi-directional text support is used to properly handle right-to-left
418 languages, like Hebrew and Arabic.  By default, fribidi library is probed
419 and this support is enabled if fribidi works.  This option explicitly
420 disables the bi-directional text support.
423   --with-fribidi-bindir         directory of fribidi-config if not in PATH
424   ~~~~~~~~~~~~~~~~~~~~~
426 The location of fribidi libraries and headers (needed for Bidi support)
427 is determined using fribidi-config utility.  This option specifies a
428 directory where fribidi-config is installed if it is not in the $PATH.
431   --disable-perllib             disable installing fvwm perl library
432   ~~~~~~~~~~~~~~~~~
434 By default the fvwm perl library is installed together with all other
435 data files.  Perl library may be used to write fvwm modules in perl.
436 Currently the FvwmPerl module uses it.  This option disables installing
437 the fvwm perl library.
440   --with-gnome                  no, yes or prefix for GNOME files (FvwmGtk only)
441   ~~~~~~~~~~~~
443 FvwmGtk may be built as a GTK application or a GNOME application.
444 This is autodetected and if GNOME libs found, they are used in FvwmGtk.
445 You may also specify the location of GNOME headers and libs using
446 --with-gnome-includes and --with-gnome-libs, but this is usually never
447 needed, since all required info should be returned by gnome-config
448 if GNOME is properly installed.  In case the GNOME installation works
449 and you don't want to be dependant on GNOME, specify --without-gnome.
452   --enable-xinerama-emulation   enable Xinerama emulation on one screen
453   ~~~~~~~~~~~~~~~~~~~~~~~~~~~
455 This option is only useful for developers.  Usually the Xinerama support
456 is only activated at run time when it is compiled in and X supports it
457 and X is run with Xinerama extension.  This option enables the Xinerama
458 emulation even when X does not support it or fvwm is run on one screen.
459 This divides the screen to 2 non equivalent parts and one black area.