File.........: 8 - Internals.txt
Copyright....: (C) 2010 Yann E. MORIN <yann.morin.1998@free.fr>
License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5


Internals  /
__________/


Internally, crosstool-NG is script-based. To ease usage, the frontend is
Makefile-based.


Makefile front-end |
-------------------+

The entry point to crosstool-NG is the Makefile script "ct-ng". Calling this
script with an action will act exactly as if the Makefile was in the current
working directory and make was called with the action as rule. Thus:
  ct-ng menuconfig

is equivalent to having the Makefile in CWD, and calling:
  make menuconfig

Having ct-ng as it is avoids copying the Makefile everywhere, and acts as a
traditional command.

ct-ng loads sub- Makefiles from the library directory $(CT_LIB_DIR), as set up
at configuration time with ./configure.

ct-ng also searches for config files, sub-tools, samples, scripts and patches in
that library directory.

Because of a stupid make behavior/bug I was unable to track down, implicit make
rules are disabled: installing with --local would trigger those rules, and mconf
was unbuildable.


Kconfig parser |
---------------+

The kconfig language is a hacked version, vampirised from the Linux kernel
(http://www.kernel.org/), and (heavily) adapted to my needs.

The list of the most notable changes (at least the ones I remember) follows:
- the CONFIG_ prefix has been replaced with CT_
- a leading | in prompts is skipped, and subsequent leading spaces are not
  trimmed; otherwise leading spaces are silently trimmed
- removed the warning about undefined environment variable

The kconfig parsers (conf and mconf) are not installed pre-built, but as
source files. Thus you can have the directory where crosstool-NG is installed,
exported (via NFS or whatever) and have clients with different architectures
use the same crosstool-NG installation, and most notably, the same set of
patches.


Architecture-specific |
----------------------+

Note: this chapter is not really well written, and might thus be a little bit
complex to understand. To get a better grasp of what an architecture is, the
reader is kindly encouraged to look at the "arch/" sub-directory, and to the
existing architectures to see how things are laid out.

An architecture is defined by:

 - a human-readable name, in lower case letters, with numbers as appropriate.
   The underscore is allowed; space and special characters are not.
     Eg.: arm, x86_64
 - a file in "config/arch/", named after the architecture's name, and suffixed
   with ".in".
     Eg.: config/arch/arm.in
 - a file in "scripts/build/arch/", named after the architecture's name, and
   suffixed with ".sh".
     Eg.: scripts/build/arch/arm.sh

The architecture's ".in" file API:
 > the config option "ARCH_%arch%" (where %arch% is to be replaced with the
   actual architecture name).
   That config option must have *neither* a type, *nor* a prompt! Also, it can
   *not* depend on any other config option (EXPERIMENTAL is managed as above).
     Eg.:
       config ARCH_arm
   + mandatory:
       defines a (terse) help entry for this architecture:
       Eg.:
         config ARCH_arm
           help
             The ARM architecture.
   + optional:
       selects adequate associated config options.
       Note: 64-bit architectures *shall* select ARCH_64
       Eg.:
         config ARCH_arm
           select ARCH_SUPPORTS_BOTH_ENDIAN
           select ARCH_DEFAULT_LE
           help
             The ARM architecture.
       Eg.:
         config ARCH_x86_64
            select ARCH_64
            help
              The x86_64 architecture.

 > other target-specific options, at your discretion. Note however that to
   avoid name-clashing, such options shall be prefixed with "ARCH_%arch%",
   where %arch% is again replaced by the actual architecture name.
   (Note: due to historical reasons, and lack of time to clean up the code,
    I may have left some config options that do not completely conform to
    this, as the architecture name was written all upper case. However, the
    prefix is unique among architectures, and does not cause harm).

The architecture's ".sh" file API:
 > the function "CT_DoArchTupleValues"
   + parameters: none
   + environment:
     - all variables from the ".config" file,
     - the two variables "target_endian_eb" and "target_endian_el" which are
       the endianness suffixes
   + return value: 0 upon success, !0 upon failure
   + provides:
     - mandatory
     - the environment variable CT_TARGET_ARCH
     - contains:
       the architecture part of the target tuple.
       Eg.: "armeb" for big endian ARM
            "i386" for an i386
   + provides:
     - optional
     - the environment variable CT_TARGET_SYS
     - contains:
       the system part of the target tuple.
       Eg.: "gnu" for glibc on most architectures
            "gnueabi" for glibc on an ARM EABI
     - defaults to:
       - for glibc-based toolchain: "gnu"
       - for uClibc-based toolchain: "uclibc"
   + provides:
     - optional
     - the environment variables to configure the cross-gcc (defaults)
       - CT_ARCH_WITH_ARCH    : the gcc ./configure switch to select architecture level         ( "--with-arch=${CT_ARCH_ARCH}"   )
       - CT_ARCH_WITH_ABI     : the gcc ./configure switch to select ABI level                  ( "--with-abi=${CT_ARCH_ABI}"     )
       - CT_ARCH_WITH_CPU     : the gcc ./configure switch to select CPU instruction set        ( "--with-cpu=${CT_ARCH_CPU}"     )
       - CT_ARCH_WITH_TUNE    : the gcc ./configure switch to select scheduling                 ( "--with-tune=${CT_ARCH_TUNE}"   )
       - CT_ARCH_WITH_FPU     : the gcc ./configure switch to select FPU type                   ( "--with-fpu=${CT_ARCH_FPU}"     )
       - CT_ARCH_WITH_FLOAT   : the gcc ./configure switch to select floating point arithmetics ( "--with-float=soft" or /empty/  )
   + provides:
     - optional
     - the environment variables to pass to the cross-gcc to build target binaries (defaults)
       - CT_ARCH_ARCH_CFLAG   : the gcc switch to select architecture level                     ( "-march=${CT_ARCH_ARCH}"            )
       - CT_ARCH_ABI_CFLAG    : the gcc switch to select ABI level                              ( "-mabi=${CT_ARCH_ABI}"              )
       - CT_ARCH_CPU_CFLAG    : the gcc switch to select CPU instruction set                    ( "-mcpu=${CT_ARCH_CPU}"              )
       - CT_ARCH_TUNE_CFLAG   : the gcc switch to select scheduling                             ( "-mtune=${CT_ARCH_TUNE}"            )
       - CT_ARCH_FPU_CFLAG    : the gcc switch to select FPU type                               ( "-mfpu=${CT_ARCH_FPU}"              )
       - CT_ARCH_FLOAT_CFLAG  : the gcc switch to choose floating point arithmetics             ( "-msoft-float" or /empty/           )
       - CT_ARCH_ENDIAN_CFLAG : the gcc switch to choose big or little endian                   ( "-mbig-endian" or "-mlittle-endian" )
     - default to:
       see above.
   + provides:
     - optional
     - the environment variables to configure the core and final compiler, specific to this architecture:
       - CT_ARCH_CC_CORE_EXTRA_CONFIG   : additional, architecture specific core gcc ./configure flags
       - CT_ARCH_CC_EXTRA_CONFIG        : additional, architecture specific final gcc ./configure flags
     - default to:
       - all empty
   + provides:
     - optional
     - the architecture-specific CFLAGS and LDFLAGS:
       - CT_ARCH_TARGET_CLFAGS
       - CT_ARCH_TARGET_LDFLAGS
     - default to:
       - all empty

You can have a look at "config/arch/arm.in" and "scripts/build/arch/arm.sh" for
a quite complete example of what an actual architecture description looks like.


Kernel specific |
----------------+

A kernel is defined by:

 - a human-readable name, in lower case letters, with numbers as appropriate.
   The underscore is allowed; space and special characters are not (although
   they are internally replaced with underscores.
     Eg.: linux, bare-metal
 - a file in "config/kernel/", named after the kernel name, and suffixed with
   ".in".
     Eg.: config/kernel/linux.in, config/kernel/bare-metal.in
 - a file in "scripts/build/kernel/", named after the kernel name, and suffixed
   with ".sh".
     Eg.: scripts/build/kernel/linux.sh, scripts/build/kernel/bare-metal.sh

The kernel's ".in" file must contain:
 > an optional lines containing exactly "# EXPERIMENTAL", starting on the
   first column, and without any following space or other character.
   If this line is present, then this kernel is considered EXPERIMENTAL,
   and correct dependency on EXPERIMENTAL will be set.

 > the config option "KERNEL_%kernel_name%" (where %kernel_name% is to be
   replaced with the actual kernel name, with all special characters and
   spaces replaced by underscores).
   That config option must have *neither* a type, *nor* a prompt! Also, it can
   *not* depends on EXPERIMENTAL.
     Eg.: KERNEL_linux, KERNEL_bare_metal
   + mandatory:
       defines a (terse) help entry for this kernel.
       Eg.:
         config KERNEL_bare_metal
           help
             Build a compiler for use without any kernel.
   + optional:
       selects adequate associated config options.
       Eg.:
         config KERNEL_bare_metal
           select BARE_METAL
           help
             Build a compiler for use without any kernel.

 > other kernel specific options, at your discretion. Note however that, to
   avoid name-clashing, such options should be prefixed with
   "KERNEL_%kernel_name%", where %kernel_name% is again tp be replaced with
   the actual kernel name.
   (Note: due to historical reasons, and lack of time to clean up the code,
    I may have left some config options that do not completely conform to
    this, as the kernel name was written all upper case. However, the prefix
    is unique among kernels, and does not cause harm).

The kernel's ".sh" file API:
 > is a bash script fragment

 > defines the function CT_DoKernelTupleValues
   + see the architecture's CT_DoArchTupleValues, except for:
   + set the environment variable CT_TARGET_KERNEL, the kernel part of the
     target tuple
   + return value: ignored

 > defines the function "do_kernel_get":
   + parameters: none
   + environment:
      - all variables from the ".config" file.
   + return value: 0 for success, !0 for failure.
   + behavior: download the kernel's sources, and store the tarball into
     "${CT_TARBALLS_DIR}". To this end, a functions is available, that
     abstracts downloading tarballs:
     - CT_DoGet <tarball_base_name> <URL1 [URL...]>
       Eg.: CT_DoGet linux-2.6.26.5 ftp://ftp.kernel.org/pub/linux/kernel/v2.6
     Note: retrieving sources from svn, cvs, git and the likes is not supported
     by CT_DoGet. You'll have to do this by hand, as it is done for eglibc in
     "scripts/build/libc/eglibc.sh"

 > defines the function "do_kernel_extract":
   + parameters: none
   + environment:
      - all variables from the ".config" file,
   + return value: 0 for success, !0 for failure.
   + behavior: extract the kernel's tarball into "${CT_SRC_DIR}", and apply
     required patches. To this end, a function is available, that abstracts
     extracting tarballs:
     - CT_ExtractAndPatch <tarball_base_name>
       Eg.: CT_ExtractAndPatch linux-2.6.26.5

 > defines the function "do_kernel_headers":
   + parameters: none
   + environment:
      - all variables from the ".config" file,
   + return value: 0 for success, !0 for failure.
   + behavior: install the kernel headers (if any) in "${CT_SYSROOT_DIR}/usr/include"

 > defines any kernel-specific helper functions
   These functions, if any, must be prefixed with "do_kernel_%CT_KERNEL%_",
   where '%CT_KERNEL%' is to be replaced with the actual kernel name, to avoid
   any name-clashing.

You can have a look at "config/kernel/linux.in" and "scripts/build/kernel/linux.sh"
as an example of what a complex kernel description looks like.


Adding a new version of a component |
------------------------------------+

When a new component, such as the Linux kernel, gcc or any other is released,
adding the new version to crosstool-NG is quite easy. There is a script that
will do all that for you:
  scripts/addToolVersion.sh

Run it with no option to get some help.


Build scripts |
--------------+

To Be Written later...