Documenting crosstool's variables

["Martin Guy" <martinwguy at gmail dot com>]

Hi all
  In my efforts to grok crosstool I've written a beginners' document
outlining what crosstool does and the variables that can be set in
.dat files and what they do, as far as I could understand.
  It's visible on the net at
http://freaknet.org/martin/doc/crosstool-vars.html and I've copied the
text in here so it's easier to comment here and tell me where I could
improve it. Please don't quote the whole thing in any replies though!
Trim trim!

Bless

     M

----8<---cut here-----

Crosstool variables
in crosstool-0.42
last updated 14 April 2006

Abstract

This document explains what crosstool's user-tweakable variables mean,
where they should be set, and what effect they have. To understand
this, you first need a brief overview of the what crosstool does to
build a crosscompiler, and the order in which it does it.

Script hierarchy

Naive users normally only run the demo-*.sh scripts, which call the
other scripts to do everything necessary to build and install a
working crosscompiler.

Semi-naive users (like me!) modify their own copies of the demo
scripts, and tweak the variables in the .dat files that are used by
the demo scripts.

Advanced users call crosstool.sh and the other scripts directly. This
document is not meant for them; instead it concentrates on the way
things happen when using the demo scripts.

Each demo-*.sh script reads in a

    * cpu.dat
    * gcc-glibc-combination.dat to set variables, then calls
    * all.sh, which does the work by calling
          o getandpatch.sh to download, unpack and patch the sources;
          o crosstool.sh or crosstool-cygwin.sh to make a cross
compiler out of them;
          o testhello.sh to try and compile "Hello world" with it
      and optionally some combination of the following:
          o gdb.sh to build gdb for it;
          o testlinux.sh to try and compile the kernel with it;
          o ptx.sh to build the ptxdist userland with it;
          o crosstest.sh to run the compiler's test suite.
      The first three optional items are enabled by flags to all.sh,
specifically --gdb, --testlinux and --builduserland, while running the
test suite is disabled by specifying --notest.

The order things happen in

      getandpatch.sh does the following:
          o Fetch, unpack and patch gdb source if GDB_DIR was specified
          o Fetch, unpack and patch binutils source
          o Fetch, unpack and patch gcc source
          o Fetch, unpack and patch gcc_core source if GCC_CORE_DIR
was specified and is different from GCC_DIR
          o Fetch, unpack and patch the linux kernel source if specified
          o Fetch, unpack and patch the sanitized linux kernel headers
if they were specified (see below)
      crosstool.sh does the following:
          o Build cross binutils
          o Build gcc-core using the system C compiler
          o Cross-build glibc using gcc-core
          o Cross-build final gcc
          o Finalize details of the the installation with the help of
extra scripts masq.sh and mkoverride.sh

What is gcc_core?

      It is the version of gcc which is used to compile glibc. It may
be a different version from the main version of gcc that will be built
as a full-feature cross compiler.

      If it is specified, it will normally be an older version than
the main gcc. This is sometimes necessary when you are building a
recent gcc that can generate code for your architecture, but which is
not yet able to build glibc for your architecture. In practice there
can be a long lead time between new gcc versions coming out and them
being able to build all of glibc for all architectures, since building
glibc uses just about every feature imaginable of the C compiler.

The variables

      Almost all communication is done between the scripts by means of
environment variables. We'll start from those set in the top-level
demo scripts and work our way down.

In demo-*.sh

      There are dozens of these scripts, one to create a crosscompiler
that will generate code for each supported cpu variant.
      These are called directly from the command line with no
parameters and set:

      TARBALLS_DIR (optional)
          Full pathname to a cache directory into which to downloaded
source tarballs, typically $HOME/downloads.
          Default: crosstool-dir/tarballs
      RESULT_TOP (optional)
          Full pathname of directory in which to place the final
crosscompiler tree that will be generated, typically /opt/crosstool
          Default: crosstool-dir/result
      GCC_LANGUAGES (optional)
          Which languages to generate crosscompilers for.
          Default: GCC_LANGUAGES=c,c++
      PARALLELMFLAGS (optional)
          Flags to pass to all invocations of make to enable the
parallel-build feature, typically -j2 on single processor systems,
-jN+1 on N-processor systems, or -j2N on N-machine single-processor
clusters with distcc
      GLIBC_ADDON_LINUXTHREADS (optional)
          If the linuxthreads addon to glibc should be included for
this variant, set this "=1", otherwise leave it out.

      then add the variables defined in cpu.dat and gcc-glibc.dat and
call all.sh

In cpu.dat

      Examples: arm.dat, mips.dat, powerpc-750.dat

      These specify:

      KERNELCONFIG
          Full pathname of the .config file to use to configure the
Linux kernel, typically `pwd`/cpu.config
      TARGET
          GCC 4-part name for the architecture that the generated
crosscompiler will generate code for. Example: sparc-unknown-linux-gnu
      TARGET_CFLAGS
          Flags to pass to GCC when building glibc for the target
architecture, typically -O. This might seem optional but must
currently be set to something of non-zero length.
      GCC_EXTRA_CONFIG
          Extra options to pass to gcc's "configure" script, used with
both the gcc_core compiler and the main compiler.
          Example: GCC_EXTRA_CONFIG="--with-cpu=pentium3 --with-arch=pentium3"
          Example: GCC_EXTRA_CONFIG=--with-float=soft
          Example: GCC_EXTRA_CONFIG=--disable-multilib
          Example: GCC_EXTRA_CONFIG=--multilib-list=m4,m4-nofpu
      USE_SYSROOT (optional)
          If this is set "=1", then, in crosstool's build directory,
