wmaker/doc/build/Compilation.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename wmaker_install.info
@settitle Window Maker Compilation and Installation 1.0
@c %**end of header

@c This documentation is written in Texinfo format:
@c   https://www.gnu.org/software/texinfo/manual/texinfo/
@c
@c The reference checker is the GNU texi2any tool, which can be invoked like this:
@c   texi2any --plaintext --no-split --verbose Compilation.texi
@c
@c If you modify this file, you may want to spell-check it with:
@c    aspell --lang=en_GB --mode=texinfo check Compilation.texi
@c
@c The length of lines in this file is set to 100 because it tends to keep sentences together
@c despite the embedded @commands{};
@c
@c It is generally considered good practice for Tex and Texinfo formats to keep sentences on
@c different lines, using the fact that in the end they will be merged in paragraph anyway, because
@c it makes the patchs clearer about where the changes actually are.

@finalout

@c If the version was not given to texi2any with -D, assume we are being run
@c on the git dev branch
@ifclear version
@set version git#next
@end ifclear

@c We provide the ability to change the email address for support from the
@c command line
@ifclear emailsupport
@set emailsupport @email{wmaker-dev@@lists.windowmaker.org}
@end ifclear

@c ---------------------------------------------------------------------------------- Title Page ---

@copying
@noindent
This manual is for @sc{Window Maker} window manager, version @value{version}.

@noindent Copyright @copyright{} 2015 The Window Maker Team.

@quotation
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program, see file COPYING for details.
@end quotation
@end copying

@titlepage
@title Window Maker Compilation and Installation
@subtitle A guide to configure, compile and install
@subtitle @sc{Window Maker} from sources.
@author The Window Maker Team

@page
@vskip 0pt plus 1filll
@insertcopying

@sp 1
Published by The Window Maker team on @today{}.
@end titlepage

@c ---------------------------------------------------------------------------- Table of Content ---
@node Top
@ifnottex
@top Window Maker Compilation and Installation

@ifclear cctexi2txt
A guide to configure, compile and install
@sc{Window Maker} from sources.
@end ifclear
@end ifnottex

@contents

@ifnottex
@ifclear cctexi2txt
@sp 1
This manual is for Window Maker, version @value{version}.
@end ifclear
@end ifnottex

@menu
* Prerequisites::         What you will need to build Window Maker
* Building Window Maker:: How to build Window Maker
* Miscellaneous::         Misc. information you may want to know
* Troubleshooting::       Help on a few rare build problems
@end menu


@c ------------------------------------------------------------------------------- Prerequisites ---
@node Prerequisites
@chapter Prerequisites

@section Supported Platforms

@itemize -
@item Intel GNU/Linux Systems in general, @t{ix86} and @t{x86_64} but other architectures should work
@item BSD systems
@item Solaris, at least on release 10 and 11
@end itemize

Patches to make it work on other platforms are welcome.


@section Software Dependencies
@anchor{Software Dependencies}

The following software is required to use @sc{Window Maker}:
@itemize -
@item X11R6.x

Window Maker can be compiled in older versions of @emph{X}, like @emph{X11R5} (@emph{Solaris})
or @emph{X11R4} (@emph{OpenWindows}) but it will not work 100% correctly.
In such servers there will not be application icons and you'll have trouble using the dock.
Upgrading the client libraries (@emph{Xlib}, @emph{Xt}, etc.) will help if you can't upgrade
the server.
@end itemize

@noindent The following is required to build @sc{Window Maker}:
@itemize -
@item Basic obvious stuff

@itemize
@item @emph{gcc} (or some other ANSI C compiler, supporting some C99 extensions)
@item @emph{glibc} development files (usually @file{glibc-devel} in Linux distributions)
@item @emph{X} development files (@file{XFree86-devel} or something similar)
@end itemize

@item @emph{Xft2} and its dependencies

