diff options
| author | take_cheeze <[email protected]> | 2014-06-21 22:00:22 +0900 |
|---|---|---|
| committer | take_cheeze <[email protected]> | 2014-06-21 22:04:00 +0900 |
| commit | 18c69508090a313bcdc3121432778a0e7f0a1635 (patch) | |
| tree | 186790e3e957b20e79789ab7ab53adb465f89259 | |
| parent | 9f25e3f3beac4b5fd3d01ea1adaad00e5d4e43f5 (diff) | |
| download | mruby-18c69508090a313bcdc3121432778a0e7f0a1635.tar.gz mruby-18c69508090a313bcdc3121432778a0e7f0a1635.zip | |
Syntax highlight code blocks with github flavored markdown.
| -rw-r--r-- | doc/compile/README.md | 255 | ||||
| -rw-r--r-- | doc/mrbgems/README.md | 123 |
2 files changed, 205 insertions, 173 deletions
diff --git a/doc/compile/README.md b/doc/compile/README.md index 4309dcdc4..f20b81eab 100644 --- a/doc/compile/README.md +++ b/doc/compile/README.md @@ -22,10 +22,11 @@ Optional: Inside of the root directory of the mruby source a file exists called *build_config.rb*. This file contains the build configuration of mruby and looks like this for example: - - MRuby::Build.new do |conf| - toolchain :gcc - end +```ruby +MRuby::Build.new do |conf| + toolchain :gcc +end +``` 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 @@ -49,29 +50,33 @@ configure the build environment for specific compiler infrastructures. #### GCC Toolchain configuration for the GNU C Compiler. - - toolchain :gcc +```ruby +toolchain :gcc +``` #### clang Toolchain configuration for the LLVM C Compiler clang. Mainly equal to the GCC toolchain. - - toolchain :clang +```ruby +toolchain :clang +``` #### Visual Studio 2010, 2012 and 2013 Toolchain configuration for Visual Studio on Windows. If you use the [Visual Studio Command Prompt](http://msdn.microsoft.com/en-us/library/ms229859\(v=vs.110\).aspx), you normally do not have to specify this manually, since it gets automatically detected by our build process. - - toolchain :visualcpp +``` +toolchain :visualcpp +``` #### Android Toolchain configuration for Android. - - toolchain :androideabi +```ruby +toolchain :androideabi +``` Requires the custom standalone Android NDK and the toolchain path in ```ANDROID_STANDALONE_TOOLCHAIN```. @@ -84,123 +89,132 @@ process. The following tools can be selected: * mirb (mruby interactive shell) To select them declare conf.gem as follows: - - conf.gem "#{root}/mrbgems/mruby-bin-mruby" - - conf.gem "#{root}/mrbgems/mruby-bin-mirb" +```ruby +conf.gem "#{root}/mrbgems/mruby-bin-mruby" +conf.gem "#{root}/mrbgems/mruby-bin-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 = '/' +```ruby +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 +```ruby +conf.cc do |cc| + cc.command = ... + cc.flags = ... + cc.include_paths = ... + cc.defines = ... + cc.option_include_path = ... + cc.option_define = ... + cc.compile_options = ... +end +``` C Compiler has header searcher to detect installed library. If you need a include path of header file use ```search_header_path```: - - # Searches ```iconv.h```. - # If found it will return include path of the header file. - # Otherwise it will return nil . - fail 'iconv.h not found' unless conf.cc.search_header_path 'iconv.h' +```ruby +# Searches ```iconv.h```. +# If found it will return include path of the header file. +# Otherwise it will return nil . +fail 'iconv.h not found' unless conf.cc.search_header_path 'iconv.h' +``` If you need a full file name of header file use ```search_header```: - - # Searches ```iconv.h```. - # If found it will return full path of the header file. - # Otherwise it will return nil . - iconv_h = conf.cc.search_header 'iconv.h' - print "iconv.h found: #{iconv_h}\n" +```ruby +# Searches ```iconv.h```. +# If found it will return full path of the header file. +# Otherwise it will return nil . +iconv_h = conf.cc.search_header 'iconv.h' +print "iconv.h found: #{iconv_h}\n" +``` Header searcher uses compiler's ```include_paths``` by default. When you are using GCC toolchain (including clang toolchain since its base is gcc toolchain) it will use compiler specific include paths too. (For example ```/usr/local/include```, ```/usr/include```) If you need a special header search paths define a singleton method ```header_search_paths``` to C compiler: - - def conf.cc.header_search_paths - ['/opt/local/include'] + include_paths - end - +```ruby +def conf.cc.header_search_paths + ['/opt/local/include'] + include_paths +end +``` ### Linker Configuration of the Linker binary, flags and library paths. - - conf.linker do |linker| - linker.command = ... - linker.flags = ... - linker.flags_before_libraries = ... - linker.libraries = ... - linker.flags_after_libraries = ... - linker.library_paths = .... - linker.option_library = ... - linker.option_library_path = ... - linker.link_options = ... - end +```ruby +conf.linker do |linker| + linker.command = ... + linker.flags = ... + linker.flags_before_libraries = ... + linker.libraries = ... + linker.flags_after_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 +```ruby +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 +```ruby +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 +```ruby +conf.gperf do |gperf| + gperf.command = ... + gperf.compile_options = ... +end +``` ### File Extensions - - conf.exts do |exts| - exts.object = ... - exts.executable = ... - exts.library = ... - end +```ruby +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' - +```ruby +# 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' +``` See doc/mrbgems/README.md for more option about mrbgems. @@ -209,8 +223,9 @@ See doc/mrbgems/README.md for more option about mrbgems. Configuration Mrbtest build process. If you want mrbtest.a only, You should set ```conf.build_mrbtest_lib_only``` - - conf.build_mrbtest_lib_only +```ruby +conf.build_mrbtest_lib_only +``` ### Bintest @@ -220,8 +235,9 @@ See ```mruby-bin-*/bintest/*.rb``` if you need examples. If you want a temporary files use `tempfile` module of CRuby instead of ```/tmp/```. You can enable it with following: - - conf.enable_bintest +```ruby +conf.enable_bintest +``` ### C++ ABI @@ -230,24 +246,27 @@ It is called C++ ABI mode. By using C++ exception it can release C++ stack object correctly. Whenever you mix C++ code C++ ABI mode would be enabled automatically. If you need to enable C++ ABI mode explicity add the following: - - conf.enable_cxx_abi +```ruby +conf.enable_cxx_abi +``` #### C++ exception disabling. If you need to force C++ exception disable (For example using a compiler option to disable C++ exception) add following: - - conf.disable_cxx_exception +```ruby +conf.disable_cxx_exception +``` Note that it must be called before ```enable_cxx_abi``` or ```gem``` method. ### Debugging mode To enable debugging mode add the following: - - conf.enable_debug +```ruby +conf.enable_debug +``` When debugging mode is enabled * Macro ```MRB_DEBUG``` would be defined. @@ -263,13 +282,14 @@ achieve 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: +```ruby +MRuby::CrossBuild.new('32bit') do |conf| + toolchain :gcc - MRuby::CrossBuild.new('32bit') do |conf| - toolchain :gcc - - conf.cc.flags << "-m32" - conf.linker.flags << "-m32" - end + conf.cc.flags << "-m32" + conf.linker.flags << "-m32" +end +``` All configuration options of ```MRuby::Build``` can also be used in ```MRuby::CrossBuild```. @@ -278,15 +298,16 @@ in ```MRuby::CrossBuild```. In cross compilation, you can run ```mrbtest``` on emulator if you have it by changing configuration of test runner. - - conf.test_runner do |t| - t.command = ... # set emulator. this value must be non nil or false - t.flags = ... # set flags of emulator - - def t.run(bin) # override `run` if you need to change the behavior of it - ... # `bin` is the full path of mrbtest - end - end +```ruby +conf.test_runner do |t| + t.command = ... # set emulator. this value must be non nil or false + t.flags = ... # set flags of emulator + + def t.run(bin) # override `run` if you need to change the behavior of it + ... # `bin` is the full path of mrbtest + end +end +``` ## Build process @@ -438,12 +459,14 @@ To build a minimal mruby library you need to use the Cross Compiling feature due to the reason that there are functions (i.e. stdio) which can't be disabled for the main build. - MRuby::CrossBuild.new('Minimal') do |conf| - toolchain :gcc +```ruby +MRuby::CrossBuild.new('Minimal') do |conf| + toolchain :gcc - conf.cc.defines = %w(DISABLE_STDIO) - conf.bins = [] - end + conf.cc.defines = %w(DISABLE_STDIO) + conf.bins = [] +end +``` This configuration defines a cross compile build called 'Minimal' which is using the GCC and compiles for the host machine. It also disables diff --git a/doc/mrbgems/README.md b/doc/mrbgems/README.md index 231914905..4929b409c 100644 --- a/doc/mrbgems/README.md +++ b/doc/mrbgems/README.md @@ -10,20 +10,21 @@ build configuration (i.e. *build_config.rb*), mrbgems will be activated and the extension integrated. To add a GEM into the *build_config.rb* add the following line for example: - - conf.gem '/path/to/your/gem/dir' +```ruby +conf.gem '/path/to/your/gem/dir' +``` You can also use a relative path which would be relative from the mruby root: - - conf.gem 'examples/mrbgems/ruby_extension_example' +```ruby +conf.gem 'examples/mrbgems/ruby_extension_example' +``` A remote GIT repository location for a GEM is also supported: - - conf.gem :git => 'https://github.com/masuidrive/mrbgems-example.git', :branch => 'master' - - conf.gem :github => 'masuidrive/mrbgems-example', :branch => 'master' - - conf.gem :bitbucket => 'mruby/mrbgems-example', :branch => 'master' +```ruby +conf.gem :git => 'https://github.com/masuidrive/mrbgems-example.git', :branch => 'master' +conf.gem :github => 'masuidrive/mrbgems-example', :branch => 'master' +conf.gem :bitbucket => 'mruby/mrbgems-example', :branch => 'master' +``` To pull all gems from remote GIT repository on build, call ```./minirake -p```, or ```./minirake --pull-gems```. @@ -41,11 +42,12 @@ via `config.gem`, but wrapped in an `MRuby::GemBox` object. GemBoxes are loaded into mruby via `config.gembox 'boxname'`. Below we have created a GemBox containing *mruby-time* and *mrbgems-example*: - - MRuby::GemBox.new do |conf| - conf.gem "#{root}/mrbgems/mruby-time" - conf.gem :github => 'masuidrive/mrbgems-example' - end +```ruby +MRuby::GemBox.new do |conf| + conf.gem "#{root}/mrbgems/mruby-time" + conf.gem :github => 'masuidrive/mrbgems-example' +end +``` As mentioned, the GemBox uses the same conventions as `MRuby::Build`. The GemBox must be saved with a *.gembox* extension inside the *mrbgems* directory to to be @@ -54,16 +56,17 @@ picked up by mruby. To use this example GemBox, we save it as `custom.gembox` inside the *mrbgems* directory in mruby, and add the following to our *build_config.rb* file inside the build block: - - conf.gembox 'custom' - +```ruby +conf.gembox 'custom' +``` This will cause the *custom* GemBox to be read in during the build process, adding *mruby-time* and *mrbgems-example* to the build. If you want, you can put GemBox outside of mruby directory. In that case you must specify absolute path like below. - - conf.gembox "#{ENV["HOME"]}/mygemboxes/custom" +```ruby +conf.gembox "#{ENV["HOME"]}/mygemboxes/custom" +``` There are two GemBoxes that ship with mruby: [default](../../mrbgems/default.gembox) and [full-core](../../mrbgems/full-core.gembox). The [default](../../mrbgems/default.gembox) GemBox @@ -98,11 +101,12 @@ to compile C and Ruby files. *README.md* is a short description of your GEM. mrbgems expects a specification file called *mrbgem.rake* inside of your GEM directory. A typical GEM specification could look like this for example: - - MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec| - spec.license = 'MIT' - spec.author = 'mruby developers' - end +```ruby +MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec| + spec.license = 'MIT' + spec.author = 'mruby developers' +end +``` The mrbgems build process will use this specification to compile Object and Ruby files. The compilation results will be added to *lib/libmruby.a*. This file exposes @@ -123,21 +127,22 @@ The license and author properties are required in every GEM! In case your GEM is depending on other GEMs please use `spec.add_dependency(gem, *requirements[, default_get_info])` like: +```ruby +MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec| + spec.license = 'MIT' + spec.author = 'mruby developers' - MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec| - spec.license = 'MIT' - spec.author = 'mruby developers' - - # Add GEM dependency mruby-parser. - # The version must be between 1.0.0 and 1.5.2 . - spec.add_dependency('mruby-parser', '>= 1.0.0', '<= 1.5.2') + # Add GEM dependency mruby-parser. + # The version must be between 1.0.0 and 1.5.2 . + spec.add_dependency('mruby-parser', '>= 1.0.0', '<= 1.5.2') - # Use any version of mruby-uv from github. - spec.add_dependency('mruby-uv', '>= 0.0.0', :github => 'mattn/mruby-uv') + # Use any version of mruby-uv from github. + spec.add_dependency('mruby-uv', '>= 0.0.0', :github => 'mattn/mruby-uv') - # Use latest mruby-onig-regexp from github. (version requirements can be ignored) - spec.add_dependency('mruby-onig-regexp', :github => 'mattn/mruby-onig-regexp') - end + # Use latest mruby-onig-regexp from github. (version requirements can be ignored) + spec.add_dependency('mruby-onig-regexp', :github => 'mattn/mruby-onig-regexp') +end +``` The version requirements and default gem information are optional. @@ -166,16 +171,17 @@ If you have conflicting GEMs use the following method: * The `requirements` argument is same as in `add_dependency` method. like following code: - - MRuby::Gem::Specification.new 'some-regexp-binding' do |spec| - spec.license = 'BSD' - spec.author = 'John Doe' - - spec.add_conflict 'mruby-onig-regexp', '> 0.0.0' - spec.add_conflict 'mruby-hs-regexp' - spec.add_conflict 'mruby-pcre-regexp' - spec.add_conflict 'mruby-regexp-pcre' - end +```ruby +MRuby::Gem::Specification.new 'some-regexp-binding' do |spec| + spec.license = 'BSD' + spec.author = 'John Doe' + + spec.add_conflict 'mruby-onig-regexp', '> 0.0.0' + spec.add_conflict 'mruby-hs-regexp' + spec.add_conflict 'mruby-pcre-regexp' + spec.add_conflict 'mruby-regexp-pcre' +end +``` In case your GEM has more complex build requirements you can use the following options additionally inside of your GEM specification: @@ -215,12 +221,13 @@ mrbgems expects that you have implemented a C method called `mrb_YOURGEMNAME_gem_init(mrb_state)`. `YOURGEMNAME` will be replaced by the name of your GEM. If you call your GEM *c_extension_example*, your initialisation method could look like this: - - void - mrb_c_extension_example_gem_init(mrb_state* mrb) { - struct RClass *class_cextension = mrb_define_module(mrb, "CExtension"); - mrb_define_class_method(mrb, class_cextension, "c_method", mrb_c_method, MRB_ARGS_NONE()); - } +```C +void +mrb_c_extension_example_gem_init(mrb_state* mrb) { + struct RClass *class_cextension = mrb_define_module(mrb, "CExtension"); + mrb_define_class_method(mrb, class_cextension, "c_method", mrb_c_method, MRB_ARGS_NONE()); +} +``` ### Finalize @@ -229,10 +236,12 @@ mrbgems expects that you have implemented a C method called by the name of your GEM. If you call your GEM *c_extension_example*, your finalizer method could look like this: - void - mrb_c_extension_example_gem_final(mrb_state* mrb) { - free(someone); - } +```C +void +mrb_c_extension_example_gem_final(mrb_state* mrb) { + free(someone); +} +``` ### Example |