instead of putting libraries in target/{include,lib}, they will be
spread between target/sys-root/{usr/include,lib,usr/lib} mimicking the
structure of a regular linux filesystem.
          The reason for wanting this is not clear to me.

In gcc-glibc.dat

      Examples: gcc-2.95.3-glibc-2.2.5.dat, gcc-4.0.2-glibc-2.3.6-tls.dat

      These specify the combination of gcc and glibc versions to use,
as well as variants such as inclusion of the optional "thread local
storage" feature. They set:

      BINUTILS_DIR
          The version of binutils to use. Example: BINUTILS_DIR=binutils-2.16.1
      GCC_DIR
          The version of GCC to build as a crosscompiler. Example:
GCC_DIR=gcc-4.1.0
      GCC_CORE_DIR (optional)
          The version of GCC that crosstool will use to build glibc.
If it is unset, the same version will be used as specified in GCC_DIR.
      LINUX_DIR (optional if LINUX_SANITIZED_HEADER_DIR is given)
          The version of the Linux kernel to use as header files for
glibc if LINUX_SANITIZED_HEADER_DIR is not set. This is also the
version of the kernel to try and build with the crosscompiler if that
test is enabled with all.sh --testlinux).
          Example: LINUX_DIR=linux-2.6.16
      LINUX_SANITIZED_HEADER_DIR (optional if LINUX_DIR is given))
          The version of the Linux kernel header files to use when
building glibc. For some old versions of linux, the headers are too
confusing for glibc to understand them, so "sanitized" versions are
provided at http://ep09.pld-linux.org/~mmazur/linux-libc-headers and
ftp://ftp.lfs-matrix.net/pub/linux-libc-headers
          If unset, the headers from LINUX_DIR are used.
          Example: LINUX_SANITIZED_HEADER_DIR=linux-libc-headers-2.6.12.0
      GLIBC_DIR
          The version of gilbc to build as a cross-library to be used
with the cross-compiler.
          Example: GLIBC_DIR=glibc-2.3.6
      GLIBCTHREADS_FILENAME (optional)
          If set, the version of the linuxthreads addon to be added on to glibc.
          This might seem an obvious derivative of the glibc version,
but when using a snapshot version of glibc, it can be useful to
specify a version of linuxthreads that is applicable to it.
          Example: GLIBCTHREADS_FILENAME=glibc-linuxthreads-2.3.6
      GLIBCCRYPT_FILENAME (optional>
          If set, the version of the crypt addon to use with glibc.
This is only used with very old versions of glibc, when data
encryption was considered "military technology" in the USA and subject
to export restrictions.
          Example: GLIBCCRYPT_FILENAME=glibc-crypt-2.1
      GLIBC_EXTRA_CONFIG
          Extra flags to pass to glibc's configure script.
          Example: GLIBC_EXTRA_CONFIG="--without-fp" if the target
system does not support floating point math.
      GLIBC_EXTRA_CC_ARGS
          "Extra flags to pass to gcc when building glibc". This is
implemented but unused, and the same function seems to be provided by
EXTRA_TARGET_CFLAGS. It seems to be oxbow code.
      EXTRA_TARGET_CFLAGS (optional)
          More flags to pass to GCC when building glibc for the target
architecture.
          This is logically the same as TARGET_CFLAGS, but is a
separate variable so that one can be given in the cpu.dat file and the
other in the gcc-glibc file.
      GDB_DIR (optional)
          The version of gdb to try and build for the crosscompiler.
          Example: GDB_DIR=gdb-6.4

      If crosstool is to build a cross compiler to make binaries that
run under CygWin (an environment emulating Unix under MSWindows), the
following variables are used instead of all the LINUX* and GLIBC*
ones.

      CYGWIN_DIR
          The version of cygwin to target.
          Example: CYGWIN_DIR=cygwin-1.5.15-1
      CYGWIN_URL
          Where to get that version of cygwin from.
          Example:
CYGWIN_URL=ftp://mirrors.rcn.net/pub/sourceware/cygwin/release/cygwin

More variables understood by crosstool.sh

      The following variables are not used in the demo scripts, but
are understood by crosstool.sh

      GCC_BUILD
          The gcc architecture name for the architecture that the
cross compiler is being built on. By default, it is set to the output
of the GNU "config.guess" script included in the crosstool
distribution, which generates code suitable for running on the same
host.
      GCC_HOST
          The gcc architecture name for the architecture that the
cross compiler will be built to run on. This is used in "Canadian
cross" builds, where a cross compiler is built that will run on a
different architecture than the one doing the building. To use this
feature you must also set CC and AR to the names of cross-compiling
versions of those commands.
          Default: the same as GCC_BUILD
      SHARED_MODE
          Shared library enabling flag to pass to glibc and to final
gcc's configure scripts.
          Default: SHARED_MODE=--enable-shared
          I assume that the alternative is --disable-shared to make a
system with just the statically-linked libraries.

      Footnote
      oxbow code, n.: Code that used to be useful but which can now
never be reached. From "oxbow lakes", which are formed in nature when
a bend in a river becomes so pronounced that the water breaks through
from before the bend to after it, making the river straight again.
When the sides of the new course silt up, a curved lake is left,
disconnected from the main stream. As in nature, so in code :)
------------------------------

--
For unsubscribe information see http://sourceware.org/lists.html#faq