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
@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)
@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{autoconf}, @emph{automake} and @emph{libtool}
@itemize
@item autoconf 2.54
@item automake 1.4
@item libtool 1.4.2
@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}).

@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 those that I have (and therefore, guaranteed to work), but
other versions might work too.

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

Older versions may not work!

Available at @uref{ftp://sunsite.unc.edu/pub/Linux/libs/X/}

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.cdrom.com/pub/png/}

@item @emph{libtiff} 3.4 or newer

For @emph{TIFF} image support,
You can get it at @uref{ftp://ftp.sgi.com/graphics/tiff}

@item @emph{libjpeg} 6.0.1 or newer

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

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

For @emph{GIF} image support,
@uref{ftp://prtr-13.ucsc.edu/pub/libungif/}

@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{ftp://ftp.gnu.org}

@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 found in the git repository at
@uref{http://repo.or.cz/w/wmaker-crm.git}

If you downloaded the git versions, type
@example
./autogen.sh
@end example
@noindent to generate the config files.


@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 and make them
smaller, you can instead type:

@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 listing of other 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 a list of other 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 don't have the @env{LANG} and @env{LINGUAS} environment variables set to @code{en_RN};

@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{wmaker} 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 has weird problems with textures, do not use textures in title bars.
Or use a different X server.

@end itemize


@section Installing the extras package

Unpack @file{WindowMaker-extra-@emph{<version-number>}.tar.gz} in @file{/usr/local/share}

You can get the file at @uref{http://windowmaker.org/pub/source/release/}.
This file is optional and only have a few icons, and themes.
Look for the latest @emph{<version-number>} available.
Also there is a @file{WindowMaker-extra.readme} to instruct you where that package should go.


@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{wmaker} 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 with 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

Try rebuilding without NLS support.


@section Error when configuring

@example
ltconfig: unrecognized option `--no-reexec'
Try `ltconfig --help' for more information.
configure: error: libtool configure failed
@end example

remove the @option{--no-reexec} option from @file{aclocal.m4} and reconfigure.
Also make sure the @emph{autoconf} and @emph{automake} versions you have installed are:
@itemize
@item @emph{autoconf} 2.13
@item @emph{automake} 1.4
@item @emph{libtool} 1.3
@end itemize

Note that it must not be @emph{libtool} 1.2b, it must be @emph{libtool} 1.3, from the GNU sites.


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


@section checking lex output file root... configure: error: cannot find output from true; giving up

Read the @ref{Software Dependencies}.


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