mirror of
https://github.com/mruby/mruby
synced 2026-06-08 16:11:16 +00:00
Merge pull request #2409 from take-cheeze/syntax_highlight
Syntax highlight code blocks with github flavored markdown.
This commit is contained in:
Yukihiro "Matz" Matsumoto
+137
-114
@@ -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.
|
||||
```ruby
|
||||
# Integrate GEM with additional configuration
|
||||
conf.gem 'path/to/gem' do |g|
|
||||
g.cc.flags << ...
|
||||
end
|
||||
|
||||
# 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'
|
||||
|
||||
# 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.
|
||||
```ruby
|
||||
conf.test_runner do |t|
|
||||
t.command = ... # set emulator. this value must be non nil or false
|
||||
t.flags = ... # set flags of emulator
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
+65
-56
@@ -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:
|
||||
```ruby
|
||||
MRuby::Gem::Specification.new 'some-regexp-binding' do |spec|
|
||||
spec.license = 'BSD'
|
||||
spec.author = 'John Doe'
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user