INSTALL

Installation Instructions
*************************

Dependencies
============

Before building  and installing  this program, you  need at  least the
following libraries:

* Main XCB libraries:
 - xcb-proto (>= 1.6)
 - libxcb (>= 1.8)
 - libxcb-composite
 - libxcb-xfixes
 - libxcb-damage
 - libxcb-image
 - libxcb-render
 - libxcb-randr

* xcb-util libraries:
 - libxcb-aux
 - libxcb-keysyms
 - libxcb-event
 - libxcb-ewmh
 - libxcb-renderutil

* Other libraries and tools:
 - x11proto-core
 - libconfuse
 - libev
 - libxdg-basedir (>= 1.0.0)
 - pkg-config

On Debian-like distribution (require at least testing for Debian), you
can install these libraries by typing the following command as root:

apt-get install xcb-proto libxcb1 libxcb-composite0-dev libxcb-xfixes0-dev \
	libxcb-damage0-dev libxcb-image0-dev libxcb-render0-dev libxcb-aux0-dev \
        libxcb-keysyms1-dev libxcb-event1-dev libxcb-ewmh1-dev \
        libxcb-randr0-dev x11proto-core-dev libxcb-render-util0-dev \
        libconfuse-dev libev-dev libxdg-basedir-dev pkg-config

Also, if you  want to build developer documentation  with Doxygen, you
must  install  doxygen  and  autoconf-archive  (for  Doxygen  autoconf
macro). On Debian-based distribution, you  can install these by typing
the following command as root:

apt-get install doxygen autoconf-archive

Basic Installation
==================

   Briefly,  the  shell  commands  `./configure; make;  make  install'
should  configure, build,  and  install this  package.  The  following
more-detailed  instructions are  generic;  see the  `README' file  for
instructions specific to this package.

   The `configure'  shell script attempts to guess  correct values for
various system-dependent  variables used during  compilation.  It uses
those values to create a  `Makefile' in each directory of the package.
It may also create one  or more `.h' files containing system-dependent
definitions.  Finally, it creates  a shell script `config.status' that
you can run in the future to recreate the current configuration, and a
file  `config.log'  containing  compiler  output  (useful  mainly  for
debugging `configure').

   It can  also use an optional file  (typically called `config.cache'
and  enabled  with `--cache-file=config.cache'  or  simply `-C')  that
saves the results of its  tests to speed up reconfiguring.  Caching is
disabled by default  to prevent problems with accidental  use of stale
cache files.

   If you need to do unusual things to compile the package, please try
to figure out how `configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for  the next release.  If you are  using the cache, and
at some point `config.cache' contains  results you don't want to keep,
you may remove or edit it.

   The  file  `configure.ac' (or  `configure.in')  is  used to  create
`configure' by  a program called `autoconf'.   You need `configure.ac'
if  you want  to change  it or  regenerate `configure'  using  a newer
version of `autoconf'.

The simplest way to compile this package is:

  1. `cd'  to the directory  containing the package's source  code and
     type `./configure' to configure the package for your system.

     Running `configure' might take a while.  While running, it prints
     some messages telling which features it is checking for.

  2. Type `make' to compile the package.

  3. Optionally,  type `make  check' to run  any self-tests  that come
     with the package.

  4. Type  `make install' to install  the programs and  any data files
     and documentation.

  5. You  can remove  the program binaries  and object files  from the
     source code directory by typing `make clean'.  To also remove the
     files that  `configure' created (so  you can compile  the package
     for a different kind  of computer), type `make distclean'.  There
     is also  a `make maintainer-clean'  target, but that  is intended
     mainly for the package's developers.  If you use it, you may have
     to get all  sorts of other programs in  order to regenerate files
     that came with the distribution.

  6. Often, you can also type `make uninstall' to remove the installed
     files again.

Compilers and Options
=====================

   Some  systems require  unusual options  for compilation  or linking
that  the `configure' script  does not  know about.   Run `./configure
--help' for details on some of the pertinent environment variables.

   You   can  give  `configure'   initial  values   for  configuration
parameters  by  setting  variables  in  the command  line  or  in  the
environment.  Here is an example:

     ./configure CC=c99 CFLAGS=-g LIBS=-lposix

   *Note Defining Variables::, for more details.

Compiling For Multiple Architectures
====================================

   You can compile  the package for more than one  kind of computer at
the same  time, by placing the  object files for  each architecture in
their own directory.  To do this, you can use GNU `make'.  `cd' to the
directory where  you want the object  files and executables  to go and
run the `configure' script.   `configure' automatically checks for the
source code in the directory that `configure' is in and in `..'.

   With a non-GNU  `make', it is safer to compile  the package for one
architecture at a  time in the source code  directory.  After you have
installed  the  package for  one  architecture,  use `make  distclean'
before reconfiguring for another architecture.

   On MacOS  X 10.5  and later systems,  you can create  libraries and
executables  that work  on multiple  system types--known  as  "fat" or
"universal"  binaries--by specifying multiple  `-arch' options  to the
compiler but only  a single `-arch' option to  the preprocessor.  Like
this:

     ./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
                 CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
                 CPP="gcc -E" CXXCPP="g++ -E"

   This is not guaranteed to  produce working output in all cases, you
may have to  build one architecture at a time  and combine the results
using the `lipo' tool if you have problems.

Installation Names
==================

   By default,  `make install'  installs the package's  commands under
