Configuring Crosser.sh & dllstack.sh
=====================================

Both dllstack.sh and crosser.sh can be configured with files named
/etc/crosser.conf, local_setup.conf in main crosser directory (same directory
where dllstack.sh and crosser.sh scripts are), .crosser.conf under home
directory or by file specified by environment variable CROSSER_CONF.
First it reads global configuration from /etc/crosser.conf if present.
In addition to that it tries to read one local configuration file in
following order:
If CROSSER_CONF environment variable is defined, crosser.sh and dllstack.sh
try to read it and fail if they cannot. If environment variable is not defined,
they first look for local_setup.conf, and if it's missing load ~/.crosser.conf
instead.

This file lists some of the variables one can place to configuration file

Entries are of form:
VARIABLE=VALUE

Before configuration is read, variable $CROSSER_MAINDIR has been set.
It contains path to the directory where file CrosserVersion is. This is
either where full crosser packet is unpacked or, lacking such location,
/usr/share/crosser.
E.g. to set log directory under that main dir one would use
CROSSER_LOGDIR="$CROSSER_MAINDIR/log"

Also variable $CROSSER_TMPDIR is already set to its default value
before configuration is read, so it can be used in setting other
variables.

=======================================================================

AUTOWINE
 ; If this has value "yes", dllstack.sh uses wine to run some
 ; gtk+ configuration programs. Do not define this if wine is not available
 ; and automatically usable.
 ; These configuration programs must be run when doing actual install to
 ; Windows machine.

CROSSER_DST_PFX
 ; Directory hierarchy where generated environment will be installed.
 ; For dllstack this can be overridden by DLLSPREFIX. 
 ; This directory will be completely removed in the beginning of build.
 ; This path is parsed:
 ;   - <TARGET>     -> Target architecture
 ;   - <DATE>       -> Build start date. Note that build may take long time and
 ;                     often start date is not same as current date of some build
 ;                     action.
 ;   - <CLIB>       -> libc to use
 ;   - <VERSION>    -> crosser version
 ;   - <VERSIONSET> -> Versionset used 
 ; Either enclose value inside quotes or escape tags like \<TARGET\>
 ; Default is:
 ;   crosser.sh, cross-compiling environment:
 ;      $HOME/.crosser/<VERSION>/<VERSIONSET>/<TARGET>-<CLIB>
 ;   crosser.sh, native chain:
 ;      $HOME/.crosser/<VERSION>/<VERSIONSET>/native

NATIVE_PREFIX
 ; Directory hierarchy where native environment generated in native-step
 ; will be installed. This affects only crosser.sh, not libtstack.sh at all.
 ; Path parsing is similar to that of PREFIX.
 ; Default is $HOME/.crosser/<VERSION>/<VERSIONSET>/host

DLLSPREFIX
 ; Directory hierarchy where generated dllstack environment will be installed.
 ; Default is PREFIX, if it's set.
 ; Otherwise $HOME/.crosser/<VERSION>/<VERSIONSET>/winstack
 ;
 ; In future versions of crosser, PREFIX will not be the default even if it's set.

DLLSHOST_PREFIX
 ; Directory hierarchy where native environment generated by dllstack.sh
 ; will be installed.
 ; Path parsing is similar to that of PREFIX.
 ; Default is $HOME/.crosser/<VERSION>/<VERSIONSET>/dllshost

LOGLEVEL_STDOUT
LOGLEVEL_FILE
 ; Level of logging to screen and to file. Values can be from
 ; 1 (Fatal errors only) to 5 (debug logging).
 ; Defaults are 2 for screen and 4 for file.

CROSSER_FORCE
 ; If this is set to 'yes', scripts will not provide confirmation prompts
 ; when deleting old directories. It's recommended that this is never
 ; used in local_setup.conf and set as environment variable before running 
 ; script only when setup has been already tested and one really knows
 ; that nothing important will be destroyed.

CROSSER_TMPDIR
 ; Default directory for temporary files. With more specific options
 ; you can change CROSSER_SRCDIR and CROSSER_BUILDDIR individually.
 ; Note that this directory is not emptied in the end but left to the
 ; state is was when build finished/failed for debugging build problems
 ; and the like.
 ; If you want to support running multiple crosser instances for several
 ; targets or versionsets simultaneously, you may set this as
 ; CROSSER_TMPDIR="$(tempfile)"
 ; Unlike with most configuration variables, default value for 
 ; CROSSER_TMPDIR is already set before configuration file is read.
 ; Default is /tmp/crosser

