yann@2076: File.........: 8 - Internals.txt
yann@2908: Copyright....: (C) 2010 Yann E. MORIN <yann.morin.1998@free.fr>
yann@2076: License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
yann@2076: 
yann@2076: 
yann@2076: Internals  /
yann@2076: __________/
yann@2076: 
yann@2076: 
yann@2076: Internally, crosstool-NG is script-based. To ease usage, the frontend is
yann@2076: Makefile-based.
yann@2076: 
yann@2076: 
yann@2076: Makefile front-end |
yann@2076: -------------------+
yann@2076: 
yann@2076: The entry point to crosstool-NG is the Makefile script "ct-ng". Calling this
yann@2076: script with an action will act exactly as if the Makefile was in the current
yann@2076: working directory and make was called with the action as rule. Thus:
yann@2076:   ct-ng menuconfig
yann@2076: 
yann@2076: is equivalent to having the Makefile in CWD, and calling:
yann@2076:   make menuconfig
yann@2076: 
yann@2076: Having ct-ng as it is avoids copying the Makefile everywhere, and acts as a
yann@2076: traditional command.
yann@2076: 
yann@2076: ct-ng loads sub- Makefiles from the library directory $(CT_LIB_DIR), as set up
yann@2076: at configuration time with ./configure.
yann@2076: 
yann@2076: ct-ng also searches for config files, sub-tools, samples, scripts and patches in
yann@2076: that library directory.
yann@2076: 
yann@2076: Because of a stupid make behavior/bug I was unable to track down, implicit make
antony@2564: rules are disabled: installing with --local would trigger those rules, and mconf
yann@2076: was unbuildable.
yann@2076: 
yann@2076: 
yann@2076: Kconfig parser |
yann@2076: ---------------+
yann@2076: 
yann@2076: The kconfig language is a hacked version, vampirised from the Linux kernel
yann@2076: (http://www.kernel.org/), and (heavily) adapted to my needs.
yann@2076: 
yann@2076: The list of the most notable changes (at least the ones I remember) follows:
yann@2076: - the CONFIG_ prefix has been replaced with CT_
yann@2076: - a leading | in prompts is skipped, and subsequent leading spaces are not
yann@2076:   trimmed; otherwise leading spaces are silently trimmed
yann@2076: - removed the warning about undefined environment variable
yann@2076: 
yann@2076: The kconfig parsers (conf and mconf) are not installed pre-built, but as
yann@2076: source files. Thus you can have the directory where crosstool-NG is installed,
yann@2076: exported (via NFS or whatever) and have clients with different architectures
yann@2076: use the same crosstool-NG installation, and most notably, the same set of
yann@2076: patches.
yann@2076: 
yann@2076: 
yann@2076: Architecture-specific |
yann@2076: ----------------------+
yann@2076: 
yann@2076: Note: this chapter is not really well written, and might thus be a little bit
yann@2076: complex to understand. To get a better grasp of what an architecture is, the
yann@2076: reader is kindly encouraged to look at the "arch/" sub-directory, and to the
yann@2076: existing architectures to see how things are laid out.
yann@2076: 
yann@2076: An architecture is defined by:
yann@2076: 
yann@2076:  - a human-readable name, in lower case letters, with numbers as appropriate.
yann@2076:    The underscore is allowed; space and special characters are not.
yann@2076:      Eg.: arm, x86_64
yann@2076:  - a file in "config/arch/", named after the architecture's name, and suffixed
yann@2076:    with ".in".
yann@2076:      Eg.: config/arch/arm.in
yann@2076:  - a file in "scripts/build/arch/", named after the architecture's name, and
yann@2076:    suffixed with ".sh".
yann@2076:      Eg.: scripts/build/arch/arm.sh
yann@2076: 
yann@2076: The architecture's ".in" file API:
yann@2076:  > the config option "ARCH_%arch%" (where %arch% is to be replaced with the
yann@2076:    actual architecture name).
yann@2076:    That config option must have *neither* a type, *nor* a prompt! Also, it can
yann@2076:    *not* depend on any other config option (EXPERIMENTAL is managed as above).
yann@2076:      Eg.:
yann@2076:        config ARCH_arm
yann@2076:    + mandatory:
yann@2076:        defines a (terse) help entry for this architecture:
yann@2076:        Eg.:
yann@2076:          config ARCH_arm
yann@2076:            help
yann@2076:              The ARM architecture.
yann@2076:    + optional:
yann@2076:        selects adequate associated config options.
yann@2076:        Note: 64-bit architectures *shall* select ARCH_64
yann@2076:        Eg.:
yann@2076:          config ARCH_arm
yann@2076:            select ARCH_SUPPORTS_BOTH_ENDIAN
yann@2076:            select ARCH_DEFAULT_LE
yann@2076:            help
yann@2076:              The ARM architecture.
yann@2076:        Eg.:
yann@2076:          config ARCH_x86_64
yann@2076:             select ARCH_64
yann@2076:             help
yann@2076:               The x86_64 architecture.
yann@2076: 
yann@2076:  > other target-specific options, at your discretion. Note however that to
yann@2076:    avoid name-clashing, such options shall be prefixed with "ARCH_%arch%",
yann@2076:    where %arch% is again replaced by the actual architecture name.
yann@2076:    (Note: due to historical reasons, and lack of time to clean up the code,
yann@2076:     I may have left some config options that do not completely conform to
yann@2076:     this, as the architecture name was written all upper case. However, the
yann@2076:     prefix is unique among architectures, and does not cause harm).
yann@2076: 
yann@2076: The architecture's ".sh" file API:
yann@2076:  > the function "CT_DoArchTupleValues"
yann@2076:    + parameters: none
yann@2076:    + environment:
yann@2076:      - all variables from the ".config" file,
yann@2076:      - the two variables "target_endian_eb" and "target_endian_el" which are
yann@2076:        the endianness suffixes
yann@2076:    + return value: 0 upon success, !0 upon failure
yann@2076:    + provides:
yann@2076:      - mandatory
yann@2076:      - the environment variable CT_TARGET_ARCH
yann@2076:      - contains:
yann@2076:        the architecture part of the target tuple.
yann@2076:        Eg.: "armeb" for big endian ARM
yann@2076:             "i386" for an i386
yann@2076:    + provides:
yann@2076:      - optional
yann@2076:      - the environment variable CT_TARGET_SYS
yann@2076:      - contains:
antony@2564:        the system part of the target tuple.
yann@2076:        Eg.: "gnu" for glibc on most architectures
yann@2076:             "gnueabi" for glibc on an ARM EABI
yann@2076:      - defaults to:
yann@2076:        - for glibc-based toolchain: "gnu"
yann@2076:        - for uClibc-based toolchain: "uclibc"
yann@2076:    + provides:
yann@2076:      - optional
yann@2076:      - the environment variables to configure the cross-gcc (defaults)
yann@2076:        - CT_ARCH_WITH_ARCH    : the gcc ./configure switch to select architecture level         ( "--with-arch=${CT_ARCH_ARCH}"   )
yann@2076:        - CT_ARCH_WITH_ABI     : the gcc ./configure switch to select ABI level                  ( "--with-abi=${CT_ARCH_ABI}"     )
yann@2076:        - CT_ARCH_WITH_CPU     : the gcc ./configure switch to select CPU instruction set        ( "--with-cpu=${CT_ARCH_CPU}"     )
yann@2076:        - CT_ARCH_WITH_TUNE    : the gcc ./configure switch to select scheduling                 ( "--with-tune=${CT_ARCH_TUNE}"   )
yann@2076:        - CT_ARCH_WITH_FPU     : the gcc ./configure switch to select FPU type                   ( "--with-fpu=${CT_ARCH_FPU}"     )
yann@2076:        - CT_ARCH_WITH_FLOAT   : the gcc ./configure switch to select floating point arithmetics ( "--with-float=soft" or /empty/  )
yann@2076:    + provides:
yann@2076:      - optional
yann@2076:      - the environment variables to pass to the cross-gcc to build target binaries (defaults)
yann@2076:        - CT_ARCH_ARCH_CFLAG   : the gcc switch to select architecture level                     ( "-march=${CT_ARCH_ARCH}"            )
yann@2076:        - CT_ARCH_ABI_CFLAG    : the gcc switch to select ABI level                              ( "-mabi=${CT_ARCH_ABI}"              )
yann@2076:        - CT_ARCH_CPU_CFLAG    : the gcc switch to select CPU instruction set                    ( "-mcpu=${CT_ARCH_CPU}"              )
yann@2076:        - CT_ARCH_TUNE_CFLAG   : the gcc switch to select scheduling                             ( "-mtune=${CT_ARCH_TUNE}"            )
yann@2076:        - CT_ARCH_FPU_CFLAG    : the gcc switch to select FPU type                               ( "-mfpu=${CT_ARCH_FPU}"              )
yann@2076:        - CT_ARCH_FLOAT_CFLAG  : the gcc switch to choose floating point arithmetics             ( "-msoft-float" or /empty/           )
yann@2076:        - CT_ARCH_ENDIAN_CFLAG : the gcc switch to choose big or little endian                   ( "-mbig-endian" or "-mlittle-endian" )
yann@2076:      - default to:
yann@2076:        see above.
yann@2076:    + provides:
yann@2076:      - optional
antony@2564:      - the environment variables to configure the core and final compiler, specific to this architecture:
yann@2076:        - CT_ARCH_CC_CORE_EXTRA_CONFIG   : additional, architecture specific core gcc ./configure flags
yann@2076:        - CT_ARCH_CC_EXTRA_CONFIG        : additional, architecture specific final gcc ./configure flags
yann@2076:      - default to:
yann@2076:        - all empty
yann@2076:    + provides:
yann@2076:      - optional
yann@2076:      - the architecture-specific CFLAGS and LDFLAGS:
yann@2076:        - CT_ARCH_TARGET_CLFAGS
yann@2076:        - CT_ARCH_TARGET_LDFLAGS
yann@2076:      - default to:
yann@2076:        - all empty
yann@2076: 
yann@2076: You can have a look at "config/arch/arm.in" and "scripts/build/arch/arm.sh" for
yann@2076: a quite complete example of what an actual architecture description looks like.
yann@2076: 
yann@2076: 
yann@2076: Kernel specific |
yann@2076: ----------------+
yann@2076: 
yann@2076: A kernel is defined by:
yann@2076: 
yann@2076:  - a human-readable name, in lower case letters, with numbers as appropriate.
yann@2076:    The underscore is allowed; space and special characters are not (although
yann@2076:    they are internally replaced with underscores.
yann@2076:      Eg.: linux, bare-metal
yann@2076:  - a file in "config/kernel/", named after the kernel name, and suffixed with
yann@2076:    ".in".
yann@2076:      Eg.: config/kernel/linux.in, config/kernel/bare-metal.in
yann@2076:  - a file in "scripts/build/kernel/", named after the kernel name, and suffixed
yann@2076:    with ".sh".
yann@2076:      Eg.: scripts/build/kernel/linux.sh, scripts/build/kernel/bare-metal.sh
yann@2076: 
yann@2076: The kernel's ".in" file must contain:
yann@2076:  > an optional lines containing exactly "# EXPERIMENTAL", starting on the
yann@2076:    first column, and without any following space or other character.
yann@2076:    If this line is present, then this kernel is considered EXPERIMENTAL,
yann@2076:    and correct dependency on EXPERIMENTAL will be set.
yann@2076: 
yann@2076:  > the config option "KERNEL_%kernel_name%" (where %kernel_name% is to be
yann@2076:    replaced with the actual kernel name, with all special characters and
yann@2076:    spaces replaced by underscores).
yann@2076:    That config option must have *neither* a type, *nor* a prompt! Also, it can
yann@2076:    *not* depends on EXPERIMENTAL.
yann@2076:      Eg.: KERNEL_linux, KERNEL_bare_metal
yann@2076:    + mandatory:
yann@2076:        defines a (terse) help entry for this kernel.
yann@2076:        Eg.:
yann@2076:          config KERNEL_bare_metal
yann@2076:            help
yann@2076:              Build a compiler for use without any kernel.
yann@2076:    + optional:
yann@2076:        selects adequate associated config options.
yann@2076:        Eg.:
yann@2076:          config KERNEL_bare_metal
yann@2076:            select BARE_METAL
yann@2076:            help
yann@2076:              Build a compiler for use without any kernel.
yann@2076: 
yann@2076:  > other kernel specific options, at your discretion. Note however that, to
yann@2076:    avoid name-clashing, such options should be prefixed with
yann@2076:    "KERNEL_%kernel_name%", where %kernel_name% is again tp be replaced with
yann@2076:    the actual kernel name.
yann@2076:    (Note: due to historical reasons, and lack of time to clean up the code,
yann@2076:     I may have left some config options that do not completely conform to
yann@2076:     this, as the kernel name was written all upper case. However, the prefix
yann@2076:     is unique among kernels, and does not cause harm).
yann@2076: 
yann@2076: The kernel's ".sh" file API:
yann@2076:  > is a bash script fragment
yann@2076: 
yann@2076:  > defines the function CT_DoKernelTupleValues
yann@2076:    + see the architecture's CT_DoArchTupleValues, except for:
yann@2076:    + set the environment variable CT_TARGET_KERNEL, the kernel part of the
yann@2076:      target tuple
yann@2076:    + return value: ignored
yann@2076: 
yann@2076:  > defines the function "do_kernel_get":
yann@2076:    + parameters: none
yann@2076:    + environment:
yann@2076:       - all variables from the ".config" file.
yann@2076:    + return value: 0 for success, !0 for failure.
yann@2076:    + behavior: download the kernel's sources, and store the tarball into
yann@2076:      "${CT_TARBALLS_DIR}". To this end, a functions is available, that
yann@2076:      abstracts downloading tarballs:
yann@2076:      - CT_DoGet <tarball_base_name> <URL1 [URL...]>
yann@2076:        Eg.: CT_DoGet linux-2.6.26.5 ftp://ftp.kernel.org/pub/linux/kernel/v2.6
yann@2076:      Note: retrieving sources from svn, cvs, git and the likes is not supported
yann@2076:      by CT_DoGet. You'll have to do this by hand, as it is done for eglibc in
yann@2076:      "scripts/build/libc/eglibc.sh"
yann@2076: 
yann@2076:  > defines the function "do_kernel_extract":
yann@2076:    + parameters: none
yann@2076:    + environment:
yann@2076:       - all variables from the ".config" file,
yann@2076:    + return value: 0 for success, !0 for failure.
yann@2076:    + behavior: extract the kernel's tarball into "${CT_SRC_DIR}", and apply
yann@2076:      required patches. To this end, a function is available, that abstracts
yann@2076:      extracting tarballs:
yann@2076:      - CT_ExtractAndPatch <tarball_base_name>
yann@2076:        Eg.: CT_ExtractAndPatch linux-2.6.26.5
yann@2076: 
yann@2076:  > defines the function "do_kernel_headers":
yann@2076:    + parameters: none
yann@2076:    + environment:
yann@2076:       - all variables from the ".config" file,
yann@2076:    + return value: 0 for success, !0 for failure.
yann@2076:    + behavior: install the kernel headers (if any) in "${CT_SYSROOT_DIR}/usr/include"
yann@2076: 
yann@2076:  > defines any kernel-specific helper functions
yann@2076:    These functions, if any, must be prefixed with "do_kernel_%CT_KERNEL%_",
yann@2076:    where '%CT_KERNEL%' is to be replaced with the actual kernel name, to avoid
yann@2076:    any name-clashing.
yann@2076: 
yann@2076: You can have a look at "config/kernel/linux.in" and "scripts/build/kernel/linux.sh"
yann@2076: as an example of what a complex kernel description looks like.
yann@2076: 
yann@2076: 
yann@2076: Adding a new version of a component |
yann@2076: ------------------------------------+
yann@2076: 
yann@2076: When a new component, such as the Linux kernel, gcc or any other is released,
yann@2076: adding the new version to crosstool-NG is quite easy. There is a script that
yann@2076: will do all that for you:
yann@2076:   scripts/addToolVersion.sh
yann@2076: 
yann@2076: Run it with no option to get some help.
yann@2076: 
yann@2076: 
yann@2076: Build scripts |
yann@2076: --------------+
yann@2076: 
yann@2076: To Be Written later...