Merge pull request #757 from bovi/compile-doc

Adapt Compile Documentation to improved Build process

1 files changed, 188 insertions, 44 deletions

diff --git a/doc/compile/README.md b/doc/compile/README.md
index 168417984..a1c915a0e 100644
--- a/doc/compile/README.md
+++ b/doc/compile/README.md
@@ -10,7 +10,7 @@ To compile mruby out of the source code you need the following tools:
 * Linker (i.e. ```gcc```)
 * Archive utility (i.e. ```ar```)
 * Parser generator (i.e. ```bison```)
-* Ruby 1.8 or 1.9
+* Ruby 1.8 or 1.9 (i.e. ```ruby``` or ```jruby```)
 
 Optional:
 * GIT (to update mruby source and integrate mrbgems easier)
@@ -25,70 +25,187 @@ of mruby and looks like this for example:
 
 ```
 MRuby::Build.new do |conf|
-  conf.cc = ENV['CC'] || 'gcc'
-  conf.ld = ENV['LD'] || 'gcc'
-  conf.ar = ENV['AR'] || 'ar'
-
-  conf.cflags << (ENV['CFLAGS'] || %w(-g -O3 -Wall -Werror-implicit-function-declaration))
-  conf.ldflags << (ENV['LDFLAGS'] || %w(-lm))
+  toolchain :gcc
 end
 ```
 
-All tools necessary to compile mruby can be set or modified here.
-The following options can be configurated:
-
-* conf.cc (C compiler)
-* conf.ld (Linker)
-* conf.ar (Archive utility)
-* conf.cxx (C++ compiler)
-* conf.objcc (Object compiler)
-* conf.asm (Assembler)
-* conf.yacc (Parser Generator)
-* conf.gperf (Hash function Generator)
-* conf.cat (Concatenate utility)
-* conf.git (GIT content tracker)
-* conf.cflags (C compiler flags)
-* conf.ldflags (Linker flags)
-* conf.cxxflags (C++ compiler flags) 
-* conf.objccflags (Object compiler flags)
-* conf.asmflags (Assembler flags)
-* conf.gem (A GEM which should be integrated - can be set several times)
-* conf.bins (Build binaries)
+All tools necessary to compile mruby can be set or modified here. In case
+you want to maintain an additional *build_config.rb* you can define a
+customized path using the  *$MRUBY_CONFIG* environment variable.
 
 To compile just call ```./minirake``` inside of the mruby source root. To
-generate the test tool environment call ```./minirake test```. To clean
+generate and execute the test tools call ```./minirake test```. To clean
 all build files call ```./minirake clean```.
 