CROSSER_SRCDIR
 ; Directory hierarchy where sources will be unpacked.
 ; Default is $CROSSER_TMPDIR/src

CROSSER_BUILDDIR
 ; Directory hierarchy where binaries will be built
 ; Default is $CROSSER_TMPDIR/build

CROSSER_LOGDIR
 ; Directory where logfiles will be written.
 ; Default is $HOME/.crosser/log
 ; Logfiles stdout.log and stderr are created anew for each build,
 ; main.log is rotated once it reaches 250000 bytes.

CROSSER_TMPFREE
 ; If this variable is set to value "yes", dllstack.sh will
 ; aggressively delete anything from temp directories as soon as
 ; it no longer needs it.

PACKETDIR
 ; Directory for storing source packets.
 ; Default is $HOME/.crosser/packets

CROSSER_DOWNLOAD
 ; This defines packet download model. Packets are ever downloaded only
 ; if they are missing, but time their existence is checked depends on
 ; this setting. Actual implementation is not yet too sophisticated.
 ; Even with "on demand" setting quite a lot of stuff is downloaded
 ; in the beginning. Default is "demand".
 ;   "yes"           - crosser.sh / dllstack.sh download all required
 ;                     packets in the beginning.
 ;   "demand"        - On demand; download just when packet is really
 ;                     needed. This setting has advantage that not time
 ;                     and resources are wasted to downloading if
 ;                     compilation of some earlier component fails.
 ;   any other value - Assume that packets are already downloaded.
 ;                     Fail if not.
 ; Options other than "demand" have advantage that time is not wasted
 ; on compiling earlier packets in case some packet cannot be downloaded.

CROSSER_CCACHE
 ; Path to directory containing links to ccache. If this varaible is set,
 ; crosser will always put that directory first in its PATH so ccache
 ; will be used. Crosser will not use user's normal ccache dir, but
 ; will create new one depending on what step is being built. This avoids
 ; trashing user's main cache by possibly results specific to certain
 ; crosser build, which may be very temporary.
 ;
 ; Example setup of ccache path directory:
 ;   > mkdir /usr/local/ccache
 ;   > cd /usr/local/ccache
 ;   > ln -s /usr/bin/ccache gcc
 ;   > ln -s /usr/bin/ccache g++
 ;   > ln -s /usr/bin/ccache cc
 ;   > ln -s /usr/bin/ccache i586-mingw32msvc-gcc
 ;   > ln -s /usr/bin/ccache i586-mingw32msvc-g++
 ;   > ln -s /usr/bin/ccache i586-mingw32msvc-cc
 ;   > ln -s /usr/bin/ccache x86_64-linux-gnu-gcc
 ;   > ln -s /usr/bin/ccache x86_64-linux-gnu-g++
 ;   > ln -s /usr/bin/ccache x86_64-linux-gnu-cc
 ;   > ln -s /usr/bin/ccache i386-linux-gnu-gcc
 ;   > ln -s /usr/bin/ccache i386-linux-gnu-g++
 ;   > ln -s /usr/bin/ccache i386-linux-gnu-cc
 ;   > ln -s /usr/bin/ccache arm-linux-gnu-gcc
 ;   > ln -s /usr/bin/ccache arm-linux-gnu-g++
 ;   > ln -s /usr/bin/ccache arm-linux-gnu-cc
 ;   > export CROSSER_CCACHE="/usr/local/ccache"

CROSSER_GROUP
 ; If set, some files crosser produces are set owned by that user group.
 ; Currently this applies to downloaded source packets.

CROSSER_DEBUG
 ; If set to 'yes', support for logging crosser internal errors and
 ; generating reports about crosser behavior is enabled. This is usefull
 ; only when developing crosser itself.

=======================================================================

local_setup.conf is actually shell script fragment. Here are some things
one may want to do in it in addition to setting variables.

renice 15 $$
 ; Crosser build takes very long time. If you want to do something
 ; else with the computer meanwhile, you may want to make crosser low
 ; priority. That makes other tasks to run faster and crosser to use just
 ; those CPU cycles left over. Above command makes current script
 ; (crosser.sh itself) to run at nice level 15.
