1.1 --- a/docs/overview.txt	Wed Jun 25 14:06:49 2008 +0000
     1.2 +++ b/docs/overview.txt	Fri Jun 27 13:58:53 2008 +0000
     1.3 @@ -3,6 +3,34 @@
     1.4  Copyrigth....: (C) 2007 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
     1.5  License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
     1.6  
     1.7 +____________________
     1.8 +                   /
     1.9 +Table Of Content  /
    1.10 +_________________/
    1.11 +
    1.12 +
    1.13 +Introduction
    1.14 +History
    1.15 +Installing crosstool-NG
    1.16 +  Install method
    1.17 +  The hacker's way
    1.18 +  Contributed code
    1.19 +Configuring crosstool-NG
    1.20 +  Interesting config options
    1.21 +  Re-building an existing toolchain
    1.22 +Running crosstool-NG
    1.23 +  Stopping and restarting a build
    1.24 +  Testing all toolchains at once
    1.25 +  Overriding the number of // jobs
    1.26 +Using the toolchain
    1.27 +Toolchain types
    1.28 +Internals
    1.29 +  Makefile front-end
    1.30 +  Kconfig parser
    1.31 +  Architecture-specific
    1.32 +  Adding a new version of a component
    1.33 +  Build scripts
    1.34 +
    1.35  ________________
    1.36                 /
    1.37  Introduction  /
    1.38 @@ -492,19 +520,50 @@
    1.39  Architecture-specific |
    1.40  ----------------------+
    1.41  
    1.42 +Note: this chapter is not really well written, and might thus be a little bit
    1.43 +complex to understand. To get a better grasp of what an architecture is, the
    1.44 +reader is kindly encouraged to look at the "arch/" sub-directory, and to the
    1.45 +existing architectures to see how things are laid out.
    1.46 +
    1.47  An architecture is defined by:
    1.48  
    1.49   - a human-readable name, in lower case letters, with numbers as appropriate.
    1.50 -   The underscore is allowed. Eg.: arm, x86_64
    1.51 - - a boolean kconfig option named after the architecture (in capital letters
    1.52 -   if possible) prefixed with "ARCH_". Eg.: ARCH_ARM, ARCH_x86_64
    1.53 +   The underscore is allowed; space and special characters are not.
    1.54 +     Eg.: arm, x86_64
    1.55   - a directory in "arch/" named after the architecture, with the same letters
    1.56     as above. Eg.: arch/arm, arch/x86_64
    1.57 -   This directory contains:
    1.58 -   - a configuration file in kconfig syntax, named "config.in", which may be
    1.59 -     empty. Eg.: arch/arm/config.in
    1.60 +   This directory contains the following files, and only those files:
    1.61 +   - a configuration file in kconfig syntax, named "config.in", which shall
    1.62 +     follow the API defined below.
    1.63 +       Eg.: arch/arm/config.in
    1.64     - a function script in bash-3.0 syntax, named "functions", which shall
    1.65 -     follow the API defined below. Eg.: arch/arm/functions
    1.66 +     follow the API defined below.
    1.67 +       Eg.: arch/arm/functions
    1.68 +   - an optional file, named "experimental" (in lower case!), which, if it
    1.69 +     is present, means that support for this architecture is EXPERIMENTAL.
    1.70 +       Eg.: arch/arm/experimental
    1.71 +
    1.72 +The "config.in" file API:
    1.73 + > the config option "ARCH_%arch%" (where %arch% is to be replaced with the
    1.74 +   actual architecture name).
    1.75 +   That config option must have *neither* a type, *nor* a prompt! Also, it can
    1.76 +   *not* depend on any other config option (EXPERIMENTAL is managed as above).
    1.77 +     Eg.:
    1.78 +       config ARCH_arm
    1.79 +   + optional:
    1.80 +       selects adequate associated config options.
    1.81 +       Eg.:
    1.82 +         config ARCH_arm
    1.83 +           select ARCH_SUPPORTS_BOTH_ENDIAN
    1.84 +           select ARCH_DEFAULT_LE
    1.85 +
    1.86 + > other target-specific options, at your discretion. Note however that to
    1.87 +   avoid name-clashing, such options shall be prefixed with "ARCH_%arch%",
    1.88 +   where %arch% is again replaced by the actual architecture name.
    1.89 +   (Note: due to historical reasons, and lack of time to clean up the code,
    1.90 +    I may have left some config options that do not completely conform to
    1.91 +    this, as the architecture name was written all upper case. However, the
    1.92 +    prefix is unique among architectures, and does not cause harm).
    1.93  
    1.94  The "functions" file API:
    1.95   > the function "CT_DoArchValues"
    1.96 @@ -578,7 +637,7 @@
    1.97         - CT_ARCH_ENDIAN_CFLAG : the gcc switch to choose big or little endian                   ( "-mbig-endian" or "-mlittle-endian" )
    1.98       - default to:
    1.99         see above.
   1.100 -     
   1.101 +
   1.102  Adding a new version of a component |
   1.103  ------------------------------------+
   1.104