Dependencies include @emph{freetype2} and @emph{fontconfig}.
You will also need the development files for them (@file{xft2-devel}).
Sources are available at: @uref{http://www.freedesktop.org/wiki/Software/Xft/}

@end itemize

@noindent @b{Note}:
@sc{Window Maker} is known to compile with @emph{gcc} and @emph{clang};
the code source is mostly ANSI C (also known as C89 and C90) but is uses very few of the C99
novelties;
it also uses a few attributes introduced in the C11 standard but those are detected automatically,
so most compilers should work.


@section Special Dependencies
@anchor{Special Dependencies}


If you want to compile using the sources from the git repository instead of the distribution
package, you will also need:
@itemize
@item @emph{git}
@item @emph{autoconf} 2.69
@item @emph{automake} 1.11
@item @emph{libtool} 1.4.2
@end itemize


@section Optional Dependencies

These libraries are not required to make @sc{Window Maker} work, but they are supported in case you
want to use them. Version numbers are indicative, but other versions might work too.

@itemize -
@item @emph{libXPM} 4.7 or newer

Older versions may not work!

Available from @uref{http://xlibs.freedesktop.org/release/}

There is built-in support for @emph{XPM} files, but it will not
load images in some uncommon encodings.

@item @emph{libpng} 0.96 or newer and @emph{zlib}

For @emph{PNG} image support,
@uref{http://www.libpng.org/pub/png/libpng.html}

@item @emph{libtiff} 3.4 or newer

For @emph{TIFF} image support,
@uref{http://www.libtiff.org/}

@item @emph{libjpeg} 6.0.1 or newer

For @emph{JPEG} image support,
@uref{http://www.ijg.org/}

Note that if you don't have it, @command{configure} will issue a big warning in the end,
this is because JPEG images are often used in themes and for background images
so you probably want this format supported.

@item @emph{libgif} 2.2 or @emph{libungif}

For @emph{GIF} image support,
@uref{http://giflib.sourceforge.net/}

@item @emph{GNU xgettext}

If you want to use translated messages, you will need @emph{GNU gettext}.
Other versions of @emph{gettext} are not compatible and will not work.
Get the @emph{GNU} version from @uref{http://www.gnu.org/software/gettext/}

@item @emph{libbsd}

This library can be used by the @emph{WINGs} utility library to make use of @command{strlcat} and
@command{strlcpy} instead of using built-in functions if your system does not provide them in its
core @emph{libc}.
You should let @sc{Window Maker}'s @command{configure} detect this for you.
You can get it from @uref{http://libbsd.freedesktop.org/wiki/}

@item @emph{Inotify}

If you have Linux's @emph{inotify} support, @sc{Window Maker} will use it to check for configuration
updates instead of polling regularly the file.
The needed header comes with the kernel, typical packages names include:
@itemize
@item @file{kernel-headers} for @emph{Slackware} and @emph{Fedora}
@item @file{linux-userspace-headers} for @emph{Mageia}
@item @file{linux-libc-dev} for @emph{Debian} and @emph{Ubuntu}
@item @file{linux-glibc-devel} for @emph{OpenSuSE}
@end itemize

@item @emph{Boehm GC}

This library can be used by the @emph{WINGs} utility toolkit to use a
@cite{Boehm-Demers-Weiser Garbage Collector} instead of the traditional
@command{malloc}/@command{free} functions from the @emph{libc}.
You have to explicitly ask for its support though (@pxref{Configure Options}).
You can get it from @uref{http://www.hboehm.info/gc/}

@end itemize


@c ----------------------------------------------------------------------- Building Window Maker ---
@node Building Window Maker
@chapter Building @sc{Window Maker}

@section Getting the Sources

The latest version of @sc{Window Maker} (@t{-crm}) can be downloaded from
@uref{http://www.windowmaker.org/}

Alternatively, the development branch, called @t{#next} is in the @emph{git} repository at
@uref{http://repo.or.cz/w/wmaker-crm.git}

If you want to use the @emph{git} versions, you can get it with:
@example
git clone -b next git://repo.or.cz/wmaker-crm.git
@end example
@noindent then, assuming you have the dependencies listed in @ref{Special Dependencies}, you have to
type:
@example
./autogen.sh
@end example
@noindent to generate the configuration script.


@section Build and Install

For a quick start, type the following in your shell prompt:

@example
./configure
make
@end example

@noindent then, login as @emph{root} and type:

@example
make install
ldconfig
@end example

@noindent or if you want to strip the debugging symbols from the binaries to make them smaller,
you can type instead:

@example
make install-strip
ldconfig
@end example

@noindent This will build and install @sc{Window Maker} with default parameters.

If you want to customise some compile-time options, you can do the following:

@enumerate
@item
(optional) Look at the @ref{Configure Options}, for the options available.
Also run:
@example
./configure --help
@end example

to get a complete list of options that are available.

@item
Run configure with the options you want.
For example, if you want to use the @option{--enable-modelock} option, type:
@example
./configure --enable-modelock
@end example

@item
(optional) Edit @file{src/wconfig.h} with your favourite text editor and browse through it for some
options you might want to change.

@item
Compile. Just type:
@example
make
@end example

@item
Login as root (if you can't do that, read the @ref{No Root Password, , I don't have the @emph{root} password})
and install @sc{Window Maker} in your system:
@example
su root
make install
@end example

@end enumerate


@section User specific configuration

These instructions do not need to be followed when upgrading @sc{Window Maker}
from an older version, unless stated differently in the @cite{NEWS} file.

Every user on your system that wishes to run @sc{Window Maker} must do the
following:

@enumerate
@item
Install Window Maker configuration files in your home directory.
Type:
@example
wmaker.inst
@end example

@command{wmaker.inst} will install @sc{Window Maker} configuration files and will
setup X to automatically launch @sc{Window Maker} at startup.

@end enumerate

That's it!

You can type @command{man wmaker} to get some general help for configuration
and other stuff.

Read the @cite{User Guide} for a more in-depth explanation of @sc{Window Maker}.

You might want to take a look at the @cite{FAQ} too.


@section Locales/Internationalisation

@sc{Window Maker} has national language support. The procedure to enable national
language support is described in the dedicated
@ref{Enabling Languages support,,,wmaker_i18n,@file{README.i18n}}.


@section Configure Options
@anchor{Configure Options}

These options can be passed to the configure script to enable/disable
some @sc{Window Maker} features. Example:
@example
./configure --enable-modelock --disable-gif
@end example
will configure @sc{Window Maker} with @emph{modelock} supported and disable @emph{gif} support.
Normally, you won't need any of them.

To get the list of all options, run @command{./configure --help}

@table @option
@item --disable-gif
disable use of @emph{GIF} library

@item --disable-jpeg
disable use of @emph{JPEG} library

@item --disable-png
disables use of @emph{PNG} library

@item --disable-tiff
disable use of @emph{TIFF} library

@item --disable-xpm
disables use of the @emph{XPM} library even if it is available on your system.

@item --with-libs-from
specify additional paths for libraries to be searched.
The @option{-L} flag must precede each path, like:
@example
--with-libs-from="-L/opt/libs -L/usr/local/lib"
@end example

@item --with-incs-from
specify additional paths for header files to be searched.
The @option{-I} flag must precede each paths, like:
@example
--with-incs-from="-I/opt/headers -I/usr/local/include"
@end example

@item --enable-modelock
XKB language status lock support. If you don't know what it is you probably don't need it.

@item --disable-shm
disable use of the MIT shared memory extension. This will slow down
texture generation a little bit, but in some cases it seems to be
necessary due to a bug that manifests as messed icons and textures.

@item --disable-shape
disables shaped windows (for @command{oclock}, @command{xeyes}, etc.)

@item --disable-motif
Disable support for Motif's MWM Window Manager hints.

@end table


@c ------------------------------------------------------------------------------- Miscelleanous ---
@node Miscellaneous
@chapter Miscellaneous

@section Platform Specific Notes

@itemize -
@item @emph{GNU/Linux} in general

Make sure you have @file{/usr/local/lib} in @file{/etc/ld.so.conf} and that you
run @command{ldconfig} after installing.
Uninstall any packaged version of @sc{Window Maker} before installing a new version.

@item @emph{RedHat GNU/Linux}

@emph{RedHat} systems have several annoying problems.
If you use it, be sure to follow the steps below or @sc{Window Maker} will not work:

@itemize
@item
if you installed the @sc{Window Maker} that comes with @emph{RedHat}, uninstall it before upgrading;

@item
make sure you have @file{/usr/local/bin} in your @env{PATH} environment variable;

@item
make sure you have @file{/usr/local/lib} in @file{/etc/ld.so.conf} before running @command{ldconfig};
@end itemize

@item @emph{PowerPC MkLinux}

You will need to have the latest version of @emph{Xpmac}.
Older versions seem to have bugs that cause the system to hang.

@item @emph{Debian GNU/Linux}

If you want @emph{JPEG} and @emph{TIFF} support, make sure you have @file{libtiff-dev}
and @file{libjpeg-dev} installed.

@item @emph{SuSE GNU/Linux}

If you installed the @sc{Window Maker} package from @emph{SuSE}, uninstall it before trying to
compile @emph{Window Maker} or you might have problems.

@item @emph{MetroX} (unknown version)

@emph{MetroX} has a bug that corrupts pixmaps that are set as window backgrounds.
If you use @emph{MetroX} and have weird problems with textures, do not use textures in title bars.
Or use a different X server.

@end itemize


@section I don't have the @emph{root} password :(
@anchor{No Root Password}

If you can't get superuser privileges (can't be @i{root}) you can install @emph{Window Maker} in your own
home directory.
For that, supply the @option{--prefix} option when running configure in step 2 of building
@sc{Window Maker}.
You will also need to supply the @option{--with-gnustepdir} option, to specify the path for
@command{WPrefs.app}.
Example:

@example
./configure --prefix=/home/jshmoe --with-gnustepdir=/home/jshmoe/GNUstep/Applications
@end example

Then make @file{/home/jshmoe/bin} be included in your search @env{PATH}, add @file{/home/jshmoe/lib}
to your @env{LD_LIBRARY_PATH} environment variable and run @command{bin/wmaker.inst}

Of course, @file{/home/jshmoe} is supposed to be replaced by your actual home directory path.


@section Upgrading

If you are upgrading from an older version of @sc{Window Maker}:

@enumerate
@item Configure and build @sc{Window Maker} as always
@item Install @sc{Window Maker} (but do not run @command{wmaker.inst})
@item Read the @cite{NEWS} file and update your configuration files if necessary.
@end enumerate


@c ------------------------------------------------------------------------------- Miscelleanous ---
@node Troubleshooting
@chapter Troubleshooting

When you have some trouble during configuration (while running configure), like not being able to
use a graphic format library you think you have installed, look at the @file{config.log} file for
clues of the problem.


@section Error with loading fonts, even if they exist

This is probably a problem with NLS (Native Language Support), you probably want to look at the
@ref{Troubleshooting,,,wmaker_i18n,@file{README.i18n}}
or try rebuilding without NLS support, which is done with:
@example
./configure LINGUAS=""
@end example


@section configure doesn't detect @emph{libtiff}, or other graphic libraries

Delete @file{config.cache}, then rerun configure adding the following options to @command{configure}
(among the other options you use):
@example
--with-libs-from="-L/usr/local/lib"
--with-incs-from="-I/usr/local/include -I/usr/local/include/tiff"
@end example
Put the paths where your graphic libs and their corresponding header files are located.
You can put multiple paths in any of these options, as the example of @option{--with-incs-from} shows.
Just put a space between them.


@section configure doesn't detect @emph{libXpm}

Check if you have a symbolic link from @file{libXpm.so.4.9} to @file{libXpm.so}


@section Segmentation fault on startup

@itemize
@item Check if the version of @emph{libXPM} you have is at least 4.7

@item Check if you have an updated version of @file{~/GNUstep/Defaults/WindowMaker}
@end itemize

If you're not sure, try renaming @file{~/GNUstep} to @file{~/GNUtmp}
and then run @command{wmaker.inst}


@section "...: your machine is misconfigured. gethostname() returned (none)"

the host name of your machine is set to something invalid, that starts with a parenthesis.
Do a @command{man hostname} for info about how to set it.


@section The root menu contains only 2 entries. ("XTerm" and "Exit...")

@sc{Window Maker} could not read your menu definition file.
You should check the output of @command{wmaker} for an error, it may be visible in the console or in the
@file{.xsession-errors} file.


@c ------------------------------------------------------------------------------------- The End ---
@bye