doc/compiler/compiler_intro.txt doc/compiler/plugins.txt doc/debugging.txt doc/kernel.txt doc/manifest.txt doc/numerics.txt doc/vm/exceptions.txt doc/vm/life_of_a_context.txt doc/vm/primitives.txt doc/vm/ruby_c_api.txt doc/vm/slots.txt @@ -27,7 +27,7 @@ that the next doc writer can be annoying with other questions. ## Run your code -You code it often more vicious than the specs. Run your pet project under +Your code it often more vicious than the specs. Run your pet project under rubinius and report crashes! See [Howto - Write a ticket](/howto/write_a_ticket.html) @@ -37,10 +37,10 @@ Search for tags like TODO, HACK, FIXME in the code and fix them. Once you're finished, submit a ticket with the [PATCH] tag and a small description. See [Howto - Write a ticket](/howto/write_a_ticket.html) -I use : `grep -re "TODO\|HACK\|FIXME" .` +I use : `grep -re "@todo\|TODO\|HACK\|FIXME" .` -You can also run failing specs and try to fix them. I use `bin/ci -i` and -`rake todo` +You can also run failing specs and try to fix them. I use `bin/mspec +spec/frozen`, `rake todo`, or `bin/mspec tag --list fails spec/frozen`. ## Ask For Help @@ -48,7 +48,8 @@ You can also run failing specs and try to fix them. I use `bin/ci -i` and Anything that we can do to help, we will. Make sure to do your own research too, if possible. We will certainly accept and appreciate simple bug reports, but it is extremely helpful if you can actively help us identify (and maybe -even fix) the problem. +even fix) the problem. Again, see [Howto - Write a +ticket](/howto/write_a_ticket.html) Q. It is all so confusing! There is the VM, the kernel, the libraries, the specs, polymorphic caches, pneumatic stegosauruses... How can I possibly doc/contributing.txt @@ -1,62 +1,51 @@ # Foreign Function Interface - FFI -TODO: Imported from Lighthouse wiki. Likely outdated - - -This section is highly underdeveloped. - - -## Overview - -To do. - - -## Usage - -The main interface function to FFI is `Module#attach_foreign.` Extracted -documentation on its usage is below: - -### Module#attach_foreign - -Create a wrapper to a function in a C-linked library that exists somewhere in -the system. If a specific library is not given, the function is assumed to -exist in the running process, the Rubinius executable. The process contains -many linked libraries in addition to Rubinius' codebase, libc of course the -most prominent on the system side. The wrapper method is added to the Module -as a singleton method or a "class method." - -The function is specified like a declaration: the first argument is the type -symbol for the return type (see FFI documentation for types), the second -argument is the name of the function and the third argument is an Array of the -types of the function's arguments. Currently at most 6 arguments can be given. - - # If you want to wrap this function: - int foobar(double arg_one, const char* some_string); - - # The arguments to #attach_foreign look like this: - :int, 'foobar', [:double, :string] - -If the function is from an external library such as, say, libpcre, libcurl -etc. you can give the name or path of the library. The fourth argument is an -option hash and the library name should be given in the +:from+ key of the -hash. The name may (and for portable code, should) omit the file extension. If -the extension is present, it must be the correct one for the runtime platform. -The library is searched for in the system library paths but if necessary, the -full absolute or relative path can be given. - -By default, the new method's name is the same as the function it wraps but in -some cases it is desirable to change this. You can specify the method name in -the +:as+ key of the option hash. So if you for whatever reason wanted to -import the `char* secret(double seed, double watermelon)` function from a -secret library into your class but name it something else (it *is* secret, -after all,) the entire invocation looks like this: - - class TotallyNotSecretClass - attach_foreign :string, :secret,[:double, :double], :from => "libsecret", :as => :completely_public +## Libraries and C++ Primitives vs. FFI + +There are two ways to "drop to C" in Rubinius. Firstly, primitives are special +instructions that are specifically defined in the VM. In general they are +operations that are impossible to do in the Ruby layer such as opening a file. +Primitives should be used to access the functionality of the VM from inside +Ruby. + +FFI or Foreign Function Interface, on the other hand, is meant as a +generalised method of accessing system libraries. FFI is able to automatically +generate the bridge code needed to call out to some library and get the result +back into Ruby. FFI functions at runtime as real machine code generation so +that it is not necessary to have anything compiled beforehand. FFI should be +used to access the code outside of Rubinius, whether it is system libraries or +some type of extension code, for example. + +There is also a specific Rubinius extension layer called Subtend. It emulates +the extension interface of Ruby to allow old Ruby extensions to work with +Rubinius. + +## FFI + +Module#attach_function allows a C function to be called from Ruby code using +FFI. + +Module#attach_function takes the C function name, the ruby module function to +bind it to, the C argument types, and the C return type. For a list of C +argument types, see kernel/platform/ffi.rb. + +Currently, FFI does not support C functions with more than 6 arguments. + +When the C function will be filling in a String, be sure the Ruby String is +large enough. For the C function rbx_Digest_MD5_Finish, the digest string is +allocated with a 16 character length. The string is passed to md5_finish +which calls rbx_Digest_MD5_Finish which fills in the string with the digest. + + class Digest::MD5 + attach_function nil, 'rbx_Digest_MD5_Finish', :md5_finish, + [:pointer, :string], :void + + def finish + digest = ' ' * 16 + self.class.md5_finish @context, digest + digest end + end - TotallyNotSecretClass.completely_public # => _Whatever it is supposed to do_ +For a complete additional example, see digest/md5.rb. -The "styling" is completely optional and if you prefer, you can use Symbols -for the names (except the library name) instead of Strings. I like to make it -look as much like the C declaration as possible, hence the indentation. doc/foreign_function_interface.txt @@ -100,6 +100,43 @@ use the +debug+ subtask: rake build:debug +## Running VM Tests + +Build and run the tests: + + rake vm:test + +To run only one test suite, use: + + rake vm:test[SomeClass] + +If you want to run a single test suite under gdb, use: + + SUITE="SomeClass" gdb vm/test/runner + + +## Running the Specs + +Rubinius includes a stable copy of the RubySpecs that is tagged so that a +clean set (i.e. passing 100%) of specs can be run as part of the continuous +integration (CI) process. To run the CI specs: + + rake spec + +OR + + bin/mspec ci + +To run the most current version of RubySpec: + + rake rubyspec:update + bin/mspec spec/ruby + +To run a particular spec file, for example, the Array specs: + + bin/mspec spec/ruby/1.8/core/array + + ## Installing Rubinius Run the 'rake install' task to install Rubinius (you may need sudo). Run the @@ -116,6 +153,10 @@ Rubinius generally works like Ruby from the command-line. For example: bin/rbx -e 'puts "Hello!"' +To run a ruby file named 'code.rb': + + bin/rbx code.rb + ## Troubleshooting doc/getting_started.txt README-DEVELOPERS doc/compiler_intro.txt doc/life_of_a_context.txt doc/vm/README db7f6cb984ccfe8386f81989426d814698ca3bfd Brian Ford bford@engineyard.com http://github.com/evanphx/rubinius/commit/b08b45f0317558f9b09963db361a45fd35d72faa b08b45f0317558f9b09963db361a45fd35d72faa 2008-12-09T22:43:03-08:00 2008-12-09T22:43:03-08:00 Migrated README-DEVELOPERS to doc/* files. c0c7b2179125f10ed264c8a505056f033d9af46e Brian Ford bford@engineyard.com