Update `docs/guides/compile.md`.
Especially description regarding the build process and `build` directory
structures, along with some typo fixes and cosmetic changes.
MODIFY
doc/guides/compile.md
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
- |
- +- src
- |
- +- test <- mrbtest tool
- |
- +- tools
+ +- mrbc <- Minimal mrbc place
|
- +- mirb
+ +- mrbgems <- Compilation result from mrbgems
|
- +- mrbc
+ +- mrblib <- Compilation result from mrblib
|
- +- 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

Update `docs/guides/compile.md`.

Especially description regarding the build process and `build` directory
structures, along with some typo fixes and cosmetic changes.