-### Cross-Compilation
+## Build Configuration
+
+Inside of the *build_config.rb* the following options can be configurated
+based on your environment.
+
+### Toolchains
+
+The mruby build system contains already a set of toolchain templates which
+configurates the build environment for specific compiler infrastructures.
+
+#### GCC
+
+Toolchain configuration for the GNU C Compiler.
+
+```
+toolchain :gcc
+```
+
+#### clang
+
+Toolchain configuration for the LLVM C Compiler clang. Mainly equal to the
+GCC toolchain.
+
+```
+toolchain :clang
+```
+
+#### Visual Studio 2012
+
+Toolchain configuration for Visual Studio 2012 on Windows.
+
+```
+toolchain :vs2012
+```
+
+### Binaries
+
+It is possible to select which tools should be compiled during the compilation
+process. The following tools can be selected:
+* mrbc (mruby compiler)
+* mruby (mruby interpreter)
+* mirb (mruby interactive shell
+
+To select all define an array in ```conf.bins```:
+```
+conf.bins = %(mrbc mruby mirb)
+```
+
+### File Separator
+
+Some environments require a different file separator character. It is possible to
+set the character via ```conf.file_separator```.
+
+```
+conf.file_separator = '/'
+```
+
+### C Compiler
+
+Configuration of the C compiler binary, flags and include paths.
+
+```
+conf.cc do |cc|
+  cc.command = ...
+  cc.flags = ...
+  cc.include_paths = ...
+  cc.defines = ...
+  cc.option_include_path = ...
+  cc.option_define = ...
+  cc.compile_options = ...
+end
+```
+
+### Linker
+
+Configuration of the Linker binary, flags and library paths.
+
+```
+conf.linker do |linker|
+  linker.command = ...
+  linker.flags = ...
+  linker.libraries = ...
+  linker.library_paths = ....
+  linker.option_library = ...
+  linker.option_library_path = ...
+  linker.link_options = ...
+end
+```
+
+### Archiver
+
+Configuration of the Archiver binary and flags.
+
+```
+conf.archiver do |archiver|
+  archiver.command = ...
+  archiver.archive_options = ...
+end
+```
+
+### Parser Generator
+
+Configuration of the Parser Generator binary and flags.
+
+```
+conf.yacc do |yacc|
+  yacc.command = ...
+  yacc.compile_options = ...
+end
+```
+
+### GPerf
+
+Configuration of the GPerf binary and flags.
+```
+conf.gperf do |gperf|
+  gperf.command = ...
+  gperf.compile_options = ...
+end
+```
+
+### File Extensions
+
+```
+conf.exts do |exts
+  exts.object = ...
+  exts.executable = ...
+  exts.library = ...
+end
+```
+
+### Mrbgems
+
+Integrate GEMs in the build process.
+
+```
+# Integrate GEM with additional configuration
+conf.gem 'path/to/gem' do |g|
+  g.cc.flags << ...
+end
+
+# Integrate GEM without additional configuration
+conf.gem 'path/to/another/gem'
+```
+
+## Cross-Compilation
 
 mruby can also be cross-compiled from one platform to another. To
 achive this the *build_config.rb* needs to contain an instance of
 ```MRuby::CrossBuild```. This instance defines the compilation
 tools and flags for the target platform. An example could look
-like this for example:
+like this:
 
 ```
-MRuby::CrossBuild.new('i386') do |conf|
-  conf.cc = ENV['CC'] || 'gcc'
-  conf.ld = ENV['LD'] || 'gcc'
-  conf.ar = ENV['AR'] || 'ar'
+MRuby::CrossBuild.new('32bit') do |conf|
+  toolchain :gcc
 
-  if ENV['OS'] == 'Windows_NT' # MinGW
-    conf.cflags = %w(-g -O3 -Wall -Werror-implicit-function-declaration -Di386_MARK)
-    conf.ldflags = %w(-s -static)
-  else
-    conf.cflags << %w(-g -O3 -Wall -Werror-implicit-function-declaration -arch i386)
-    conf.ldflags << %w(-arch i386)
-  end
+  conf.cc.flags << "-m32"
+  conf.linker.flags << "-m32
 end
 ```
 
-You can configurate the same options as for a normal build. You can specified your own build_config.rb with *$MRUBY_CONFIG*.
+All configuration options of ```MRuby::Build``` can also be used
+in ```MRuby::CrossBuild```.
 
 ## Build process
 
-During the build process the directory *build* will be created. The
-directory structure will look like this:
+During the build process the directory *build* will be created in the
+root directory. The structure of this directory will look like this:
 
 ```
 +- build
@@ -132,6 +249,13 @@ link with *build/host/lib/libmruby.a*
 * create ```build/host/bin/mirb``` by compile *tools/mirb/mirb.c* and
 link with *build/host/lib/libmruby.a*
 
+```
+ _____    _____    ______    ____    ____    _____    _____    ____
+| CC  |->|GEN  |->|AR    |->|CC  |->|CC  |->|AR   |->|CC   |->|CC  |
+| *.c |  |y.tab|  |core.a|  |mrbc|  |*.rb|  |lib.a|  |mruby|  |mirb|
+ -----    -----    ------    ----    ----    -----    -----    ----
+```
+
 ### Cross-Compilation
 
 In case of a cross-compilation to *i386* the *build* directory structure looks
@@ -204,6 +328,26 @@ link with *build/i386/lib/libmruby.a*
 * create ```build/i386/bin/mrbc``` by cross-compile *tools/mrbc/mrbc.c* and
 link with *build/i386/lib/libmruby_core.a* 
 
+```
+ _____________________________________________________________
+|              Native Compilation for Host System             |
+| _____      ______      _____      ____      ____      _____ |
+|| CC  | -> |AR    | -> |GEN  | -> |CC  | -> |CC  | -> |AR   ||
+|| *.c |    |core.a|    |y.tab|    |mrbc|    |*.rb|    |lib.a||
+| -----      ------      -----      ----      ----      ----- |
+ -------------------------------------------------------------
+                                ||
+                               \||/
+                                \/
+ ______________________________________________________________
+|             Cross Compilation for Target System              |
+| _____      _____      _____      ____      ______      _____ |
+|| CC  | -> |AR   | -> |CC   | -> |CC  | -> |AR    | -> |CC   ||
+|| *.c |    |lib.a|    |mruby|    |mirb|    |core.a|    |mrbc ||
+| -----      -----      -----      ----      ------      ----- |
+ --------------------------------------------------------------
+```
+
 ## Test Environment
 
 mruby's build process includes a test environment. In case you start the testing