|
Groonga 3.0.9 Source Code Document
|
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
|
Groonga 3.0.9 Source Code Document
|
mruby is using Rake to compile and cross-compile all libraries and binaries.
To compile mruby out of the source code you need the following tools:
gcc)gcc)ar)bison)ruby or jruby)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
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 and execute the test tools call ./minirake test. To clean all build files call ./minirake clean. To see full command line on build, call ./minirake -v.
Inside of the build_config.rb the following options can be configured based on your environment.
The mruby build system already contains a set of toolchain templates which configure the build environment for specific compiler infrastructures.
Toolchain configuration for the GNU C Compiler.
toolchain :gcc
Toolchain configuration for the LLVM C Compiler clang. Mainly equal to the GCC toolchain.
toolchain :clang
Toolchain configuration for Visual Studio 2010 on Windows.
toolchain :vs2010
Toolchain configuration for Visual Studio 2012 on Windows.
toolchain :vs2012
Toolchain configuration for Android.
toolchain :androideabi
Requires the custom standalone Android NDK and the toolchain path in ANDROID_STANDALONE_TOOLCHAIN.
It is possible to select which tools should be compiled during the compilation process. The following tools can be selected:
To select them declare conf.gem as follows:
conf.gem "#{root}/mrbgems/mruby-bin-mruby"
conf.gem "#{root}/mrbgems/mruby-bin-mirb"
Some environments require a different file separator character. It is possible to set the character via conf.file_separator.
conf.file_separator = '/'
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
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
Configuration of the Archiver binary and flags.
conf.archiver do |archiver|
archiver.command = ...
archiver.archive_options = ...
end
Configuration of the Parser Generator binary and flags.
conf.yacc do |yacc|
yacc.command = ...
yacc.compile_options = ...
end
Configuration of the GPerf binary and flags.
conf.gperf do |gperf|
gperf.command = ...
gperf.compile_options = ...
end
conf.exts do |exts
exts.object = ...
exts.executable = ...
exts.library = ...
end
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'
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
mruby can also be cross-compiled from one platform to another. To 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:
MRuby::CrossBuild.new('32bit') do |conf|
toolchain :gcc
conf.cc.flags << "-m32"
conf.linker.flags << "-m32"
end
All configuration options of MRuby::Build can also be used in MRuby::CrossBuild.
During the build process the directory build will be created in the root directory. The structure of this directory will look like this:
+- build
|
+- host
|
+- bin <- Binaries (mirb, mrbc and mruby)
|
+- lib <- Libraries (libmruby.a and libmruby_core.a)
|
+- mrblib
|
+- src
|
+- test <- mrbtest tool
|
+- tools
|
+- mirb
|
+- mrbc
|
+- mruby
The compilation workflow will look like this:
build/host/bin/mrbc by compiling tools/mrbc/mrbc.c and linking with build/host/lib/libmruby_core.abuild/host/bin/mrbcbuild/host/bin/mruby by compiling mrbgems/mruby-bin-mruby/tools/mruby/mruby.c and linking with build/host/lib/libmruby.abuild/host/bin/mirb by compiling mrbgems/mruby-bin-mirb/tools/mirb/mirb.c and linking with build/host/lib/libmruby.a```
In case of a cross-compilation to i386 the build directory structure looks like this:
+- build
|
+- host
| |
| +- bin <- Native Binaries
| |
| +- lib <- Native Libraries
| |
| +- mrblib
| |
| +- src
| |
| +- test <- Native mrbtest tool
| |
| +- tools
| |
| +- mirb
| |
| +- mrbc
| |
| +- mruby
+- i386
|
+- bin <- Cross-compiled Binaries
|
+- lib <- Cross-compiled Libraries
|
+- mrblib
|
+- src
|
+- test <- Cross-compiled mrbtest tool
|
+- tools
|
+- mirb
|
+- mrbc
|
+- mruby
An extra directory is created for the target platform. In case you compile for i386 a directory called i386 is created under the build direcotry.
The cross compilation workflow starts in the same way as the normal compilation by compiling all native libraries and binaries. Afterwards the cross compilation process proceeds like this:
build/host/bin/mrbcbuild/i386/bin/mruby by cross-compiling mrbgems/mruby-bin-mruby/tools/mruby/mruby.c and linking with build/i386/lib/libmruby.abuild/i386/bin/mirb by cross-compiling mrbgems/mruby-bin-mirb/tools/mirb/mirb.c and linking with build/i386/lib/libmruby.abuild/i386/bin/mrbc by cross-compiling tools/mrbc/mrbc.c and linking with build/i386/lib/libmruby_core.a```
|| ||/ \/
```
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
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 all usages of stdio and doesn't compile any binaries (i.e. mrbc).
mruby's build process includes a test environment. In case you start the testing of mruby, a native binary called mrbtest will be generated and executed. This binary contains all test cases which are defined under test/t. In case of a cross-compilation an additional cross-compiled mrbtest binary is generated. You can copy this binary and run on your target system.
mrbgems is a library manager to integrate C and Ruby extension in an easy and standardised way into mruby.
By default mrbgems is currently deactivated. As soon as you add a GEM to your 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'
You can also use a relative path which would be relative from the mruby root:
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'
To pull all gems from remote GIT repository on build, call ./minirake -p, or ./minirake --pull-gems.
NOTE: :bitbucket option supports only git. Hg is unsupported in this version.
There are instances when you wish to add a collection of mrbgems into mruby at once, or be able to substitute mrbgems based on configuration, without having to add each gem to the build_config.rb file. A packaged collection of mrbgems is called a GemBox. A GemBox is a file that contains a list of mrbgems to load into mruby, in the same format as if you were adding them to build_config.rb 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
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 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'
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"
There are two GemBoxes that ship with mruby: default and full-core. The default GemBox contains several core components of mruby, and full-core contains every gem found in the mrbgems directory.
The maximal GEM structure looks like this:
+- GEM_NAME <- Name of GEM
|
+- mrblib/ <- Source for Ruby extension
|
+- src/ <- Source for C extension
|
+- test/ <- Test code (Ruby)
|
+- mrbgem.rake <- GEM Specification
|
+- README.md <- Readme for GEM
The folder mrblib contains pure Ruby files to extend mruby. The folder src contains C files to extend mruby. The folder test contains C and pure Ruby files for testing purposes which will be used by mrbtest. mrbgem.rake contains the specification 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
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 the GEM functionality to tools like mruby and mirb.
The following properties can be set inside of your MRuby::Gem::Specification for information purpose:
spec.license or spec.licenses (A single license or a list of them under which this GEM is licensed)spec.author or spec.authors (Developer name or a list of them)spec.version (Current version)spec.description (Detailed description)spec.summary (Short summary)spec.homepage (Homepage)spec.requirements (External requirements as information for user)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) like:
MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec|
spec.license = 'MIT'
spec.author = 'mruby developers'
# add GEM dependency mruby-parser.
# Version has to be between 1.0.0 and 1.5.2
spec.add_dependency('mruby-parser', '> 1.0.0', '< 1.5.2')
end
The usage of versions is optional.
ATTENTION: The dependency system is currently (May 2013) under development and doesn't check or resolve dependencies!
In case your GEM has more complex build requirements you can use the following options additionally inside of your GEM specification:
spec.cflags (C compiler flags)spec.mruby_cflags (global C compiler flags for everything)spec.mruby_ldflags (global linker flags for everything)spec.mruby_libs (global libraries for everything)spec.mruby_includes (global includes for everything)spec.rbfiles (Ruby files to compile)spec.objs (Object files to compile)spec.test_rbfiles (Ruby test files for integration into mrbtest)spec.test_objs (Object test files for integration into mrbtest)spec.test_preload (Initialization files for mrbtest)mruby can be extended with C. This is possible by using the C API to integrate C libraries into mruby.
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());
}
mrbgems expects that you have implemented a C method called mrb_YOURGEMNAME_gem_final(mrb_state). YOURGEMNAME will be replaced 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_extension_example/
|
+- src/
| |
| +- example.c <- C extension source
|
+- test/
| |
| +- example.rb <- Test code for C extension
|
+- mrbgem.rake <- GEM specification
|
+- README.md
mruby can be extended with pure Ruby. It is possible to override existing classes or add new ones in this way. Put all Ruby files into the mrblib folder.
none
+- ruby_extension_example/
|
+- mrblib/
| |
| +- example.rb <- Ruby extension source
|
+- test/
| |
| +- example.rb <- Test code for Ruby extension
|
+- mrbgem.rake <- GEM specification
|
+- README.md
mruby can be extended with C and Ruby at the same time. It is possible to override existing classes or add new ones in this way. Put all Ruby files into the mrblib folder and all C files into the src folder.
See C and Ruby example.
+- c_and_ruby_extension_example/
|
+- mrblib/
| |
| +- example.rb <- Ruby extension source
|
+- src/
| |
| +- example.c <- C extension source
|
+- test/
| |
| +- example.rb <- Test code for C and Ruby extension
|
+- mrbgem.rake <- GEM specification
|
+- README.mdThis is an example gem which implements a C and Ruby extension.
This is an example gem which implements a C extension.
This is an example gem which implements a pure Ruby extension.
This is a preliminary release for internal team review. The URLs and addresses described below are not available yet. The official release will be announced later. Any suggestions for modification are welcome. Delays in replies are to be expected. Sorry in advance.
mruby is the lightweight implementation of the Ruby language complying to (part of) the ISO standard. mruby can be linked and embedded within your application. We provide the interpreter program "mruby" and the interactive mruby shell "mirb" as examples. You can also compile Ruby programs into compiled byte code using the mruby compiler "mrbc". All those tools reside in "bin" directory. The "mrbc" is also able to generate compiled byte code in a C source file. You can check the "mrbtest" program under the "test" directory.
This achievement was sponsored by the Regional Innovation Creation R&D Programs of the Ministry of Economy, Trade and Industry of Japan.
The mruby distribution files can be found in the following site:
https://github.com/mruby/mruby/zipball/master
The trunk of the mruby source tree can be checked out with the following command:
$ git clone https://github.com/mruby/mruby.git
There are some other branches under development. Try the following command and see the list of branches:
$ git branch -r
mruby's website is not launched yet but we are actively working on it.
The URL of the mruby home-page will be:
To subscribe to the mruby mailing list....[T.B.D.]
See the INSTALL file.
To run the tests, execute the following from the project's root directory.
$ make test
Or
$ ruby ./minirake test
mruby contains a package manager called mrbgems. To create extensions in C and/or Ruby you should create a GEM. You will find a complete documentation with examples under examples/mrbgems.
Copyright (c) 2013 mruby developers
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
mruby has chosen a MIT License due to its permissive license allowing developers to target various environments such as embedded systems. However, the license requires the display of the copyright notice and license information in manuals for instance. Doing so for big projects can be complicated or troublesome. This is why mruby has decided to display "mruby developers" as the copyright name to make it simple conventionally. In the future, mruby might ask you to distribute your new code (that you will commit,) under the MIT License as a member of "mruby developers" but contributors will keep their copyright. (We did not intend for contributors to transfer or waive their copyrights, Actual copyright holder name (contributors) will be listed in the AUTHORS file.)
Please ask us if you want to distribute your code under another license.
See the contribution guidelines then send a pull request to http://github.com/mruby/mruby. We consider you have granted non-exclusive right to your contributed code under MIT license. If you want to be named as one of mruby developers, please include an update to the AUTHORS file in your pull request.
To run the tests, execute the following from the project's root directory.
$ make test
1.8.1.2