![]() |
mruby 3.3.0
mruby is the lightweight implementation of the Ruby language
|
mruby uses Rake to compile and cross-compile all libraries and binaries.
To compile mruby out of the source code you need the following tools:
gcc
or clang
)gcc
or clang
)ar
)ruby
or jruby
)Optional:
*.cpp
, *.cxx
, *.cc
)mrbgems/mruby-compiler/core/parse.y
)mrbgems/mruby-compiler/core/keywords
)Note that bison
bundled with macOS is too old to compile mruby
. Try brew install bison
and follow the instruction shown to update the $PATH
to compile mruby
. We also encourage you to upgrade ruby
on macOS in similar manner.
To compile mruby
with the default build configuration, just invoke rake
inside of the mruby source root. To generate and execute the test tools call rake test
. To clean all build files call rake clean
. To see full command line on build, call rake -v
.
You can specify your own configuration file by the MRUBY_CONFIG
environment variable (you can use CONFIG
for shorthand for MRUBY_CONFIG
). If the path doesn't exist, build_config/${MRUBY_CONFIG}.rb
is used. The default configuration is defined in the build_config/default.rb
file.
Those build configuration files contain the build configuration of mruby, for example:
All tools necessary to compile mruby can be set or modified here.
We wish you submit a pull-request to build_config/PLATFORM.rb
, once you created a new configuration for a new platform.
Inside the configuration file, 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 configuration for the LLVM C Compiler clang. Mainly equal to the GCC toolchain.
Toolchain configuration for Visual Studio on Windows. If you use the Visual Studio Command Prompt, you normally do not have to specify this manually, since it gets automatically detected by our build process.
Toolchain configuration for Android.
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. For example,
mruby
mirb
The configuration are done via mrbgems
. See Mrbgems
section.
Some environments require a different file separator character. It is possible to set the character via conf.file_separator
.
Configuration of the C compiler binary, flags and include paths.
C Compiler has header searcher to detect installed library.
If you need an include path of header file use search_header_path
:
If you need a full file name of header file use search_header
:
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:
Configuration of the Linker binary, flags and library paths.
Configuration of the Archiver binary and flags.
Configuration of the Parser Generator binary and flags.
Configuration of the GPerf binary and flags.
By far, preallocated symbols are highly compatible with the previous versions, so we expect you won't see any problem with them. But just in case you face any issue, you can disable preallocated symbols by specifying conf.disable_presym
.
In the build process, mrbc
under cross compiling environment will be compiled with this configuration.
mruby
comes with the (sort of) packaging system named mrbgems
. To specify gem
, you can use conf.gem
in the configuration file.
A GemBox is a set of Gems defined in mrbgems/default.gembox
for example. It's just a set of mrbgem
configurations.
There is a RubyGem
(gem for CRuby) named mgem
that help you to manage mrbgems
. Try gem install mgem
. mgem
can show you the list of registered mrbgems
.
See doc/guides/mrbgems.md for more option about mrbgems.
Configuration Mrbtest build process.
If you want mrbtest.a
only, You should set conf.build_mrbtest_lib_only
Tests for mrbgem tools using CRuby. To have bintests place *.rb
scripts to bintest/
directory of mrbgems. 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:
By default, mruby uses setjmp/longjmp to implement its exceptions. But it doesn't release C++ stack object correctly. To support mrbgems written in C++, mruby can be configured to use C++ exception.
There are two levels of C++ exception handling. The one is enable_cxx_exception
that enables C++ exception, but uses C ABI. The other is enable_cxx_abi
where all files are compiled by C++ compiler.
When you mix C++ code, C++ exception would be enabled automatically. If you need to enable C++ exception explicitly add the following:
If your compiler does not support C++, and you want to ensure you don't use mrbgem written in C++, you can explicitly disable C++ exception, add following:
and you will get an error when you try to use C++ gem. Note that it must be called before enable_cxx_exception
or gem
method.
To enable debugging mode add the following:
When debugging mode is enabled
MRB_DEBUG
would be defined.mrb_assert()
macro is enabled.mrbc
.-g
flag would be added to mrbc
runner.mruby can also be cross-compiled from one platform to another. To achieve cross-compilation, the build configuration 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:
All configuration options of MRuby::Build
can also be used in MRuby::CrossBuild
. You can find examples under the build_config
directory.
In cross compilation, you can run mrbtest
on an emulator if you have it by changing configuration of test runner.
During the build process the build
directory will be created in the root directory. The structure of this directory will look like this:
The compilation workflow will look like this:
mrbc
from src
and mrblib
sourcessrc
(object files will be stored in build/host/mrbc/src
)mruby-compiler
gembuild/host/mrbc/lib/libmruby_core.a
out of all object files (C only)build/host/mrbc/bin/mrbc
via mruby-bin-mrbc
gemsrc
and store result in build/host/src
build/host/mrblib/mrblib.c
by compiling all *.rb
files under mrblib
with build/host/mrbc/bin/mrbc
build/host/mrblib/mrblib.c
to build/host/mrblib/mrblib.o
build/host/lib/libmruby.a
out of all object files (C and Ruby)build/host/lib/libmruby.a
from object files from gems and libmruby_core.a
mirb
and mruby
)build/host/bin
to bin
directoryIn case of a cross-compilation to i386
the build
directory structure looks like this:
An extra directory is created for the target platform. In case you compile for i386
a directory called i386
is created under the build directory.
The cross compilation workflow starts in the same way as the normal compilation by compiling all native libraries and binaries, except for we don't have host/mrbc
directory (host
directory itself works as placeholder for mrbc
). Afterwards the cross compilation process proceeds like this:
src
and store result in build/i386/src
build/i386/lib/libmruby_core.a
out of C object filesbuild/i386/mrblib/mrblib.c
by compiling all *.rb
files under mrblib
with native build/host/bin/mrbc
build/i386/mrblib/mrblib.c
to build/i386/mrblib/mrblib.o
build/i386/lib/libmruby.a
from object files from gems and libmruby_core.a
mirb
and mruby
)build/host/bin
to bin
directoryTo build a minimal mruby library you need to use the Cross Compiling feature due to the reason that there are functions (e.g. stdio) which can't be disabled for the main build.
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 (e.g. 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.
mruby
in Your ApplicationAfter the build, you will get libmruby.a
. You can link it to your application.
For compiler options and library path, you can use mruby-config
command for convenience. mruby-config
command prints the configuration used for libmruby.a
.
For example, when you have a C source file (c.c
) and try to compile and link it with libmruby.a
, you can run the following command,
When you use make
, add following lines in Makefile
To install the files in the bin
, include
and lib
directories generated by the "host" build target into a system directory, do the following:
If there are multiple build targets in the build configuration file, to install the products of all build targets, do the following:
To install only one of several build targets, e.g., the "its-mine" build target, do the following:
To install only the executable files, do the following:
The installation directory is /usr/local
for the "host" build target and /usr/local/mruby/<build-name>
for the others. To change them, you can set the environment variable PREFIX
or use MRuby::Build#install_prefix = dir
in your build configuration file.
The PREFIX
environment variable affects all build targets and changes the /usr/local
part.
The MRuby::Build#install_prefix
can be set for each individual build target. In this case, the environment variable PREFIX
is ignored.
Also, if the environment variable DESTDIR
is set, it will prepend to the path obtained by install_prefix
to determine the final write directory. This is intended for temporary file expansion by the user's package work.
To summarize:
PREFIX
is /usr/local
.MRuby::Build#install_prefix
is <PREFIX>
.MRuby::Build#install_prefix
is <PREFIX>/mruby/<build-name>
.DESTDIR
is set, the actual write directory is <DESTDIR>/<MRuby::Build#install_prefix>
.rake clean
first.