From cf8e978447be434064d7b3a3e8f32899f6c7ed9c Mon Sep 17 00:00:00 2001 From: Daniel Bovensiepen Date: Sun, 20 Jan 2013 23:23:40 +0800 Subject: Modify documentation for new build process --- doc/compile/README.md | 180 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 144 insertions(+), 36 deletions(-) diff --git a/doc/compile/README.md b/doc/compile/README.md index 168417984..055ca719e 100644 --- a/doc/compile/README.md +++ b/doc/compile/README.md @@ -25,40 +25,155 @@ 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) To compile just call ```./minirake``` inside of the mruby source root. To generate the test tool environment call ```./minirake test```. To clean all build files call ```./minirake clean```. +## Build Configuration + +The following options can be configurated: + +### Toolchains + +A template for a specific toolchain setting: + +### GCC + +Toolchain configuration for the GNU C Compiler. + +``` +toolchain :gcc +``` + +### clang + +Toolchain configuration based on GCC using the LLVM C Compiler clang. + +``` +toolchain :clang +``` + +### Visual Studio 2012 + +Toolchain configuration for Visual Studio 2012 on Windows. + +``` +toolchain :vs2012 +``` + +### Binaries + +Which tools should be compiled? +* mrbc (mruby compiler) +* mruby (mruby interpreter) +* mirb (mruby interactive shell + +``` +conf.bins = %(mrbc mruby mirb) +``` + +### File Separator + +Which file separator is used? + +``` +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 @@ -68,18 +183,11 @@ tools and flags for the target platform. An example could look like this for example: ``` -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 ``` -- cgit v1.2.3 From 8721f891298a9753c96514401de70c81be755c74 Mon Sep 17 00:00:00 2001 From: Daniel Bovensiepen Date: Mon, 21 Jan 2013 11:48:28 +0800 Subject: Add diagram for new build process --- doc/compile/README.md | 64 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 48 insertions(+), 16 deletions(-) diff --git a/doc/compile/README.md b/doc/compile/README.md index 055ca719e..fb1b73cfb 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) @@ -29,21 +29,25 @@ MRuby::Build.new do |conf| end ``` -All tools necessary to compile mruby can be set or modified here. +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```. ## Build Configuration -The following options can be configurated: +Inside of the *build_config.rb* the following options can be configurated +based on your environment. ### Toolchains -A template for a specific toolchain setting: +The mruby build system contains already a set of toolchain templates which +configurates the build environment for specific compiler infrastructures. -### GCC +#### GCC Toolchain configuration for the GNU C Compiler. @@ -51,15 +55,16 @@ Toolchain configuration for the GNU C Compiler. toolchain :gcc ``` -### clang +#### clang -Toolchain configuration based on GCC using the LLVM C Compiler clang. +Toolchain configuration for the LLVM C Compiler clang. Mainly equal to the +GCC toolchain. ``` toolchain :clang ``` -### Visual Studio 2012 +#### Visual Studio 2012 Toolchain configuration for Visual Studio 2012 on Windows. @@ -69,18 +74,21 @@ toolchain :vs2012 ### Binaries -Which tools should be compiled? +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 -Which file separator is used? +Some environments require a different file separator character. It is possible to +set the character via ```conf.file_separator```. ``` conf.file_separator = '/' @@ -174,13 +182,13 @@ end conf.gem 'path/to/another/gem' ``` -### Cross-Compilation +## 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('32bit') do |conf| @@ -191,12 +199,13 @@ MRuby::CrossBuild.new('32bit') do |conf| 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 @@ -240,6 +249,11 @@ 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 @@ -312,6 +326,24 @@ 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 -- cgit v1.2.3 From 2b3fe91b8209de4fb2be7bb953cbb9445cbe31f6 Mon Sep 17 00:00:00 2001 From: Daniel Bovensiepen Date: Mon, 21 Jan 2013 11:54:39 +0800 Subject: Beautify the graphs in the compilation documentation --- doc/compile/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/compile/README.md b/doc/compile/README.md index fb1b73cfb..a1c915a0e 100644 --- a/doc/compile/README.md +++ b/doc/compile/README.md @@ -249,10 +249,12 @@ 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 @@ -326,6 +328,7 @@ 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 | | _____ ______ _____ ____ ____ _____ | @@ -343,6 +346,7 @@ link with *build/i386/lib/libmruby_core.a* || *.c | |lib.a| |mruby| |mirb| |core.a| |mrbc || | ----- ----- ----- ---- ------ ----- | -------------------------------------------------------------- +``` ## Test Environment -- cgit v1.2.3