`/usr/local/bin', include files  under `/usr/local/include', etc.  You
can specify  an installation prefix other than  `/usr/local' by giving
`configure' the option `--prefix=PREFIX'.

   You    can    specify    separate   installation    prefixes    for
architecture-specific  files and  architecture-independent  files.  If
you pass the option `--exec-prefix=PREFIX' to `configure', the package
uses  PREFIX as  the  prefix for  installing  programs and  libraries.
Documentation and other data files still use the regular prefix.

   In addition,  if you use an  unusual directory layout  you can give
options like `--bindir=DIR' to specify different values for particular
kinds of files.  Run `configure  --help' for a list of the directories
you can set and what kinds of files go in them.

   If the package supports it,  you can cause programs to be installed
with an  extra prefix or suffix  on their names  by giving `configure'
the option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.

Optional Features
=================

   Some  packages  pay  attention  to  `--enable-FEATURE'  options  to
`configure', where FEATURE indicates  an optional part of the package.
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
is  something like `gnu-as'  or `x'  (for the  X Window  System).  The
`README' should mention any `--enable-' and `--with-' options that the
package recognizes.

   For packages that use the  X Window System, `configure' can usually
find the X include and library files automatically, but if it doesn't,
you   can   use  the   `configure'   options  `--x-includes=DIR'   and
`--x-libraries=DIR' to specify their locations.

Particular systems
==================

   On HP-UX, the default C compiler  is not ANSI C compatible.  If GNU
CC is not installed, it is recommended to use the following options in
order to use an ANSI C compiler:

     ./configure CC="cc -Ae"

and if that doesn't work, install pre-built binaries of GCC for HP-UX.

   On  OSF/1 a.k.a.  Tru64, some  versions of  the default  C compiler
cannot parse its `<wchar.h>' header  file.  The option `-nodtk' can be
used as  a workaround.  If  GNU CC is  not installed, it  is therefore
recommended to try

     ./configure CC="cc"

and if that doesn't work, try

     ./configure CC="cc -nodtk"

Specifying the System Type
==========================

   There  may   be  some   features  `configure'  cannot   figure  out
automatically,  but needs  to determine  by  the type  of machine  the
package will run on.  Usually, assuming the package is built to be run
on the _same_  architectures, `configure' can figure that  out, but if
it prints a  message saying it cannot guess the  machine type, give it
the `--build=TYPE'  option.  TYPE can either  be a short  name for the
system type, such as `sun4', or a canonical name which has the form:

     CPU-COMPANY-SYSTEM

where SYSTEM can have one of these forms:

     OS KERNEL-OS

   See the  file `config.sub' for  the possible values of  each field.
If  `config.sub' isn't  included in  this package,  then  this package
doesn't need to know the machine type.

   If  you  are _building_  compiler  tools  for cross-compiling,  you
should use  the option  `--target=TYPE' to select  the type  of system
they will produce code for.

   If you  want to _use_ a  cross compiler, that generates  code for a
platform  different from the  build platform,  you should  specify the
"host"  platform (i.e.,  that  on which  the  generated programs  will
eventually be run) with `--host=TYPE'.

Sharing Defaults
================

   If you want to set default values for `configure' scripts to share,
you can  create a  site shell script  called `config.site'  that gives
default values  for variables  like `CC', `cache_file',  and `prefix'.
`configure'  looks for `PREFIX/share/config.site'  if it  exists, then
`PREFIX/etc/config.site'  if   it  exists.    Or,  you  can   set  the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.

Defining Variables
==================

   Variables not  defined in  a site  shell script can  be set  in the
environment  passed to  `configure'.  However,  some packages  may run
configure again during  the build, and the customized  values of these
variables may be lost.  In order to avoid this problem, you should set
them in the `configure' command line, using `VAR=value'.  For example:

     ./configure CC=/usr/local2/bin/gcc

causes the specified `gcc' to be  used as the C compiler (unless it is
overridden in the site shell script).

Unfortunately, this technique does  not work for `CONFIG_SHELL' due to
an Autoconf bug.  Until the bug is fixed you can use this workaround:

     CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash

`configure' Invocation
======================

   `configure' recognizes the following options to control how it
operates.

`--help'
`-h'
     Print a summary of all of the options to `configure', and exit.

`--help=short'
`--help=recursive'
     Print a summary of the options unique to this package's
     `configure', and exit.  The `short' variant lists options used
     only in the top level, while the `recursive' variant lists options
     also present in any nested packages.

`--version'
`-V'
     Print the version of Autoconf used to generate the `configure'
     script, and exit.

`--cache-file=FILE'
     Enable the cache: use and save the results of the tests in FILE,
     traditionally `config.cache'.  FILE defaults to `/dev/null' to
     disable caching.

`--config-cache'
`-C'
     Alias for `--cache-file=config.cache'.

`--quiet'
`--silent'
`-q'
     Do not print messages saying which checks are being made.  To
     suppress all normal output, redirect it to `/dev/null' (any error
     messages will still be shown).

`--srcdir=DIR'
     Look for the package's source code in directory DIR.  Usually
     `configure' can determine that directory automatically.

`--prefix=DIR'
     Use DIR as the installation prefix.  *Note Installation Names::
     for more details, including other options available for fine-tuning
     the installation locations.

`--no-create'
`-n'
     Run the configure checks, but stop before creating any output
     files.

`configure' also accepts some other, not widely useful, options.  Run
`configure --help' for more details.