From 76f24d2182449038ace3d0c414f657e6253fdf02 Mon Sep 17 00:00:00 2001 From: Seba Gamboa Date: Mon, 28 Sep 2015 12:53:44 -0300 Subject: Testing yard generation --- .gitignore | 2 + .yardopts | 5 + doc/api/README.md | 30 - doc/api/mruby.h.md | 217 ---- doc/api/mruby/array.h.md | 250 ----- doc/api/mruby/hash.h.md | 380 ------- doc/api/mruby/range.h.md | 47 - doc/api/mruby/re.h.md | 3 - doc/api/mruby/string.h.md | 91 -- doc/api/mruby/value.h.md | 238 ----- doc/api/mruby/version.h.md | 33 - doc/compile/README.md | 481 --------- doc/debugger/README.md | 370 ------- doc/language/Core.md | 1590 ----------------------------- doc/language/README.md | 9 - doc/language/generator.rb | 15 - doc/language/mrbdoc/lib/mrbdoc_analyze.rb | 231 ----- doc/language/mrbdoc/lib/mrbdoc_docu.rb | 118 --- doc/language/mrbdoc/mrbdoc.rb | 38 - doc/mrbconf/README.md | 160 --- doc/mrbgems/README.md | 337 ------ guides/compile.md | 481 +++++++++ guides/debugger.md | 370 +++++++ guides/mrbconf.md | 160 +++ guides/mrbgems.md | 337 ++++++ 25 files changed, 1355 insertions(+), 4638 deletions(-) create mode 100644 .yardopts delete mode 100644 doc/api/README.md delete mode 100644 doc/api/mruby.h.md delete mode 100644 doc/api/mruby/array.h.md delete mode 100644 doc/api/mruby/hash.h.md delete mode 100644 doc/api/mruby/range.h.md delete mode 100644 doc/api/mruby/re.h.md delete mode 100644 doc/api/mruby/string.h.md delete mode 100644 doc/api/mruby/value.h.md delete mode 100644 doc/api/mruby/version.h.md delete mode 100644 doc/compile/README.md delete mode 100755 doc/debugger/README.md delete mode 100644 doc/language/Core.md delete mode 100644 doc/language/README.md delete mode 100755 doc/language/generator.rb delete mode 100644 doc/language/mrbdoc/lib/mrbdoc_analyze.rb delete mode 100644 doc/language/mrbdoc/lib/mrbdoc_docu.rb delete mode 100755 doc/language/mrbdoc/mrbdoc.rb delete mode 100644 doc/mrbconf/README.md delete mode 100644 doc/mrbgems/README.md create mode 100644 guides/compile.md create mode 100755 guides/debugger.md create mode 100644 guides/mrbconf.md create mode 100644 guides/mrbgems.md diff --git a/.gitignore b/.gitignore index 6d10a9c8b..ba4da68f4 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,5 @@ cscope.out /bin /build /mruby-source-*.gem +doc +.yardoc diff --git a/.yardopts b/.yardopts new file mode 100644 index 000000000..5914be882 --- /dev/null +++ b/.yardopts @@ -0,0 +1,5 @@ +- +AUTHORS +MITL +CONTRIBUTING.md +guides/*.md diff --git a/doc/api/README.md b/doc/api/README.md deleted file mode 100644 index a83330d82..000000000 --- a/doc/api/README.md +++ /dev/null @@ -1,30 +0,0 @@ -# C API Reference - -This is a C API Reference. -The structure of this document will follow the directory structure of `include/` directory. - -## Headers list -Header name|Features ------------|-------- -[mrbconf.h](../mrbconf/README.md)|Defines macros for mruby configurations. -[mruby.h](./mruby.h.md)|Main header of mruby C API. Include this first. -[mruby/array.h](./mruby/array.h.md)|`Array` class. -[mruby/class.h](./mruby/class.h.md)|`Class` class. -[mruby/compile.h](./mruby/compile.h.md)|mruby compiler. -[mruby/data.h](./mruby/data.h.md)|User defined object. -[mruby/debug.h](./mruby/debug.h.md)|Debugging. -[mruby/dump.h](./mruby/dump.h.md)|Dumping compiled mruby script. -[mruby/error.h](./mruby/error.h.md)|Error handling. -[mruby/gc.h](./mruby/gc.h.md)|Uncommon memory management stuffs. -[mruby/hash.h](./mruby/hash.h.md)|`Hash` class. -[mruby/irep.h](./mruby/irep.h.md)|Compiled mruby script. -[mruby/khash.h](./mruby/khash.h.md)|Defines of khash which is used in hash table of mruby. -[mruby/numeric.h](./mruby/numeric.h.md)|`Numeric` class and sub-classes of it. -[mruby/opode.h](./mruby/opcode.h.md)|Operation codes used in mruby VM. -[mruby/proc.h](./mruby/proc.h.md)|`Proc` class. -[mruby/range.h](./mruby/range.h.md)|`Range` class. -[mruby/re.h](./mruby/re.h.md)|`Regexp` class. -[mruby/string.h](./mruby/string.h.md)|`String` class. -[mruby/value.h](./mruby/value.h.md)|`mrb_value` functions and macros. -[mruby/variable.h](./mruby/variable.h.md)|Functions to access to mruby variables. -[mruby/version.h](./mruby/version.h.md)|Macros of mruby version. diff --git a/doc/api/mruby.h.md b/doc/api/mruby.h.md deleted file mode 100644 index 06bab2d56..000000000 --- a/doc/api/mruby.h.md +++ /dev/null @@ -1,217 +0,0 @@ -# mruby.h - -Basic header of mruby. -It includes **mrbconf.h**, **mruby/value.h**, **mruby/version.h** internally. - -## `mrb_state` management - -### mrb_open -```C -mrb_state* mrb_open(); -``` -Creates new `mrb_state`. - -### mrb_allocf -```C -typedef void* (*mrb_allocf) (struct mrb_state *mrb, void *ptr, size_t s, void *ud); -``` -Function pointer type of custom allocator used in `mrb_open_allocf`. - -The function pointing it must behave similarly as `realloc` except: -* If `ptr` is `NULL` it must allocate new space. -* If `s` is `NULL`, `ptr` must be freed. - -### mrb_open_allocf -```C -mrb_state* mrb_open_allocf(mrb_allocf f, void *ud); -``` -Create new `mrb_state` with custom allocator. -`ud` will be passed to custom allocator `f`. -If user data isn't required just pass `NULL`. -Function pointer `f` must satisfy requirements of its type. - -### mrb_close -```C -void mrb_close(mrb_state *mrb); -``` -Deletes `mrb_state`. - -## Method - -### mrb_get_args -```C -int mrb_get_args(mrb_state *mrb, const char *format, ...); -``` -Retrieve arguments from `mrb_state`. -When applicable, implicit conversions (such as `to_str`, -`to_ary`, `to_hash`) are applied to received arguments. -Use it inside a function pointed by `mrb_func_t`. -It returns the number of arguments retrieved. -`format` is a list of following format specifiers: - -char|mruby type|retrieve types|note -:---:|----------|--------------|--- -`o`|`Object`|`mrb_value`|Could be used to retrieve any type of argument -`C`|`Class`/`Module`|`mrb_value`| -`S`|`String`|`mrb_value`|when ! follows, the value may be nil -`A`|`Array`|`mrb_value`|when ! follows, the value may be nil -`H`|`Hash`|`mrb_value`|when ! follows, the value may be nil -`s`|`String`|`char*`, `mrb_int`|Receive two arguments; s! gives (NULL,0) for nil -`z`|`String`|`char*`|NUL terminated string; z! gives NULL for nil -`a`|`Array`|`mrb_value*`, `mrb_int`|Receive two arguments; a! gives (NULL,0) for nil -`f`|`Float`|`mrb_float`| -`i`|`Integer`|`mrb_int`| -`b`|boolean|`mrb_bool`| -`n`|`Symbol`|`mrb_sym`| -`&`|block|`mrb_value`| -`*`|rest arguments|`mrb_value*`, `mrb_int`|Receive the rest of arguments as an array. -||optional||After this spec following specs would be optional. -`?`|optional given|`mrb_bool`|True if preceding argument is given. Used to check optional argument is given. - -The passing variadic arguments must be a pointer of retrieving type. - -### mrb_define_class -```C -MRB_API struct RClass *mrb_define_class(mrb_state *, const char*, struct RClass*); -``` -Defines a new class. If you're creating a gem it may look something like this: - -```C -void mrb_example_gem_init(mrb_state* mrb) { - struct RClass *example_class; - example_class = mrb_define_class(mrb, "Example_Class", mrb->object_class); -} - -void mrb_example_gem_final(mrb_state* mrb) { - //free(TheAnimals); -} -``` -### mrb_define_method - -```C -MRB_API void mrb_define_method(mrb_state*, struct RClass*, const char*, mrb_func_t, mrb_aspec); -``` - -Defines a global function in ruby. If you're creating a gem it may look something like this: - -```C -mrb_value example_method(mrb_state* mrb, mrb_value self){ - puts("Executing example command!"); - return self; -} - -void mrb_example_gem_init(mrb_state* mrb) { - mrb_define_method(mrb, mrb->kernel_module, "example_method", example_method, MRB_ARGS_NONE()); -} - -void mrb_example_gem_final(mrb_state* mrb) { - //free(TheAnimals); -} -``` - -Or maybe you want to create a class method for a class? It might look something like this: - -```C -mrb_value example_method(mrb_state* mrb, mrb_value self){ - puts("Examples are like pizza..."); - return self; -} - -void mrb_example_gem_init(mrb_state* mrb) { - struct RClass *example_class; - example_class = mrb_define_class(mrb, "Example_Class", mrb->object_class); - mrb_define_method(mrb, example_class, "example_method", example_method, MRB_ARGS_NONE()); -} - -void mrb_example_gem_final(mrb_state* mrb) { - //free(TheAnimals); -} -``` -### mrb_define_module - -```C -MRB_API struct RClass *mrb_define_module(mrb_state *, const char*); -``` - -Defines a module. If you're creating a gem it may look something like this: - -```C -mrb_value example_method(mrb_state* mrb, mrb_value self){ - puts("Examples are like tacos..."); - return self; -} - -void mrb_example_gem_init(mrb_state* mrb) { - struct RClass *example_module; - example_module = mrb_define_module(mrb, "Example_Module"); -} - -void mrb_example_gem_final(mrb_state* mrb) { - //free(TheAnimals); -} -``` - -### mrb_define_module_function - -```C -MRB_API void mrb_define_module_function(mrb_state*, struct RClass*, const char*, mrb_func_t, mrb_aspec); -``` - -Defines a module function. If you're creating a gem it may look something like this: - - -```C -mrb_value example_method(mrb_state* mrb, mrb_value self){ - puts("Examples are like hot wings..."); - return self; -} - -void mrb_example_gem_init(mrb_state* mrb) { - struct RClass *example_module; - example_module = mrb_define_module(mrb, "Example_Module"); - mrb_define_module_function(mrb, example_module, "example_method", example_method, MRB_ARGS_NONE()); -} - -void mrb_example_gem_final(mrb_state* mrb) { - //free(TheAnimals); -} -``` - -### mrb_define_const - -```C -MRB_API void mrb_define_const(mrb_state*, struct RClass*, const char *name, mrb_value); -``` - -Defines a constant. If you're creating a gem it may look something like this: - -```C -mrb_value example_method(mrb_state* mrb, mrb_value self){ - puts("Examples are like hot wings..."); - return self; -} - -void mrb_example_gem_init(mrb_state* mrb) { - mrb_define_const(mrb, mrb->kernel_module, "EXAPMLE_CONSTANT", mrb_fixnum_value(0x00000001)); -} - -void mrb_example_gem_final(mrb_state* mrb) { - //free(TheAnimals); -} -``` - -### mrb_str_new_cstr - -```C -MRB_API mrb_value mrb_str_new_cstr(mrb_state*, const char*); -``` - -Turns a C string into a Ruby string value. - - -### mrb_value mrb_funcall - -```C -MRB_API mrb_value mrb_funcall(mrb_state*, mrb_value, const char*, mrb_int,...); -``` -Call existing ruby functions. diff --git a/doc/api/mruby/array.h.md b/doc/api/mruby/array.h.md deleted file mode 100644 index 36c253cec..000000000 --- a/doc/api/mruby/array.h.md +++ /dev/null @@ -1,250 +0,0 @@ -### mrb_ary_new - -```C -mrb_value mrb_ary_new(mrb_state *mrb); -``` -Initializes an array. -#### Example -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument and what class the passed in value is. In this case we are declaring a variable new_ary of data type mrb_value. Then we are initializing it with the mrb_ary_new function which only takes an mruby state as an argument. -```C -#include -#include -#include "mruby/array.h" // Needs the array header. -#include "mruby/compile.h" - -int main(int argc, char *argv[]) -{ - mrb_value new_ary; // Declare variable. - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - FILE *fp = fopen("test.rb","r"); - new_ary = mrb_ary_new(mrb); - mrb_value obj = mrb_load_file(mrb,fp); - mrb_funcall(mrb, obj, "method_name", 1, new_ary); - fclose(fp); - mrb_close(mrb); - return 0; -} -``` -test.rb -```Ruby -class Example_Class - def method_name(a) - puts a - puts a.class - end -end -Example_Class.new -``` - -### mrb_ary_push -```C -void mrb_ary_push(mrb_state*, mrb_value, mrb_value); -``` -Pushes given value into an array. -#### Example -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument and what class the passed in value is. In this case after initializing our array. We are declaring two variables with the mrb_int data type random_value1 & random_value2 and we initialize them 70 and 60 respectively. Then we use the mrb_ary_push function to push values those values into the array. -```C -#include -#include -#include "mruby/array.h" // Needs the array header. -#include "mruby/compile.h" - -int main(int argc, char *argv[]) -{ - mrb_value new_ary; // Declare variable. - mrb_int random_value1 = 70; // Initialize variable - mrb_int random_value2 = 60; // Initialize variable - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - FILE *fp = fopen("test.rb","r"); - new_ary = mrb_ary_new(mrb); // Initialize ruby array. - /* Pushes the fixnum value from random_value1 to the new_ary instance. */ - mrb_ary_push(mrb, new_ary, mrb_fixnum_value(random_value1)); - /* Pushes the fixnum value from random_value2 to the new_ary instance. */ - mrb_ary_push(mrb, new_ary, mrb_fixnum_value(random_value2)); - mrb_value obj = mrb_load_file(mrb,fp); - mrb_funcall(mrb, obj, "method_name", 1, new_ary); - fclose(fp); - mrb_close(mrb); - return 0; -} -``` -test.rb -```Ruby -class Example_Class - def method_name(a) - puts a - puts a.class - end -end -Example_Class.new -``` -#### Result -After compiling you should get these results. -```Ruby -[70, 60] -Array -``` - -## mrb_ary_pop -```C -mrb_value mrb_ary_pop(mrb_state *mrb, mrb_value ary); -``` -Pops the last element from the array. -#### Example -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument and what class the passed in value is. In this case after initializing our array. We are declaring two variables with the mrb_int data type random_value1 & random_value2 and we initialize them 70 and 60 respectively. Then we use the mrb_ary_push function to push values those values into the array. Now here in the Ruby files we add another method -called pop_ary that will return the array alone(just to be clean) and you should see the last element gone. -```C -#include -#include -#include "mruby/array.h" // Needs the array header. -#include "mruby/compile.h" - -int main(int argc, char *argv[]) -{ - mrb_value new_ary; // Declare variable. - mrb_int random_value1 = 70; // Initialize variable - mrb_int random_value2 = 60; // Initialize variable - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - FILE *fp = fopen("test.rb","r"); - new_ary = mrb_ary_new(mrb); // Initialize ruby array. - /* Pushes the fixnum value from random_value1 to the new_ary instance. */ - mrb_ary_push(mrb, new_ary, mrb_fixnum_value(random_value1)); - /* Pushes the fixnum value from random_value2 to the new_ary instance. */ - mrb_ary_push(mrb, new_ary, mrb_fixnum_value(random_value2)); - mrb_value obj = mrb_load_file(mrb,fp); - mrb_funcall(mrb, obj, "method_name", 1, new_ary); - mrb_ary_pop(mrb, new_ary); // Pops the last element of the array. In this case 60. - mrb_funcall(mrb, obj, "pop_ary", 1, new_ary); // Calls the method again to show the results. - fclose(fp); - mrb_close(mrb); - return 0; -} -``` -test.rb -```Ruby -class Example_Class - def method_name(a) - puts a - puts a.class - end - def pop_ary(a) - puts a - end -end -Example_Class.new -``` -#### Result -After compiling you should get these results. -```Ruby -[70, 60] -Array -[70] -``` -## mrb_ary_ref -```C -mrb_value mrb_ary_ref(mrb_state *mrb, mrb_value ary, mrb_int n); -``` -Returns a reference to an element of the array. Specified by the value given to mrb_int n. -#### Example -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument and what class the passed in value is. In this case we're declaring a variable ary_ref with the data type of mrb_value. Then we assign mrb_ary_ref to it getting new_ary's value at index 1. -```C -#include -#include -#include "mruby/array.h" // Needs the array header. -#include "mruby/compile.h" - -int main(int argc, char *argv[]) -{ - mrb_value ary_ref; // Declare variable. - mrb_value new_ary; // Declare variable. - mrb_int random_value1 = 70; // Initialize variable - mrb_int random_value2 = 60; // Initialize variable - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - FILE *fp = fopen("test.rb","r"); - new_ary = mrb_ary_new(mrb); // Initialize ruby array. - /* Pushes the fixnum value from random_value1 to the new_ary instance. */ - mrb_ary_push(mrb, new_ary, mrb_fixnum_value(random_value1)); - /* Pushes the fixnum value from random_value2 to the new_ary instance. */ - mrb_ary_push(mrb, new_ary, mrb_fixnum_value(random_value2)); - ary_ref = mrb_ary_ref(mrb, new_ary, 1); // Gets the value of new_ary's second element at index 1. - mrb_value obj = mrb_load_file(mrb,fp); - /* Passing the value from ary_ref to the method method_name.*/ - mrb_funcall(mrb, obj, "method_name", 1, ary_ref); - fclose(fp); - mrb_close(mrb); - return 0; -} -``` -test.rb -```Ruby -class Example_Class - def method_name(a) - puts a - puts a.class - end -end -Example_Class.new -``` -#### Result -After compiling you should get these results. -```Ruby -60 -Fixnum -``` - -### mrb_ary_set -```C -void mrb_ary_set(mrb_state *mrb, mrb_value ary, mrb_int n, mrb_value val); -``` -Sets a value to an index. -#### Example -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument and what class the passed in value is. In this case we're declaring a variable ary_ref with the data type of mrb_value. Then we assign mrb_ary_ref to it getting new_ary's value at index 1. -```C -#include -#include -#include "mruby/array.h" // Needs the array header. -#include "mruby/compile.h" - -int main(int argc, char *argv[]) -{ - mrb_value new_ary; - mrb_value ary_obj; - mrb_int random_value1 = 70; - mrb_int random_value2 = 60; - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - FILE *fp = fopen("test.rb","r"); - new_ary = mrb_ary_new(mrb); - mrb_ary_push(mrb, new_ary, mrb_fixnum_value(random_value1)); - mrb_ary_push(mrb, new_ary, mrb_fixnum_value(random_value2)); - /* Sets the fixnum value of 7 to the second index of the array.*/ - mrb_ary_set(mrb, new_ary, 2, mrb_fixnum_value(7)); - mrb_value obj = mrb_load_file(mrb,fp); - mrb_funcall(mrb, obj, "before_after", 1, new_ary); - fclose(fp); - mrb_close(mrb); - return 0; -} -``` -test.rb -```Ruby -class Example_Class - def method_name(a) - puts a - puts a.class - end - def before_after(a) - puts a - end -end -Example_Class.new -``` -#### Result -After compiling you should get these results. -```Ruby -[70, 60, 7] -``` diff --git a/doc/api/mruby/hash.h.md b/doc/api/mruby/hash.h.md deleted file mode 100644 index fa12ea670..000000000 --- a/doc/api/mruby/hash.h.md +++ /dev/null @@ -1,380 +0,0 @@ -### mrb_hash_new - -```C -mrb_value mrb_hash_new(mrb_state *mrb); -``` - -Initializes a hash. -#### Example - -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument -and what class the passed in value is. This example initializes a hash. In pure Ruby doing this is equivalent -to Hash.new. - -```C -#include -#include -#include "mruby/hash.h" // Needs the hash header. -#include "mruby/compile.h" - -int main(int argc, char *argv[]) -{ - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - mrb_value new_hash; // Declare variable. - FILE *fp = fopen("test_ext.rb","r"); - new_hash = mrb_hash_new(mrb); // Initialize hash. - mrb_value obj = mrb_load_file(mrb,fp); - mrb_funcall(mrb, obj, "method_name", 1, new_hash); - fclose(fp); - mrb_close(mrb); - return 0; -} -``` - -#### test_ext.rb - -``` Ruby -class Example_Class - def method_name(a) - puts a - puts a.class - end -end -Example_Class.new -``` - -### mrb_hash_set - -```C -void mrb_hash_set(mrb_state *mrb, mrb_value hash, mrb_value key, mrb_value val); -``` - -Sets a keys and values to hashes. -#### Example - -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument -and what class the passed in value is. This example sets a key and value pair to a hash. In pure Ruby doing this is equivalent to: - -```Ruby -a = {:da_key => 80} -``` - -```C -#include -#include -#include "mruby/hash.h" // Needs the hash header. -#include "mruby/compile.h" - -int main(int argc, char *argv[]) -{ - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - mrb_value new_hash; // Declare variable. - mrb_sym hash_key = mrb_intern_cstr(mrb, "da_key"); // Declare a symbol. - mrb_int hash_value = 80; // Declare a fixnum value. - FILE *fp = fopen("test_ext.rb","r"); - new_hash = mrb_hash_new(mrb); // Initialize hash. - mrb_value obj = mrb_load_file(mrb,fp); - mrb_hash_set(mrb, new_hash, mrb_symbol_value(hash_key), mrb_fixnum_value(hash_value)); // Set values to hash. - mrb_funcall(mrb, obj, "method_name", 1, new_hash); - fclose(fp); - mrb_close(mrb); - return 0; -} -``` - -#### test_ext.rb - -```Ruby -class Example_Class - def method_name(a) - puts a - puts a.class - end -end -Example_Class.new -``` - -#### Result - -After compiling you should get these results. - -```Ruby -{:da_key=>80} -Hash -``` - -### mrb_hash_get - -```C -mrb_value mrb_hash_get(mrb_state *mrb, mrb_value hash, mrb_value key); -``` - -Gets a value from a key. -#### Example - -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument -and what class the passed in value is. This example gets a value from a key. In pure Ruby doing this is equivalent to: - -```Ruby -a = {:da_key => 80} -a[:da_key] -``` - -```C -#include -#include -#include "mruby/hash.h" // Needs the hash header. -#include "mruby/compile.h" - -int main(int argc, char *argv[]) -{ - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - mrb_value new_hash; // Declare variable for new hash object. - mrb_value get_hash_value; // Declare variable for getting a value from a hash. - mrb_sym hash_key_a = mrb_intern_cstr(mrb, "da_key1"); // Declare a symbol. - mrb_sym hash_key_b = mrb_intern_cstr(mrb, "da_key2"); // Declare a symbol. - mrb_int hash_value_a = 80; // Declare a fixnum value. - mrb_int hash_value_b = 90; // Declare a fixnum value. - FILE *fp = fopen("test_ext.rb","r"); - new_hash = mrb_hash_new(mrb); // Initialize hash. - mrb_value obj = mrb_load_file(mrb,fp); - mrb_hash_set(mrb, new_hash, mrb_symbol_value(hash_key_a), mrb_fixnum_value(hash_value_a)); // Set values to hash. - mrb_hash_set(mrb, new_hash, mrb_symbol_value(hash_key_b), mrb_fixnum_value(hash_value_b)); // Set values to hash. - get_hash_value = mrb_hash_get(mrb, new_hash, mrb_symbol_value(hash_key_b)); // Get value from hash. - mrb_funcall(mrb, obj, "method_name", 1, get_hash_value); - fclose(fp); - mrb_close(mrb); - return 0; -} -``` - -#### test_ext.rb - -```Ruby -class Example_Class - def method_name(a) - puts a - puts a.class - end -end -Example_Class.new -``` - -#### Result - -After compiling you should get these results. - -```Ruby -90 -Fixnum -``` - -### mrb_hash_delete_key - -```C -mrb_value mrb_hash_delete_key(mrb_state *mrb, mrb_value hash, mrb_value key); -``` - -Deletes hash key and value pair. -#### Example - -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument -and what class the passed in value is. This example deletes hash key and value pair. In pure Ruby doing this is equivalent to: - -```Ruby -a = {:da_key1 => 80,:da_key2 => 90} -a.delete(:da_key2) -``` - -```C -#include -#include -#include "mruby/hash.h" // Needs the hash header. -#include "mruby/compile.h" - -int main(int argc, char *argv[]) -{ - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - mrb_value new_hash; // Declare variable for new hash object. - mrb_value get_hash_value; // Declare variable for getting a value from a hash. - mrb_sym hash_key_a = mrb_intern_cstr(mrb, "da_key1"); // Declare a symbol. - mrb_sym hash_key_b = mrb_intern_cstr(mrb, "da_key2"); // Declare a symbol. - mrb_sym hash_key_b = mrb_intern_cstr(mrb, "da_key2"); // Declare a symbol. - mrb_int hash_value_a = 80; // Declare a fixnum value. - mrb_int hash_value_b = 90; // Declare a fixnum value. - FILE *fp = fopen("test_ext.rb","r"); - new_hash = mrb_hash_new(mrb); // Initialize hash. - mrb_value obj = mrb_load_file(mrb,fp); - mrb_hash_set(mrb, new_hash, mrb_symbol_value(hash_key_a), mrb_fixnum_value(hash_value_a)); // Set values to hash. - mrb_hash_set(mrb, new_hash, mrb_symbol_value(hash_key_b), mrb_fixnum_value(hash_value_b)); // Set values to hash. - mrb_funcall(mrb, obj, "method_name", 1, new_hash); - mrb_hash_delete_key(mrb, new_hash, mrb_symbol_value(hash_key_b)); - mrb_funcall(mrb, obj, "another_method_name", 1, new_hash); - fclose(fp); - mrb_close(mrb); - return 0; -} -``` - -#### test_ext.rb - -```Ruby -class Example_Class - def method_name(a) - puts "Hash pre deletion #{a}" - #puts a.class - end - # Show deleted key and value pair. - def another_method_name(a) - puts "Hash post deletion #{a}" - end -end -Example_Class.new -``` - -#### Result - -After compiling you should get these results. - -```Ruby -Hash pre deletion {:da_key1 => 80, :da_key2 => 90} -Hash post deletion {:da_key1 => 80} -``` - -### mrb_hash_keys - -```C -mrb_value mrb_hash_keys(mrb_state *mrb, mrb_value hash); -``` - -Gets an array of keys. -#### Example - -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument -and what class the passed in value is. This example gets an array of keys from a hash. - -```C -#include -#include -#include "mruby/hash.h" // Needs the hash header. -#include "mruby/compile.h" - -int main(int argc, char *argv[]) -{ - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - mrb_value new_hash; // Declare variable for new hash object. - mrb_value get_hash_keys; // Declare variable for getting an array of keys. - mrb_sym hash_key_a = mrb_intern_cstr(mrb, "da_key1"); // Declare a symbol. - mrb_sym hash_key_b = mrb_intern_cstr(mrb, "da_key2"); // Declare a symbol. - mrb_int hash_value_a = 80; // Declare a fixnum value. - mrb_int hash_value_b = 90; // Declare a fixnum value. - FILE *fp = fopen("test_ext.rb","r"); - new_hash = mrb_hash_new(mrb); // Initialize hash. - mrb_value obj = mrb_load_file(mrb,fp); - mrb_hash_set(mrb, new_hash, mrb_symbol_value(hash_key_a), mrb_fixnum_value(hash_value_a)); // Set values to hash. - mrb_hash_set(mrb, new_hash, mrb_symbol_value(hash_key_b), mrb_fixnum_value(hash_value_b)); // Set values to hash. - get_hash_keys = mrb_hash_keys(mrb, new_hash); // get an array of keys. - mrb_funcall(mrb, obj, "method_name", 1, get_hash_keys); - fclose(fp); - mrb_close(mrb); - return 0; -} -``` - -#### test_ext.rb - -```Ruby -class Example_Class - def method_name(a) - puts a - puts a.class - end -end -Example_Class.new -``` - -#### Result - -After compiling you should get these results. - -```Ruby -[:da_key1, :da_key2] -Array -``` - -### mrb_hash_clear - -```C -mrb_value mrb_hash_clear(mrb_state *mrb, mrb_value hash); -``` - -Clears the hash. -#### Example - -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument -and what class the passed in value is. This example clears the hash. In pure Ruby doing this is equivalent to: - -```Ruby -a = {:da_key1 => 80,:da_key2 => 90} -a.clear -``` - -```C -#include -#include -#include "mruby/hash.h" // Needs the hash header. -#include "mruby/compile.h" - -int main(int argc, char *argv[]) -{ - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - mrb_value new_hash; // Declare variable for new hash object. - mrb_value get_hash; // Declare variable for getting a hash. - mrb_sym hash_key_a = mrb_intern_cstr(mrb, "da_key1"); // Declare a symbol. - mrb_sym hash_key_b = mrb_intern_cstr(mrb, "da_key2"); // Declare a symbol. - mrb_int hash_value_a = 80; // Declare a fixnum value. - mrb_int hash_value_b = 90; // Declare a fixnum value. - FILE *fp = fopen("test_ext.rb","r"); - new_hash = mrb_hash_new(mrb); // Initialize hash. - mrb_value obj = mrb_load_file(mrb,fp); - mrb_hash_set(mrb, new_hash, mrb_symbol_value(hash_key_a), mrb_fixnum_value(hash_value_a)); // Set values to hash. - mrb_hash_set(mrb, new_hash, mrb_symbol_value(hash_key_b), mrb_fixnum_value(hash_value_b)); // Set values to hash. - mrb_funcall(mrb, obj, "method_name", 1, new_hash); - get_hash = mrb_hash_clear(mrb, new_hash); - mrb_funcall(mrb, obj, "another_method_name", 1, get_hash); - fclose(fp); - mrb_close(mrb); - return 0; -} -``` - -#### test_ext.rb - -```Ruby -class Example_Class - def method_name(a) - puts "Hash pre clear #{a}" - #puts a.class - end - # Show clear hash. - def another_method_name(a) - puts "Hash post clear #{a}" - end -end -Example_Class.new -``` - -#### Result - -After compiling you should get these results. - -```Ruby -Hash pre clear {:da_key1 => 80, :da_key2 => 90} -Hash post clear {} -``` diff --git a/doc/api/mruby/range.h.md b/doc/api/mruby/range.h.md deleted file mode 100644 index 188e6ede6..000000000 --- a/doc/api/mruby/range.h.md +++ /dev/null @@ -1,47 +0,0 @@ -#### mrb_range_new -```C - mrb_value mrb_range_new(mrb_state*, mrb_value, mrb_value, mrb_bool); -``` -Initializes a Range. The first mrb_value being the beginning value and second being the ending value. -The third parameter is an mrb_bool value that represents the inclusion or exclusion of the last value. -If the third parameter is 0 then it includes the last value in the range. If the third parameter is 1 -then it excludes the last value in the range. -C code -```C - #include - #include - #include "mruby/range.h" // Needs the range header. - #include "mruby/compile.h" - - int main(int argc, char *argv[]) - { - mrb_int beg = 0; - mrb_int end = 2; - mrb_bool exclude = 1; - mrb_value range_obj; - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - FILE *fp = fopen("test.rb","r"); - range_obj = mrb_range_new(mrb, mrb_fixnum_value(beg), mrb_fixnum_value(end), exclude); - mrb_value obj = mrb_load_file(mrb,fp); - mrb_funcall(mrb, obj, "method_name", 1, range_obj); - fclose(fp); - mrb_close(mrb); - return 0; - } -``` -Ruby code -```Ruby - class Example_Class - def method_name(a) - puts a - puts a.class - end - end - Example_Class.new -``` -This returns the following: -```Ruby - 0...2 - Range -``` diff --git a/doc/api/mruby/re.h.md b/doc/api/mruby/re.h.md deleted file mode 100644 index f5cd2a71e..000000000 --- a/doc/api/mruby/re.h.md +++ /dev/null @@ -1,3 +0,0 @@ -### Macros -#### REGEXP_CLASS -A string with the name of the REGEXP class. diff --git a/doc/api/mruby/string.h.md b/doc/api/mruby/string.h.md deleted file mode 100644 index 7bf94df5b..000000000 --- a/doc/api/mruby/string.h.md +++ /dev/null @@ -1,91 +0,0 @@ -## Macros -### mrb_str_ptr(s) -Returns a pointer from a Ruby string. -## Functions -### mrb_str_plus -```C - mrb_value mrb_str_plus(mrb_state*, mrb_value, mrb_value); -``` -Adds to strings together. -### mrb_ptr_to_str -```C - mrb_value mrb_ptr_to_str(mrb_state *, void*); -``` -Converts pointer into a Ruby string. -### mrb_obj_as_string -```C - mrb_value mrb_obj_as_string(mrb_state *mrb, mrb_value obj); -``` -Returns an object as a Ruby string. -### mrb_str_resize -```C - mrb_value mrb_str_resize(mrb_state *mrb, mrb_value str, mrb_int len); -``` -Resizes the string's length. -### mrb_str_substr -```C - mrb_value mrb_str_substr(mrb_state *mrb, mrb_value str, mrb_int beg, mrb_int len); -``` -Returns a sub string. -### mrb_string_type -```C - mrb_value mrb_string_type(mrb_state *mrb, mrb_value str); -``` -Returns a Ruby string type. -### mrb_str_new_cstr -```C - const char *mrb_string_value_cstr(mrb_state *mrb, mrb_value *ptr); -``` -Returns a Ruby string as a C string. -### mrb_str_dup -```C - mrb_value mrb_str_dup(mrb_state *mrb, mrb_value str); -``` -Duplicates a string object. -### mrb_str_intern -```C - mrb_value mrb_str_intern(mrb_state *mrb, mrb_value self); -``` -Returns a symbol from a passed in string. -### mrb_str_to_str -```C - mrb_value mrb_str_to_str(mrb_state *mrb, mrb_value str); -``` -Returns a converted string type. -### mrb_str_equal -```C - mrb_bool mrb_str_equal(mrb_state *mrb, mrb_value str1, mrb_value str2); -``` -Returns true if the strings match and false if the strings don't match. -### mrb_str_cat -```C - mrb_value mrb_str_cat(mrb_state *mrb, mrb_value str, const char *ptr, size_t len); -``` -Returns a concated string comprised of a Ruby string and a C string. -### mrb_str_cat_cstr -```C - mrb_value mrb_str_cat_str(mrb_state *mrb, mrb_value str, mrb_value str2); -``` -Returns a concated string comprised of a Ruby string and a C string(A shorter alternative to mrb_str_cat). -### mrb_str_append -```C - mrb_value mrb_str_append(mrb_state *mrb, mrb_value str1, mrb_value str2); -``` -Adds str2 to the end of str1. -### mrb_str_cmp -```C - int mrb_str_cmp(mrb_state *mrb, mrb_value str1, mrb_value str2); -``` -Returns 0 if both Ruby strings are equal. -Returns a value < 0 if Ruby str1 is less than Ruby str2. -Returns a value > 0 if Ruby str2 is greater than Ruby str1. -### mrb_str_to_cstr -```C - char *mrb_str_to_cstr(mrb_state *mrb, mrb_value str); -``` -Returns a C string from a Ruby string. -### mrb_str_inspect -```C - mrb_str_inspect(mrb_state *mrb, mrb_value str); -``` -Returns a printable version of str, surrounded by quote marks, with special characters escaped. diff --git a/doc/api/mruby/value.h.md b/doc/api/mruby/value.h.md deleted file mode 100644 index fbf2dadf1..000000000 --- a/doc/api/mruby/value.h.md +++ /dev/null @@ -1,238 +0,0 @@ -### mrb_float_value -```C -static inline mrb_value mrb_float_value(struct mrb_state *mrb, mrb_float f) -``` - -Returns a float in Ruby. - -##### Example - -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument -and what class the passed in value is. In this case we are passing in mrb_float f = 0.09. Alternatively -double i = 0.09 could also be used. - - -example.c -```C -#include -#include -#include "mruby/compile.h" -#include "mruby/string.h" - -int -main(void) -{ - mrb_float f = 0.09;// or double i = 0.09; - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - FILE *fp = fopen("test.rb","r"); - mrb_value obj = mrb_load_file(mrb,fp); - mrb_funcall(mrb, obj, "method_name", 1, mrb_float_value(mrb, f)); - fclose(fp); - mrb_close(mrb); - return 0; -} - -``` - -test.rb -```Ruby -class My_Class - def method_name(s) - puts s - puts s.class - end -end -a = My_Class.new -``` - -### mrb_fixnum_value - -```C -static inline mrb_value mrb_fixnum_value(mrb_int i) -``` - -Returns a fixnum in Ruby. - -##### Example - -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument -and what class the passed in value is. In this case we are passing in mrb_int i = 99. Alternativly int i = 99 -could also be used. - - -example.c -```C -#include -#include -#include "mruby/compile.h" - -int -main(void) -{ - mrb_int i = 99; // or int i = 99; - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - FILE *fp = fopen("test.rb","r"); - mrb_value obj = mrb_load_file(mrb,fp); - mrb_funcall(mrb, obj, "method_name", 1, mrb_fixnum_value(i)); - fclose(fp); - mrb_close(mrb); - return 0; -} - -``` - -test.rb -```Ruby -class My_Class - def method_name(s) - puts s - puts s.class - end -end -a = My_Class.new -``` - - - -### mrb_nil_value - -```C -static inline mrb_value mrb_nil_value(void) -``` - -Returns nil in Ruby. - -##### Example - -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument -and what class the passed in value is. In this case we are passing in nothing and we will get NillClass. - - -example.c -```C -#include -#include -#include "mruby/compile.h" - -int -main(void) -{ - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - FILE *fp = fopen("test.rb","r"); - mrb_value obj = mrb_load_file(mrb,fp); - mrb_funcall(mrb, obj, "method_name", 1, mrb_nil_value()); - fclose(fp); - mrb_close(mrb); - return 0; -} - -``` - -test.rb -```Ruby -class My_Class - def method_name(s) - puts s - puts s.class - end -end -a = My_Class.new -``` - - -### mrb_false_value - -```C -static inline mrb_value mrb_false_value(void) -``` - -Returns false in Ruby. - -##### Example - -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument -and what class the passed in value is. In this case we are passing in nothing and we will get FalseClass. - - -example.c -```C -#include -#include -#include "mruby/compile.h" - -int -main(void) -{ - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - FILE *fp = fopen("test.rb","r"); - mrb_value obj = mrb_load_file(mrb,fp); - mrb_funcall(mrb, obj, "method_name", 1, mrb_false_value()); - fclose(fp); - mrb_close(mrb); - return 0; -} - -``` - -test.rb -```Ruby -class My_Class - def method_name(s) - puts s - puts s.class - end -end -a = My_Class.new -``` - - - -### mrb_true_value - -```C -static inline mrb_value mrb_true_value(void) -``` - -Returns true in Ruby. - -##### Example - -In this example we read from a Ruby file inside C. The Ruby code will print what you pass as an argument -and what class the passed in value is. In this case we are passing in nothing and we will get TrueClass. - - -example.c -```C -#include -#include -#include "mruby/compile.h" - -int -main(void) -{ - mrb_state *mrb = mrb_open(); - if (!mrb) { /* handle error */ } - FILE *fp = fopen("test.rb","r"); - mrb_value obj = mrb_load_file(mrb,fp); - mrb_funcall(mrb, obj, "method_name", 1, mrb_true_value()); - fclose(fp); - mrb_close(mrb); - return 0; -} - -``` - -test.rb -```Ruby -class My_Class - def method_name(s) - puts s - puts s.class - end -end -a = My_Class.new -``` diff --git a/doc/api/mruby/version.h.md b/doc/api/mruby/version.h.md deleted file mode 100644 index f627b1da1..000000000 --- a/doc/api/mruby/version.h.md +++ /dev/null @@ -1,33 +0,0 @@ -### Macros -#### MRUBY_RUBY_VERSION -The version of Ruby used by mruby. -#### MRUBY_RUBY_ENGINE -Ruby engine. -#### MRUBY_VERSION -The mruby version. -#### MRUBY_RELEASE_MAJOR -Major release version. -#### MRUBY_RELEASE_MINOR -Minor release version. -#### MRUBY_RELEASE_NO -Release number. -#### MRUBY_RELEASE_DATE -Release date as a string. -#### MRUBY_RELEASE_YEAR -Release year. -#### MRUBY_RELEASE_MONTH -Release month. -#### MRUBY_RELEASE_DAY -Release day. -#### MRUBY_BIRTH_YEAR -The year mruby was first created. -#### MRUBY_AUTHOR -Mruby's authors. -#### MRB_STRINGIZE0(expr) -A passed in expression. -#### MRB_STRINGIZE(expr) -Passes in an expression to MRB_STRINGIZE0. -#### MRUBY_DESCRIPTION -mruby's version, and release date. -#### MRUBY_COPYRIGHT -mruby's copyright information. diff --git a/doc/compile/README.md b/doc/compile/README.md deleted file mode 100644 index 8e91e7546..000000000 --- a/doc/compile/README.md +++ /dev/null @@ -1,481 +0,0 @@ -# Compile - -mruby uses Rake to compile and cross-compile all libraries and -binaries. - -## Prerequisites - -To compile mruby out of the source code you need the following tools: -* C Compiler (i.e. ```gcc```) -* Linker (i.e. ```gcc```) -* Archive utility (i.e. ```ar```) -* Parser generator (i.e. ```bison```) -* Ruby 1.8 or 1.9 (i.e. ```ruby``` or ```jruby```) - -Optional: -* GIT (to update mruby source and integrate mrbgems easier) -* C++ compiler (to use GEMs which include \*.cpp, \*.cxx, \*.cc) -* Assembler (to use GEMs which include \*.asm) - -## Usage - -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: -```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 -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```. - -## Build Configuration - -Inside of the *build_config.rb* the following options can be configured -based on your environment. - -### Toolchains - -The mruby build system already contains a set of toolchain templates which -configure the build environment for specific compiler infrastructures. - -#### GCC - -Toolchain configuration for the GNU C Compiler. -```ruby -toolchain :gcc -``` - -#### clang - -Toolchain configuration for the LLVM C Compiler clang. Mainly equal to the -GCC toolchain. -```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 -``` - -#### Android - -Toolchain configuration for Android. -```ruby -toolchain :androideabi -``` - -Requires the custom standalone Android NDK and the toolchain path -in ```ANDROID_STANDALONE_TOOLCHAIN```. - -### Binaries - -It is possible to select which tools should be compiled during the compilation -process. The following tools can be selected: -* mruby (mruby interpreter) -* mirb (mruby interactive shell) - -To select them declare conf.gem as follows: -```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```. -```ruby -conf.file_separator = '/' -``` - -### C Compiler - -Configuration of the C compiler binary, flags and include paths. -```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```: -```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```: -```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: -```ruby -def conf.cc.header_search_paths - ['/opt/local/include'] + include_paths -end -``` - -### Linker - -Configuration of the Linker binary, flags and library paths. -```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. -```ruby -conf.archiver do |archiver| - archiver.command = ... - archiver.archive_options = ... -end -``` - -### Parser Generator - -Configuration of the Parser Generator binary and flags. -```ruby -conf.yacc do |yacc| - yacc.command = ... - yacc.compile_options = ... -end -``` - -### GPerf - -Configuration of the GPerf binary and flags. -```ruby -conf.gperf do |gperf| - gperf.command = ... - gperf.compile_options = ... -end -``` - -### File Extensions -```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 without additional configuration -conf.gem 'path/to/another/gem' -``` - -See doc/mrbgems/README.md for more option about mrbgems. - -### Mrbtest - -Configuration Mrbtest build process. - -If you want mrbtest.a only, You should set ```conf.build_mrbtest_lib_only``` -```ruby -conf.build_mrbtest_lib_only -``` - -### Bintest - -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: -```ruby -conf.enable_bintest -``` - -### C++ ABI - -mruby can use C++ exception to raise exception internally. -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 explicitly add the following: -```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: -```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: -```ruby -conf.enable_debug -``` - -When debugging mode is enabled -* Macro ```MRB_DEBUG``` would be defined. - * Which means ```mrb_assert()``` macro is enabled. -* Debug information of irep would be generated by ```mrbc```. - * Because ```-g``` flag would be added to ```mrbc``` runner. - * You can have better backtrace of mruby scripts with this. - -## Cross-Compilation - -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: -```ruby -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```. - -### Mrbtest in Cross-Compilation - -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 - - 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 - -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: -* 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* - -``` - _____ _____ ______ ____ ____ _____ _____ ____ -| CC |->|GEN |->|AR |->|CC |->|CC |->|AR |->|CC |->|CC | -| *.c | |y.tab| |core.a| |mrbc| |*.rb| |lib.a| |mruby| |mirb| - ----- ----- ------ ---- ---- ----- ----- ---- -``` - -### Cross-Compilation - -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 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* - -``` - _______________________________________________________________ -| Native Compilation for Host System | -| _____ ______ _____ ____ ____ _____ | -| | CC | -> |AR | -> |GEN | -> |CC | -> |CC | -> |AR | | -| | *.c | |core.a| |y.tab| |mrbc| |*.rb| |lib.a| | -| ----- ------ ----- ---- ---- ----- | - --------------------------------------------------------------- - || - \||/ - \/ - ________________________________________________________________ -| Cross Compilation for Target System | -| _____ _____ _____ ____ ______ _____ | -| | CC | -> |AR | -> |CC | -> |CC | -> |AR | -> |CC | | -| | *.c | |lib.a| |mruby| |mirb| |core.a| |mrbc | | -| ----- ----- ----- ---- ------ ----- | - ---------------------------------------------------------------- -``` - -## Build Configuration Examples - -### Minimal Library - -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. - -```ruby -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). - -## 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 -generated. You can copy this binary and run on your target system. diff --git a/doc/debugger/README.md b/doc/debugger/README.md deleted file mode 100755 index a13e91cec..000000000 --- a/doc/debugger/README.md +++ /dev/null @@ -1,370 +0,0 @@ -# How to Use the mruby Debugger - -copyright (c) 2014 Specified Non-Profit Corporation mruby Forum - -## 1. Summary - -This file documents the mruby debugger ('mrdb') methods. - -## 2 Debugging with mrdb - -## 2.1 Building mrdb - -The trunk of the mruby source tree, with the most recent mrdb, can be checked out with the following command: - -```bash -$ git clone https://github.com/mruby/mruby.git -``` - -To run the `make` command: - -```bash -$ cd mruby -$ make -``` - -By default, the `make` command will install the debugger files into mruby/bin. - -You can add the path for mrdb on your host environment with the following command: - -```bash -$ echo "export PATH=\$PATH:MRUBY_ROOT/bin" >> ~/.bashrc -$ source ~/.bashrc -``` - -`*MRUBY_ROOT` is the directory in which mruby source code will be installed. - -To confirm mrdb was installed properly, run mrdb with the `--version` option: - -```bash -$ mrdb --version -mruby 1.1.0 (2014-11-19) -``` - -## 2.2 Basic Operation - -### 2.2.1 Debugging mruby Script Files (rb file) with mrdb - -To invoke the mruby debugger, just type `mrdb`. - -To specify the script file: - -```bash -$ mrdb [option] file name -``` - -For example: Debugging sample.rb - -```bash -$ mrdb sample.rb -``` - -You can execute the shell commands listed below: - -|command|description| -|:-:|:--| -|run|execute programs| -|step|execute stepping| -|continue|execute continuing program| -|break|configure the breaking point| -|delete|deleting the breaking points| -|disable|disabling the breaking points| -|enable|enabling the breaking points| -|info breakpoints|showing list of the breaking points| -|print|evaluating and printing the values of the mruby expressions in the script| -|list|displaying the source cords| -|help|showing help| -|quit|terminating the mruby debugger| - -### 2.2.2 Debugging mruby Binary Files (mrb file) with mrdb - -You can debug the mruby binary files. - -#### 2.2.2.1 Debugging the binary files - -* notice -To debug mruby binary files, you need to compile mruby files with option `-g`. - -```bash -$ mrbc -g sample.rb -``` - -You can debug the mruby binary files with following command and the option `-b`. - -```bash -$ mrdb -b sample.mrb -``` - -Then you can execute all debugger shell commands. - -#### Break Command - -You can use any breakpoint to stop the program by specifying the line number and method name. -The breakpoint list will be displayed after you have set the breakpoint successfully. - -Usage: - -``` -break [file:]linenum -b [file:]linenum -break [class:]method -b [class:]method -``` - -The breakpoint will be ordered in serial from 1. -The number, which was given to the deleted breakpoint, will never be given to another breakpoint again. - -You can give multiple breakpoints to specified the line number and method. -Be ware that breakpoint command will not check the validity of the class name and method name. - -You can get the current breakpoint information by the following options. - -breakpoint breakpoint number : file name. line number - -breakpoint breakpoint number : [class name,] method name - -#### Continue Command - -Usage: - -``` -continue [N] -c [N] -``` - -N: the next breakpoint number - -When resuming the program, it will stop at breakpoint N (N-1 breakpoint will be ignored). - -When you run the `continue` command without specifying N, the program will be stopped at the next breakpoint. - -Example: - -``` -(foo.rb:1) continue 3 -``` - -This will resume the program and stop it at the third breakpoint. - -#### Delete Command - -This will delete the specified breakpoint. - -Usage: - -``` -delete [breakpoint-no] -d [breakpoint-no] -``` - -breakpoint-no: breakpoint number - -Example: - -``` -(foo.rb:1) delete -``` - -This will delete all of the breakpoints. - -``` -(foo.rb:1) delete 1 3 -``` - -This will delete the breakpoint at 1 and 3. - -#### Disable Command - -This will disable the specified breakpoint. - -Usage: - -``` -disable [breakpoint-no] -dis [breakpoint-no] -``` - -reappointing: breakpoint number - -Example: - -``` -(foo.rb:1) disable -``` - -Use `disable` if you would like to disable all of the breakpoints. - -``` -(foo.rb:1) disable 1 3 -``` - -This will disable the breakpoints at 1 and 3. - -#### Enable Command - -This will enable the specified breakpoints. - -Usage: - -``` -enable [breakpoint-no] -e [breakpoint-no] -``` - -breakpoint-no: breakpoint number - -Example: - -``` -(foo.rb:1) enable -``` - -Enabling all breakpoints -``` -(foo.rb:1) enable 1 3 -``` - -Enabling the breakpoint 1 and 3 - -#### eval command - -Evaluating the string as source code and printing the value. - -Same as print command, please see print command. - -#### help command - -Displaying the help message. - -Usage: - -``` -help [command] -h [command] -``` - -Typing `help` without any options will display the command list. - -#### Info Breakpoints Command - -Displaying the specified breakpoint information. - -Usage: - -``` -info breakpoints [breakpoint-no] -i b [breakpoint-no] -``` - -breakpoint-no: breakpoint number - -Typing "info breakpoints" without ant option will display all breakpoint information. -Example: - -``` -(sample.rb:1) info breakpoints -Num Type Enb What -1 breakpoint y at sample.rb:3 -> file name,line number -2 breakpoint n in Sample_class:sample_class_method -> [class:]method name -3 breakpoint y in sample_global_method -``` - -Displaying the specified breakpoint number: - -``` -(foo.rb:1) info breakpoints 1 3 -Num Type Enb What -1 breakpoint y at sample.rb:3 -3 breakpoint y in sample_global_method -``` - -#### List Command - -To display the code of the source file. - -Usage: - -``` -list [filename:]first[,last] -l [filename]:first[,last] -``` - -first: the opening row number -last : the closing row number - -When you specify the `first`, but not the `last` option, you will receive 10 rows. -When you do not specify both the `first` and `last` options, you will receive the next 10 rows. - -Example: - -``` -Specifying file name and first row number -sample.rb:1) list sample2.rb:5 -``` - -Specifying the file name and the first and last row number: - -``` -(sample.rb:1) list sample2.rb:6,7 -``` - -#### Print Command - -Evaluating the string as source code and printing the value. - -Usage: - -``` -print [expr] -p [expr] -``` - -expr: expression - -The expression is mandatory. -The displayed expressions will be serially ordered from 1. -If an exception occurs, the exception information will be displayed and the debugging will be continued. - -Example: - -``` -(sample.rb:1) print 1+2 -$1 = 3 -(sample.rb:1) print self -$2 = main -``` - -Below is the case of the exception: - -``` -(sample.rb:1) print (1+2 -$1 = SyntaxError: line 1: syntax error, unexpected $end, expecting ')' -``` - -#### Quit Command - -Quitting the debugger. - -Usage: - -``` -quit -q -``` - -#### Run Command - -Running the program and stopping at the first breakpoint. - -Usage: - -``` -run -r -``` - -#### Step Command - -This will run the program step by step. -When the method and the block are invoked, the program will be stop at the first row. -The program, which is developed in C, will be ignored. diff --git a/doc/language/Core.md b/doc/language/Core.md deleted file mode 100644 index 390581f87..000000000 --- a/doc/language/Core.md +++ /dev/null @@ -1,1590 +0,0 @@ -# Core Classes - -## Array - -ISO Code | Mixins | Source File ---- | --- | --- -15.2.12 | n/a | src/array.c - -### Class Methods - -#### [] - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.4.1 | src/array.c | mrb_ary_s_create - -### Methods - -#### * - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.2 | src/array.c | mrb_ary_times - -#### + - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.1 | src/array.c | mrb_ary_plus - -#### << - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.3 | src/array.c | mrb_ary_push_m - -#### [] - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.4 | src/array.c | mrb_ary_aget - -#### []= - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.5 | src/array.c | mrb_ary_aset - -#### __ary_cmp - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/array.c | mrb_ary_cmp - -#### __ary_eq - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/array.c | mrb_ary_eq - -#### clear - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.6 | src/array.c | mrb_ary_clear - -#### concat - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.8 | src/array.c | mrb_ary_concat_m - -#### delete_at - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.9 | src/array.c | mrb_ary_delete_at - -#### empty? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.12 | src/array.c | mrb_ary_empty_p - -#### first - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.13 | src/array.c | mrb_ary_first - -#### index - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.14 | src/array.c | mrb_ary_index_m - -#### initialize_copy - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.16 | src/array.c | mrb_ary_replace_m - -#### join - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.17 | src/array.c | mrb_ary_join_m - -#### last - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.18 | src/array.c | mrb_ary_last - -#### length - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.19 | src/array.c | mrb_ary_size - -#### pop - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.21 | src/array.c | mrb_ary_pop - -#### push - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.22 | src/array.c | mrb_ary_push_m - -#### replace - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.23 | src/array.c | mrb_ary_replace_m - -#### reverse - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.24 | src/array.c | mrb_ary_reverse - -#### reverse! - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.25 | src/array.c | mrb_ary_reverse_bang - -#### rindex - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.26 | src/array.c | mrb_ary_rindex_m - -#### shift - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.27 | src/array.c | mrb_ary_shift - -#### size - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.28 | src/array.c | mrb_ary_size - -#### slice - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.29 | src/array.c | mrb_ary_aget - -#### unshift - -ISO Code | Source File | C Function ---- | --- | --- -15.2.12.5.30 | src/array.c | mrb_ary_unshift_m - -## Exception - -ISO Code | Mixins | Source File ---- | --- | --- -15.2.22 | n/a | src/error.c - -### Class Methods - -#### exception - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/class.c | mrb_instance_new - -### Methods - -#### == - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/error.c | exc_equal - -#### backtrace - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/backtrace.c | mrb_exc_backtrace - -#### exception - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/error.c | exc_exception - -#### initialize - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/error.c | exc_initialize - -#### inspect - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/error.c | exc_inspect - -#### message - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/error.c | exc_message - -#### to_s - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/error.c | exc_to_s - -## FalseClass - -ISO Code | Mixins | Source File ---- | --- | --- -n/a | n/a | src/object.c - -### Methods - -#### & - -ISO Code | Source File | C Function ---- | --- | --- -15.2.6.3.1 | src/object.c | false_and - -#### ^ - -ISO Code | Source File | C Function ---- | --- | --- -15.2.6.3.2 | src/object.c | false_xor - -#### inspect - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/object.c | false_to_s - -#### to_s - -ISO Code | Source File | C Function ---- | --- | --- -15.2.6.3.3 | src/object.c | false_to_s - -#### | - -ISO Code | Source File | C Function ---- | --- | --- -15.2.6.3.4 | src/object.c | false_or - -## Fixnum - -ISO Code | Mixins | Source File ---- | --- | --- -n/a | n/a | src/numeric.c - -### Methods - -#### % - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.5 | src/numeric.c | fix_mod - -#### & - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.9 | src/numeric.c | fix_and - -#### * - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.3 | src/numeric.c | fix_mul - -#### + - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.1 | src/numeric.c | fix_plus - -#### - - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.2 | src/numeric.c | fix_minus - -#### << - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.12 | src/numeric.c | fix_lshift - -#### == - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.7 | src/numeric.c | fix_equal - -#### >> - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.13 | src/numeric.c | fix_rshift - -#### ^ - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.11 | src/numeric.c | fix_xor - -#### divmod - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.30 | src/numeric.c | fix_divmod - -#### eql? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.16 | src/numeric.c | fix_eql - -#### hash - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.18 | src/numeric.c | flo_hash - -#### inspect - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/numeric.c | fix_to_s - -#### to_f - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.23 | src/numeric.c | fix_to_f - -#### to_s - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.25 | src/numeric.c | fix_to_s - -#### | - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.10 | src/numeric.c | fix_or - -#### ~ - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.8 | src/numeric.c | fix_rev - -## Float - -ISO Code | Mixins | Source File ---- | --- | --- -15.2.9 | n/a | src/numeric.c - -### Methods - -#### % - -ISO Code | Source File | C Function ---- | --- | --- -15.2.9.3.5 | src/numeric.c | flo_mod - -#### * - -ISO Code | Source File | C Function ---- | --- | --- -15.2.9.3.3 | src/numeric.c | flo_mul - -#### + - -ISO Code | Source File | C Function ---- | --- | --- -15.2.9.3.1 | src/numeric.c | flo_plus - -#### - - -ISO Code | Source File | C Function ---- | --- | --- -15.2.9.3.2 | src/numeric.c | flo_minus - -#### == - -ISO Code | Source File | C Function ---- | --- | --- -15.2.9.3.7 | src/numeric.c | flo_eq - -#### ceil - -ISO Code | Source File | C Function ---- | --- | --- -15.2.9.3.8 | src/numeric.c | flo_ceil - -#### divmod - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/numeric.c | flo_divmod - -#### eql? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.16 | src/numeric.c | flo_eql - -#### finite? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.9.3.9 | src/numeric.c | flo_finite_p - -#### floor - -ISO Code | Source File | C Function ---- | --- | --- -15.2.9.3.10 | src/numeric.c | flo_floor - -#### infinite? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.9.3.11 | src/numeric.c | flo_infinite_p - -#### inspect - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/numeric.c | flo_to_s - -#### nan? - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/numeric.c | flo_nan_p - -#### round - -ISO Code | Source File | C Function ---- | --- | --- -15.2.9.3.12 | src/numeric.c | flo_round - -#### to_f - -ISO Code | Source File | C Function ---- | --- | --- -15.2.9.3.13 | src/numeric.c | flo_to_f - -#### to_i - -ISO Code | Source File | C Function ---- | --- | --- -15.2.9.3.14 | src/numeric.c | flo_truncate - -#### to_int - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/numeric.c | flo_truncate - -#### to_s - -ISO Code | Source File | C Function ---- | --- | --- -15.2.9.3.16 | src/numeric.c | flo_to_s - -#### truncate - -ISO Code | Source File | C Function ---- | --- | --- -15.2.9.3.15 | src/numeric.c | flo_truncate - -## Hash - -ISO Code | Mixins | Source File ---- | --- | --- -15.2.13 | n/a | src/hash.c - -### Methods - -#### [] - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.2 | src/hash.c | mrb_hash_aget - -#### []= - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.3 | src/hash.c | mrb_hash_aset - -#### __delete - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.8 | src/hash.c | mrb_hash_delete - -#### clear - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.4 | src/hash.c | mrb_hash_clear - -#### default - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.5 | src/hash.c | mrb_hash_default - -#### default= - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.6 | src/hash.c | mrb_hash_set_default - -#### default_proc - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.7 | src/hash.c | mrb_hash_default_proc - -#### default_proc= - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.7 | src/hash.c | mrb_hash_set_default_proc - -#### dup - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/hash.c | mrb_hash_dup - -#### empty? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.12 | src/hash.c | mrb_hash_empty_p - -#### has_key? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.13 | src/hash.c | mrb_hash_has_key - -#### has_value? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.14 | src/hash.c | mrb_hash_has_value - -#### include? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.15 | src/hash.c | mrb_hash_has_key - -#### initialize - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.16 | src/hash.c | mrb_hash_init - -#### key? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.18 | src/hash.c | mrb_hash_has_key - -#### keys - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.19 | src/hash.c | mrb_hash_keys - -#### length - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.20 | src/hash.c | mrb_hash_size_m - -#### member? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.21 | src/hash.c | mrb_hash_has_key - -#### shift - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.24 | src/hash.c | mrb_hash_shift - -#### size - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.25 | src/hash.c | mrb_hash_size_m - -#### store - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.26 | src/hash.c | mrb_hash_aset - -#### to_hash - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.29 | src/hash.c | mrb_hash_to_hash - -#### value? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.27 | src/hash.c | mrb_hash_has_value - -#### values - -ISO Code | Source File | C Function ---- | --- | --- -15.2.13.4.28 | src/hash.c | mrb_hash_values - -## Integer - -ISO Code | Mixins | Source File ---- | --- | --- -15.2.8 | n/a | src/numeric.c - -### Methods - -#### to_i - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.24 | src/numeric.c | int_to_i - -#### to_int - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/numeric.c | int_to_i - -## NilClass - -ISO Code | Mixins | Source File ---- | --- | --- -n/a | n/a | src/object.c - -### Methods - -#### & - -ISO Code | Source File | C Function ---- | --- | --- -15.2.4.3.1 | src/object.c | false_and - -#### ^ - -ISO Code | Source File | C Function ---- | --- | --- -15.2.4.3.2 | src/object.c | false_xor - -#### inspect - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/object.c | nil_inspect - -#### nil? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.4.3.4 | src/object.c | mrb_true - -#### to_s - -ISO Code | Source File | C Function ---- | --- | --- -15.2.4.3.5 | src/object.c | nil_to_s - -#### | - -ISO Code | Source File | C Function ---- | --- | --- -15.2.4.3.3 | src/object.c | false_or - -## Numeric - -ISO Code | Mixins | Source File ---- | --- | --- -15.2.7 | n/a | src/numeric.c - -### Methods - -#### ** - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/numeric.c | num_pow - -#### / - -ISO Code | Source File | C Function ---- | --- | --- -15.2.8.3.4 | src/numeric.c | num_div - -#### <=> - -ISO Code | Source File | C Function ---- | --- | --- -15.2.9.3.6 | src/numeric.c | num_cmp - -#### quo - -ISO Code | Source File | C Function ---- | --- | --- -15.2.7.4.5 | src/numeric.c | num_div - -## Proc - -ISO Code | Mixins | Source File ---- | --- | --- -15.2.17 | n/a | src/proc.c - -### Methods - -#### arity - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/proc.c | mrb_proc_arity - -#### initialize - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/proc.c | mrb_proc_initialize - -#### initialize_copy - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/proc.c | mrb_proc_init_copy - -## Range - -ISO Code | Mixins | Source File ---- | --- | --- -15.2.14 | n/a | src/range.c - -### Methods - -#### == - -ISO Code | Source File | C Function ---- | --- | --- -15.2.14.4.1 | src/range.c | mrb_range_eq - -#### === - -ISO Code | Source File | C Function ---- | --- | --- -15.2.14.4.2 | src/range.c | mrb_range_include - -#### begin - -ISO Code | Source File | C Function ---- | --- | --- -15.2.14.4.3 | src/range.c | mrb_range_beg - -#### end - -ISO Code | Source File | C Function ---- | --- | --- -15.2.14.4.5 | src/range.c | mrb_range_end - -#### eql? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.14.4.14 | src/range.c | range_eql - -#### exclude_end? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.14.4.6 | src/range.c | mrb_range_excl - -#### first - -ISO Code | Source File | C Function ---- | --- | --- -15.2.14.4.7 | src/range.c | mrb_range_beg - -#### include? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.14.4.8 | src/range.c | mrb_range_include - -#### initialize - -ISO Code | Source File | C Function ---- | --- | --- -15.2.14.4.9 | src/range.c | mrb_range_initialize - -#### initialize_copy - -ISO Code | Source File | C Function ---- | --- | --- -15.2.14.4.15 | src/range.c | range_initialize_copy - -#### inspect - -ISO Code | Source File | C Function ---- | --- | --- -15.2.14.4.13 | src/range.c | range_inspect - -#### last - -ISO Code | Source File | C Function ---- | --- | --- -15.2.14.4.10 | src/range.c | mrb_range_end - -#### member? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.14.4.11 | src/range.c | mrb_range_include - -#### to_s - -ISO Code | Source File | C Function ---- | --- | --- -15.2.14.4.12 | src/range.c | range_to_s - -## RuntimeError - -ISO Code | Mixins | Source File ---- | --- | --- -15.2.28 | n/a | src/error.c - -## ScriptError - -ISO Code | Mixins | Source File ---- | --- | --- -15.2.37 | n/a | src/error.c - -## StandardError - -ISO Code | Mixins | Source File ---- | --- | --- -15.2.23 | n/a | src/error.c - -## String - -ISO Code | Mixins | Source File ---- | --- | --- -15.2.10 | n/a | src/string.c - -### Methods - -#### * - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.5 | src/string.c | mrb_str_times - -#### + - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.4 | src/string.c | mrb_str_plus_m - -#### <=> - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.1 | src/string.c | mrb_str_cmp_m - -#### == - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.2 | src/string.c | mrb_str_equal_m - -#### [] - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.6 | src/string.c | mrb_str_aref_m - -#### bytes - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/string.c | mrb_str_bytes - -#### bytesize - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/string.c | mrb_str_size - -#### capitalize - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.7 | src/string.c | mrb_str_capitalize - -#### capitalize! - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.8 | src/string.c | mrb_str_capitalize_bang - -#### chomp - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.9 | src/string.c | mrb_str_chomp - -#### chomp! - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.10 | src/string.c | mrb_str_chomp_bang - -#### chop - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.11 | src/string.c | mrb_str_chop - -#### chop! - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.12 | src/string.c | mrb_str_chop_bang - -#### downcase - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.13 | src/string.c | mrb_str_downcase - -#### downcase! - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.14 | src/string.c | mrb_str_downcase_bang - -#### empty? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.16 | src/string.c | mrb_str_empty_p - -#### eql? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.17 | src/string.c | mrb_str_eql - -#### hash - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.20 | src/string.c | mrb_str_hash_m - -#### include? - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.21 | src/string.c | mrb_str_include - -#### index - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.22 | src/string.c | mrb_str_index_m - -#### initialize - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.23 | src/string.c | mrb_str_init - -#### initialize_copy - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.24 | src/string.c | mrb_str_replace - -#### inspect - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.46 | src/string.c | mrb_str_inspect - -#### intern - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.25 | src/string.c | mrb_str_intern - -#### length - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.26 | src/string.c | mrb_str_size - -#### replace - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.28 | src/string.c | mrb_str_replace - -#### reverse - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.29 | src/string.c | mrb_str_reverse - -#### reverse! - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.30 | src/string.c | mrb_str_reverse_bang - -#### rindex - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.31 | src/string.c | mrb_str_rindex_m - -#### size - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.33 | src/string.c | mrb_str_size - -#### slice - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.34 | src/string.c | mrb_str_aref_m - -#### split - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.35 | src/string.c | mrb_str_split_m - -#### to_f - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.38 | src/string.c | mrb_str_to_f - -#### to_i - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.39 | src/string.c | mrb_str_to_i - -#### to_s - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.40 | src/string.c | mrb_str_to_s - -#### to_str - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/string.c | mrb_str_to_s - -#### to_sym - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.41 | src/string.c | mrb_str_intern - -#### upcase - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.42 | src/string.c | mrb_str_upcase - -#### upcase! - -ISO Code | Source File | C Function ---- | --- | --- -15.2.10.5.43 | src/string.c | mrb_str_upcase_bang - -## Symbol - -ISO Code | Mixins | Source File ---- | --- | --- -15.2.11 | n/a | src/symbol.c - -### Methods - -#### <=> - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/symbol.c | sym_cmp - -#### === - -ISO Code | Source File | C Function ---- | --- | --- -15.2.11.3.1 | src/symbol.c | sym_equal - -#### id2name - -ISO Code | Source File | C Function ---- | --- | --- -15.2.11.3.2 | src/symbol.c | mrb_sym_to_s - -#### inspect - -ISO Code | Source File | C Function ---- | --- | --- -15.2.11.3.5 | src/symbol.c | sym_inspect - -#### to_s - -ISO Code | Source File | C Function ---- | --- | --- -15.2.11.3.3 | src/symbol.c | mrb_sym_to_s - -#### to_sym - -ISO Code | Source File | C Function ---- | --- | --- -15.2.11.3.4 | src/symbol.c | sym_to_sym - -## SyntaxError - -ISO Code | Mixins | Source File ---- | --- | --- -15.2.38 | n/a | src/error.c - -## TrueClass - -ISO Code | Mixins | Source File ---- | --- | --- -n/a | n/a | src/object.c - -### Methods - -#### & - -ISO Code | Source File | C Function ---- | --- | --- -15.2.5.3.1 | src/object.c | true_and - -#### ^ - -ISO Code | Source File | C Function ---- | --- | --- -15.2.5.3.2 | src/object.c | true_xor - -#### inspect - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/object.c | true_to_s - -#### to_s - -ISO Code | Source File | C Function ---- | --- | --- -15.2.5.3.3 | src/object.c | true_to_s - -#### | - -ISO Code | Source File | C Function ---- | --- | --- -15.2.5.3.4 | src/object.c | true_or - -# Core Modules - -## Comparable - -ISO Code | Source File ---- | --- -15.3.3 | src/compar.c - -## Enumerable - -ISO Code | Source File ---- | --- -15.3.2 | src/enum.c - -## GC - -ISO Code | Source File ---- | --- -n/a | src/gc.c - -### Class Methods - -#### disable - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/gc.c | gc_disable - -#### enable - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/gc.c | gc_enable - -#### generational_mode - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/gc.c | gc_generational_mode_get - -#### generational_mode= - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/gc.c | gc_generational_mode_set - -#### interval_ratio - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/gc.c | gc_interval_ratio_get - -#### interval_ratio= - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/gc.c | gc_interval_ratio_set - -#### start - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/gc.c | gc_start - -#### step_ratio - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/gc.c | gc_step_ratio_get - -#### step_ratio= - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/gc.c | gc_step_ratio_set - -#### test - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/gc.c | gc_test - -## Kernel - -ISO Code | Source File ---- | --- -15.3.1 | src/kernel.c - -### Class Methods - -#### block_given? - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.2.2 | src/kernel.c | mrb_f_block_given_p_m - -#### global_variables - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.2.4 | src/kernel.c | mrb_f_global_variables - -#### iterator? - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.2.5 | src/kernel.c | mrb_f_block_given_p_m - -#### local_variables - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.2.7 | src/kernel.c | mrb_local_variables - -#### raise - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.2.12 | src/kernel.c | mrb_f_raise - -### Methods - -#### != - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/kernel.c | mrb_obj_not_equal_m - -#### == - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.1 | src/kernel.c | mrb_obj_equal_m - -#### === - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.2 | src/kernel.c | mrb_equal_m - -#### __case_eqq - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/kernel.c | mrb_obj_ceqq - -#### __id__ - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.3 | src/kernel.c | mrb_obj_id_m - -#### __send__ - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.4 | src/kernel.c | mrb_f_send - -#### block_given? - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.6 | src/kernel.c | mrb_f_block_given_p_m - -#### class - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.7 | src/kernel.c | mrb_obj_class_m - -#### clone - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.8 | src/kernel.c | mrb_obj_clone - -#### define_singleton_method - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/kernel.c | mod_define_singleton_method - -#### dup - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.9 | src/kernel.c | mrb_obj_dup - -#### eql? - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.10 | src/kernel.c | mrb_obj_equal_m - -#### equal? - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.11 | src/kernel.c | mrb_obj_equal_m - -#### extend - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.13 | src/kernel.c | mrb_obj_extend_m - -#### global_variables - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.14 | src/kernel.c | mrb_f_global_variables - -#### hash - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.15 | src/kernel.c | mrb_obj_hash - -#### initialize_copy - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.16 | src/kernel.c | mrb_obj_init_copy - -#### inspect - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.17 | src/kernel.c | mrb_obj_inspect - -#### instance_eval - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.18 | src/kernel.c | mrb_obj_instance_eval - -#### instance_of? - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.19 | src/kernel.c | obj_is_instance_of - -#### instance_variable_defined? - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.20 | src/kernel.c | mrb_obj_ivar_defined - -#### instance_variable_get - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.21 | src/kernel.c | mrb_obj_ivar_get - -#### instance_variable_set - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.22 | src/kernel.c | mrb_obj_ivar_set - -#### instance_variables - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.23 | src/kernel.c | mrb_obj_instance_variables - -#### is_a? - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.24 | src/kernel.c | mrb_obj_is_kind_of_m - -#### iterator? - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.25 | src/kernel.c | mrb_f_block_given_p_m - -#### kind_of? - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.26 | src/kernel.c | mrb_obj_is_kind_of_m - -#### local_variables - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.28 | src/kernel.c | mrb_local_variables - -#### methods - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.31 | src/kernel.c | mrb_obj_methods_m - -#### nil? - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.32 | src/kernel.c | mrb_false - -#### object_id - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.33 | src/kernel.c | mrb_obj_id_m - -#### private_methods - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.36 | src/kernel.c | mrb_obj_private_methods - -#### protected_methods - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.37 | src/kernel.c | mrb_obj_protected_methods - -#### public_methods - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.38 | src/kernel.c | mrb_obj_public_methods - -#### raise - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.40 | src/kernel.c | mrb_f_raise - -#### remove_instance_variable - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.41 | src/kernel.c | mrb_obj_remove_instance_variable - -#### respond_to? - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.43 | src/kernel.c | obj_respond_to - -#### send - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.44 | src/kernel.c | mrb_f_send - -#### singleton_class - -ISO Code | Source File | C Function ---- | --- | --- -n/a | src/kernel.c | mrb_singleton_class - -#### singleton_methods - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.45 | src/kernel.c | mrb_obj_singleton_methods_m - -#### to_s - -ISO Code | Source File | C Function ---- | --- | --- -15.3.1.3.46 | src/kernel.c | mrb_any_to_s - diff --git a/doc/language/README.md b/doc/language/README.md deleted file mode 100644 index 24dd598ac..000000000 --- a/doc/language/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Language - -mruby is an implementation of the Ruby programming language. -These documents are describing the language features and libraries -which are provided together with mruby. - -## Built-In Class and Modules - -see *doc/language/Core.md* diff --git a/doc/language/generator.rb b/doc/language/generator.rb deleted file mode 100755 index c5bab1f84..000000000 --- a/doc/language/generator.rb +++ /dev/null @@ -1,15 +0,0 @@ -#!/usr/bin/env ruby - -require 'pty' - -c_dir = File.dirname(__FILE__) -MRUBY_ROOT = File.expand_path("#{c_dir}/../..") -DOC_DIR = File.expand_path(c_dir) - -cmd = "ruby #{DOC_DIR}/mrbdoc/mrbdoc.rb #{MRUBY_ROOT} #{DOC_DIR} false" -IO.popen(cmd, "r+") do |io| - io.close_write - while line = io.gets - puts line - end -end diff --git a/doc/language/mrbdoc/lib/mrbdoc_analyze.rb b/doc/language/mrbdoc/lib/mrbdoc_analyze.rb deleted file mode 100644 index 94f368c08..000000000 --- a/doc/language/mrbdoc/lib/mrbdoc_analyze.rb +++ /dev/null @@ -1,231 +0,0 @@ -class MRBDoc - SRC_DIR = 'src' - MRBLIB_DIR = 'mrblib' - - def analyze_code dir, &block - @mrb_files = {} - @dir = File.expand_path(dir) - - block.call "MRBDOC\tanalyze #{@dir}" - - analyze(dir) do |progress| - block.call progress - end - end - - def each_file(&block); @mrb_files.each {|k,v| block.call k,v}; end - - def find_c_func(c_func_name) - each_file do |file_name, file| - c_func = file.c_funcs(c_func_name) - return c_func unless c_func.nil? - end - {} - end - - def find_c_file(rb_obj_name, c_func_name) - last_file_name_match = '' - each_file do |file_name, file| - c_func = file.c_funcs(c_func_name) - if c_func and file.rb_class(rb_obj_name) or file.rb_module(rb_obj_name) - return file_name - elsif c_func - last_file_name_match = file_name - end - end - last_file_name_match - end - - def find_c_file_by_class(name) - each_file do |file_name, file| - rb_class = file.rb_class(name) - return file_name unless rb_class.nil? - end - 'nil' - end - - def find_c_file_by_module(name) - each_file do |file_name, file| - rb_module = file.rb_module(name) - return file_name unless rb_module.nil? - end - 'nil' - end - - private - - def analyze dir, &block - collect_all_files dir, &block - end - - def collect_all_files dir, &block - l = lambda {|f| block.call " - #{f.name}"} - collect_files(src_code_dir(dir), /\.c$/, &l) - collect_files(mrb_code_dir(dir), /\.rb$/, &l) - end - - def collect_files dir, rxp, &block - Dir.foreach(dir) do |file| - next unless file =~ rxp - - file_path = "#{dir}/#{file}" - mrb_file = MRBFile.new "#{file_path}" - @mrb_files["#{file_path}"] = mrb_file - - block.call mrb_file - end - end - - def src_code_dir dir; File.expand_path SRC_DIR, dir; end - def mrb_code_dir dir; File.expand_path MRBLIB_DIR, dir; end -end - -class MRBFile - attr_reader :name - attr_reader :file - - def initialize mrb_file - @file = mrb_file - @name = File.basename file - @c_funcs = {} - @rb_class_c_def = {} - @rb_method_c_def = {} - @rb_class_method_c_def = {} - @rb_module_c_def = {} - @last_line = nil - @assignments = {} - - @assignments['mrb->object_class'] = 'Object' - @assignments['mrb->kernel_module'] = 'Kernel' - @assignments['mrb->module_class'] = 'Module' - @assignments['mrb->nil_class'] = 'NilClass' - @assignments['mrb->true_class'] = 'TrueClass' - @assignments['mrb->class_class'] = 'Class' - - analyze - end - - def each_class &block - @rb_class_c_def.each do |class_name, class_hsh| - block.call class_name, class_hsh - end - end - - def each_method name, &block - @rb_method_c_def.each do |met_name, met_hsh| - met_name_tmp = met_name.sub /^#{name}_/, '' - block.call met_name_tmp, met_hsh if met_hsh[:rb_class] == name - end - end - - def each_class_method name, &block - @rb_class_method_c_def.each do |met_name, met_hsh| - met_name_tmp = met_name.sub /^#{name}_/, '' - block.call met_name_tmp, met_hsh if met_hsh[:rb_class] == name - end - end - - def each_module &block - @rb_module_c_def.each do |module_name, module_hsh| - block.call module_name, module_hsh - end - end - - def each_core_object &block - each_class {|n| block.call n} - each_module {|n| block.call n} - end - - def c_funcs c_func_name; @c_funcs[c_func_name]; end - def rb_class rb_class_name; @rb_class_c_def[rb_class_name]; end - def rb_module rb_module_name; @rb_module_c_def[rb_module_name]; end - - private - - def analyze - File.open(file).each_line.each_with_index do |line, idx| - line_no = idx.succ - if c_file? - analyze_c_line line, line_no - elsif rb_file? - analyze_rb_line line, line_no - else - raise ArgumentError.new "#{file} is a not supported file type" - end - @last_line = line.strip - end - end - - def c_file?; (name =~ /\.c$/); end - def rb_file?; (name =~ /\.rb$/); end - - RXP_C_VAR = /\s*([^\s]*?)\s*?/ - RXP_C_STR = /\s*?\"(.*?)\"\s*?/ - #RXP_C_ISO = /\s*\;\s*[\/\*]*\s*.*?([15\.]{0,3}[0-9\.]*)\s*[\\\\\*]*/ - RXP_C_ISO = /\s*;\s*[\/\*]*[\sa-zA-Z]*([\d\.]*)[\sa-zA-Z]*[\*\/]*/ - - def analyze_c_line line, line_no - case line.strip - when /^([a-zA-Z\_][a-zA-Z\_0-9]*?)\((.*?)\)\s*?$/ - # assuming c method definition - @c_funcs[$1] = {:line_no => line_no, :args => $2, :return => @last_line} - when /mrb_define_class\(.*?\,#{RXP_C_STR}\,#{RXP_C_VAR}\)#{RXP_C_ISO}/ - # assuming ruby class definition in c - class_name = $1.clone - iso = $3.clone - iso.strip! - @rb_class_c_def[class_name] = {:c_object => $2, :iso => iso} - assigns = line.split '=' - if assigns.size > 1 - assigns[0..-2].each do |v| - @assignments[v.strip] = class_name - end - end - when /mrb_define_module\(.*?\,#{RXP_C_STR}\)#{RXP_C_ISO}/ - # assuming ruby class definition in c - module_name = $1.clone - iso = $2.clone - iso.strip! - @rb_module_c_def[module_name] = {:iso => iso} - assigns = line.split '=' - if assigns.size > 1 - assigns[0..-2].each do |v| - @assignments[v.strip] = module_name - end - end - when /mrb_define_method\(.*?\,#{RXP_C_VAR}\,#{RXP_C_STR}\,#{RXP_C_VAR}\,#{RXP_C_VAR}\)#{RXP_C_ISO}/ - # assuming ruby method definition in c - name = $1.clone - name = resolve_obj(name) - iso = $5.clone - iso.strip! - @rb_method_c_def["#{name}_#{$2}"] = {:c_func => $3, :args => $4, :rb_class => name, :iso => iso} - when /mrb_define_class_method\(.*?\,#{RXP_C_VAR}\,#{RXP_C_STR}\,#{RXP_C_VAR}\,#{RXP_C_VAR}\)#{RXP_C_ISO}/ - # assuming ruby class method definition in c - class_name = $1.clone - class_name = resolve_obj(class_name) - iso = $5.clone - iso.strip! - @rb_class_method_c_def["#{class_name}_#{$2}"] = {:c_func => $3, :args => $4, :rb_class => class_name, :iso => iso} - when /mrb_name_class\(.*?\,#{RXP_C_VAR}\,\s*mrb_intern\(.*?,#{RXP_C_STR}\)\)#{RXP_C_ISO}/ - class_name = $2.clone - iso = $3.clone - iso.strip! - @rb_class_c_def[class_name] = {:c_object => $1, :iso => iso} - @assignments[$1] = class_name - when /mrb_include_module\(.*?\,#{RXP_C_VAR}\,\s*mrb_class_get\(.*?\,#{RXP_C_STR}\)\)/ - class_name = resolve_obj($1) - mod = $2.clone - @rb_class_c_def[class_name][:include] = [] unless @rb_class_c_def[class_name].has_key? :include - @rb_class_c_def[class_name][:include] << mod - end - end - - def analyze_rb_line line, line_no - - end - - def resolve_obj c_var - @assignments[c_var] - end -end diff --git a/doc/language/mrbdoc/lib/mrbdoc_docu.rb b/doc/language/mrbdoc/lib/mrbdoc_docu.rb deleted file mode 100644 index f6f327804..000000000 --- a/doc/language/mrbdoc/lib/mrbdoc_docu.rb +++ /dev/null @@ -1,118 +0,0 @@ -class MRBDoc - def write_documentation dir, cfg, &block - block.call "MRBDOC\twrite to #{File.expand_path(dir)}" - - write(dir, cfg) do |progress| - block.call progress - end - end - - private - - def write dir, cfg - File.open(File.expand_path('Core.md', dir), 'wb+') do |io| - print_core_classes(io, cfg) - print_core_modules(io, cfg) - end - end - - def get_core_list id - core_list = {} - each_file do |file_path, mrb_file| - mrb_file.send(id) do |name, cls_hsh| - core_list[name] = {:data => cls_hsh, :methods => {}, :class_methods => {}} - mrb_file.each_method name do |met_name, met_hsh| - core_list[name][:methods][met_name] = met_hsh - end - mrb_file.each_class_method name do |met_name, met_hsh| - core_list[name][:class_methods][met_name] = met_hsh - end - end - end - core_list - end - - def print_core_classes(io, cfg) - core_list = get_core_list :each_class - io.puts "# Core Classes\n\n" - core_list.sort.each do |name, hsh| - file = find_c_file_by_class(name) - file = file.split("#{@dir}/")[1] - iso = hsh[:data][:iso] - iso = 'n/a' if iso.nil? or iso == '' - mixins = hsh[:data][:include].join(', ') unless hsh[:data][:include].nil? - mixins = 'n/a' if mixins.nil? or mixins == '' - - io.puts < 0 - io.puts "### Methods\n\n" - hsh[:methods].sort.each do |met_name, met_hsh| - print_method(io, met_name, met_hsh, cfg) - end - end - - def print_class_methods(io, hsh, cfg) - return unless hsh[:class_methods].size > 0 - io.puts "### Class Methods\n\n" - hsh[:class_methods].sort.each do |met_name, met_hsh| - print_method(io, met_name, met_hsh, cfg) - end - end - - def print_method(io, met_name, met_hsh, cfg) - if cfg[:print_line_no] - line_no_head = ' | Line' - line_no = " | #{find_c_func(met_hsh[:c_func])[:line_no]}" - else - line_no, line_no_head = '', '' - end - file = find_c_file(met_hsh[:rb_class], met_hsh[:c_func]) - file = file.split("#{@dir}/")[1] - iso = met_hsh[:iso] - iso = 'n/a' if iso.nil? or iso == '' - - io.puts < WRITE_LINE_NO} -mrbdoc.write_documentation DOC_ROOT, cfg do |progress| - puts progress -end diff --git a/doc/mrbconf/README.md b/doc/mrbconf/README.md deleted file mode 100644 index dfff41898..000000000 --- a/doc/mrbconf/README.md +++ /dev/null @@ -1,160 +0,0 @@ -# mruby configuration macros. - -## How to use these macros. -You can use mrbconfs with following ways: -* Write them in `mrbconf.h`. - * Using compiler flags is preferred when building a cross binaries or multiple mruby binaries - since it's easier to use different mrbconf per each `MRuby::Build`. - * Most flags can be enabled by just commenting in. -* Pass them as compiler flags. - * Make sure you pass the same flags to all compilers since some mrbconf(e.g., `MRB_GC_FIXED_ARENA`) - changes `struct` layout and cause memory access error when C and other language(e.g., C++) is mixed. - -## stdio setting. -`ENABLE_STDIO` -* Will be defined automatically if `DISABLE_STDIO` isn't defined. -* Uses `` functions. - -`DISABLE_STDIO` -* When defined `` functions won't be used. -* Some features will be disabled when this is enabled: - * `mrb_irep` load/dump from/to file. - * Compiling mruby script from file. - * Printing features in **src/print.c**. - -## Debug macros. -`ENABLE_DEBUG` -* When defined code fetch hook and debug OP hook will be enabled. -* When using any of the hook set function pointer `code_fetch_hook` and/or `debug_op_hook` of `mrb_state`. -* Fetch hook will be called before any OP. -* Debug OP hook will be called when dispatching `OP_DEBUG`. - -`DISABLE_DEBUG` -* Will be define automatically if `ENABLE_DEBUG` isn't defined. - -`MRB_DEBUG` -* When defined `mrb_assert*` macro will be defined with macros from ``. -* Could be enabled via `enable_debug` method of `MRuby::Build`. - -## Stack configuration - -`MRB_STACK_EXTEND_DOUBLING` -* If defined doubles the stack size when extending it. -* Else extends stack with `MRB_STACK_GROWTH`. - -`MRB_STACK_GROWTH` -* Default value is `128`. -* Used in stack extending. -* Ignored when `MRB_STACK_EXTEND_DOUBLING` is defined. - -`MRB_STACK_MAX` -* Default value is `0x40000 - MRB_STACK_GROWTH`. -* Raises `RuntimeError` when stack size exceeds this value. - -## Primitive type configuration. - -`MRB_USE_FLOAT` -* When defined single precision floating point type(C type `float`) is used as `mrb_float`. -* Else double precision floating point type(C type `double`) is used as `mrb_float`. - -`MRB_INT16` -* When defined `int16_t` will be defined as `mrb_int`. -* Conflicts with `MRB_INT64`. - -`MRB_INT64` -* When defined `int64_t` will be defined as `mrb_int`. -* Conflicts with `MRB_INT16`. -* When `MRB_INT16` or `MRB_INT64` isn't defined `int`(most of the times 32-bit integer) -will be defined as `mrb_int`. - -## Garbage collector configuration. - -`MRB_GC_STRESS` -* When defined full GC is emitted per each `RBasic` allocation. -* Mainly used in memory manager debugging. - -`MRB_GC_TURN_OFF_GENERATIONAL` -* When defined turns generational GC by default. - -`MRB_GC_FIXED_ARENA` -* When defined used fixed size GC arena. -* Raises `RuntimeError` when this is defined and GC arena size exceeds `MRB_GC_ARENA_SIZE`. -* Useful tracking unnecessary mruby object allocation. - -`MRB_GC_ARENA_SIZE` -* Default value is `100`. -* Ignored when `MRB_GC_FIXED_ARENA` isn't defined. -* Defines fixed GC arena size. - -`MRB_HEAP_PAGE_SIZE` -* Defines value is `1024`. -* Specifies number of `RBasic` per each heap page. - -## Memory pool configuration. - -`POOL_ALIGNMENT` -* Default value is `4`. -* If you're allocating data types that requires alignment more than default value define the -largest value of required alignment. - -`POOL_PAGE_SIZE` -* Default value is `16000`. -* Specifies page size of pool page. -* Smaller the value is increases memory overhead. - -## State atexit configuration. - -`MRB_FIXED_STATE_ATEXIT_STACK` -* If defined enables fixed size `mrb_state` atexit stack. -* Raises `RuntimeError` when `mrb_state_atexit` call count to same `mrb_state` exceeds -`MRB_FIXED_STATE_ATEXIT_STACK_SIZE`'s value. - -`MRB_FIXED_STATE_ATEXIT_STACK_SIZE` -* Default value is `5`. -* If `MRB_FIXED_STATE_ATEXIT_STACK` isn't defined this macro is ignored. - -## `mrb_value` configuration. - -`MRB_ENDIAN_BIG` -* If defined compiles mruby for big endian machines. -* Used in `MRB_NAN_BOXING`. -* Some mrbgem use this mrbconf. - -`MRB_NAN_BOXING` -* If defined represent `mrb_value` in boxed `double`. -* Conflicts with `MRB_USE_FLOAT`. - -`MRB_WORD_BOXING` -* If defined represent `mrb_value` as a word. -* If defined `Float` will be a mruby object with `RBasic`. - -## Instance variable configuration. -`MRB_USE_IV_SEGLIST` -* If defined enable segmented list in instance variable table instead of khash. -* Segmented list is a linked list of key and value segments. -* It will linear search instead of hash search. - -`MRB_SEGMENT_SIZE` -* Default value is `4`. -* Specifies size of each segment in segment list. -* Ignored when `MRB_USE_IV_SEGLIST` isn't defined. - -`MRB_IVHASH_INIT_SIZE` -* Default value is `8`. -* Specifies initial size for instance variable table. -* Ignored when `MRB_USE_IV_SEGLIST` is defined. - -## Other configuration. -`MRB_FUNCALL_ARGC_MAX` -* Default value is `16`. -* Specifies 4th argument(`argc`) max value of `mrb_funcall`. -* Raises `ArgumentError` when the `argc` argument is bigger then this value `mrb_funcall`. - -`KHASH_DEFAULT_SIZE` -* Default value is `32`. -* Specifies default size of khash table bucket. -* Used in `kh_init_ ## name` function. - -`MRB_STR_BUF_MIN_SIZE` -* Default value is `128`. -* Specifies initial capacity of `RString` created by `mrb_str_buf_new` function.. diff --git a/doc/mrbgems/README.md b/doc/mrbgems/README.md deleted file mode 100644 index f75231f71..000000000 --- a/doc/mrbgems/README.md +++ /dev/null @@ -1,337 +0,0 @@ -# mrbgems - -mrbgems is a library manager to integrate C and Ruby extension in an easy and -standardised way into mruby. - -## Usage - -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: -```ruby -conf.gem '/path/to/your/gem/dir' -``` - -You can also use a relative path which would be relative from the mruby root: -```ruby -conf.gem 'examples/mrbgems/ruby_extension_example' -``` - -A remote GIT repository location for a GEM is also supported: -```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 use mrbgem from [mgem-list](https://github.com/mruby/mgem-list) use `:mgem` option: -```ruby -conf.gem :mgem => 'mruby-yaml' -conf.gem :mgem => 'yaml' # 'mruby-' prefix could be omitted -``` - -If there is missing dependencies, mrbgem dependencies solver will reference -mrbgem from core or mgem-list. - -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. - -## GemBox - -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*: -```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 -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: -```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 an absolute path like below. -```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 -contains several core components of mruby, and [full-core](../../mrbgems/full-core.gembox) -contains every gem found in the *mrbgems* directory. - -## GEM Structure - -The maximal GEM structure looks like this: - - +- GEM_NAME <- Name of GEM - | - +- include/ <- Header for Ruby extension (will exported) - | - +- 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/C++ files to extend mruby. The folder *include* contains C/C++ header -files. The folder *test* contains C/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. - -## Build process - -mrbgems expects a specification file called *mrbgem.rake* inside of your -GEM directory. A typical GEM specification could look like this for example: -```ruby -MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec| - spec.license = 'MIT' - spec.author = 'mruby developers' - spec.summary = 'Example mrbgem using C and ruby' -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` - * One line short description of mrbgem. - * Printed in build summary of rake when set. -* `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[, default_get_info])` like: -```ruby -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') - - # 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 omitted) - spec.add_dependency('mruby-onig-regexp', :github => 'mattn/mruby-onig-regexp') -end -``` - -The version requirements and default gem information are optional. - -Version requirement supports following operators: -* '=': is equal -* '!=': is not equal -* '>': is greater -* '<': is lesser -* '>=': is equal or greater -* '<=': is equal or lesser -* '~>': is equal or greater and is lesser than the next major version - * example 1: '~> 2.2.2' means '>= 2.2.2' and '< 2.3.0' - * example 2: '~> 2.2' means '>= 2.2.0' and '< 3.0.0' - -When more than one version requirements is passed, the dependency must satisfy all of it. - -You can have default gem to use as depedency when it's not defined in *build_config.rb*. -When the last argument of `add_dependency` call is `Hash`, it will be treated as default gem information. -Its format is same as argument of method `MRuby::Build#gem`, expect that it can't be treated as path gem location. - -When a special version of depedency is required, -use `MRuby::Build#gem` in *build_config.rb* to override default gem. - -If you have conflicting GEMs use the following method: -* `spec.add_conflict(gem, *requirements)` - * 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' - - 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: - -* `spec.cc.flags` (C compiler flags) -* `spec.cc.defines` (C compiler defines) -* `spec.cc.include_paths` (C compiler include paths) -* `spec.linker.flags` (Linker flags) -* `spec.linker.libraries` (Linker libraries) -* `spec.linker.library_paths` (Linker additional library path) -* `spec.bins` (Generate binary file) -* `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) - -You also can use `spec.mruby.cc` and `spec.mruby.linker` to add extra global parameters for compiler and linker. - -### include_paths and dependency - -Your GEM can export include paths to another GEMs that depends on your GEM. -By default, `/...absolute path.../{GEM_NAME}/include` will be exported. -So it is recommended not to put GEM's local header files on include/. - -These exports are retroactive. -For example: when B depends to C and A depends to B, A will get include paths exported by C. - -Exported include_paths are automatically appended to GEM local include_paths by Minirake. -You can use `spec.export_include_paths` accessor if you want more complex build. - - -## C Extension - -mruby can be extended with C. This is possible by using the C API to -integrate C libraries into mruby. - -### Preconditions - -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: -```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 - -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: - -```C -void -mrb_c_extension_example_gem_final(mrb_state* mrb) { - free(someone); -} -``` - -### Example - - +- c_extension_example/ - | - +- src/ - | | - | +- example.c <- C extension source - | - +- test/ - | | - | +- example.rb <- Test code for C extension - | - +- mrbgem.rake <- GEM specification - | - +- README.md - -## Ruby Extension - -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. - - -### Pre-Conditions - -none - -### Example - - +- ruby_extension_example/ - | - +- mrblib/ - | | - | +- example.rb <- Ruby extension source - | - +- test/ - | | - | +- example.rb <- Test code for Ruby extension - | - +- mrbgem.rake <- GEM specification - | - +- README.md - -## C and Ruby Extension - -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. - -mruby codes under *mrblib* directory would be executed after gem init C -function is called. Make sure *mruby script* depends on *C code* and -*C code* doesn't depend on *mruby script*. - -### Pre-Conditions - -See C and Ruby example. - -### 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.md diff --git a/guides/compile.md b/guides/compile.md new file mode 100644 index 000000000..8e91e7546 --- /dev/null +++ b/guides/compile.md @@ -0,0 +1,481 @@ +# Compile + +mruby uses Rake to compile and cross-compile all libraries and +binaries. + +## Prerequisites + +To compile mruby out of the source code you need the following tools: +* C Compiler (i.e. ```gcc```) +* Linker (i.e. ```gcc```) +* Archive utility (i.e. ```ar```) +* Parser generator (i.e. ```bison```) +* Ruby 1.8 or 1.9 (i.e. ```ruby``` or ```jruby```) + +Optional: +* GIT (to update mruby source and integrate mrbgems easier) +* C++ compiler (to use GEMs which include \*.cpp, \*.cxx, \*.cc) +* Assembler (to use GEMs which include \*.asm) + +## Usage + +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: +```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 +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```. + +## Build Configuration + +Inside of the *build_config.rb* the following options can be configured +based on your environment. + +### Toolchains + +The mruby build system already contains a set of toolchain templates which +configure the build environment for specific compiler infrastructures. + +#### GCC + +Toolchain configuration for the GNU C Compiler. +```ruby +toolchain :gcc +``` + +#### clang + +Toolchain configuration for the LLVM C Compiler clang. Mainly equal to the +GCC toolchain. +```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 +``` + +#### Android + +Toolchain configuration for Android. +```ruby +toolchain :androideabi +``` + +Requires the custom standalone Android NDK and the toolchain path +in ```ANDROID_STANDALONE_TOOLCHAIN```. + +### Binaries + +It is possible to select which tools should be compiled during the compilation +process. The following tools can be selected: +* mruby (mruby interpreter) +* mirb (mruby interactive shell) + +To select them declare conf.gem as follows: +```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```. +```ruby +conf.file_separator = '/' +``` + +### C Compiler + +Configuration of the C compiler binary, flags and include paths. +```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```: +```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```: +```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: +```ruby +def conf.cc.header_search_paths + ['/opt/local/include'] + include_paths +end +``` + +### Linker + +Configuration of the Linker binary, flags and library paths. +```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. +```ruby +conf.archiver do |archiver| + archiver.command = ... + archiver.archive_options = ... +end +``` + +### Parser Generator + +Configuration of the Parser Generator binary and flags. +```ruby +conf.yacc do |yacc| + yacc.command = ... + yacc.compile_options = ... +end +``` + +### GPerf + +Configuration of the GPerf binary and flags. +```ruby +conf.gperf do |gperf| + gperf.command = ... + gperf.compile_options = ... +end +``` + +### File Extensions +```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 without additional configuration +conf.gem 'path/to/another/gem' +``` + +See doc/mrbgems/README.md for more option about mrbgems. + +### Mrbtest + +Configuration Mrbtest build process. + +If you want mrbtest.a only, You should set ```conf.build_mrbtest_lib_only``` +```ruby +conf.build_mrbtest_lib_only +``` + +### Bintest + +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: +```ruby +conf.enable_bintest +``` + +### C++ ABI + +mruby can use C++ exception to raise exception internally. +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 explicitly add the following: +```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: +```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: +```ruby +conf.enable_debug +``` + +When debugging mode is enabled +* Macro ```MRB_DEBUG``` would be defined. + * Which means ```mrb_assert()``` macro is enabled. +* Debug information of irep would be generated by ```mrbc```. + * Because ```-g``` flag would be added to ```mrbc``` runner. + * You can have better backtrace of mruby scripts with this. + +## Cross-Compilation + +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: +```ruby +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```. + +### Mrbtest in Cross-Compilation + +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 + + 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 + +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: +* 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* + +``` + _____ _____ ______ ____ ____ _____ _____ ____ +| CC |->|GEN |->|AR |->|CC |->|CC |->|AR |->|CC |->|CC | +| *.c | |y.tab| |core.a| |mrbc| |*.rb| |lib.a| |mruby| |mirb| + ----- ----- ------ ---- ---- ----- ----- ---- +``` + +### Cross-Compilation + +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 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* + +``` + _______________________________________________________________ +| Native Compilation for Host System | +| _____ ______ _____ ____ ____ _____ | +| | CC | -> |AR | -> |GEN | -> |CC | -> |CC | -> |AR | | +| | *.c | |core.a| |y.tab| |mrbc| |*.rb| |lib.a| | +| ----- ------ ----- ---- ---- ----- | + --------------------------------------------------------------- + || + \||/ + \/ + ________________________________________________________________ +| Cross Compilation for Target System | +| _____ _____ _____ ____ ______ _____ | +| | CC | -> |AR | -> |CC | -> |CC | -> |AR | -> |CC | | +| | *.c | |lib.a| |mruby| |mirb| |core.a| |mrbc | | +| ----- ----- ----- ---- ------ ----- | + ---------------------------------------------------------------- +``` + +## Build Configuration Examples + +### Minimal Library + +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. + +```ruby +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). + +## 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 +generated. You can copy this binary and run on your target system. diff --git a/guides/debugger.md b/guides/debugger.md new file mode 100755 index 000000000..a13e91cec --- /dev/null +++ b/guides/debugger.md @@ -0,0 +1,370 @@ +# How to Use the mruby Debugger + +copyright (c) 2014 Specified Non-Profit Corporation mruby Forum + +## 1. Summary + +This file documents the mruby debugger ('mrdb') methods. + +## 2 Debugging with mrdb + +## 2.1 Building mrdb + +The trunk of the mruby source tree, with the most recent mrdb, can be checked out with the following command: + +```bash +$ git clone https://github.com/mruby/mruby.git +``` + +To run the `make` command: + +```bash +$ cd mruby +$ make +``` + +By default, the `make` command will install the debugger files into mruby/bin. + +You can add the path for mrdb on your host environment with the following command: + +```bash +$ echo "export PATH=\$PATH:MRUBY_ROOT/bin" >> ~/.bashrc +$ source ~/.bashrc +``` + +`*MRUBY_ROOT` is the directory in which mruby source code will be installed. + +To confirm mrdb was installed properly, run mrdb with the `--version` option: + +```bash +$ mrdb --version +mruby 1.1.0 (2014-11-19) +``` + +## 2.2 Basic Operation + +### 2.2.1 Debugging mruby Script Files (rb file) with mrdb + +To invoke the mruby debugger, just type `mrdb`. + +To specify the script file: + +```bash +$ mrdb [option] file name +``` + +For example: Debugging sample.rb + +```bash +$ mrdb sample.rb +``` + +You can execute the shell commands listed below: + +|command|description| +|:-:|:--| +|run|execute programs| +|step|execute stepping| +|continue|execute continuing program| +|break|configure the breaking point| +|delete|deleting the breaking points| +|disable|disabling the breaking points| +|enable|enabling the breaking points| +|info breakpoints|showing list of the breaking points| +|print|evaluating and printing the values of the mruby expressions in the script| +|list|displaying the source cords| +|help|showing help| +|quit|terminating the mruby debugger| + +### 2.2.2 Debugging mruby Binary Files (mrb file) with mrdb + +You can debug the mruby binary files. + +#### 2.2.2.1 Debugging the binary files + +* notice +To debug mruby binary files, you need to compile mruby files with option `-g`. + +```bash +$ mrbc -g sample.rb +``` + +You can debug the mruby binary files with following command and the option `-b`. + +```bash +$ mrdb -b sample.mrb +``` + +Then you can execute all debugger shell commands. + +#### Break Command + +You can use any breakpoint to stop the program by specifying the line number and method name. +The breakpoint list will be displayed after you have set the breakpoint successfully. + +Usage: + +``` +break [file:]linenum +b [file:]linenum +break [class:]method +b [class:]method +``` + +The breakpoint will be ordered in serial from 1. +The number, which was given to the deleted breakpoint, will never be given to another breakpoint again. + +You can give multiple breakpoints to specified the line number and method. +Be ware that breakpoint command will not check the validity of the class name and method name. + +You can get the current breakpoint information by the following options. + +breakpoint breakpoint number : file name. line number + +breakpoint breakpoint number : [class name,] method name + +#### Continue Command + +Usage: + +``` +continue [N] +c [N] +``` + +N: the next breakpoint number + +When resuming the program, it will stop at breakpoint N (N-1 breakpoint will be ignored). + +When you run the `continue` command without specifying N, the program will be stopped at the next breakpoint. + +Example: + +``` +(foo.rb:1) continue 3 +``` + +This will resume the program and stop it at the third breakpoint. + +#### Delete Command + +This will delete the specified breakpoint. + +Usage: + +``` +delete [breakpoint-no] +d [breakpoint-no] +``` + +breakpoint-no: breakpoint number + +Example: + +``` +(foo.rb:1) delete +``` + +This will delete all of the breakpoints. + +``` +(foo.rb:1) delete 1 3 +``` + +This will delete the breakpoint at 1 and 3. + +#### Disable Command + +This will disable the specified breakpoint. + +Usage: + +``` +disable [breakpoint-no] +dis [breakpoint-no] +``` + +reappointing: breakpoint number + +Example: + +``` +(foo.rb:1) disable +``` + +Use `disable` if you would like to disable all of the breakpoints. + +``` +(foo.rb:1) disable 1 3 +``` + +This will disable the breakpoints at 1 and 3. + +#### Enable Command + +This will enable the specified breakpoints. + +Usage: + +``` +enable [breakpoint-no] +e [breakpoint-no] +``` + +breakpoint-no: breakpoint number + +Example: + +``` +(foo.rb:1) enable +``` + +Enabling all breakpoints +``` +(foo.rb:1) enable 1 3 +``` + +Enabling the breakpoint 1 and 3 + +#### eval command + +Evaluating the string as source code and printing the value. + +Same as print command, please see print command. + +#### help command + +Displaying the help message. + +Usage: + +``` +help [command] +h [command] +``` + +Typing `help` without any options will display the command list. + +#### Info Breakpoints Command + +Displaying the specified breakpoint information. + +Usage: + +``` +info breakpoints [breakpoint-no] +i b [breakpoint-no] +``` + +breakpoint-no: breakpoint number + +Typing "info breakpoints" without ant option will display all breakpoint information. +Example: + +``` +(sample.rb:1) info breakpoints +Num Type Enb What +1 breakpoint y at sample.rb:3 -> file name,line number +2 breakpoint n in Sample_class:sample_class_method -> [class:]method name +3 breakpoint y in sample_global_method +``` + +Displaying the specified breakpoint number: + +``` +(foo.rb:1) info breakpoints 1 3 +Num Type Enb What +1 breakpoint y at sample.rb:3 +3 breakpoint y in sample_global_method +``` + +#### List Command + +To display the code of the source file. + +Usage: + +``` +list [filename:]first[,last] +l [filename]:first[,last] +``` + +first: the opening row number +last : the closing row number + +When you specify the `first`, but not the `last` option, you will receive 10 rows. +When you do not specify both the `first` and `last` options, you will receive the next 10 rows. + +Example: + +``` +Specifying file name and first row number +sample.rb:1) list sample2.rb:5 +``` + +Specifying the file name and the first and last row number: + +``` +(sample.rb:1) list sample2.rb:6,7 +``` + +#### Print Command + +Evaluating the string as source code and printing the value. + +Usage: + +``` +print [expr] +p [expr] +``` + +expr: expression + +The expression is mandatory. +The displayed expressions will be serially ordered from 1. +If an exception occurs, the exception information will be displayed and the debugging will be continued. + +Example: + +``` +(sample.rb:1) print 1+2 +$1 = 3 +(sample.rb:1) print self +$2 = main +``` + +Below is the case of the exception: + +``` +(sample.rb:1) print (1+2 +$1 = SyntaxError: line 1: syntax error, unexpected $end, expecting ')' +``` + +#### Quit Command + +Quitting the debugger. + +Usage: + +``` +quit +q +``` + +#### Run Command + +Running the program and stopping at the first breakpoint. + +Usage: + +``` +run +r +``` + +#### Step Command + +This will run the program step by step. +When the method and the block are invoked, the program will be stop at the first row. +The program, which is developed in C, will be ignored. diff --git a/guides/mrbconf.md b/guides/mrbconf.md new file mode 100644 index 000000000..dfff41898 --- /dev/null +++ b/guides/mrbconf.md @@ -0,0 +1,160 @@ +# mruby configuration macros. + +## How to use these macros. +You can use mrbconfs with following ways: +* Write them in `mrbconf.h`. + * Using compiler flags is preferred when building a cross binaries or multiple mruby binaries + since it's easier to use different mrbconf per each `MRuby::Build`. + * Most flags can be enabled by just commenting in. +* Pass them as compiler flags. + * Make sure you pass the same flags to all compilers since some mrbconf(e.g., `MRB_GC_FIXED_ARENA`) + changes `struct` layout and cause memory access error when C and other language(e.g., C++) is mixed. + +## stdio setting. +`ENABLE_STDIO` +* Will be defined automatically if `DISABLE_STDIO` isn't defined. +* Uses `` functions. + +`DISABLE_STDIO` +* When defined `` functions won't be used. +* Some features will be disabled when this is enabled: + * `mrb_irep` load/dump from/to file. + * Compiling mruby script from file. + * Printing features in **src/print.c**. + +## Debug macros. +`ENABLE_DEBUG` +* When defined code fetch hook and debug OP hook will be enabled. +* When using any of the hook set function pointer `code_fetch_hook` and/or `debug_op_hook` of `mrb_state`. +* Fetch hook will be called before any OP. +* Debug OP hook will be called when dispatching `OP_DEBUG`. + +`DISABLE_DEBUG` +* Will be define automatically if `ENABLE_DEBUG` isn't defined. + +`MRB_DEBUG` +* When defined `mrb_assert*` macro will be defined with macros from ``. +* Could be enabled via `enable_debug` method of `MRuby::Build`. + +## Stack configuration + +`MRB_STACK_EXTEND_DOUBLING` +* If defined doubles the stack size when extending it. +* Else extends stack with `MRB_STACK_GROWTH`. + +`MRB_STACK_GROWTH` +* Default value is `128`. +* Used in stack extending. +* Ignored when `MRB_STACK_EXTEND_DOUBLING` is defined. + +`MRB_STACK_MAX` +* Default value is `0x40000 - MRB_STACK_GROWTH`. +* Raises `RuntimeError` when stack size exceeds this value. + +## Primitive type configuration. + +`MRB_USE_FLOAT` +* When defined single precision floating point type(C type `float`) is used as `mrb_float`. +* Else double precision floating point type(C type `double`) is used as `mrb_float`. + +`MRB_INT16` +* When defined `int16_t` will be defined as `mrb_int`. +* Conflicts with `MRB_INT64`. + +`MRB_INT64` +* When defined `int64_t` will be defined as `mrb_int`. +* Conflicts with `MRB_INT16`. +* When `MRB_INT16` or `MRB_INT64` isn't defined `int`(most of the times 32-bit integer) +will be defined as `mrb_int`. + +## Garbage collector configuration. + +`MRB_GC_STRESS` +* When defined full GC is emitted per each `RBasic` allocation. +* Mainly used in memory manager debugging. + +`MRB_GC_TURN_OFF_GENERATIONAL` +* When defined turns generational GC by default. + +`MRB_GC_FIXED_ARENA` +* When defined used fixed size GC arena. +* Raises `RuntimeError` when this is defined and GC arena size exceeds `MRB_GC_ARENA_SIZE`. +* Useful tracking unnecessary mruby object allocation. + +`MRB_GC_ARENA_SIZE` +* Default value is `100`. +* Ignored when `MRB_GC_FIXED_ARENA` isn't defined. +* Defines fixed GC arena size. + +`MRB_HEAP_PAGE_SIZE` +* Defines value is `1024`. +* Specifies number of `RBasic` per each heap page. + +## Memory pool configuration. + +`POOL_ALIGNMENT` +* Default value is `4`. +* If you're allocating data types that requires alignment more than default value define the +largest value of required alignment. + +`POOL_PAGE_SIZE` +* Default value is `16000`. +* Specifies page size of pool page. +* Smaller the value is increases memory overhead. + +## State atexit configuration. + +`MRB_FIXED_STATE_ATEXIT_STACK` +* If defined enables fixed size `mrb_state` atexit stack. +* Raises `RuntimeError` when `mrb_state_atexit` call count to same `mrb_state` exceeds +`MRB_FIXED_STATE_ATEXIT_STACK_SIZE`'s value. + +`MRB_FIXED_STATE_ATEXIT_STACK_SIZE` +* Default value is `5`. +* If `MRB_FIXED_STATE_ATEXIT_STACK` isn't defined this macro is ignored. + +## `mrb_value` configuration. + +`MRB_ENDIAN_BIG` +* If defined compiles mruby for big endian machines. +* Used in `MRB_NAN_BOXING`. +* Some mrbgem use this mrbconf. + +`MRB_NAN_BOXING` +* If defined represent `mrb_value` in boxed `double`. +* Conflicts with `MRB_USE_FLOAT`. + +`MRB_WORD_BOXING` +* If defined represent `mrb_value` as a word. +* If defined `Float` will be a mruby object with `RBasic`. + +## Instance variable configuration. +`MRB_USE_IV_SEGLIST` +* If defined enable segmented list in instance variable table instead of khash. +* Segmented list is a linked list of key and value segments. +* It will linear search instead of hash search. + +`MRB_SEGMENT_SIZE` +* Default value is `4`. +* Specifies size of each segment in segment list. +* Ignored when `MRB_USE_IV_SEGLIST` isn't defined. + +`MRB_IVHASH_INIT_SIZE` +* Default value is `8`. +* Specifies initial size for instance variable table. +* Ignored when `MRB_USE_IV_SEGLIST` is defined. + +## Other configuration. +`MRB_FUNCALL_ARGC_MAX` +* Default value is `16`. +* Specifies 4th argument(`argc`) max value of `mrb_funcall`. +* Raises `ArgumentError` when the `argc` argument is bigger then this value `mrb_funcall`. + +`KHASH_DEFAULT_SIZE` +* Default value is `32`. +* Specifies default size of khash table bucket. +* Used in `kh_init_ ## name` function. + +`MRB_STR_BUF_MIN_SIZE` +* Default value is `128`. +* Specifies initial capacity of `RString` created by `mrb_str_buf_new` function.. diff --git a/guides/mrbgems.md b/guides/mrbgems.md new file mode 100644 index 000000000..f75231f71 --- /dev/null +++ b/guides/mrbgems.md @@ -0,0 +1,337 @@ +# mrbgems + +mrbgems is a library manager to integrate C and Ruby extension in an easy and +standardised way into mruby. + +## Usage + +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: +```ruby +conf.gem '/path/to/your/gem/dir' +``` + +You can also use a relative path which would be relative from the mruby root: +```ruby +conf.gem 'examples/mrbgems/ruby_extension_example' +``` + +A remote GIT repository location for a GEM is also supported: +```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 use mrbgem from [mgem-list](https://github.com/mruby/mgem-list) use `:mgem` option: +```ruby +conf.gem :mgem => 'mruby-yaml' +conf.gem :mgem => 'yaml' # 'mruby-' prefix could be omitted +``` + +If there is missing dependencies, mrbgem dependencies solver will reference +mrbgem from core or mgem-list. + +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. + +## GemBox + +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*: +```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 +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: +```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 an absolute path like below. +```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 +contains several core components of mruby, and [full-core](../../mrbgems/full-core.gembox) +contains every gem found in the *mrbgems* directory. + +## GEM Structure + +The maximal GEM structure looks like this: + + +- GEM_NAME <- Name of GEM + | + +- include/ <- Header for Ruby extension (will exported) + | + +- 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/C++ files to extend mruby. The folder *include* contains C/C++ header +files. The folder *test* contains C/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. + +## Build process + +mrbgems expects a specification file called *mrbgem.rake* inside of your +GEM directory. A typical GEM specification could look like this for example: +```ruby +MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec| + spec.license = 'MIT' + spec.author = 'mruby developers' + spec.summary = 'Example mrbgem using C and ruby' +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` + * One line short description of mrbgem. + * Printed in build summary of rake when set. +* `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[, default_get_info])` like: +```ruby +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') + + # 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 omitted) + spec.add_dependency('mruby-onig-regexp', :github => 'mattn/mruby-onig-regexp') +end +``` + +The version requirements and default gem information are optional. + +Version requirement supports following operators: +* '=': is equal +* '!=': is not equal +* '>': is greater +* '<': is lesser +* '>=': is equal or greater +* '<=': is equal or lesser +* '~>': is equal or greater and is lesser than the next major version + * example 1: '~> 2.2.2' means '>= 2.2.2' and '< 2.3.0' + * example 2: '~> 2.2' means '>= 2.2.0' and '< 3.0.0' + +When more than one version requirements is passed, the dependency must satisfy all of it. + +You can have default gem to use as depedency when it's not defined in *build_config.rb*. +When the last argument of `add_dependency` call is `Hash`, it will be treated as default gem information. +Its format is same as argument of method `MRuby::Build#gem`, expect that it can't be treated as path gem location. + +When a special version of depedency is required, +use `MRuby::Build#gem` in *build_config.rb* to override default gem. + +If you have conflicting GEMs use the following method: +* `spec.add_conflict(gem, *requirements)` + * 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' + + 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: + +* `spec.cc.flags` (C compiler flags) +* `spec.cc.defines` (C compiler defines) +* `spec.cc.include_paths` (C compiler include paths) +* `spec.linker.flags` (Linker flags) +* `spec.linker.libraries` (Linker libraries) +* `spec.linker.library_paths` (Linker additional library path) +* `spec.bins` (Generate binary file) +* `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) + +You also can use `spec.mruby.cc` and `spec.mruby.linker` to add extra global parameters for compiler and linker. + +### include_paths and dependency + +Your GEM can export include paths to another GEMs that depends on your GEM. +By default, `/...absolute path.../{GEM_NAME}/include` will be exported. +So it is recommended not to put GEM's local header files on include/. + +These exports are retroactive. +For example: when B depends to C and A depends to B, A will get include paths exported by C. + +Exported include_paths are automatically appended to GEM local include_paths by Minirake. +You can use `spec.export_include_paths` accessor if you want more complex build. + + +## C Extension + +mruby can be extended with C. This is possible by using the C API to +integrate C libraries into mruby. + +### Preconditions + +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: +```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 + +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: + +```C +void +mrb_c_extension_example_gem_final(mrb_state* mrb) { + free(someone); +} +``` + +### Example + + +- c_extension_example/ + | + +- src/ + | | + | +- example.c <- C extension source + | + +- test/ + | | + | +- example.rb <- Test code for C extension + | + +- mrbgem.rake <- GEM specification + | + +- README.md + +## Ruby Extension + +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. + + +### Pre-Conditions + +none + +### Example + + +- ruby_extension_example/ + | + +- mrblib/ + | | + | +- example.rb <- Ruby extension source + | + +- test/ + | | + | +- example.rb <- Test code for Ruby extension + | + +- mrbgem.rake <- GEM specification + | + +- README.md + +## C and Ruby Extension + +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. + +mruby codes under *mrblib* directory would be executed after gem init C +function is called. Make sure *mruby script* depends on *C code* and +*C code* doesn't depend on *mruby script*. + +### Pre-Conditions + +See C and Ruby example. + +### 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.md -- cgit v1.2.3 From 554406b987bde19f25aef2adbc1431d8f30f9871 Mon Sep 17 00:00:00 2001 From: Seba Gamboa Date: Mon, 28 Sep 2015 19:02:05 -0300 Subject: Testing @see tag --- include/mruby.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/include/mruby.h b/include/mruby.h index 6d34b241c..3d91b2f51 100644 --- a/include/mruby.h +++ b/include/mruby.h @@ -279,12 +279,12 @@ MRB_API void mrb_undef_class_method(mrb_state*, struct RClass*, const char*); * Number of arguments in argv * @param argv * Array of @ref mrb_value "mrb_values" to initialize the object - * @returns + * @return * The newly initialized object */ MRB_API mrb_value mrb_obj_new(mrb_state *mrb, struct RClass *c, mrb_int argc, const mrb_value *argv); -/** See @ref mrb_obj_new */ +/** @see mrb_obj_new */ MRB_INLINE mrb_value mrb_class_new_instance(mrb_state *mrb, mrb_int argc, const mrb_value *argv, struct RClass *c) { return mrb_obj_new(mrb,c,argc,argv); @@ -469,7 +469,7 @@ char* mrb_locale_from_utf8(const char *p, size_t len); /** * Creates new mrb_state. * - * @returns + * @return * Pointer to the newly created mrb_state. */ MRB_API mrb_state* mrb_open(void); @@ -482,7 +482,7 @@ MRB_API mrb_state* mrb_open(void); * @param ud * User data will be passed to custom allocator f. * If user data isn't required just pass NULL. - * @returns + * @return * Pointer to the newly created mrb_state. */ MRB_API mrb_state* mrb_open_allocf(mrb_allocf f, void *ud); @@ -496,7 +496,7 @@ MRB_API mrb_state* mrb_open_allocf(mrb_allocf f, void *ud); * @param ud * User data will be passed to custom allocator f. * If user data isn't required just pass NULL. - * @returns + * @return * Pointer to the newly created mrb_state. */ MRB_API mrb_state* mrb_open_core(mrb_allocf f, void *ud); -- cgit v1.2.3 From a0fe0c40b103411dd9e98f153fab8cbb35c7fa93 Mon Sep 17 00:00:00 2001 From: Seba Gamboa Date: Mon, 28 Sep 2015 19:15:59 -0300 Subject: Remove old doxygen tags --- include/mruby.h | 28 +++++++++++++--------------- include/mruby/array.h | 11 ++++------- include/mruby/class.h | 6 +----- include/mruby/common.h | 13 ++++++------- include/mruby/compile.h | 5 +---- include/mruby/data.h | 7 +------ include/mruby/debug.h | 6 +----- include/mruby/dump.h | 6 +----- include/mruby/error.h | 6 +----- include/mruby/gc.h | 6 +----- include/mruby/hash.h | 6 +----- include/mruby/irep.h | 6 +----- include/mruby/khash.h | 6 +----- include/mruby/numeric.h | 9 ++------- include/mruby/proc.h | 6 +----- include/mruby/range.h | 6 +----- include/mruby/string.h | 6 +----- include/mruby/value.h | 9 +-------- include/mruby/variable.h | 6 +----- include/mruby/version.h | 6 +----- 20 files changed, 41 insertions(+), 119 deletions(-) diff --git a/include/mruby.h b/include/mruby.h index 3d91b2f51..47d65ee4c 100644 --- a/include/mruby.h +++ b/include/mruby.h @@ -38,9 +38,7 @@ #include "mruby/version.h" /** - * @file mruby.h - * @defgroup mruby MRuby C API - * @{ + * MRuby C API entry point */ MRB_BEGIN_DECL @@ -56,13 +54,13 @@ struct mrb_irep; struct mrb_state; /** - * Function pointer type of custom allocator used in @ref mrb_open_allocf. + * Function pointer type of custom allocator used in @see mrb_open_allocf. * * The function pointing it must behave similarly as realloc except: * - If ptr is NULL it must allocate new space. * - If s is NULL, ptr must be freed. * - * See @ref mrb_default_allocf for the default implementation. + * See @see mrb_default_allocf for the default implementation. */ typedef void* (*mrb_allocf) (struct mrb_state *mrb, void*, size_t, void *ud); @@ -213,16 +211,17 @@ typedef mrb_value (*mrb_func_t)(mrb_state *mrb, mrb_value); * Defines a new class. * * If you're creating a gem it may look something like this: - * 
- *    void mrb_example_gem_init(mrb_state* mrb) {
- *      struct RClass *example_class;
- *      example_class = mrb_define_class(mrb, "Example_Class", mrb->object_class);
- *    }
  *
