Permalink
Browse files

Updates for most files under doc directory.

  • Loading branch information...
1 parent a6ee22c commit 63553ff68dc64227babb7145b54c2920bef1ce83 Brian Ford committed May 13, 2010
View
4 README
@@ -19,8 +19,8 @@ Microsoft Windows.
To install Rubinius, use the following steps. For more information about
building and running Rubinius, see doc/getting_started.txt.
-Before installing Rubinius, ensure you have MRI version 1.8.7, rubygems, and
-git installed.
+Before installing Rubinius, ensure you have MRI version 1.8.7, rubygems, rake,
+and git installed.
1. git clone git://github.com/evanphx/rubinius.git
2. cd rubinius
View
@@ -1,6 +1,9 @@
-# Actors - Concurrent Rubinius
+1. Actors - Concurrent Rubinius
-## Background
+NOTE this document is outdated in parts referencing the older implementation
+of Rubinius that was based on the stackless execution model.
+
+2. Background
Rubinius is shaping up to be quite a nice platform for networking and
distributed computing. The virtual machine uses
@@ -11,7 +14,7 @@ the Channel class, an elegant mechanism that comes from the
[π-calculus](http://en.wikipedia.org/wiki/Pi-calculus) that serves a number of
roles in Rubinius.
-## Channel
+3. Channel
First, you can treat a Channel like a thread safe queue that lets you push an
item onto the tail from any thread, and then receive the item at the head from
@@ -70,7 +73,7 @@ resources between threads it's not so tricky, but for more complex occasions
threads can get really tough. Beyond that, if you try to uses multiple
threaded libraries you can run into extremely difficult to debug problems.
-## Actors
+4. Actors
One answer to this problem is the [actor
model](http://en.wikipedia.org/wiki/Actor_model). In this model an actor is a
@@ -82,15 +85,15 @@ simplifies the concurrency problems that can arise. Additionally, it makes it
easy to run actors in parallel on multi-core machines, or across a network on
multiple boxes.
-### Current Status
+4.1. Current Status
Rubinius has initial support for local actors now, and we are working on
building them up to be the foundation for a full fledged distributed computing
framework. This is an outline of the currently envisioned design:
![actors.png](images/actors.png)
-## Glossary
+5. Glossary
*Actor*
View
@@ -1,67 +1,73 @@
+1. Bootstrapping
+
Bootstrapping is the process of building up functionality of the system until
all Ruby code can be executed. There are seven stages to the bootstrap process:
-1. VM: The virtual machine is able to load and execute bytecode, send messages
- (i.e. look up and execute methods), and all primitive functions are
- available, but not yet hooked up as Ruby methods.
-
- The Class class has to be manually set up this early in the process by
- setting its class to be itself and its superclass to be Module. In
- addition to Class and Module, a couple of other base classes are created
- here including Object, Tuple, LookupTable, and MethodTable.
-
- Now that classes can be defined, 35 or so built in classes are told to
- initialize themselves, symbols for top level methods (:object_id, :call,
- :protected, etc) are created, basic exceptions are defined, and primitives
- are registered. Finally IO gets hooked up.
-
- At this point there is enough defined behavior to begin to load up the
- rest of the runtime kernel which is all defined in ruby. This has to be
- done in several passes as the language grows.
-
-2. alpha: This starts the loading of Ruby code. The ability to open classes
- and modules and define methods exists. The minimum functionality to
- support the following methods is implemented in kernel/alpha.rb:
-
- attr_reader :sym
- attr_writer :sym
- attr_accessor :sym
- private :sym
- protected :sym
- module_function :sym
- include mod
-
- Also, it is possible to raise exceptions and cause the running process to
- exit. This stage lays the foundation for the next two stages.
-
-3. bootstrap: This stage continues to add the minimum functionality to
- support loading platform and common. The primitive functions are added for
- most of the kernel classes.
-
-4. platform: The FFI (foreign function interface) system is implemented and
- Ruby method interfaces to platform-specific functions are created. Once
- this is set up, platform specific things such as pointers, file access,
- math, and POSIX commands are attached.
-
-5. common: The vast majority of the Ruby core library classes are
- implemented. The Ruby core classes are kept as implementation-neutral as
- possible. Also, most of the functionality for Rubinius specific classes
- is added.
-
-6. delta: Final versions of methods like #attr_reader, etc. are added. Also,
- implementation-specific versions of methods that override the versions
- provided in common are added.
-
-7. loader: The compiled version of kernel/loader.rb is run.
-
- The final stage setups the life cycle of a ruby process. It starts by
- connecting the VM to the system, sets up load paths, and reads
- customization scripts from the home directory. It traps signals, and
- processes command line arguments.
-
- After that, it either runs the script passed to it from the command line
- or boots up the interactive ruby shell. When that finishes, it runs any
- at_exit blocks that had been registered, finalizes all objects, and exits.
+ 1. VM: The virtual machine is able to load and execute bytecode, send
+ messages (i.e. look up and execute methods), and all primitive functions
+ are available, but not yet hooked up as Ruby methods.
+
+ The Class class has to be manually set up this early in the process by
+ setting its class to be itself and its superclass to be Module. In
+ addition to Class and Module, a couple of other base classes are created
+ here including Object, Tuple, LookupTable, and MethodTable.
+
+ Now that classes can be defined, 35 or so built in classes are told to
+ initialize themselves, symbols for top level methods (:object_id, :call,
+ :protected, etc) are created, basic exceptions are defined, and
+ primitives are registered. Finally IO gets hooked up. Also at this stage,
+ several fundamental Ruby methods are bound to primitives.
+
+ At this point there is enough defined behavior to begin to load up the
+ rest of the runtime kernel which is all defined in ruby. This has to be
+ done in several passes as the language grows.
+
+ 2. alpha: This starts the loading of Ruby code. The ability to open classes
+ and modules and define methods exists. The minimum functionality to
+ support the following methods is implemented in kernel/alpha.rb:
+
+ attr_reader :sym
+ attr_writer :sym
+ attr_accessor :sym
+ private :sym
+ protected :sym
+ module_function :sym
+ include mod
+
+ Also, it is possible to raise exceptions and cause the running process to
+ exit. This stage lays the foundation for the next two stages.
+
+ 3. bootstrap: This stage continues to add the minimum functionality to
+ support loading platform and common. The primitive functions are added
+ for most of the kernel classes.
+
+ 4. platform: The FFI (foreign function interface) system is implemented and
+ Ruby method interfaces to platform-specific functions are created. Once
+ this is set up, platform specific things such as pointers, file access,
+ math, and POSIX commands are attached.
+
+ 5. common: The vast majority of the Ruby core library classes are
+ implemented. The Ruby core classes are kept as implementation-neutral as
+ possible. Also, most of the functionality for Rubinius specific classes
+ is added.
+
+ 6. delta: Final versions of methods like #attr_reader, etc. are added. Also,
+ implementation-specific versions of methods that override the versions
+ provided in common are added.
+
+ 7. loader: The compiled version of kernel/loader.rb is run.
+
+ The final stage setups the life cycle of a ruby process. It starts by
+ connecting the VM to the system, sets up load paths, and reads
+ customization scripts from the home directory. It traps signals, and
+ processes command line arguments.
+
+ After that, it either runs the script passed to it from the command line
+ or boots up the interactive ruby shell. When that finishes, it runs any
+ at_exit blocks that had been registered, finalizes all objects, and
+ exits.
+
+1.1 Load Order
The files in the kernel directories bootstrap, platform, common, and delta,
implement the respective bootstrapping stages above. The order in
@@ -88,13 +94,3 @@ of the kernel directories, you must add the file name to the load_order.txt
file in that directory. These files are copied to the appropriate runtime/**
directories during build. During each of the bootstrap stages above, the VM
loads the files listed in load_order.txt in order.
-
-## Kernel Coding Guidelines
-
-The primary guideline for all kernel code is simple and efficient. Simple code
-is often more efficient and generally more comprehensible. There should be no
-metaprogramming code in bootstrap. Use the #attr_xxx methods throughout the
-kernel source. Also, alias methods using the #alias_method call next to the
-method definition. Specify private methods with the 'private :sym' method next
-to the method definition. Remember that the versions of the methods listed
-above in the alpha stage take a single, symbol argument.
View
@@ -1,12 +1,12 @@
-# Rubinius Build System
+1. Rubinius Build System
TODO: Many details are missing.
Rubinius uniformly uses Rake as the build system for its own files. However
Rubinius also includes the source for several external libraries and these
typically use makefiles.
-## Development versus Install Builds
+2. Development versus Install Builds
Rubinius is comprised of the executable and various support files like the core
and standard libraries. The executable needs to know where to find these files
@@ -31,27 +31,15 @@ function, *even if the executable is in the directory*. The executable checks a
single, hard-coded path. If this ends up being very painful for some reason,
we'll revise it.
-## Installing Rubinius
+3. Installing Rubinius
-As detailed in _Development versus Install Builds_, a specific version of the
-Rubinius executable is built to be installed. The install task is a bit of a
-kludge because of the way that Rake resolves dependencies.
+To install Rubinius, you must first configure it with an install prefix:
-The install task first cleans, then configures, then builds, and finally
-installs. However, when Rake begins running, it resolves the dependencies for
-build, but the dependencies may already exist, so Rake does not expect to build
-them. Then the clean task removes these files. After clean runs, the build task
-runs but will fail because dependencies have not been built.
+ ./configure --prefix=/path/to/install/dir
-To handle this, the install task shells out to another invocation of Rake to
-build. It may be possible to force Rake to re-resolve the build dependencies.
-However, a better approach may be to convert the build system to Tap (see
-http://tap.rubyforge.org).
-
-To install Rubinius, run
-
- [sudo] rake install
-
-To uninstall Rubinius, run
-
- [sudo] rake uninstall
+The configure process creates a 'config.rb' file that specifies the key file
+paths that Rubinius uses. Once configured, run 'rake install' to build and
+install. The install procedure builds all the files, including compiling the
+Ruby standard library files in the lib/ directory, then copies them into the
+install location using the 'install' program. The install tasks are located in
+'rakelib/install.rake'.
View
@@ -1,73 +1,43 @@
-# Common Build Problems and Solutions
+1. Common Build Problems and Solutions
-TODO: Imported from Lighthouse wiki. Likely outdated
+The following are errors that you may encounter while building, installing, or
+running Rubinius along with suggested solutions.
-These are typical error messages / scenarios that you may encounter at various
-stages of building Rubinius, along with the typical causes and solutions.
+For any error, a first step is to ensure you have a current, clean checkout of
+Rubinius. Before going further, consider running the following steps:
-## Before anything else
+ $ git co master
+ $ git reset --hard
+ $ git pull
+ $ rake distclean
+ $ rake
-*Make certain that you do not have an old version of Rubinius installed
-somewhere.* Executing new code using the old libraries will end in tears. The
-name should be `librubinius-*` and the typical location is `/usr/local/lib/`
-or `/usr/lib` but you can use `find` to make sure you get everything in case
-your install location is strange.
-Old .rbc files may be getting in the way. 'rake clean build' should eliminate
-these problems.
+Error:
+ ERROR: unable to find runtime directory
-## C Compilation Errors
+ Rubinius was configured to find the runtime directory at:
-### "undefined reference to '[some symbol]"
+ /Users/brian/devel/rubinius/runtime
-Try `rake distclean build` to make sure the entire C codebase is rebuilt.
+ but that directory does not exist.
-### "error: IN_DONT_FOLLOW not declared"
+ Set the environment variable RBX_RUNTIME to the location
+ of the directory with the compiled Rubinius kernel files.
-On Linux at least, the inotify library may be used but for some reason, some
-distributions' sys/inotify.h does not have the necessary constants. You can
-either disable it in the configuration or try to use updated header files at
-least from
-[here](http://inotify.aiken.cz/?section=inotify&page=download&lang=en).
+ You may have configured Rubinius for a different install
+ directory but you have not run 'rake install' yet.
-### "Unable to compile [extension].so/dylib/etc."
+Solution:
-First, even if an extension fails to build, you should still be OK. Try
-`shotgun/rubinius -v` to verify that Rubinius itself works.
+ If you configured rubinius with a --prefix, run rake install.
-### "glibtool: link: cannot build libtool library `librubinius.la' from
-non-libtool objects: ..." (Mac OS X)
+ If you configured rubinius with a --prefix and renamed the install directory
+ after installing Rubinius, re-configure Rubinius and reinstall it.
-Make sure your `glibtool` is at least version 1.5. You may also have multiple
-versions installed, use `` `which glibtool` `` to locate the one that is
-currently being picked up. Typically this problem occurs if you have an
-outdated version in `/sw/bin/glibtool` and a newer one in `/usr/bin/glibtool`.
+ If you renamed the source directory after building Rubinius, re-configure
+ and rebuild it.
-### "MACOSX_DEPLOYMENT_TARGET ..."
-
-The error message is probably complaining that it is supposedly set to 10.1 or
-something; you can override this by giving the env explicitly on the command
-line. The Rubinius code seems to be correct though so it is likely you have
-that invalid #define in your system headers somewhere.
-
-## Ruby Build Errors
-
-### "... in `initialize': uninitialized constant Mutex::Channel"
-
-Unset `$RUBYOPT` (usually set for Gems.)
-
-### "Unable to find [ClassName]"
-
-These are caused by some load order dependency not being properly constructed.
-Determine which file needs which other file and insert a "depends on
-[file].rb", then `rake build : load_order`.
-
-### "Unable to find 'kernel/bootstrap/archive.rbc'" -- "Unable to run
-runtime/stable/bootstrap.rba"
-
-Either:
-
-1. You have accidentally deleted/moved/etc. something in `runtime/` and you
-can probably restore it with a quick `git checkout runtime/` ; or
-1. Something is breaking in the loader, break out the GDB.
+ In general, do not rename the source or build directory after building
+ Rubinius.
Oops, something went wrong.

0 comments on commit 63553ff

Please sign in to comment.