WIP: Migrate Wiki content over to src/docs

docs/chromium_software_construction_system.md

Index: docs/chromium_software_construction_system.md
diff --git a/docs/chromium_software_construction_system.md b/docs/chromium_software_construction_system.md
new file mode 100644
index 0000000000000000000000000000000000000000..78fcdfb4c510b5fe0402d40611d576cb11f13941
--- /dev/null
+++ b/docs/chromium_software_construction_system.md
@@ -0,0 +1,233 @@
+This page is under work, consider it as a draft.
+
+## Prerequisites
+
+Before proceeding, be sure you have read: [Getting Around the Chromium Source Code](http://dev.chromium.org/developers/how-tos/getting-around-the-chrome-source-code)
+
+## Obsolete

[Bons, 2015/08/20 20:16:50]

propose to delete based on this

+
+This document describes our previous attempt at a cross-platform build system.
+Chromium moved to [GYP](http://code.google.com/p/gyp/w/list), a new
+cross-platform build system that generates platform-native build files.
+e.g. on Windows, it generates Visual Studio project files; on Mac, it generates XCode
+project files; on Linux, it generates Ninja files.
+
+## SCons and Hammer
+
+Chromium used [SCons](http://www.scons.org/) as **software construction tool**.
+SCons is based on the Python programming language and is a replacement for the traditional Make construction tool used in Linux Open Source projects.
+
+The Chromium source tree includes a local copy of the official SCons Package under the directory $CHROMIUM\_ROOT/src/third\_party/scons/.
+This allows the user to avoid installing SCons as a system-wide utility.
+
+The use of the SCons tool allows the Chromium team to easily deploy a source tree that can be built on Windows, Linux, and Mac OS.
+
+The preferred way to use Scons is through Hammer. This application is included in the depot\_tools package and is installed directly from the SVN repository.
+
+
+---
+
+
+## Using Hammer
+
+### Basic Usage
+
+Hammer is used to perform operations on the source tree.
+
+Remember to make it usable from your shell environment, by adding the directory `$CHROMIUM_ROOT/depot_tools` to the `$PATH`.
+
+To build Chromium, you need to type the following instructions:
+
+```
+cd $CHROMIUM_ROOT/chrome
+hammer
+```
+
+To clean the source's tree, you need to type instructions:
+
+```
+cd $CHROMIUM_ROOT/chrome
+hammer -c
+```
+
+By default a debug build is performed (with debugging symbols present etc). If you want an optimized (release) build, use this:
+
+```
+cd $CHROMIUM_ROOT/chrome
+hammer --mode=opt
+```
+
+Executables created during the build process will be placed in `$CHROMIUM_ROOT/src/chrome/Hammer`.
+
+After a compilation of Chromium you can recompile only a single library, binary executable or object file. To do so, type commands like these:
+
+  * To recompile an object file:
+```
+hammer Hammer/dbg/obj/skia/animator/SkTime.o 
+```
+  * To recompile a library:
+```
+hammer Hammer/dbg/lib/libicu.a 
+```
+  * To recompile a binary executable file:
+```
+hammer Hammer/unit_tests
+```
+
+
+### Passing Chromium-Specific Arguments
+
+You can also pass other command line arguments to the Hammer script, that affect the compilation.
+The following table lists the most important parameters you can use.
+
+| **Parameter**   | **Meaning**                        | **Platform** | **Note** |
+|:----------------|:-----------------------------------|:-------------|:---------|
+| `PROGRESS=type` | Display a progress indicator       | All          | Use the values 'name' (print each evaluated target name) and 'spinner' (print a spinner every 5 targets) |
+| `SYSTEM_LIBS=[lib,...]` | Comma-separated list of system libraries to link dynamically | All`         | by default they are built in from included sources |
+| `LOAD=module`   | (to be completed)                  | All          |          |
+| `COVERAGE=1`    | To Build with support for gcov     | Linux        |          |
+| `PROFILE=1`     | To Build with support for gprof    | Linux        |          |
+| `SYMBOLS=1`     | To Build with symbols              | Linux        |          |
+| `SHARED=1`      | To produce Shared Libraries (Default is Static) | Linux        |          |
+
+
+
+### Passing Standard SCons Arguments
+
+Any other parameters accepted by SCons can also be passed to the Hammer script. Sometimes it is useful to use parameters `--verbose` to affect the Scons output, or `-j num` to accelerate the compilation.
+
+The command:
+```
+hammer --verbose
+```
+will print the full commands being executed, instead of shortened info like "Compiling x.cc".
+
+The command:
+```
+hammer -j 5
+```
+will create five parallel compile jobs. But, on Linux only one link job will run at a time (to prevent excessive memory usage when linking for example test\_shell and test\_shell\_tests).
+
+
+### More on the Argument SYSTEM\_LIBS
+
+Chromium's source tree includes some system libraries under the directory `$CHROMIUM_ROOT/src/third_party/`. These libraries are compiled and linked by default.
+
+The argument `SYSTEM_LIBS` tells hammer not to compile certain embedded libraries under `$CHROMIUM_ROOT/src/third_party/`, but instead to link the libraries installed on the host system (the machine where you are compiling).
+
+For example, the following command:
+
+```
+hammer SYSTEM_LIBS=libxslt
+```
+
+tells hammer to skip compilation of `$CHROMIUM_ROOT/src/tird_party/libxslt` and instead to link directly the library installed under `/usr/lib` (most Linux distributions use this location).
+
+Before using the `SYSTEM_LIBS` argument, be sure to have also installed the C/C++ headers of the system library you are using.
+
+Remember also that the Chromium build system uses the tool `pkg-config` to get information about a system library.
+
+For the previous example you need to have installed the file `/usr/lib/pkgconfig/libxslt.pc`.
+Chromium build system uses a command like:
+```
+pkg-config --cflags --libs libxslt
+```
+to get the C Compiler Flags configuration of the local version of libxslt:
+```
+-I/usr/include/libxml2  -lxslt -lz -lm -lxml2
+```
+
+This is the list of libraries included in the Chromium source tree that you can override using the SYSTEM\_LIBS argument:
+
+  * `hunspell`
+  * `sqlite`
+  * `zlib`
+  * `bzip2`
+  * `libjpeg`
+  * `libxslt`
+  * `lzma_sdk`
+  * `libpng`
+  * `libxml`
+
+
+
+
+---
+
+
+
+## Understanding Hammer and the Use of SCons
+
+### What happens when you call the hammer script
+
+The Python-based Hammer script is a front end for scons.py and can be considered a synonym for the following shell command:
+
+```
+exec python ../third_party/scons/scons.py  --site-dir=../site_scons <SCONS-ARGUMENTS>
+```
+
+Remember that directories `$CHROMIUM_ROOT/src/chrome and $CHROMIUM_ROOT/src/site_scons` are in the same filesystem tree. The hammer tool is always executed from inside the directory `$CHROMIUM_ROOT/src/chrome`.
+
+The command above tells the Python interpreter:
+
+  1. to run the local embedded copy of SCons (third\_party/scons/scons.py)
+  1. to use the directory `$CHROMIUM_ROOT/src/site_scons` as a custom tool repository (SCons loads custom add-on tools located here before any other SConstruct or SConscript)
+  1. to pass the remaining arguments to scons.py
+
+By default SCons uses the file `$CHROMIUM_ROOT/src/chrome/SConstruct` as the starting point for the build. This script in turn calls the main script `$CHROMIUM_ROOT/src/build/SConscript.main`, which describes all the details.
+
+The script `$CHROMIUM_ROOT/src/build/SConscript.main` takes following actions:
+
+  * It parses ARGUMENTS
+  * It prepares the list of the modules to build (that is, a list of SCons scripts to run)
+  * It sets compiler and linker configurations
+  * It prepares the SCons environment for the compilation
+
+At the end of all it calls the function:
+```
+BuildComponents(environment_list)
+```
+which starts the build process of Chromium.
+
+
+### How the Chromium Construction System handles platform-specific code
+
+Sometime it is necessary to make settings or take actions depending on which platform we are running on.
+
+Currently supported platforms are:
+
+  * Windows, or MSVS
+  * Linux, or Posix
+  * Mac, or Xcode
+
+To customize the SCons code on the platform you have to use a statement like:
+
+```
+if env.Bit('windows'):
+  env.Append(
+      CCFLAGS = [
+          '/TC',
+          '/wd4800',
+      ],
+  )
+```
+
+This example adds compilation flags '/TC' and '/wd4800' only if we are running on a windows platform.
+
+
+### How modules are integrated with the Chromium Construction System
+
+Each module of the Chromium source tree has its own SCons script, and this is chained to the main SConscript list (see `$CHROMIUM_ROOT/src/build/SConscript.main`).
+
+Let's take a short look at the SCons script of the package libxslt, located at `$CHROMIUM_ROOT/src/third_party/libxslt/libxslt.scons` (see sources).
+
+Then:
+
+  * Before starting the script we check if the user has requested to compile and link this embedded version of the library (see also the use of the argument SYSTEM\_LIBS)
+  * The script takes following actions:
+    * It sets extra compiler and linker configuration (appending to the standard configuration)
+    * It builds the list of files to compile
+    * It runs the compilation and links (env.ChromeStaticLibrary('libxslt', input\_files))
+    * It takes specific actions depending on the platform (win32 or posix)
+
+The other Chromium modules have similar scripts.