From 69f8a52866e83951bdfcfc3cae4f83a34c17bd9d Mon Sep 17 00:00:00 2001 From: "Yukihiro \"Matz\" Matsumoto" Date: Fri, 12 Feb 2021 10:27:10 +0900 Subject: Update `docs/guides/compile.md`. Especially description regarding the build process and `build` directory structures, along with some typo fixes and cosmetic changes. --- doc/guides/compile.md | 132 ++++++++++++++++++++------------------------------ 1 file changed, 52 insertions(+), 80 deletions(-) (limited to 'doc') diff --git a/doc/guides/compile.md b/doc/guides/compile.md index 1e5314b95..d2b58c48c 100644 --- a/doc/guides/compile.md +++ b/doc/guides/compile.md @@ -32,7 +32,7 @@ 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 +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 @@ -48,7 +48,7 @@ All tools necessary to compile mruby can be set or modified here. ## Build Configuration -We wish you submit a pull-request to *build_config/**PLATFORM**.rb*, once you +We wish you submit a pull-request to `build_config/PLATFORM.rb`, once you created a new configuration for a new platform. Inside of the configuration file, the following options can be @@ -228,7 +228,7 @@ end ### Preallocated Symbols -By far, preallocate symbols are highly compatible with the previous versions, so +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`. @@ -279,7 +279,7 @@ conf.build_mrbtest_lib_only ### Bintest Tests for mrbgem tools using CRuby. -To have bintests place \*.rb scripts to `bintest/` directory of mrbgems. +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/`. @@ -354,7 +354,7 @@ end ``` All configuration options of `MRuby::Build` can also be used in -`MRuby::CrossBuild`. You can find examples under the *build_config* +`MRuby::CrossBuild`. You can find examples under the `build_config` directory. ### Mrbtest in Cross-Compilation @@ -375,49 +375,42 @@ end ## Build process -During the build process the directory *build* will be created in the +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 + | + +- LEGAL <- License description | +- bin <- Binaries (mirb, mrbc and mruby) | +- lib <- Libraries (libmruby.a and libmruby_core.a) | - +- mrblib + +- mrbc <- Minimal mrbc place | - +- src + +- mrbgems <- Compilation result from mrbgems | - +- test <- mrbtest tool + +- mrblib <- Compilation result from mrblib | - +- tools - | - +- mirb - | - +- mrbc - | - +- mruby + +- src <- Compilation result from C sources The compilation workflow will look like this: -* compile all files under *src* (object files will be stored -in *build/host/src*) -* generate parser grammar out of *src/parse.y* (generated -result will be stored in *build/host/src/y.tab.c*) -* compile *build/host/src/y.tab.c* to *build/host/src/y.tab.o* -* create *build/host/lib/libmruby_core.a* out of all object files (C only) -* create `build/host/bin/mrbc` by compiling *tools/mrbc/mrbc.c* and -linking with *build/host/lib/libmruby_core.a* -* create *build/host/mrblib/mrblib.c* by compiling all \*.rb files -under *mrblib* with `build/host/bin/mrbc` -* compile *build/host/mrblib/mrblib.c* to *build/host/mrblib/mrblib.o* -* create *build/host/lib/libmruby.a* out of all object files (C and Ruby) -* create `build/host/bin/mruby` by compiling *mrbgems/mruby-bin-mruby/tools/mruby/mruby.c* and -linking with *build/host/lib/libmruby.a* -* create `build/host/bin/mirb` by compiling *mrbgems/mruby-bin-mirb/tools/mirb/mirb.c* and -linking with *build/host/lib/libmruby.a* +* compile minimal `mrbc` from `src` and `mrblib` sources + * compile all files under `src` (object files will be stored in `build/host/mrbc/src`) + * compile `mruby-compiler` gem + * create `build/host/mrbc/lib/libmruby_core.a` out of all object files (C only) + * create `build/host/mrbc/bin/mrbc` via `mruby-bin-mrbc` gem +* compile all files under `src` and store result in `build/host/src` +* create `build/host/mrblib/mrblib.c` by compiling all `*.rb` files under `mrblib` with `build/host/mrbc/bin/mrbc` +* compile `build/host/mrblib/mrblib.c` to `build/host/mrblib/mrblib.o` +* create `build/host/lib/libmruby.a` out of all object files (C and Ruby) +* compile (normal) mrbgems specified in the configuration file +* create `build/host/lib/libmruby.a` from object files from gems and `libmruby_core.a` +* create binary commands according to binary gems (e.g. `mirb` and `mruby`) +* copy binaries under `build/host/bin` to `bin` directory ``` _____ _____ ______ ____ ____ _____ _____ ____ @@ -428,7 +421,7 @@ linking with *build/host/lib/libmruby.a* ### Cross-Compilation -In case of a cross-compilation to *i386* the *build* directory structure looks +In case of a cross-compilation to `i386` the `build` directory structure looks like this: +- build @@ -439,63 +432,42 @@ like this: | | | +- lib <- Native Libraries | | - | +- mrblib + | +- mrbgems | | | +- src - | | - | +- test <- Native mrbtest tool - | | - | +- tools - | | - | +- mirb - | | - | +- mrbc - | | - | +- mruby + | +- i386 | +- bin <- Cross-compiled Binaries | + +- include <- Header Directory + | +- lib <- Cross-compiled Libraries | + +- mrbgems + | +- 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 +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. -Afterwards the cross compilation process proceeds like this: - -* cross-compile all files under *src* (object files will be stored -in *build/i386/src*) -* generate parser grammar out of *src/parse.y* (generated -result will be stored in *build/i386/src/y.tab.c*) -* cross-compile *build/i386/src/y.tab.c* to *build/i386/src/y.tab.o* -* create *build/i386/mrblib/mrblib.c* by compiling all \*.rb files -under *mrblib* with the native `build/host/bin/mrbc` -* cross-compile *build/host/mrblib/mrblib.c* to *build/host/mrblib/mrblib.o* -* create *build/i386/lib/libmruby.a* out of all object files (C and Ruby) -* create `build/i386/bin/mruby` by cross-compiling *mrbgems/mruby-bin-mruby/tools/mruby/mruby.c* and -linking with *build/i386/lib/libmruby.a* -* create `build/i386/bin/mirb` by cross-compiling *mrbgems/mruby-bin-mirb/tools/mirb/mirb.c* and -linking with *build/i386/lib/libmruby.a* -* create *build/i386/lib/libmruby_core.a* out of all object files (C only) -* create `build/i386/bin/mrbc` by cross-compiling *tools/mrbc/mrbc.c* and -linking with *build/i386/lib/libmruby_core.a* +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: + +* cross-compile all files under `src` and store result in `build/i386/src` +* create `build/i386/lib/libmruby_core.a` out of C object files +* create `build/i386/mrblib/mrblib.c` by compiling all `*.rb` files under `mrblib` with native `build/host/bin/mrbc` +* cross-compile `build/i386/mrblib/mrblib.c` to `build/i386/mrblib/mrblib.o` +* create `build/i386/lib/libmruby.a` from object files from gems and `libmruby_core.a` +* create binary commands according to binary gems (e.g. `mirb` and `mruby`) +* copy binaries under `build/host/bin` to `bin` directory + ``` _______________________________________________________________ @@ -526,24 +498,23 @@ feature due to the reason that there are functions (e.g. stdio) which can't be disabled for the main build. ```ruby -MRuby::CrossBuild.new('Minimal') do |conf| +MRuby::CrossBuild.new('minimal') do |conf| toolchain :gcc conf.cc.defines = %w(MRB_NO_STDIO) - conf.bins = [] end ``` -This configuration defines a cross compile build called 'Minimal' which +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). +all usages of stdio and doesn't compile any binaries (e.g. `mrbc`). ## Test Environment 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 +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. ## Embedding `mruby` in Your Application @@ -562,6 +533,7 @@ Usage: mruby-config [switches] --ldflags-before-libs print flags passed to linker before linked libraries --libs print linked libraries --libmruby-path print libmruby path + --help print this help ``` For example, when you have a C source file (`c.c`) and try to -- cgit v1.2.3