- *    void mrb_example_gem_final(mrb_state* mrb) {
- *      //free(TheAnimals);
- *    }
- *
+ * ```c + * void mrb_example_gem_init(mrb_state* mrb) { + * struct RClass *example_class; + * example_class = mrb_define_class(mrb, "Example_Class", mrb->object_class); + * } + * + * void mrb_example_gem_final(mrb_state* mrb) { + * //free(TheAnimals); + * } + * ``` * * @param name The name of the defined class * @param super The new class parent @@ -676,7 +675,6 @@ MRB_API void mrb_show_copyright(mrb_state *mrb); MRB_API mrb_value mrb_format(mrb_state *mrb, const char *format, ...); -/** @} */ MRB_END_DECL #endif /* MRUBY_H */ diff --git a/include/mruby/array.h b/include/mruby/array.h index e716c883d..cd4156836 100644 --- a/include/mruby/array.h +++ b/include/mruby/array.h @@ -10,10 +10,7 @@ #include "mruby/common.h" /** - * @file mruby/array.h - * @defgroup mruby_array Array class - * @ingroup mruby - * @{ + * Array class */ MRB_BEGIN_DECL @@ -58,7 +55,7 @@ MRB_API mrb_value mrb_ary_new_capa(mrb_state*, mrb_int); * * @param mrb * The MRuby state reference. - * @returns + * @return * The initialized array */ MRB_API mrb_value mrb_ary_new(mrb_state *mrb); @@ -94,7 +91,7 @@ MRB_API void mrb_ary_push(mrb_state *mrb, mrb_value array, mrb_value value); * The MRuby state reference. * @param ary * The array from which the value will be poped. - * @returns + * @return * The poped value. */ MRB_API mrb_value mrb_ary_pop(mrb_state *mrb, mrb_value ary); @@ -112,7 +109,7 @@ MRB_API mrb_value mrb_ary_pop(mrb_state *mrb, mrb_value ary); * The target array. * @param n * The array index being referenced - * @returns + * @return * The referenced value. */ MRB_API mrb_value mrb_ary_ref(mrb_state *mrb, mrb_value ary, mrb_int n); diff --git a/include/mruby/class.h b/include/mruby/class.h index 35edce86c..09565ec08 100644 --- a/include/mruby/class.h +++ b/include/mruby/class.h @@ -10,10 +10,7 @@ #include "mruby/common.h" /** - * @file mruby/class.h - * @defgroup mruby_class Class class - * @ingroup mruby - * @{ + * Class class */ MRB_BEGIN_DECL @@ -87,7 +84,6 @@ void mrb_gc_mark_mt(mrb_state*, struct RClass*); size_t mrb_gc_mark_mt_size(mrb_state*, struct RClass*); void mrb_gc_free_mt(mrb_state*, struct RClass*); -/** @} */ MRB_END_DECL #endif /* MRUBY_CLASS_H */ diff --git a/include/mruby/common.h b/include/mruby/common.h index 01e558291..e7841f38f 100644 --- a/include/mruby/common.h +++ b/include/mruby/common.h @@ -7,12 +7,6 @@ #ifndef MRUBY_COMMON_H #define MRUBY_COMMON_H -/** - * @file mruby/common.h - * @defgroup mruby_common Shared compiler macros - * @ingroup mruby - * @{ - */ #ifdef __cplusplus # define MRB_BEGIN_DECL extern "C" { @@ -24,6 +18,11 @@ # define MRB_END_DECL #endif +/** + * Shared compiler macros + */ +MRB_BEGIN_DECL + /** Declare a function that never returns. */ #if __STDC_VERSION__ >= 201112L # define mrb_noreturn _Noreturn @@ -63,6 +62,6 @@ # define MRB_API extern #endif -/** @} */ +MRB_END_DECL #endif /* MRUBY_COMMON_H */ diff --git a/include/mruby/compile.h b/include/mruby/compile.h index c482ddf69..637b469a8 100644 --- a/include/mruby/compile.h +++ b/include/mruby/compile.h @@ -10,10 +10,7 @@ #include "mruby/common.h" /** - * @file mruby/compile.h - * @defgroup mruby_compile Compiler - * @ingroup mruby - * @{ + * MRuby Compiler */ MRB_BEGIN_DECL diff --git a/include/mruby/data.h b/include/mruby/data.h index c68b050f7..472829c57 100644 --- a/include/mruby/data.h +++ b/include/mruby/data.h @@ -10,13 +10,9 @@ #include "mruby/common.h" /** - * @file mruby/data.h - * @defgroup mruby_data Custom C wrapped data. + * Custom C wrapped data. * * Defining Ruby wrappers around native objects. - * - * @ingroup mruby - * @{ */ MRB_BEGIN_DECL @@ -74,7 +70,6 @@ mrb_data_init(mrb_value v, void *ptr, const mrb_data_type *type) DATA_TYPE(v) = type; } -/** @} */ MRB_END_DECL #endif /* MRUBY_DATA_H */ diff --git a/include/mruby/debug.h b/include/mruby/debug.h index 94ef1e723..553968a86 100644 --- a/include/mruby/debug.h +++ b/include/mruby/debug.h @@ -10,10 +10,7 @@ #include "mruby/common.h" /** - * @file mruby/debug.h - * @defgroup mruby_debug Debugging. - * @ingroup mruby - * @{ + * MRuby Debugging. */ MRB_BEGIN_DECL @@ -64,7 +61,6 @@ MRB_API mrb_irep_debug_info_file *mrb_debug_info_append_file( MRB_API mrb_irep_debug_info *mrb_debug_info_alloc(mrb_state *mrb, mrb_irep *irep); MRB_API void mrb_debug_info_free(mrb_state *mrb, mrb_irep_debug_info *d); -/** @} */ MRB_END_DECL #endif /* MRUBY_DEBUG_H */ diff --git a/include/mruby/dump.h b/include/mruby/dump.h index 293122f9a..6a36cbce6 100644 --- a/include/mruby/dump.h +++ b/include/mruby/dump.h @@ -12,10 +12,7 @@ #include "mruby/common.h" /** - * @file mruby/dump.h - * @defgroup mruby_dump Dumping compiled mruby script. - * @ingroup mruby - * @{ + * Dumping compiled mruby script. */ MRB_BEGIN_DECL @@ -190,7 +187,6 @@ bin_to_uint8(const uint8_t *bin) return (uint8_t)bin[0]; } -/** @} */ MRB_END_DECL /** @internal crc.c */ diff --git a/include/mruby/error.h b/include/mruby/error.h index 347ca7738..8b6430137 100644 --- a/include/mruby/error.h +++ b/include/mruby/error.h @@ -10,10 +10,7 @@ #include "mruby/common.h" /** - * @file mruby/error.h - * @defgroup mruby_error Error handling. - * @ingroup mruby - * @{ + * MRuby error handling. */ MRB_BEGIN_DECL @@ -45,7 +42,6 @@ MRB_API mrb_value mrb_rescue_exceptions(mrb_state *mrb, mrb_func_t body, mrb_val mrb_func_t rescue, mrb_value r_data, mrb_int len, struct RClass **classes); -/** @} */ MRB_END_DECL #endif /* MRUBY_ERROR_H */ diff --git a/include/mruby/gc.h b/include/mruby/gc.h index a9187bb56..0b33617de 100644 --- a/include/mruby/gc.h +++ b/include/mruby/gc.h @@ -10,10 +10,7 @@ #include "mruby/common.h" /** - * @file mruby/gc.h - * @defgroup mruby_gc Uncommon memory management stuffs. - * @ingroup mruby - * @{ + * Uncommon memory management stuffs. */ MRB_BEGIN_DECL @@ -21,7 +18,6 @@ typedef void (mrb_each_object_callback)(mrb_state *mrb, struct RBasic *obj, void void mrb_objspace_each_objects(mrb_state *mrb, mrb_each_object_callback *callback, void *data); MRB_API void mrb_free_context(mrb_state *mrb, struct mrb_context *c); -/** @} */ MRB_END_DECL #endif /* MRUBY_GC_H */ diff --git a/include/mruby/hash.h b/include/mruby/hash.h index 1f69b4215..ea4a79dc4 100644 --- a/include/mruby/hash.h +++ b/include/mruby/hash.h @@ -10,10 +10,7 @@ #include "mruby/common.h" /** - * @file mruby/hash.h - * @defgroup mruby_hash Hash class - * @ingroup mruby - * @{ + * Hash class */ MRB_BEGIN_DECL @@ -53,7 +50,6 @@ void mrb_gc_mark_hash(mrb_state*, struct RHash*); size_t mrb_gc_mark_hash_size(mrb_state*, struct RHash*); void mrb_gc_free_hash(mrb_state*, struct RHash*); -/** @} */ MRB_END_DECL #endif /* MRUBY_HASH_H */ diff --git a/include/mruby/irep.h b/include/mruby/irep.h index 1f08f44fa..aaf8bd0ef 100644 --- a/include/mruby/irep.h +++ b/include/mruby/irep.h @@ -11,10 +11,7 @@ #include "mruby/compile.h" /** - * @file mruby/irep.h - * @defgroup mruby_irep Compiled mruby scripts. - * @ingroup mruby - * @{ + * Compiled mruby scripts. */ MRB_BEGIN_DECL @@ -58,7 +55,6 @@ void mrb_irep_free(mrb_state*, struct mrb_irep*); void mrb_irep_incref(mrb_state*, struct mrb_irep*); void mrb_irep_decref(mrb_state*, struct mrb_irep*); -/** @} */ MRB_END_DECL #endif /* MRUBY_IREP_H */ diff --git a/include/mruby/khash.h b/include/mruby/khash.h index 36119bfcf..4331ef137 100644 --- a/include/mruby/khash.h +++ b/include/mruby/khash.h @@ -13,10 +13,7 @@ #include "mruby/common.h" /** - * @file mruby/khash.h - * @defgroup mruby_khash khash definitions used in mruby's hash table. - * @ingroup mruby - * @{ + * khash definitions used in mruby's hash table. */ MRB_BEGIN_DECL @@ -272,7 +269,6 @@ static inline khint_t __ac_X31_hash_string(const char *s) typedef const char *kh_cstr_t; -/** @} */ MRB_END_DECL #endif /* MRUBY_KHASH_H */ diff --git a/include/mruby/numeric.h b/include/mruby/numeric.h index a7aa6c81b..6366e8674 100644 --- a/include/mruby/numeric.h +++ b/include/mruby/numeric.h @@ -10,13 +10,9 @@ #include "mruby/common.h" /** - * @file mruby/numeric.h - * @defgroup mruby_numeric Numeric class and it's sub-classes. + * Numeric class and it's sub-classes. * - * Numeric, Integer, Float, Fixnum classes - * - * @ingroup mruby - * @{ + * Integer, Float and Fixnum */ MRB_BEGIN_DECL @@ -113,7 +109,6 @@ mrb_int_sub_overflow(mrb_int minuend, mrb_int subtrahend, mrb_int *difference) #undef MRB_UINT_MAKE #undef MRB_UINT_MAKE2 -/** @} */ MRB_END_DECL #endif /* MRUBY_NUMERIC_H */ diff --git a/include/mruby/proc.h b/include/mruby/proc.h index 6b8d3cd9f..85096fe5e 100644 --- a/include/mruby/proc.h +++ b/include/mruby/proc.h @@ -11,10 +11,7 @@ #include "mruby/irep.h" /** - * @file mruby/proc.h - * @defgroup mruby_proc Proc class - * @ingroup mruby - * @{ + * Proc class */ MRB_BEGIN_DECL @@ -74,7 +71,6 @@ MRB_API mrb_value mrb_proc_cfunc_env_get(mrb_state*, mrb_int); #include "mruby/khash.h" KHASH_DECLARE(mt, mrb_sym, struct RProc*, TRUE) -/** @} */ MRB_END_DECL #endif /* MRUBY_PROC_H */ diff --git a/include/mruby/range.h b/include/mruby/range.h index e30c71ab5..f97853fc5 100644 --- a/include/mruby/range.h +++ b/include/mruby/range.h @@ -10,10 +10,7 @@ #include "mruby/common.h" /** - * @file mruby/range.h - * @defgroup mruby_range Range class - * @ingroup mruby - * @{ + * Range class */ MRB_BEGIN_DECL @@ -35,7 +32,6 @@ MRB_API mrb_value mrb_range_new(mrb_state*, mrb_value, mrb_value, mrb_bool); MRB_API mrb_bool mrb_range_beg_len(mrb_state *mrb, mrb_value range, mrb_int *begp, mrb_int *lenp, mrb_int len); mrb_value mrb_get_values_at(mrb_state *mrb, mrb_value obj, mrb_int olen, mrb_int argc, const mrb_value *argv, mrb_value (*func)(mrb_state*, mrb_value, mrb_int)); -/** @} */ MRB_END_DECL #endif /* MRUBY_RANGE_H */ diff --git a/include/mruby/string.h b/include/mruby/string.h index e182bb6fa..04040663d 100644 --- a/include/mruby/string.h +++ b/include/mruby/string.h @@ -10,10 +10,7 @@ #include "mruby/common.h" /** - * @file mruby/string.h - * @defgroup mrb_string String class - * @ingroup mruby - * @{ + * String class */ MRB_BEGIN_DECL @@ -126,7 +123,6 @@ void mrb_regexp_check(mrb_state *mrb, mrb_value obj); #define mrb_str_buf_cat(mrb, str, ptr, len) mrb_str_cat(mrb, str, ptr, len) #define mrb_str_buf_append(mrb, str, str2) mrb_str_cat_str(mrb, str, str2) -/** @} */ MRB_END_DECL #endif /* MRUBY_STRING_H */ diff --git a/include/mruby/value.h b/include/mruby/value.h index d9614f356..216fe9279 100644 --- a/include/mruby/value.h +++ b/include/mruby/value.h @@ -10,13 +10,7 @@ #include "mruby/common.h" /** - * @file mruby/value.h - * @defgroup mruby_value Value definitions - * - * @ref mrb_value functions and macros. - * - * @ingroup mruby - * @{ + * MRuby Value definition functions and macros. */ MRB_BEGIN_DECL @@ -245,7 +239,6 @@ mrb_ro_data_p(const char *p) # define mrb_ro_data_p(p) FALSE #endif -/** @} */ MRB_END_DECL #endif /* MRUBY_VALUE_H */ diff --git a/include/mruby/variable.h b/include/mruby/variable.h index 91d50c106..063d65b71 100644 --- a/include/mruby/variable.h +++ b/include/mruby/variable.h @@ -10,10 +10,7 @@ #include "mruby/common.h" /** - * @file mruby/variable.h - * @defgroup mruby_variable Functions to access to mruby variables. - * @ingroup mruby - * @{ + * Functions to access mruby variables. */ MRB_BEGIN_DECL @@ -80,7 +77,6 @@ void mrb_gc_mark_iv(mrb_state*, struct RObject*); size_t mrb_gc_mark_iv_size(mrb_state*, struct RObject*); void mrb_gc_free_iv(mrb_state*, struct RObject*); -/** @} */ MRB_END_DECL #endif /* MRUBY_VARIABLE_H */ diff --git a/include/mruby/version.h b/include/mruby/version.h index 09be56811..cf5aa57eb 100644 --- a/include/mruby/version.h +++ b/include/mruby/version.h @@ -10,11 +10,7 @@ #include "mruby/common.h" /** - * @file mruby/version.h - * @brief MRuby version macros - * @defgroup mrb_string MRuby version macros - * @ingroup MRuby - * @{ + * MRuby version macros */ MRB_BEGIN_DECL -- cgit v1.2.3 From facc4bf428f5213f038eeb120f2119fcf52cd805 Mon Sep 17 00:00:00 2001 From: Seba Gamboa Date: Tue, 29 Sep 2015 14:09:05 -0300 Subject: Fix samples syntax highlighting --- .yardopts | 1 + include/mruby.h | 19 ++++++++++--------- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/.yardopts b/.yardopts index 5914be882..af8937b55 100644 --- a/.yardopts +++ b/.yardopts @@ -1,3 +1,4 @@ +--plugin coderay - AUTHORS MITL diff --git a/include/mruby.h b/include/mruby.h index 47d65ee4c..ed1f08b7f 100644 --- a/include/mruby.h +++ b/include/mruby.h @@ -212,21 +212,21 @@ typedef mrb_value (*mrb_func_t)(mrb_state *mrb, mrb_value); * * If you're creating a gem it may look something like this: * - * ```c - * void mrb_example_gem_init(mrb_state* mrb) { - * struct RClass *example_class; - * example_class = mrb_define_class(mrb, "Example_Class", mrb->object_class); - * } + * !!!c + * void mrb_example_gem_init(mrb_state* mrb) { + * struct RClass *example_class; + * example_class = mrb_define_class(mrb, "Example_Class", mrb->object_class); + * } * - * void mrb_example_gem_final(mrb_state* mrb) { - * //free(TheAnimals); - * } - * ``` + * void mrb_example_gem_final(mrb_state* mrb) { + * //free(TheAnimals); + * } * * @param name The name of the defined class * @param super The new class parent */ MRB_API struct RClass *mrb_define_class(mrb_state *mrb, const char *name, struct RClass *super); + MRB_API struct RClass *mrb_define_module(mrb_state *, const char*); MRB_API mrb_value mrb_singleton_class(mrb_state*, mrb_value); MRB_API void mrb_include_module(mrb_state*, struct RClass*, struct RClass*); @@ -237,6 +237,7 @@ MRB_API void mrb_prepend_module(mrb_state*, struct RClass*, struct RClass*); * * If you're creating a gem it may look something like this: * + * !!!c * mrb_value example_method(mrb_state* mrb, mrb_value self) * { * puts("Executing example command!"); -- cgit v1.2.3 From 249226730fa3fd59b0ab7145ae08e5ef30af781b Mon Sep 17 00:00:00 2001 From: Seba Gamboa Date: Tue, 29 Sep 2015 15:06:53 -0300 Subject: Formatting docs to new YARD structure --- include/mruby.h | 64 ++++++++++++++++++++++++--------------------------------- 1 file changed, 27 insertions(+), 37 deletions(-) diff --git a/include/mruby.h b/include/mruby.h index ed1f08b7f..670733bb3 100644 --- a/include/mruby.h +++ b/include/mruby.h @@ -222,8 +222,11 @@ typedef mrb_value (*mrb_func_t)(mrb_state *mrb, mrb_value); * //free(TheAnimals); * } * + * @param mrb The current mruby state. * @param name The name of the defined class * @param super The new class parent + * @return Reference to the newly defined class + * @see mrb_define_class_under */ MRB_API struct RClass *mrb_define_class(mrb_state *mrb, const char *name, struct RClass *super); @@ -249,15 +252,10 @@ MRB_API void mrb_prepend_module(mrb_state*, struct RClass*, struct RClass*); * mrb_define_method(mrb, mrb->kernel_module, "example_method", example_method, MRB_ARGS_NONE()); * } * - * @param mrb - * The MRuby state reference. - * @param cla - * The class pointer where the method will be defined. - * @param func - * The function pointer to the method definition. - * @param aspec - * The method parameters declaration. - * See @ref mruby_mrb_aspec for details. + * @param mrb The MRuby state reference. + * @param cla The class pointer where the method will be defined. + * @param func The function pointer to the method definition. + * @param aspec The method parameters declaration. */ MRB_API void mrb_define_method(mrb_state *mrb, struct RClass *cla, const char *name, mrb_func_t func, mrb_aspec aspec); @@ -271,16 +269,11 @@ MRB_API void mrb_undef_class_method(mrb_state*, struct RClass*, const char*); /** * Initialize a new object instace of c class. * - * @param mrb - * The current mruby state. - * @param c - * Reference to the class of the new object. - * @param argc - * Number of arguments in argv - * @param argv - * Array of @ref mrb_value "mrb_values" to initialize the object - * @return - * The newly initialized object + * @param mrb The current mruby state. + * @param c Reference to the class of the new object. + * @param argc Number of arguments in argv + * @param argv Array of mrb_value to initialize the object + * @return The newly initialized object */ MRB_API mrb_value mrb_obj_new(mrb_state *mrb, struct RClass *c, mrb_int argc, const mrb_value *argv); @@ -302,18 +295,21 @@ MRB_API mrb_value mrb_notimplement_m(mrb_state*, mrb_value); MRB_API mrb_value mrb_obj_dup(mrb_state *mrb, mrb_value obj); MRB_API mrb_value mrb_check_to_integer(mrb_state *mrb, mrb_value val, const char *method); -MRB_API mrb_bool mrb_obj_respond_to(mrb_state *mrb, struct RClass* c, mrb_sym mid); -MRB_API struct RClass * mrb_define_class_under(mrb_state *mrb, struct RClass *outer, const char *name, struct RClass *super); -MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *outer, const char *name); +MRB_API mrb_bool mrb_obj_mrb_define_class_underrespond_to(mrb_state *mrb, struct RClass* c, mrb_sym mid); /** - * @defgroup mruby_mrb_aspec Required arguments declaration helpers. - * - * Helper functions to declare arguments requirements on methods declared by - * \ref mrb_define_method and the like + * Defines a new class under a given module * - * @{ + * @param mrb The current mruby state. + * @param outer Reference to the module under which the new class will be defined + * @param name The name of the defined class + * @param super The new class parent + * @return Reference to the newly defined class + * @see mrb_define_class */ +MRB_API struct RClass * mrb_define_class_under(mrb_state *mrb, struct RClass *outer, const char *name, struct RClass *super); + +MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *outer, const char *name); /** * Function requires n arguments. @@ -365,8 +361,6 @@ MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *o */ #define MRB_ARGS_NONE() ((mrb_aspec)0) -/** @} */ - /** * Format specifiers for \ref mrb_get_args function * @@ -400,14 +394,10 @@ typedef const char *mrb_args_format; * applied to received arguments. * Use it inside a function pointed by mrb_func_t. * - * @param mrb - * The current MRuby state. - * @param format - * is a list of format specifiers see @ref mrb_args_format - * @param ... - * The passing variadic arguments must be a pointer of retrieving type. - * @return - * the number of arguments retrieved. + * @param mrb The current MRuby state. + * @param format is a list of format specifiers see @ref mrb_args_format + * @param ... The passing variadic arguments must be a pointer of retrieving type. + * @return the number of arguments retrieved. */ MRB_API mrb_int mrb_get_args(mrb_state *mrb, mrb_args_format format, ...); -- cgit v1.2.3 From 657d06958262a8f9f1c0c4c4754adc7f328a7c04 Mon Sep 17 00:00:00 2001 From: Seba Gamboa Date: Tue, 6 Oct 2015 14:26:48 -0300 Subject: Move guides location --- .gitignore | 2 +- .yardopts | 4 +- doc/api/gc-arena-howto.md | 171 --------------- doc/guides/compile.md | 481 +++++++++++++++++++++++++++++++++++++++++++ doc/guides/debugger.md | 370 +++++++++++++++++++++++++++++++++ doc/guides/gc-arena-howto.md | 171 +++++++++++++++ doc/guides/mrbconf.md | 160 ++++++++++++++ doc/guides/mrbgems.md | 337 ++++++++++++++++++++++++++++++ guides/compile.md | 481 ------------------------------------------- guides/debugger.md | 370 --------------------------------- guides/mrbconf.md | 160 -------------- guides/mrbgems.md | 337 ------------------------------ 12 files changed, 1523 insertions(+), 1521 deletions(-) delete mode 100644 doc/api/gc-arena-howto.md create mode 100644 doc/guides/compile.md create mode 100644 doc/guides/debugger.md create mode 100644 doc/guides/gc-arena-howto.md create mode 100644 doc/guides/mrbconf.md create mode 100644 doc/guides/mrbgems.md delete mode 100644 guides/compile.md delete mode 100755 guides/debugger.md delete mode 100644 guides/mrbconf.md delete mode 100644 guides/mrbgems.md diff --git a/.gitignore b/.gitignore index ba4da68f4..800680821 100644 --- a/.gitignore +++ b/.gitignore @@ -21,5 +21,5 @@ cscope.out /bin /build /mruby-source-*.gem -doc +doc/api .yardoc diff --git a/.yardopts b/.yardopts index af8937b55..017b7ce70 100644 --- a/.yardopts +++ b/.yardopts @@ -1,6 +1,8 @@ +--plugin mruby --plugin coderay +--output-dir doc/api - AUTHORS MITL CONTRIBUTING.md -guides/*.md +doc/guides/*.md diff --git a/doc/api/gc-arena-howto.md b/doc/api/gc-arena-howto.md deleted file mode 100644 index f2a0448bd..000000000 --- a/doc/api/gc-arena-howto.md +++ /dev/null @@ -1,171 +0,0 @@ -# How to use `mrb_gc_arena_save()`/`mrb_gc_arena_restore()` - -This is basically English translation of [Matz's blog post](http://www.rubyist.net/~matz/20130731.html) written in Japanese. -Some parts are updated to reflect recent changes. - -When you are extending mruby using C language, you may encounter -mysterious "arena overflow error" or memory leak or very slow -execution speed. This is an error indicating overflow of "GC arena" -implementing "conservative GC". - -GC (garbage collector) must ensure that object is "alive", in other -words, that it is referenced by somewhere from program. This can be -determined by checking that that object can be directly or indirectly -referenced by root. The local variables, global variables and -constants etc are root. - -If program execution is performed inside mruby VM, there is nothing to -worry about because GC can access all roots owned by VM. - -The problem arises when executing C functions. The object referenced -by C variable is also "alive", but mruby GC cannot aware of this, so -it might mistakenly recognize the objects referenced by only C -variables as dead. - -It is a fatal bug for GC to collect live objects. - -In CRuby, we scan C stack area, and use C variable as root to check -whether object is alive or not. Of course, because we are accessing C -stack just as memory region, we never know it is an integer or a -pointer. We workaround this by assuming that if it looks like a -pointer, then assume it as a pointer. We call it "conservative". - -By the way, CRuby's "conservative GC" has some problems. - -Its biggest problem is we have no way to access to the stack area in -portable way. Therefore, we cannot use this method if we'd like to -implement highly portable runtime, like mruby. - -So we came up an another plan to implement "conservative GC" in mruby. - -Again, the problem is that there is an object which was created in C -function, and is not referenced by Ruby world, and cannot be treated -as garbage. - -In mruby, we recognize all objects created in C function are alive. -Then we have no problem such as recognizing live object as dead. - -This means that because we cannot collect truly dead object, we may -get a little bit less efficiency, but GC itself is highly portable. -We can say goodbye to the problem that GC deletes live objects due to -optimization which sometimes occurs in CRuby. - -According to this idea, we have a table, called "GC arena", which -remembers objects created in C function. The arena is stack -structure, when C function execution is returned to mruby VM, all -objects registered in the arena are popped. - -This works very well, but GC arena causes another problem. "arena -overflow error" or memory leak. - -As of this writing, mruby automatically extend arena to remember -objects (See `MRB_GC_FIXED_ARENA` and `MRB_GC_ARENA_SIZE` in -doc/mrbconf/README.md). If you keep creating objects in C functions, -it increases memory usage, since GC never kick in. This memory usage -may look like memory leak, and also makes execution slower. - -With the build time configuration, you can limit the maximum size of -arena (e.g., 100). Then if you create many objects, arena overflows, -thus you will get "arena overflow error". - -To workaround these problems, we have `mrb_gc_arena_save()` and -`mrb_gc_arena_restore()` functions. - -`int mrb_gc_arena_save(mrb)` returns the current position of the stack -top of GC arena, and `void mrb_gc_arena_restore(mrb, idx)` sets the -stack top position to back to given idx. We uses them like so: - -```c -int arena_idx = mrb_gc_arena_save(mrb); - -...create objects... -mrb_gc_arena_restore(mrb, arena_idx); - -``` - -In mruby, C function call are surrounded by this save/restore, but we -can further optimize memory usage by surrounding save/restore, and can -avoid arena overflow. - -Let's take a real example. Here is the source code of `Array#inspect`: - -```c -static mrb_value -inspect_ary(mrb_state *mrb, mrb_value ary, mrb_value list) -{ - mrb_int i; - mrb_value s, arystr; - char head[] = { '[' }; - char sep[] = { ',', ' ' }; - char tail[] = { ']' }; - - /* check recursive */ - for(i=0; i 0) { - mrb_str_buf_cat(mrb, arystr, sep, sizeof(sep)); - } - if (mrb_array_p(RARRAY_PTR(ary)[i])) { - s = inspect_ary(mrb, RARRAY_PTR(ary)[i], list); - } - else { - s = mrb_inspect(mrb, RARRAY_PTR(ary)[i]); - } - mrb_str_buf_cat(mrb, arystr, RSTRING_PTR(s), RSTRING_LEN(s)); - mrb_gc_arena_restore(mrb, ai); - } - - mrb_str_buf_cat(mrb, arystr, tail, sizeof(tail)); - mrb_ary_pop(mrb, list); - - return arystr; -} -``` - -This is a real example, so a little bit complicated, so bear with me. -The essence of `Array#inspect` is that after stringifying each element -of array using `inspect` method, we join them together so that we can -get `inspect` representation of entire array. - -After the `inspect` representation of entire array is created, we no -longer require the individual string representation. That means that -we don't have to register these temporal objects into GC arena. - -Therefore, in `ary_inspect()` function, we do: - -* save the position of the stack top using `mrb_gc_arena_save()`. -* get `inspect` representation of each element. -* append it to the constructing entire `inspect` representation of array. -* restore stack top position using `mrb_gc_arena_restore()`. - -to keep the arena size small. - -Please note that the final `inspect` representation of entire array -was created before the call of `mrb_gc_arena_restore()`. Otherwise, -required temporal object may be deleted by GC. - -We may have a usecase that after creating many temporal objects, we'd -like to keep some of them. In this case, we cannot use the same idea -in `ary_inspect()` like appending objects to existing one. Instead, -after `mrb_gc_arena_restore()`, we register back the objects we'd like -to keep to the arena using `mrb_gc_protect(mrb, obj)`. Use -`mrb_gc_protect()` with caution because its usage could lead to arena -overflow error. - -We also have to mention that when `mrb_funcall` is called in top -level, its return value is also registered to GC arena, so calling -them repeatedly eventually lead to arena overflow error. Use -`mrb_gc_arena_save()` and `mrb_gc_arena_restore()` or possible use of -`mrb_gc_protect()` to workaround this. diff --git a/doc/guides/compile.md b/doc/guides/compile.md new file mode 100644 index 000000000..8e91e7546 --- /dev/null +++ b/doc/guides/compile.md @@ -0,0 +1,481 @@ +# Compile + +mruby uses Rake to compile and cross-compile all libraries and +binaries. + +## Prerequisites + +To compile mruby out of the source code you need the following tools: +* C Compiler (i.e. ```gcc```) +* Linker (i.e. ```gcc```) +* Archive utility (i.e. ```ar```) +* Parser generator (i.e. ```bison```) +* Ruby 1.8 or 1.9 (i.e. ```ruby``` or ```jruby```) + +Optional: +* GIT (to update mruby source and integrate mrbgems easier) +* C++ compiler (to use GEMs which include \*.cpp, \*.cxx, \*.cc) +* Assembler (to use GEMs which include \*.asm) + +## Usage + +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: +```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 +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```. + +## Build Configuration + +Inside of the *build_config.rb* the following options can be configured +based on your environment. + +### Toolchains + +The mruby build system already contains a set of toolchain templates which +configure the build environment for specific compiler infrastructures. + +#### GCC + +Toolchain configuration for the GNU C Compiler. +```ruby +toolchain :gcc +``` + +#### clang + +Toolchain configuration for the LLVM C Compiler clang. Mainly equal to the +GCC toolchain. +```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 +``` + +#### Android + +Toolchain configuration for Android. +```ruby +toolchain :androideabi +``` + +Requires the custom standalone Android NDK and the toolchain path +in ```ANDROID_STANDALONE_TOOLCHAIN```. + +### Binaries + +It is possible to select which tools should be compiled during the compilation +process. The following tools can be selected: +* mruby (mruby interpreter) +* mirb (mruby interactive shell) + +To select them declare conf.gem as follows: +```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```. +```ruby +conf.file_separator = '/' +``` + +### C Compiler + +Configuration of the C compiler binary, flags and include paths. +```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```: +```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```: +```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: +```ruby +def conf.cc.header_search_paths + ['/opt/local/include'] + include_paths +end +``` + +### Linker + +Configuration of the Linker binary, flags and library paths. +```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. +```ruby +conf.archiver do |archiver| + archiver.command = ... + archiver.archive_options = ... +end +``` + +### Parser Generator + +Configuration of the Parser Generator binary and flags. +```ruby +conf.yacc do |yacc| + yacc.command = ... + yacc.compile_options = ... +end +``` + +### GPerf + +Configuration of the GPerf binary and flags. +```ruby +conf.gperf do |gperf| + gperf.command = ... + gperf.compile_options = ... +end +``` + +### File Extensions +```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 without additional configuration +conf.gem 'path/to/another/gem' +``` + +See doc/mrbgems/README.md for more option about mrbgems. + +### Mrbtest + +Configuration Mrbtest build process. + +If you want mrbtest.a only, You should set ```conf.build_mrbtest_lib_only``` +```ruby +conf.build_mrbtest_lib_only +``` + +### Bintest + +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: +```ruby +conf.enable_bintest +``` + +### C++ ABI + +mruby can use C++ exception to raise exception internally. +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 explicitly add the following: +```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: +```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: +```ruby +conf.enable_debug +``` + +When debugging mode is enabled +* Macro ```MRB_DEBUG``` would be defined. + * Which means ```mrb_assert()``` macro is enabled. +* Debug information of irep would be generated by ```mrbc```. + * Because ```-g``` flag would be added to ```mrbc``` runner. + * You can have better backtrace of mruby scripts with this. + +## Cross-Compilation + +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: +```ruby +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```. + +### Mrbtest in Cross-Compilation + +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 + + 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 + +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: +* 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* + +``` + _____ _____ ______ ____ ____ _____ _____ ____ +| CC |->|GEN |->|AR |->|CC |->|CC |->|AR |->|CC |->|CC | +| *.c | |y.tab| |core.a| |mrbc| |*.rb| |lib.a| |mruby| |mirb| + ----- ----- ------ ---- ---- ----- ----- ---- +``` + +### Cross-Compilation + +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 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* + +``` + _______________________________________________________________ +| Native Compilation for Host System | +| _____ ______ _____ ____ ____ _____ | +| | CC | -> |AR | -> |GEN | -> |CC | -> |CC | -> |AR | | +| | *.c | |core.a| |y.tab| |mrbc| |*.rb| |lib.a| | +| ----- ------ ----- ---- ---- ----- | + --------------------------------------------------------------- + || + \||/ + \/ + ________________________________________________________________ +| Cross Compilation for Target System | +| _____ _____ _____ ____ ______ _____ | +| | CC | -> |AR | -> |CC | -> |CC | -> |AR | -> |CC | | +| | *.c | |lib.a| |mruby| |mirb| |core.a| |mrbc | | +| ----- ----- ----- ---- ------ ----- | + ---------------------------------------------------------------- +``` + +## Build Configuration Examples + +### Minimal Library + +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. + +```ruby +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). + +## 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 +generated. You can copy this binary and run on your target system. diff --git a/doc/guides/debugger.md b/doc/guides/debugger.md new file mode 100644 index 000000000..a13e91cec --- /dev/null +++ b/doc/guides/debugger.md @@ -0,0 +1,370 @@ +# How to Use the mruby Debugger + +copyright (c) 2014 Specified Non-Profit Corporation mruby Forum + +## 1. Summary + +This file documents the mruby debugger ('mrdb') methods. + +## 2 Debugging with mrdb + +## 2.1 Building mrdb + +The trunk of the mruby source tree, with the most recent mrdb, can be checked out with the following command: + +```bash +$ git clone https://github.com/mruby/mruby.git +``` + +To run the `make` command: + +```bash +$ cd mruby +$ make +``` + +By default, the `make` command will install the debugger files into mruby/bin. + +You can add the path for mrdb on your host environment with the following command: + +```bash +$ echo "export PATH=\$PATH:MRUBY_ROOT/bin" >> ~/.bashrc +$ source ~/.bashrc +``` + +`*MRUBY_ROOT` is the directory in which mruby source code will be installed. + +To confirm mrdb was installed properly, run mrdb with the `--version` option: + +```bash +$ mrdb --version +mruby 1.1.0 (2014-11-19) +``` + +## 2.2 Basic Operation + +### 2.2.1 Debugging mruby Script Files (rb file) with mrdb + +To invoke the mruby debugger, just type `mrdb`. + +To specify the script file: + +```bash +$ mrdb [option] file name +``` + +For example: Debugging sample.rb + +```bash +$ mrdb sample.rb +``` + +You can execute the shell commands listed below: + +|command|description| +|:-:|:--| +|run|execute programs| +|step|execute stepping| +|continue|execute continuing program| +|break|configure the breaking point| +|delete|deleting the breaking points| +|disable|disabling the breaking points| +|enable|enabling the breaking points| +|info breakpoints|showing list of the breaking points| +|print|evaluating and printing the values of the mruby expressions in the script| +|list|displaying the source cords| +|help|showing help| +|quit|terminating the mruby debugger| + +### 2.2.2 Debugging mruby Binary Files (mrb file) with mrdb + +You can debug the mruby binary files. + +#### 2.2.2.1 Debugging the binary files + +* notice +To debug mruby binary files, you need to compile mruby files with option `-g`. + +```bash +$ mrbc -g sample.rb +``` + +You can debug the mruby binary files with following command and the option `-b`. + +```bash +$ mrdb -b sample.mrb +``` + +Then you can execute all debugger shell commands. + +#### Break Command + +You can use any breakpoint to stop the program by specifying the line number and method name. +The breakpoint list will be displayed after you have set the breakpoint successfully. + +Usage: + +``` +break [file:]linenum +b [file:]linenum +break [class:]method +b [class:]method +``` + +The breakpoint will be ordered in serial from 1. +The number, which was given to the deleted breakpoint, will never be given to another breakpoint again. + +You can give multiple breakpoints to specified the line number and method. +Be ware that breakpoint command will not check the validity of the class name and method name. + +You can get the current breakpoint information by the following options. + +breakpoint breakpoint number : file name. line number + +breakpoint breakpoint number : [class name,] method name + +#### Continue Command + +Usage: + +``` +continue [N] +c [N] +``` + +N: the next breakpoint number + +When resuming the program, it will stop at breakpoint N (N-1 breakpoint will be ignored). + +When you run the `continue` command without specifying N, the program will be stopped at the next breakpoint. + +Example: + +``` +(foo.rb:1) continue 3 +``` + +This will resume the program and stop it at the third breakpoint. + +#### Delete Command + +This will delete the specified breakpoint. + +Usage: + +``` +delete [breakpoint-no] +d [breakpoint-no] +``` + +breakpoint-no: breakpoint number + +Example: + +``` +(foo.rb:1) delete +``` + +This will delete all of the breakpoints. + +``` +(foo.rb:1) delete 1 3 +``` + +This will delete the breakpoint at 1 and 3. + +#### Disable Command + +This will disable the specified breakpoint. + +Usage: + +``` +disable [breakpoint-no] +dis [breakpoint-no] +``` + +reappointing: breakpoint number + +Example: + +``` +(foo.rb:1) disable +``` + +Use `disable` if you would like to disable all of the breakpoints. + +``` +(foo.rb:1) disable 1 3 +``` + +This will disable the breakpoints at 1 and 3. + +#### Enable Command + +This will enable the specified breakpoints. + +Usage: + +``` +enable [breakpoint-no] +e [breakpoint-no] +``` + +breakpoint-no: breakpoint number + +Example: + +``` +(foo.rb:1) enable +``` + +Enabling all breakpoints +``` +(foo.rb:1) enable 1 3 +``` + +Enabling the breakpoint 1 and 3 + +#### eval command + +Evaluating the string as source code and printing the value. + +Same as print command, please see print command. + +#### help command + +Displaying the help message. + +Usage: + +``` +help [command] +h [command] +``` + +Typing `help` without any options will display the command list. + +#### Info Breakpoints Command + +Displaying the specified breakpoint information. + +Usage: + +``` +info breakpoints [breakpoint-no] +i b [breakpoint-no] +``` + +breakpoint-no: breakpoint number + +Typing "info breakpoints" without ant option will display all breakpoint information. +Example: + +``` +(sample.rb:1) info breakpoints +Num Type Enb What +1 breakpoint y at sample.rb:3 -> file name,line number +2 breakpoint n in Sample_class:sample_class_method -> [class:]method name +3 breakpoint y in sample_global_method +``` + +Displaying the specified breakpoint number: + +``` +(foo.rb:1) info breakpoints 1 3 +Num Type Enb What +1 breakpoint y at sample.rb:3 +3 breakpoint y in sample_global_method +``` + +#### List Command + +To display the code of the source file. + +Usage: + +``` +list [filename:]first[,last] +l [filename]:first[,last] +``` + +first: the opening row number +last : the closing row number + +When you specify the `first`, but not the `last` option, you will receive 10 rows. +When you do not specify both the `first` and `last` options, you will receive the next 10 rows. + +Example: + +``` +Specifying file name and first row number +sample.rb:1) list sample2.rb:5 +``` + +Specifying the file name and the first and last row number: + +``` +(sample.rb:1) list sample2.rb:6,7 +``` + +#### Print Command + +Evaluating the string as source code and printing the value. + +Usage: + +``` +print [expr] +p [expr] +``` + +expr: expression + +The expression is mandatory. +The displayed expressions will be serially ordered from 1. +If an exception occurs, the exception information will be displayed and the debugging will be continued. + +Example: + +``` +(sample.rb:1) print 1+2 +$1 = 3 +(sample.rb:1) print self +$2 = main +``` + +Below is the case of the exception: + +``` +(sample.rb:1) print (1+2 +$1 = SyntaxError: line 1: syntax error, unexpected $end, expecting ')' +``` + +#### Quit Command + +Quitting the debugger. + +Usage: + +``` +quit +q +``` + +#### Run Command + +Running the program and stopping at the first breakpoint. + +Usage: + +``` +run +r +``` + +#### Step Command + +This will run the program step by step. +When the method and the block are invoked, the program will be stop at the first row. +The program, which is developed in C, will be ignored. diff --git a/doc/guides/gc-arena-howto.md b/doc/guides/gc-arena-howto.md new file mode 100644 index 000000000..f2a0448bd --- /dev/null +++ b/doc/guides/gc-arena-howto.md @@ -0,0 +1,171 @@ +# How to use `mrb_gc_arena_save()`/`mrb_gc_arena_restore()` + +This is basically English translation of [Matz's blog post](http://www.rubyist.net/~matz/20130731.html) written in Japanese. +Some parts are updated to reflect recent changes. + +When you are extending mruby using C language, you may encounter +mysterious "arena overflow error" or memory leak or very slow +execution speed. This is an error indicating overflow of "GC arena" +implementing "conservative GC". + +GC (garbage collector) must ensure that object is "alive", in other +words, that it is referenced by somewhere from program. This can be +determined by checking that that object can be directly or indirectly +referenced by root. The local variables, global variables and +constants etc are root. + +If program execution is performed inside mruby VM, there is nothing to +worry about because GC can access all roots owned by VM. + +The problem arises when executing C functions. The object referenced +by C variable is also "alive", but mruby GC cannot aware of this, so +it might mistakenly recognize the objects referenced by only C +variables as dead. + +It is a fatal bug for GC to collect live objects. + +In CRuby, we scan C stack area, and use C variable as root to check +whether object is alive or not. Of course, because we are accessing C +stack just as memory region, we never know it is an integer or a +pointer. We workaround this by assuming that if it looks like a +pointer, then assume it as a pointer. We call it "conservative". + +By the way, CRuby's "conservative GC" has some problems. + +Its biggest problem is we have no way to access to the stack area in +portable way. Therefore, we cannot use this method if we'd like to +implement highly portable runtime, like mruby. + +So we came up an another plan to implement "conservative GC" in mruby. + +Again, the problem is that there is an object which was created in C +function, and is not referenced by Ruby world, and cannot be treated +as garbage. + +In mruby, we recognize all objects created in C function are alive. +Then we have no problem such as recognizing live object as dead. + +This means that because we cannot collect truly dead object, we may +get a little bit less efficiency, but GC itself is highly portable. +We can say goodbye to the problem that GC deletes live objects due to +optimization which sometimes occurs in CRuby. + +According to this idea, we have a table, called "GC arena", which +remembers objects created in C function. The arena is stack +structure, when C function execution is returned to mruby VM, all +objects registered in the arena are popped. + +This works very well, but GC arena causes another problem. "arena +overflow error" or memory leak. + +As of this writing, mruby automatically extend arena to remember +objects (See `MRB_GC_FIXED_ARENA` and `MRB_GC_ARENA_SIZE` in +doc/mrbconf/README.md). If you keep creating objects in C functions, +it increases memory usage, since GC never kick in. This memory usage +may look like memory leak, and also makes execution slower. + +With the build time configuration, you can limit the maximum size of +arena (e.g., 100). Then if you create many objects, arena overflows, +thus you will get "arena overflow error". + +To workaround these problems, we have `mrb_gc_arena_save()` and +`mrb_gc_arena_restore()` functions. + +`int mrb_gc_arena_save(mrb)` returns the current position of the stack +top of GC arena, and `void mrb_gc_arena_restore(mrb, idx)` sets the +stack top position to back to given idx. We uses them like so: + +```c +int arena_idx = mrb_gc_arena_save(mrb); + +...create objects... +mrb_gc_arena_restore(mrb, arena_idx); + +``` + +In mruby, C function call are surrounded by this save/restore, but we +can further optimize memory usage by surrounding save/restore, and can +avoid arena overflow. + +Let's take a real example. Here is the source code of `Array#inspect`: + +```c +static mrb_value +inspect_ary(mrb_state *mrb, mrb_value ary, mrb_value list) +{ + mrb_int i; + mrb_value s, arystr; + char head[] = { '[' }; + char sep[] = { ',', ' ' }; + char tail[] = { ']' }; + + /* check recursive */ + for(i=0; i 0) { + mrb_str_buf_cat(mrb, arystr, sep, sizeof(sep)); + } + if (mrb_array_p(RARRAY_PTR(ary)[i])) { + s = inspect_ary(mrb, RARRAY_PTR(ary)[i], list); + } + else { + s = mrb_inspect(mrb, RARRAY_PTR(ary)[i]); + } + mrb_str_buf_cat(mrb, arystr, RSTRING_PTR(s), RSTRING_LEN(s)); + mrb_gc_arena_restore(mrb, ai); + } + + mrb_str_buf_cat(mrb, arystr, tail, sizeof(tail)); + mrb_ary_pop(mrb, list); + + return arystr; +} +``` + +This is a real example, so a little bit complicated, so bear with me. +The essence of `Array#inspect` is that after stringifying each element +of array using `inspect` method, we join them together so that we can +get `inspect` representation of entire array. + +After the `inspect` representation of entire array is created, we no +longer require the individual string representation. That means that +we don't have to register these temporal objects into GC arena. + +Therefore, in `ary_inspect()` function, we do: + +* save the position of the stack top using `mrb_gc_arena_save()`. +* get `inspect` representation of each element. +* append it to the constructing entire `inspect` representation of array. +* restore stack top position using `mrb_gc_arena_restore()`. + +to keep the arena size small. + +Please note that the final `inspect` representation of entire array +was created before the call of `mrb_gc_arena_restore()`. Otherwise, +required temporal object may be deleted by GC. + +We may have a usecase that after creating many temporal objects, we'd +like to keep some of them. In this case, we cannot use the same idea +in `ary_inspect()` like appending objects to existing one. Instead, +after `mrb_gc_arena_restore()`, we register back the objects we'd like +to keep to the arena using `mrb_gc_protect(mrb, obj)`. Use +`mrb_gc_protect()` with caution because its usage could lead to arena +overflow error. + +We also have to mention that when `mrb_funcall` is called in top +level, its return value is also registered to GC arena, so calling +them repeatedly eventually lead to arena overflow error. Use +`mrb_gc_arena_save()` and `mrb_gc_arena_restore()` or possible use of +`mrb_gc_protect()` to workaround this. diff --git a/doc/guides/mrbconf.md b/doc/guides/mrbconf.md new file mode 100644 index 000000000..dfff41898 --- /dev/null +++ b/doc/guides/mrbconf.md @@ -0,0 +1,160 @@ +# mruby configuration macros. + +## How to use these macros. +You can use mrbconfs with following ways: +* Write them in `mrbconf.h`. + * Using compiler flags is preferred when building a cross binaries or multiple mruby binaries + since it's easier to use different mrbconf per each `MRuby::Build`. + * Most flags can be enabled by just commenting in. +* Pass them as compiler flags. + * Make sure you pass the same flags to all compilers since some mrbconf(e.g., `MRB_GC_FIXED_ARENA`) + changes `struct` layout and cause memory access error when C and other language(e.g., C++) is mixed. + +## stdio setting. +`ENABLE_STDIO` +* Will be defined automatically if `DISABLE_STDIO` isn't defined. +* Uses `` functions. + +`DISABLE_STDIO` +* When defined `` functions won't be used. +* Some features will be disabled when this is enabled: + * `mrb_irep` load/dump from/to file. + * Compiling mruby script from file. + * Printing features in **src/print.c**. + +## Debug macros. +`ENABLE_DEBUG` +* When defined code fetch hook and debug OP hook will be enabled. +* When using any of the hook set function pointer `code_fetch_hook` and/or `debug_op_hook` of `mrb_state`. +* Fetch hook will be called before any OP. +* Debug OP hook will be called when dispatching `OP_DEBUG`. + +`DISABLE_DEBUG` +* Will be define automatically if `ENABLE_DEBUG` isn't defined. + +`MRB_DEBUG` +* When defined `mrb_assert*` macro will be defined with macros from ``. +* Could be enabled via `enable_debug` method of `MRuby::Build`. + +## Stack configuration + +`MRB_STACK_EXTEND_DOUBLING` +* If defined doubles the stack size when extending it. +* Else extends stack with `MRB_STACK_GROWTH`. + +`MRB_STACK_GROWTH` +* Default value is `128`. +* Used in stack extending. +* Ignored when `MRB_STACK_EXTEND_DOUBLING` is defined. + +`MRB_STACK_MAX` +* Default value is `0x40000 - MRB_STACK_GROWTH`. +* Raises `RuntimeError` when stack size exceeds this value. + +## Primitive type configuration. + +`MRB_USE_FLOAT` +* When defined single precision floating point type(C type `float`) is used as `mrb_float`. +* Else double precision floating point type(C type `double`) is used as `mrb_float`. + +`MRB_INT16` +* When defined `int16_t` will be defined as `mrb_int`. +* Conflicts with `MRB_INT64`. + +`MRB_INT64` +* When defined `int64_t` will be defined as `mrb_int`. +* Conflicts with `MRB_INT16`. +* When `MRB_INT16` or `MRB_INT64` isn't defined `int`(most of the times 32-bit integer) +will be defined as `mrb_int`. + +## Garbage collector configuration. + +`MRB_GC_STRESS` +* When defined full GC is emitted per each `RBasic` allocation. +* Mainly used in memory manager debugging. + +`MRB_GC_TURN_OFF_GENERATIONAL` +* When defined turns generational GC by default. + +`MRB_GC_FIXED_ARENA` +* When defined used fixed size GC arena. +* Raises `RuntimeError` when this is defined and GC arena size exceeds `MRB_GC_ARENA_SIZE`. +* Useful tracking unnecessary mruby object allocation. + +`MRB_GC_ARENA_SIZE` +* Default value is `100`. +* Ignored when `MRB_GC_FIXED_ARENA` isn't defined. +* Defines fixed GC arena size. + +`MRB_HEAP_PAGE_SIZE` +* Defines value is `1024`. +* Specifies number of `RBasic` per each heap page. + +## Memory pool configuration. + +`POOL_ALIGNMENT` +* Default value is `4`. +* If you're allocating data types that requires alignment more than default value define the +largest value of required alignment. + +`POOL_PAGE_SIZE` +* Default value is `16000`. +* Specifies page size of pool page. +* Smaller the value is increases memory overhead. + +## State atexit configuration. + +`MRB_FIXED_STATE_ATEXIT_STACK` +* If defined enables fixed size `mrb_state` atexit stack. +* Raises `RuntimeError` when `mrb_state_atexit` call count to same `mrb_state` exceeds +`MRB_FIXED_STATE_ATEXIT_STACK_SIZE`'s value. + +`MRB_FIXED_STATE_ATEXIT_STACK_SIZE` +* Default value is `5`. +* If `MRB_FIXED_STATE_ATEXIT_STACK` isn't defined this macro is ignored. + +## `mrb_value` configuration. + +`MRB_ENDIAN_BIG` +* If defined compiles mruby for big endian machines. +* Used in `MRB_NAN_BOXING`. +* Some mrbgem use this mrbconf. + +`MRB_NAN_BOXING` +* If defined represent `mrb_value` in boxed `double`. +* Conflicts with `MRB_USE_FLOAT`. + +`MRB_WORD_BOXING` +* If defined represent `mrb_value` as a word. +* If defined `Float` will be a mruby object with `RBasic`. + +## Instance variable configuration. +`MRB_USE_IV_SEGLIST` +* If defined enable segmented list in instance variable table instead of khash. +* Segmented list is a linked list of key and value segments. +* It will linear search instead of hash search. + +`MRB_SEGMENT_SIZE` +* Default value is `4`. +* Specifies size of each segment in segment list. +* Ignored when `MRB_USE_IV_SEGLIST` isn't defined. + +`MRB_IVHASH_INIT_SIZE` +* Default value is `8`. +* Specifies initial size for instance variable table. +* Ignored when `MRB_USE_IV_SEGLIST` is defined. + +## Other configuration. +`MRB_FUNCALL_ARGC_MAX` +* Default value is `16`. +* Specifies 4th argument(`argc`) max value of `mrb_funcall`. +* Raises `ArgumentError` when the `argc` argument is bigger then this value `mrb_funcall`. + +`KHASH_DEFAULT_SIZE` +* Default value is `32`. +* Specifies default size of khash table bucket. +* Used in `kh_init_ ## name` function. + +`MRB_STR_BUF_MIN_SIZE` +* Default value is `128`. +* Specifies initial capacity of `RString` created by `mrb_str_buf_new` function.. diff --git a/doc/guides/mrbgems.md b/doc/guides/mrbgems.md new file mode 100644 index 000000000..f75231f71 --- /dev/null +++ b/doc/guides/mrbgems.md @@ -0,0 +1,337 @@ +# mrbgems + +mrbgems is a library manager to integrate C and Ruby extension in an easy and +standardised way into mruby. + +## Usage + +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: +```ruby +conf.gem '/path/to/your/gem/dir' +``` + +You can also use a relative path which would be relative from the mruby root: +```ruby +conf.gem 'examples/mrbgems/ruby_extension_example' +``` + +A remote GIT repository location for a GEM is also supported: +```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 use mrbgem from [mgem-list](https://github.com/mruby/mgem-list) use `:mgem` option: +```ruby +conf.gem :mgem => 'mruby-yaml' +conf.gem :mgem => 'yaml' # 'mruby-' prefix could be omitted +``` + +If there is missing dependencies, mrbgem dependencies solver will reference +mrbgem from core or mgem-list. + +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. + +## GemBox + +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*: +```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 +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: +```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 an absolute path like below. +```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 +contains several core components of mruby, and [full-core](../../mrbgems/full-core.gembox) +contains every gem found in the *mrbgems* directory. + +## GEM Structure + +The maximal GEM structure looks like this: + + +- GEM_NAME <- Name of GEM + | + +- include/ <- Header for Ruby extension (will exported) + | + +- 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/C++ files to extend mruby. The folder *include* contains C/C++ header +files. The folder *test* contains C/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. + +## Build process + +mrbgems expects a specification file called *mrbgem.rake* inside of your +GEM directory. A typical GEM specification could look like this for example: +```ruby +MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec| + spec.license = 'MIT' + spec.author = 'mruby developers' + spec.summary = 'Example mrbgem using C and ruby' +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` + * One line short description of mrbgem. + * Printed in build summary of rake when set. +* `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[, default_get_info])` like: +```ruby +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') + + # 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 omitted) + spec.add_dependency('mruby-onig-regexp', :github => 'mattn/mruby-onig-regexp') +end +``` + +The version requirements and default gem information are optional. + +Version requirement supports following operators: +* '=': is equal +* '!=': is not equal +* '>': is greater +* '<': is lesser +* '>=': is equal or greater +* '<=': is equal or lesser +* '~>': is equal or greater and is lesser than the next major version + * example 1: '~> 2.2.2' means '>= 2.2.2' and '< 2.3.0' + * example 2: '~> 2.2' means '>= 2.2.0' and '< 3.0.0' + +When more than one version requirements is passed, the dependency must satisfy all of it. + +You can have default gem to use as depedency when it's not defined in *build_config.rb*. +When the last argument of `add_dependency` call is `Hash`, it will be treated as default gem information. +Its format is same as argument of method `MRuby::Build#gem`, expect that it can't be treated as path gem location. + +When a special version of depedency is required, +use `MRuby::Build#gem` in *build_config.rb* to override default gem. + +If you have conflicting GEMs use the following method: +* `spec.add_conflict(gem, *requirements)` + * 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' + + 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: + +* `spec.cc.flags` (C compiler flags) +* `spec.cc.defines` (C compiler defines) +* `spec.cc.include_paths` (C compiler include paths) +* `spec.linker.flags` (Linker flags) +* `spec.linker.libraries` (Linker libraries) +* `spec.linker.library_paths` (Linker additional library path) +* `spec.bins` (Generate binary file) +* `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) + +You also can use `spec.mruby.cc` and `spec.mruby.linker` to add extra global parameters for compiler and linker. + +### include_paths and dependency + +Your GEM can export include paths to another GEMs that depends on your GEM. +By default, `/...absolute path.../{GEM_NAME}/include` will be exported. +So it is recommended not to put GEM's local header files on include/. + +These exports are retroactive. +For example: when B depends to C and A depends to B, A will get include paths exported by C. + +Exported include_paths are automatically appended to GEM local include_paths by Minirake. +You can use `spec.export_include_paths` accessor if you want more complex build. + + +## C Extension + +mruby can be extended with C. This is possible by using the C API to +integrate C libraries into mruby. + +### Preconditions + +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: +```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 + +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: + +```C +void +mrb_c_extension_example_gem_final(mrb_state* mrb) { + free(someone); +} +``` + +### Example + + +- c_extension_example/ + | + +- src/ + | | + | +- example.c <- C extension source + | + +- test/ + | | + | +- example.rb <- Test code for C extension + | + +- mrbgem.rake <- GEM specification + | + +- README.md + +## Ruby Extension + +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. + + +### Pre-Conditions + +none + +### Example + + +- ruby_extension_example/ + | + +- mrblib/ + | | + | +- example.rb <- Ruby extension source + | + +- test/ + | | + | +- example.rb <- Test code for Ruby extension + | + +- mrbgem.rake <- GEM specification + | + +- README.md + +## C and Ruby Extension + +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. + +mruby codes under *mrblib* directory would be executed after gem init C +function is called. Make sure *mruby script* depends on *C code* and +*C code* doesn't depend on *mruby script*. + +### Pre-Conditions + +See C and Ruby example. + +### 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.md diff --git a/guides/compile.md b/guides/compile.md deleted file mode 100644 index 8e91e7546..000000000 --- a/guides/compile.md +++ /dev/null @@ -1,481 +0,0 @@ -# Compile - -mruby uses Rake to compile and cross-compile all libraries and -binaries. - -## Prerequisites - -To compile mruby out of the source code you need the following tools: -* C Compiler (i.e. ```gcc```) -* Linker (i.e. ```gcc```) -* Archive utility (i.e. ```ar```) -* Parser generator (i.e. ```bison```) -* Ruby 1.8 or 1.9 (i.e. ```ruby``` or ```jruby```) - -Optional: -* GIT (to update mruby source and integrate mrbgems easier) -* C++ compiler (to use GEMs which include \*.cpp, \*.cxx, \*.cc) -* Assembler (to use GEMs which include \*.asm) - -## Usage - -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: -```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 -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```. - -## Build Configuration - -Inside of the *build_config.rb* the following options can be configured -based on your environment. - -### Toolchains - -The mruby build system already contains a set of toolchain templates which -configure the build environment for specific compiler infrastructures. - -#### GCC - -Toolchain configuration for the GNU C Compiler. -```ruby -toolchain :gcc -``` - -#### clang - -Toolchain configuration for the LLVM C Compiler clang. Mainly equal to the -GCC toolchain. -```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 -``` - -#### Android - -Toolchain configuration for Android. -```ruby -toolchain :androideabi -``` - -Requires the custom standalone Android NDK and the toolchain path -in ```ANDROID_STANDALONE_TOOLCHAIN```. - -### Binaries - -It is possible to select which tools should be compiled during the compilation -process. The following tools can be selected: -* mruby (mruby interpreter) -* mirb (mruby interactive shell) - -To select them declare conf.gem as follows: -```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```. -```ruby -conf.file_separator = '/' -``` - -### C Compiler - -Configuration of the C compiler binary, flags and include paths. -```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```: -```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```: -```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: -```ruby -def conf.cc.header_search_paths - ['/opt/local/include'] + include_paths -end -``` - -### Linker - -Configuration of the Linker binary, flags and library paths. -```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. -```ruby -conf.archiver do |archiver| - archiver.command = ... - archiver.archive_options = ... -end -``` - -### Parser Generator - -Configuration of the Parser Generator binary and flags. -```ruby -conf.yacc do |yacc| - yacc.command = ... - yacc.compile_options = ... -end -``` - -### GPerf - -Configuration of the GPerf binary and flags. -```ruby -conf.gperf do |gperf| - gperf.command = ... - gperf.compile_options = ... -end -``` - -### File Extensions -```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 without additional configuration -conf.gem 'path/to/another/gem' -``` - -See doc/mrbgems/README.md for more option about mrbgems. - -### Mrbtest - -Configuration Mrbtest build process. - -If you want mrbtest.a only, You should set ```conf.build_mrbtest_lib_only``` -```ruby -conf.build_mrbtest_lib_only -``` - -### Bintest - -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: -```ruby -conf.enable_bintest -``` - -### C++ ABI - -mruby can use C++ exception to raise exception internally. -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 explicitly add the following: -```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: -```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: -```ruby -conf.enable_debug -``` - -When debugging mode is enabled -* Macro ```MRB_DEBUG``` would be defined. - * Which means ```mrb_assert()``` macro is enabled. -* Debug information of irep would be generated by ```mrbc```. - * Because ```-g``` flag would be added to ```mrbc``` runner. - * You can have better backtrace of mruby scripts with this. - -## Cross-Compilation - -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: -```ruby -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```. - -### Mrbtest in Cross-Compilation - -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 - - 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 - -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: -* 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* - -``` - _____ _____ ______ ____ ____ _____ _____ ____ -| CC |->|GEN |->|AR |->|CC |->|CC |->|AR |->|CC |->|CC | -| *.c | |y.tab| |core.a| |mrbc| |*.rb| |lib.a| |mruby| |mirb| - ----- ----- ------ ---- ---- ----- ----- ---- -``` - -### Cross-Compilation - -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 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* - -``` - _______________________________________________________________ -| Native Compilation for Host System | -| _____ ______ _____ ____ ____ _____ | -| | CC | -> |AR | -> |GEN | -> |CC | -> |CC | -> |AR | | -| | *.c | |core.a| |y.tab| |mrbc| |*.rb| |lib.a| | -| ----- ------ ----- ---- ---- ----- | - --------------------------------------------------------------- - || - \||/ - \/ - ________________________________________________________________ -| Cross Compilation for Target System | -| _____ _____ _____ ____ ______ _____ | -| | CC | -> |AR | -> |CC | -> |CC | -> |AR | -> |CC | | -| | *.c | |lib.a| |mruby| |mirb| |core.a| |mrbc | | -| ----- ----- ----- ---- ------ ----- | - ---------------------------------------------------------------- -``` - -## Build Configuration Examples - -### Minimal Library - -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. - -```ruby -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). - -## 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 -generated. You can copy this binary and run on your target system. diff --git a/guides/debugger.md b/guides/debugger.md deleted file mode 100755 index a13e91cec..000000000 --- a/guides/debugger.md +++ /dev/null @@ -1,370 +0,0 @@ -# How to Use the mruby Debugger - -copyright (c) 2014 Specified Non-Profit Corporation mruby Forum - -## 1. Summary - -This file documents the mruby debugger ('mrdb') methods. - -## 2 Debugging with mrdb - -## 2.1 Building mrdb - -The trunk of the mruby source tree, with the most recent mrdb, can be checked out with the following command: - -```bash -$ git clone https://github.com/mruby/mruby.git -``` - -To run the `make` command: - -```bash -$ cd mruby -$ make -``` - -By default, the `make` command will install the debugger files into mruby/bin. - -You can add the path for mrdb on your host environment with the following command: - -```bash -$ echo "export PATH=\$PATH:MRUBY_ROOT/bin" >> ~/.bashrc -$ source ~/.bashrc -``` - -`*MRUBY_ROOT` is the directory in which mruby source code will be installed. - -To confirm mrdb was installed properly, run mrdb with the `--version` option: - -```bash -$ mrdb --version -mruby 1.1.0 (2014-11-19) -``` - -## 2.2 Basic Operation - -### 2.2.1 Debugging mruby Script Files (rb file) with mrdb - -To invoke the mruby debugger, just type `mrdb`. - -To specify the script file: - -```bash -$ mrdb [option] file name -``` - -For example: Debugging sample.rb - -```bash -$ mrdb sample.rb -``` - -You can execute the shell commands listed below: - -|command|description| -|:-:|:--| -|run|execute programs| -|step|execute stepping| -|continue|execute continuing program| -|break|configure the breaking point| -|delete|deleting the breaking points| -|disable|disabling the breaking points| -|enable|enabling the breaking points| -|info breakpoints|showing list of the breaking points| -|print|evaluating and printing the values of the mruby expressions in the script| -|list|displaying the source cords| -|help|showing help| -|quit|terminating the mruby debugger| - -### 2.2.2 Debugging mruby Binary Files (mrb file) with mrdb - -You can debug the mruby binary files. - -#### 2.2.2.1 Debugging the binary files - -* notice -To debug mruby binary files, you need to compile mruby files with option `-g`. - -```bash -$ mrbc -g sample.rb -``` - -You can debug the mruby binary files with following command and the option `-b`. - -```bash -$ mrdb -b sample.mrb -``` - -Then you can execute all debugger shell commands. - -#### Break Command - -You can use any breakpoint to stop the program by specifying the line number and method name. -The breakpoint list will be displayed after you have set the breakpoint successfully. - -Usage: - -``` -break [file:]linenum -b [file:]linenum -break [class:]method -b [class:]method -``` - -The breakpoint will be ordered in serial from 1. -The number, which was given to the deleted breakpoint, will never be given to another breakpoint again. - -You can give multiple breakpoints to specified the line number and method. -Be ware that breakpoint command will not check the validity of the class name and method name. - -You can get the current breakpoint information by the following options. - -breakpoint breakpoint number : file name. line number - -breakpoint breakpoint number : [class name,] method name - -#### Continue Command - -Usage: - -``` -continue [N] -c [N] -``` - -N: the next breakpoint number - -When resuming the program, it will stop at breakpoint N (N-1 breakpoint will be ignored). - -When you run the `continue` command without specifying N, the program will be stopped at the next breakpoint. - -Example: - -``` -(foo.rb:1) continue 3 -``` - -This will resume the program and stop it at the third breakpoint. - -#### Delete Command - -This will delete the specified breakpoint. - -Usage: - -``` -delete [breakpoint-no] -d [breakpoint-no] -``` - -breakpoint-no: breakpoint number - -Example: - -``` -(foo.rb:1) delete -``` - -This will delete all of the breakpoints. - -``` -(foo.rb:1) delete 1 3 -``` - -This will delete the breakpoint at 1 and 3. - -#### Disable Command - -This will disable the specified breakpoint. - -Usage: - -``` -disable [breakpoint-no] -dis [breakpoint-no] -``` - -reappointing: breakpoint number - -Example: - -``` -(foo.rb:1) disable -``` - -Use `disable` if you would like to disable all of the breakpoints. - -``` -(foo.rb:1) disable 1 3 -``` - -This will disable the breakpoints at 1 and 3. - -#### Enable Command - -This will enable the specified breakpoints. - -Usage: - -``` -enable [breakpoint-no] -e [breakpoint-no] -``` - -breakpoint-no: breakpoint number - -Example: - -``` -(foo.rb:1) enable -``` - -Enabling all breakpoints -``` -(foo.rb:1) enable 1 3 -``` - -Enabling the breakpoint 1 and 3 - -#### eval command - -Evaluating the string as source code and printing the value. - -Same as print command, please see print command. - -#### help command - -Displaying the help message. - -Usage: - -``` -help [command] -h [command] -``` - -Typing `help` without any options will display the command list. - -#### Info Breakpoints Command - -Displaying the specified breakpoint information. - -Usage: - -``` -info breakpoints [breakpoint-no] -i b [breakpoint-no] -``` - -breakpoint-no: breakpoint number - -Typing "info breakpoints" without ant option will display all breakpoint information. -Example: - -``` -(sample.rb:1) info breakpoints -Num Type Enb What -1 breakpoint y at sample.rb:3 -> file name,line number -2 breakpoint n in Sample_class:sample_class_method -> [class:]method name -3 breakpoint y in sample_global_method -``` - -Displaying the specified breakpoint number: - -``` -(foo.rb:1) info breakpoints 1 3 -Num Type Enb What -1 breakpoint y at sample.rb:3 -3 breakpoint y in sample_global_method -``` - -#### List Command - -To display the code of the source file. - -Usage: - -``` -list [filename:]first[,last] -l [filename]:first[,last] -``` - -first: the opening row number -last : the closing row number - -When you specify the `first`, but not the `last` option, you will receive 10 rows. -When you do not specify both the `first` and `last` options, you will receive the next 10 rows. - -Example: - -``` -Specifying file name and first row number -sample.rb:1) list sample2.rb:5 -``` - -Specifying the file name and the first and last row number: - -``` -(sample.rb:1) list sample2.rb:6,7 -``` - -#### Print Command - -Evaluating the string as source code and printing the value. - -Usage: - -``` -print [expr] -p [expr] -``` - -expr: expression - -The expression is mandatory. -The displayed expressions will be serially ordered from 1. -If an exception occurs, the exception information will be displayed and the debugging will be continued. - -Example: - -``` -(sample.rb:1) print 1+2 -$1 = 3 -(sample.rb:1) print self -$2 = main -``` - -Below is the case of the exception: - -``` -(sample.rb:1) print (1+2 -$1 = SyntaxError: line 1: syntax error, unexpected $end, expecting ')' -``` - -#### Quit Command - -Quitting the debugger. - -Usage: - -``` -quit -q -``` - -#### Run Command - -Running the program and stopping at the first breakpoint. - -Usage: - -``` -run -r -``` - -#### Step Command - -This will run the program step by step. -When the method and the block are invoked, the program will be stop at the first row. -The program, which is developed in C, will be ignored. diff --git a/guides/mrbconf.md b/guides/mrbconf.md deleted file mode 100644 index dfff41898..000000000 --- a/guides/mrbconf.md +++ /dev/null @@ -1,160 +0,0 @@ -# mruby configuration macros. - -## How to use these macros. -You can use mrbconfs with following ways: -* Write them in `mrbconf.h`. - * Using compiler flags is preferred when building a cross binaries or multiple mruby binaries - since it's easier to use different mrbconf per each `MRuby::Build`. - * Most flags can be enabled by just commenting in. -* Pass them as compiler flags. - * Make sure you pass the same flags to all compilers since some mrbconf(e.g., `MRB_GC_FIXED_ARENA`) - changes `struct` layout and cause memory access error when C and other language(e.g., C++) is mixed. - -## stdio setting. -`ENABLE_STDIO` -* Will be defined automatically if `DISABLE_STDIO` isn't defined. -* Uses `` functions. - -`DISABLE_STDIO` -* When defined `` functions won't be used. -* Some features will be disabled when this is enabled: - * `mrb_irep` load/dump from/to file. - * Compiling mruby script from file. - * Printing features in **src/print.c**. - -## Debug macros. -`ENABLE_DEBUG` -* When defined code fetch hook and debug OP hook will be enabled. -* When using any of the hook set function pointer `code_fetch_hook` and/or `debug_op_hook` of `mrb_state`. -* Fetch hook will be called before any OP. -* Debug OP hook will be called when dispatching `OP_DEBUG`. - -`DISABLE_DEBUG` -* Will be define automatically if `ENABLE_DEBUG` isn't defined. - -`MRB_DEBUG` -* When defined `mrb_assert*` macro will be defined with macros from ``. -* Could be enabled via `enable_debug` method of `MRuby::Build`. - -## Stack configuration - -`MRB_STACK_EXTEND_DOUBLING` -* If defined doubles the stack size when extending it. -* Else extends stack with `MRB_STACK_GROWTH`. - -`MRB_STACK_GROWTH` -* Default value is `128`. -* Used in stack extending. -* Ignored when `MRB_STACK_EXTEND_DOUBLING` is defined. - -`MRB_STACK_MAX` -* Default value is `0x40000 - MRB_STACK_GROWTH`. -* Raises `RuntimeError` when stack size exceeds this value. - -## Primitive type configuration. - -`MRB_USE_FLOAT` -* When defined single precision floating point type(C type `float`) is used as `mrb_float`. -* Else double precision floating point type(C type `double`) is used as `mrb_float`. - -`MRB_INT16` -* When defined `int16_t` will be defined as `mrb_int`. -* Conflicts with `MRB_INT64`. - -`MRB_INT64` -* When defined `int64_t` will be defined as `mrb_int`. -* Conflicts with `MRB_INT16`. -* When `MRB_INT16` or `MRB_INT64` isn't defined `int`(most of the times 32-bit integer) -will be defined as `mrb_int`. - -## Garbage collector configuration. - -`MRB_GC_STRESS` -* When defined full GC is emitted per each `RBasic` allocation. -* Mainly used in memory manager debugging. - -`MRB_GC_TURN_OFF_GENERATIONAL` -* When defined turns generational GC by default. - -`MRB_GC_FIXED_ARENA` -* When defined used fixed size GC arena. -* Raises `RuntimeError` when this is defined and GC arena size exceeds `MRB_GC_ARENA_SIZE`. -* Useful tracking unnecessary mruby object allocation. - -`MRB_GC_ARENA_SIZE` -* Default value is `100`. -* Ignored when `MRB_GC_FIXED_ARENA` isn't defined. -* Defines fixed GC arena size. - -`MRB_HEAP_PAGE_SIZE` -* Defines value is `1024`. -* Specifies number of `RBasic` per each heap page. - -## Memory pool configuration. - -`POOL_ALIGNMENT` -* Default value is `4`. -* If you're allocating data types that requires alignment more than default value define the -largest value of required alignment. - -`POOL_PAGE_SIZE` -* Default value is `16000`. -* Specifies page size of pool page. -* Smaller the value is increases memory overhead. - -## State atexit configuration. - -`MRB_FIXED_STATE_ATEXIT_STACK` -* If defined enables fixed size `mrb_state` atexit stack. -* Raises `RuntimeError` when `mrb_state_atexit` call count to same `mrb_state` exceeds -`MRB_FIXED_STATE_ATEXIT_STACK_SIZE`'s value. - -`MRB_FIXED_STATE_ATEXIT_STACK_SIZE` -* Default value is `5`. -* If `MRB_FIXED_STATE_ATEXIT_STACK` isn't defined this macro is ignored. - -## `mrb_value` configuration. - -`MRB_ENDIAN_BIG` -* If defined compiles mruby for big endian machines. -* Used in `MRB_NAN_BOXING`. -* Some mrbgem use this mrbconf. - -`MRB_NAN_BOXING` -* If defined represent `mrb_value` in boxed `double`. -* Conflicts with `MRB_USE_FLOAT`. - -`MRB_WORD_BOXING` -* If defined represent `mrb_value` as a word. -* If defined `Float` will be a mruby object with `RBasic`. - -## Instance variable configuration. -`MRB_USE_IV_SEGLIST` -* If defined enable segmented list in instance variable table instead of khash. -* Segmented list is a linked list of key and value segments. -* It will linear search instead of hash search. - -`MRB_SEGMENT_SIZE` -* Default value is `4`. -* Specifies size of each segment in segment list. -* Ignored when `MRB_USE_IV_SEGLIST` isn't defined. - -`MRB_IVHASH_INIT_SIZE` -* Default value is `8`. -* Specifies initial size for instance variable table. -* Ignored when `MRB_USE_IV_SEGLIST` is defined. - -## Other configuration. -`MRB_FUNCALL_ARGC_MAX` -* Default value is `16`. -* Specifies 4th argument(`argc`) max value of `mrb_funcall`. -* Raises `ArgumentError` when the `argc` argument is bigger then this value `mrb_funcall`. - -`KHASH_DEFAULT_SIZE` -* Default value is `32`. -* Specifies default size of khash table bucket. -* Used in `kh_init_ ## name` function. - -`MRB_STR_BUF_MIN_SIZE` -* Default value is `128`. -* Specifies initial capacity of `RString` created by `mrb_str_buf_new` function.. diff --git a/guides/mrbgems.md b/guides/mrbgems.md deleted file mode 100644 index f75231f71..000000000 --- a/guides/mrbgems.md +++ /dev/null @@ -1,337 +0,0 @@ -# mrbgems - -mrbgems is a library manager to integrate C and Ruby extension in an easy and -standardised way into mruby. - -## Usage - -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: -```ruby -conf.gem '/path/to/your/gem/dir' -``` - -You can also use a relative path which would be relative from the mruby root: -```ruby -conf.gem 'examples/mrbgems/ruby_extension_example' -``` - -A remote GIT repository location for a GEM is also supported: -```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 use mrbgem from [mgem-list](https://github.com/mruby/mgem-list) use `:mgem` option: -```ruby -conf.gem :mgem => 'mruby-yaml' -conf.gem :mgem => 'yaml' # 'mruby-' prefix could be omitted -``` - -If there is missing dependencies, mrbgem dependencies solver will reference -mrbgem from core or mgem-list. - -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. - -## GemBox - -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*: -```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 -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: -```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 an absolute path like below. -```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 -contains several core components of mruby, and [full-core](../../mrbgems/full-core.gembox) -contains every gem found in the *mrbgems* directory. - -## GEM Structure - -The maximal GEM structure looks like this: - - +- GEM_NAME <- Name of GEM - | - +- include/ <- Header for Ruby extension (will exported) - | - +- 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/C++ files to extend mruby. The folder *include* contains C/C++ header -files. The folder *test* contains C/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. - -## Build process - -mrbgems expects a specification file called *mrbgem.rake* inside of your -GEM directory. A typical GEM specification could look like this for example: -```ruby -MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec| - spec.license = 'MIT' - spec.author = 'mruby developers' - spec.summary = 'Example mrbgem using C and ruby' -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` - * One line short description of mrbgem. - * Printed in build summary of rake when set. -* `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[, default_get_info])` like: -```ruby -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') - - # 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 omitted) - spec.add_dependency('mruby-onig-regexp', :github => 'mattn/mruby-onig-regexp') -end -``` - -The version requirements and default gem information are optional. - -Version requirement supports following operators: -* '=': is equal -* '!=': is not equal -* '>': is greater -* '<': is lesser -* '>=': is equal or greater -* '<=': is equal or lesser -* '~>': is equal or greater and is lesser than the next major version - * example 1: '~> 2.2.2' means '>= 2.2.2' and '< 2.3.0' - * example 2: '~> 2.2' means '>= 2.2.0' and '< 3.0.0' - -When more than one version requirements is passed, the dependency must satisfy all of it. - -You can have default gem to use as depedency when it's not defined in *build_config.rb*. -When the last argument of `add_dependency` call is `Hash`, it will be treated as default gem information. -Its format is same as argument of method `MRuby::Build#gem`, expect that it can't be treated as path gem location. - -When a special version of depedency is required, -use `MRuby::Build#gem` in *build_config.rb* to override default gem. - -If you have conflicting GEMs use the following method: -* `spec.add_conflict(gem, *requirements)` - * 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' - - 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: - -* `spec.cc.flags` (C compiler flags) -* `spec.cc.defines` (C compiler defines) -* `spec.cc.include_paths` (C compiler include paths) -* `spec.linker.flags` (Linker flags) -* `spec.linker.libraries` (Linker libraries) -* `spec.linker.library_paths` (Linker additional library path) -* `spec.bins` (Generate binary file) -* `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) - -You also can use `spec.mruby.cc` and `spec.mruby.linker` to add extra global parameters for compiler and linker. - -### include_paths and dependency - -Your GEM can export include paths to another GEMs that depends on your GEM. -By default, `/...absolute path.../{GEM_NAME}/include` will be exported. -So it is recommended not to put GEM's local header files on include/. - -These exports are retroactive. -For example: when B depends to C and A depends to B, A will get include paths exported by C. - -Exported include_paths are automatically appended to GEM local include_paths by Minirake. -You can use `spec.export_include_paths` accessor if you want more complex build. - - -## C Extension - -mruby can be extended with C. This is possible by using the C API to -integrate C libraries into mruby. - -### Preconditions - -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: -```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 - -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: - -```C -void -mrb_c_extension_example_gem_final(mrb_state* mrb) { - free(someone); -} -``` - -### Example - - +- c_extension_example/ - | - +- src/ - | | - | +- example.c <- C extension source - | - +- test/ - | | - | +- example.rb <- Test code for C extension - | - +- mrbgem.rake <- GEM specification - | - +- README.md - -## Ruby Extension - -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. - - -### Pre-Conditions - -none - -### Example - - +- ruby_extension_example/ - | - +- mrblib/ - | | - | +- example.rb <- Ruby extension source - | - +- test/ - | | - | +- example.rb <- Test code for Ruby extension - | - +- mrbgem.rake <- GEM specification - | - +- README.md - -## C and Ruby Extension - -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. - -mruby codes under *mrblib* directory would be executed after gem init C -function is called. Make sure *mruby script* depends on *C code* and -*C code* doesn't depend on *mruby script*. - -### Pre-Conditions - -See C and Ruby example. - -### 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.md -- cgit v1.2.3 From 4dc98697000cf95cf34ee03d8cb0e53882a1c8de Mon Sep 17 00:00:00 2001 From: Seba Gamboa Date: Thu, 8 Oct 2015 12:45:25 -0300 Subject: Merge contents from doc/api/mruby/version.h.md --- include/mruby/version.h | 64 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 61 insertions(+), 3 deletions(-) diff --git a/include/mruby/version.h b/include/mruby/version.h index cf5aa57eb..733863511 100644 --- a/include/mruby/version.h +++ b/include/mruby/version.h @@ -10,43 +10,101 @@ #include "mruby/common.h" /** - * MRuby version macros + * mruby version definition macros */ MRB_BEGIN_DECL +/* + * A passed in expression. + */ #define MRB_STRINGIZE0(expr) #expr + +/* + * Passes in an expression to MRB_STRINGIZE0. + */ #define MRB_STRINGIZE(expr) MRB_STRINGIZE0(expr) +/* + * The version of Ruby used by mruby. + */ #define MRUBY_RUBY_VERSION "1.9" + +/* + * Ruby engine. + */ #define MRUBY_RUBY_ENGINE "mruby" +/* + * Major release version number. + */ #define MRUBY_RELEASE_MAJOR 1 + +/* + * Minor release version number. + */ #define MRUBY_RELEASE_MINOR 1 + +/* + * Tiny release version number. + */ #define MRUBY_RELEASE_TEENY 1 +/* + * The mruby version. + */ #define MRUBY_VERSION MRB_STRINGIZE(MRUBY_RELEASE_MAJOR) "." MRB_STRINGIZE(MRUBY_RELEASE_MINOR) "." MRB_STRINGIZE(MRUBY_RELEASE_TEENY) + +/* + * Release number. + */ #define MRUBY_RELEASE_NO (MRUBY_RELEASE_MAJOR * 100 * 100 + MRUBY_RELEASE_MINOR * 100 + MRUBY_RELEASE_TEENY) + +/* + * Release year. + */ #define MRUBY_RELEASE_YEAR 2014 + +/* + * Release month. + */ #define MRUBY_RELEASE_MONTH 11 + +/* + * Release day. + */ #define MRUBY_RELEASE_DAY 19 + +/* + * Release date as a string. + */ #define MRUBY_RELEASE_DATE MRB_STRINGIZE(MRUBY_RELEASE_YEAR) "-" MRB_STRINGIZE(MRUBY_RELEASE_MONTH) "-" MRB_STRINGIZE(MRUBY_RELEASE_DAY) +/* + * The year mruby was first created. + */ #define MRUBY_BIRTH_YEAR 2010 +/* + * MRuby's authors. + */ #define MRUBY_AUTHOR "mruby developers" - +/* + * mruby's version, and release date. + */ #define MRUBY_DESCRIPTION \ "mruby " MRUBY_VERSION \ " (" MRUBY_RELEASE_DATE ") " \ +/* + * mruby's copyright information. + */ #define MRUBY_COPYRIGHT \ "mruby - Copyright (c) " \ MRB_STRINGIZE(MRUBY_BIRTH_YEAR)"-" \ MRB_STRINGIZE(MRUBY_RELEASE_YEAR)" " \ MRUBY_AUTHOR \ -/** @} */ MRB_END_DECL #endif /* MRUBY_VERSION_H */ -- cgit v1.2.3 From 649901b75c3a800ba132f9cb9fbcf21e705c1912 Mon Sep 17 00:00:00 2001 From: Seba Gamboa Date: Thu, 8 Oct 2015 12:55:28 -0300 Subject: Merge doc/api/mruby/string.h.md contents --- include/mruby/string.h | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/include/mruby/string.h b/include/mruby/string.h index 04040663d..c049a72c7 100644 --- a/include/mruby/string.h +++ b/include/mruby/string.h @@ -66,6 +66,9 @@ struct RString { #define RSTR_SET_FROZEN_FLAG(s) ((s)->flags |= MRB_STR_FROZEN) #define RSTR_UNSET_FROZEN_FLAG(s) ((s)->flags &= ~MRB_STR_FROZEN) +/* + * Returns a pointer from a Ruby string + */ #define mrb_str_ptr(s) ((struct RString*)(mrb_ptr(s))) #define RSTRING(s) mrb_str_ptr(s) #define RSTRING_PTR(s) RSTR_PTR(RSTRING(s)) @@ -85,34 +88,104 @@ mrb_int mrb_str_strlen(mrb_state*, struct RString*); void mrb_gc_free_str(mrb_state*, struct RString*); MRB_API void mrb_str_modify(mrb_state*, struct RString*); MRB_API void mrb_str_concat(mrb_state*, mrb_value, mrb_value); + +/* + * Adds two strings together. + */ MRB_API mrb_value mrb_str_plus(mrb_state*, mrb_value, mrb_value); + +/* + * Converts pointer into a Ruby string. + */ MRB_API mrb_value mrb_ptr_to_str(mrb_state *, void*); + +/* + * Returns an object as a Ruby string. + */ MRB_API mrb_value mrb_obj_as_string(mrb_state *mrb, mrb_value obj); + +/* + * Resizes the string's length. + */ MRB_API mrb_value mrb_str_resize(mrb_state *mrb, mrb_value str, mrb_int len); + +/* + * Returns a sub string. + */ MRB_API mrb_value mrb_str_substr(mrb_state *mrb, mrb_value str, mrb_int beg, mrb_int len); + +/* + * Returns a Ruby string type. + */ MRB_API mrb_value mrb_string_type(mrb_state *mrb, mrb_value str); + MRB_API mrb_value mrb_check_string_type(mrb_state *mrb, mrb_value str); MRB_API mrb_value mrb_str_buf_new(mrb_state *mrb, size_t capa); MRB_API const char *mrb_string_value_cstr(mrb_state *mrb, mrb_value *ptr); MRB_API const char *mrb_string_value_ptr(mrb_state *mrb, mrb_value ptr); + +/* + * Duplicates a string object. + */ MRB_API mrb_value mrb_str_dup(mrb_state *mrb, mrb_value str); + +/* + * Returns a symbol from a passed in string. + */ MRB_API mrb_value mrb_str_intern(mrb_state *mrb, mrb_value self); + MRB_API mrb_value mrb_str_to_inum(mrb_state *mrb, mrb_value str, mrb_int base, mrb_bool badcheck); MRB_API double mrb_str_to_dbl(mrb_state *mrb, mrb_value str, mrb_bool badcheck); + +/* + * Returns a converted string type. + */ MRB_API mrb_value mrb_str_to_str(mrb_state *mrb, mrb_value str); + +/* + * Returns true if the strings match and false if the strings don't match. + */ MRB_API mrb_bool mrb_str_equal(mrb_state *mrb, mrb_value str1, mrb_value str2); + +/* + * Returns a concated string comprised of a Ruby string and a C string. + * + * @see mrb_str_cat_cstr + */ MRB_API mrb_value mrb_str_cat(mrb_state *mrb, mrb_value str, const char *ptr, size_t len); + +/* + * Returns a concated string comprised of a Ruby string and a C string. + * + * @see mrb_str_cat + */ MRB_API mrb_value mrb_str_cat_cstr(mrb_state *mrb, mrb_value str, const char *ptr); MRB_API mrb_value mrb_str_cat_str(mrb_state *mrb, mrb_value str, mrb_value str2); #define mrb_str_cat_lit(mrb, str, lit) mrb_str_cat(mrb, str, lit, mrb_strlen_lit(lit)) + +/* + * Adds str2 to the end of str1. + */ MRB_API mrb_value mrb_str_append(mrb_state *mrb, mrb_value str, mrb_value str2); +/* + * Returns 0 if both Ruby strings are equal. Returns a value < 0 if Ruby str1 is less than Ruby str2. Returns a value > 0 if Ruby str2 is greater than Ruby str1. + */ MRB_API int mrb_str_cmp(mrb_state *mrb, mrb_value str1, mrb_value str2); + +/* + * Returns a C string from a Ruby string. + */ MRB_API char *mrb_str_to_cstr(mrb_state *mrb, mrb_value str); + mrb_value mrb_str_pool(mrb_state *mrb, mrb_value str); mrb_int mrb_str_hash(mrb_state *mrb, mrb_value str); mrb_value mrb_str_dump(mrb_state *mrb, mrb_value str); + +/* + * Returns a printable version of str, surrounded by quote marks, with special characters escaped. + */ mrb_value mrb_str_inspect(mrb_state *mrb, mrb_value str); void mrb_noregexp(mrb_state *mrb, mrb_value self); -- cgit v1.2.3 From e441fdaad8c769470bb55e3ed839e89b18164476 Mon Sep 17 00:00:00 2001 From: Seba Gamboa Date: Thu, 8 Oct 2015 13:17:31 -0300 Subject: Merge doc/api/mruby/value.h.md docs --- include/mruby/value.h | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/include/mruby/value.h b/include/mruby/value.h index 216fe9279..dfad3ec73 100644 --- a/include/mruby/value.h +++ b/include/mruby/value.h @@ -128,8 +128,10 @@ enum mrb_vtype { #define mrb_test(o) mrb_bool(o) MRB_API mrb_bool mrb_regexp_p(struct mrb_state*, mrb_value); -static inline mrb_value -mrb_float_value(struct mrb_state *mrb, mrb_float f) +/* + * Returns a float in Ruby. + */ +MRB_INLINE mrb_value mrb_float_value(struct mrb_state *mrb, mrb_float f) { mrb_value v; (void) mrb; @@ -146,8 +148,10 @@ mrb_cptr_value(struct mrb_state *mrb, void *p) return v; } -static inline mrb_value -mrb_fixnum_value(mrb_int i) +/* + * Returns a fixnum in Ruby. + */ +MRB_INLINE mrb_value mrb_fixnum_value(mrb_int i) { mrb_value v; SET_INT_VALUE(v, i); @@ -171,7 +175,7 @@ mrb_obj_value(void *p) } -/** +/* * Get a nil mrb_value object. * * @return @@ -184,16 +188,20 @@ MRB_INLINE mrb_value mrb_nil_value(void) return v; } -static inline mrb_value -mrb_false_value(void) +/* + * Returns false in Ruby. + */ +MRB_INLINE mrb_value mrb_false_value(void) { mrb_value v; SET_FALSE_VALUE(v); return v; } -static inline mrb_value -mrb_true_value(void) +/* + * Returns true in Ruby. + */ +MRB_INLINE mrb_value mrb_true_value(void) { mrb_value v; SET_TRUE_VALUE(v); -- cgit v1.2.3 From 5dfdd53bcce1ad9bdea0ff214e31ec2366d6dcaa Mon Sep 17 00:00:00 2001 From: Seba Gamboa Date: Thu, 8 Oct 2015 13:26:23 -0300 Subject: Merge doc/api/mruby/range.h.md docs --- include/mruby/range.h | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/include/mruby/range.h b/include/mruby/range.h index f97853fc5..008698fac 100644 --- a/include/mruby/range.h +++ b/include/mruby/range.h @@ -28,7 +28,18 @@ struct RRange { #define mrb_range_ptr(v) ((struct RRange*)(mrb_ptr(v))) #define mrb_range_value(p) mrb_obj_value((void*)(p)) -MRB_API mrb_value mrb_range_new(mrb_state*, mrb_value, mrb_value, mrb_bool); +/* + * Initializes a Range. + * + * If the third parameter is FALSE then it includes the last value in the range. + * If the third parameter is TRUE then it excludes the last value in the range. + * + * @param start the beginning value. + * @param end the ending value. + * @param exclude represents the inclusion or exclusion of the last value. + */ +MRB_API mrb_value mrb_range_new(mrb_state *mrb, mrb_value start, mrb_value end, mrb_bool exclude); + MRB_API mrb_bool mrb_range_beg_len(mrb_state *mrb, mrb_value range, mrb_int *begp, mrb_int *lenp, mrb_int len); mrb_value mrb_get_values_at(mrb_state *mrb, mrb_value obj, mrb_int olen, mrb_int argc, const mrb_value *argv, mrb_value (*func)(mrb_state*, mrb_value, mrb_int)); -- cgit v1.2.3 From 11fb10a21a7f62ed2bc3e530056b4960f0394ca0 Mon Sep 17 00:00:00 2001 From: Seba Gamboa Date: Thu, 8 Oct 2015 13:29:57 -0300 Subject: Merge doc/api/mruby/hash.h.md docs --- include/mruby/hash.h | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/include/mruby/hash.h b/include/mruby/hash.h index ea4a79dc4..542986c92 100644 --- a/include/mruby/hash.h +++ b/include/mruby/hash.h @@ -24,15 +24,39 @@ struct RHash { #define mrb_hash_value(p) mrb_obj_value((void*)(p)) MRB_API mrb_value mrb_hash_new_capa(mrb_state*, int); + +/* + * Initializes a new hash. + */ MRB_API mrb_value mrb_hash_new(mrb_state *mrb); +/* + * Sets a keys and values to hashes. + */ MRB_API void mrb_hash_set(mrb_state *mrb, mrb_value hash, mrb_value key, mrb_value val); + +/* + * Gets a value from a key. + */ MRB_API mrb_value mrb_hash_get(mrb_state *mrb, mrb_value hash, mrb_value key); + MRB_API mrb_value mrb_hash_fetch(mrb_state *mrb, mrb_value hash, mrb_value key, mrb_value def); + +/* + * Deletes hash key and value pair. + */ MRB_API mrb_value mrb_hash_delete_key(mrb_state *mrb, mrb_value hash, mrb_value key); + +/* + * Gets an array of keys. + */ MRB_API mrb_value mrb_hash_keys(mrb_state *mrb, mrb_value hash); MRB_API mrb_value mrb_check_hash_type(mrb_state *mrb, mrb_value hash); MRB_API mrb_value mrb_hash_empty_p(mrb_state *mrb, mrb_value self); + +/* + * Clears the hash. + */ MRB_API mrb_value mrb_hash_clear(mrb_state *mrb, mrb_value hash); /* RHASH_TBL allocates st_table if not available. */ -- cgit v1.2.3 From ef73ec560ec4be77fdcfbbb89e7f956a31902fb6 Mon Sep 17 00:00:00 2001 From: Seba Gamboa Date: Thu, 8 Oct 2015 13:33:11 -0300 Subject: array header cleanup --- include/mruby/array.h | 62 +++++++++++++++++++-------------------------------- 1 file changed, 23 insertions(+), 39 deletions(-) diff --git a/include/mruby/array.h b/include/mruby/array.h index cd4156836..16f5acee2 100644 --- a/include/mruby/array.h +++ b/include/mruby/array.h @@ -9,7 +9,7 @@ #include "mruby/common.h" -/** +/* * Array class */ MRB_BEGIN_DECL @@ -46,89 +46,74 @@ void mrb_ary_decref(mrb_state*, mrb_shared_array*); MRB_API void mrb_ary_modify(mrb_state*, struct RArray*); MRB_API mrb_value mrb_ary_new_capa(mrb_state*, mrb_int); -/** +/* * Initializes a new array. * * Equivalent to: * * Array.new * - * @param mrb - * The MRuby state reference. - * @return - * The initialized array + * @param mrb The mruby state reference. + * @return The initialized array */ MRB_API mrb_value mrb_ary_new(mrb_state *mrb); + MRB_API mrb_value mrb_ary_new_from_values(mrb_state *mrb, mrb_int size, const mrb_value *vals); MRB_API mrb_value mrb_assoc_new(mrb_state *mrb, mrb_value car, mrb_value cdr); MRB_API void mrb_ary_concat(mrb_state*, mrb_value, mrb_value); MRB_API mrb_value mrb_ary_splat(mrb_state*, mrb_value); -/** +/* * Pushes value into array. * * Equivalent to: * * ary << value * - * @param mrb - * The MRuby state reference. - * @param ary - * The array in which the value will be pushed - * @param value - * The value to be pushed into array + * @param mrb The mruby state reference. + * @param ary The array in which the value will be pushed + * @param value The value to be pushed into array */ MRB_API void mrb_ary_push(mrb_state *mrb, mrb_value array, mrb_value value); -/** +/* * Pops the last element from the array. * * Equivalent to: * * ary.pop * - * @param mrb - * The MRuby state reference. - * @param ary - * The array from which the value will be poped. - * @return - * The poped value. + * @param mrb The mruby state reference. + * @param ary The array from which the value will be poped. + * @return The poped value. */ MRB_API mrb_value mrb_ary_pop(mrb_state *mrb, mrb_value ary); -/** +/* * Returns a reference to an element of the array on the given index. * * Equivalent to: * * ary[n] * - * @param mrb - * The MRuby state reference. - * @param ary - * The target array. - * @param n - * The array index being referenced - * @return - * The referenced value. + * @param mrb The mruby state reference. + * @param ary The target array. + * @param n The array index being referenced + * @return The referenced value. */ MRB_API mrb_value mrb_ary_ref(mrb_state *mrb, mrb_value ary, mrb_int n); -/** +/* * Sets a value on an array at the given index * * Equivalent to: * * ary[n] = val * - * @param mrb - * The MRuby state reference. - * @param ary - * The target array. - * @param n - * The array index being referenced. - * @param val - * The value being setted. + * @param mrb The mruby state reference. + * @param ary The target array. + * @param n The array index being referenced. + * @param val The value being setted. */ MRB_API void mrb_ary_set(mrb_state *mrb, mrb_value ary, mrb_int n, mrb_value val); @@ -149,7 +134,6 @@ mrb_ary_len(mrb_state *mrb, mrb_value ary) return RARRAY_LEN(ary); } -/** @} */ MRB_END_DECL #endif /* MRUBY_ARRAY_H */ -- cgit v1.2.3 From 87e0840e9d8894d491e5180c7f7923a5cc403f5d Mon Sep 17 00:00:00 2001 From: Seba Gamboa Date: Thu, 8 Oct 2015 16:34:10 -0200 Subject: Fix `mrb_obj_respond_to` --- include/mruby.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mruby.h b/include/mruby.h index 670733bb3..55d3c369d 100644 --- a/include/mruby.h +++ b/include/mruby.h @@ -295,7 +295,7 @@ MRB_API mrb_value mrb_notimplement_m(mrb_state*, mrb_value); MRB_API mrb_value mrb_obj_dup(mrb_state *mrb, mrb_value obj); MRB_API mrb_value mrb_check_to_integer(mrb_state *mrb, mrb_value val, const char *method); -MRB_API mrb_bool mrb_obj_mrb_define_class_underrespond_to(mrb_state *mrb, struct RClass* c, mrb_sym mid); +MRB_API mrb_bool mrb_obj_respond_to(mrb_state *mrb, struct RClass* c, mrb_sym mid); /** * Defines a new class under a given module -- cgit v1.2.3