Merge pull request #76 from wrapl/dev

Updates.

docs/index.rst

@@ -9,7 +9,7 @@ Welcome to Rabs's documentation!
 Overview
 --------
 
-Rabs is a general purpose build system, designed for fast and consistent incremental rebuilds.
+Rabs is a general purpose build system, designed for fast and consistent incremental rebuilds. See here to get started: :doc:`/quickstart`.
 
 Features
 --------
@@ -68,11 +68,13 @@ Rabs provides several types of targets:
 * :doc:`/targets/expressions`
 * :doc:`/targets/scans`
 
+Rabs build scripts are written using :doc:`/minilang`.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+   /quickstart
    /targets
    /contexts
 

docs/minilang.rst

@@ -0,0 +1,41 @@
+Minilang
+========
+
+.. warning::
+   Minilang uses the `Hans-Boehm conservative garbage collector <https://github.com/ivmai/bdwgc>`_. This simplifies memory management in most cases, but may not be compatible with all use cases. In the future, the option to use a different form of memory management may be added to Minilang. 
+
+Introduction
+------------
+
+*Minilang* is a small imperative language, designed to be embedded into programs written in *C*.
+It has the following goals / features:
+
+**Minimal dependencies**
+   *Minilang* has no dependencies other than the Hans Boehm garbage collector, and standard *C* libraries.
+
+**Full Closures**
+   Functions in *Minilang* automatically capture their environment, creating closures at runtime.
+   Closures can be passed around as first-class values, which are used to build targets in *Rabs*. 
+
+**Dynamic scoping**
+   The *Minilang* interpreter provides a callback for identifier resolution, allowing programs to provide dynamic scoping.
+   This is used within *Rabs* to provide dynamic symbol resolution.
+
+**Easy to extend**
+   It is easy to create new functions in *C* to use in *Minilang*.
+
+Sample
+------
+
+.. code-block:: mini
+
+   var L := [1, 2, 3, 4, 5]
+ 
+   for X in L do
+      print('X = {X}\n')
+   end
+
+Syntax
+------
+
+*Minilang* uses a simple syntax, similar to *Pascal* or *Lua*.

docs/quickstart.rst

@@ -0,0 +1,74 @@
+Quickstart
+==========
+
+Description
+-----------
+
+Folder structure
+~~~~~~~~~~~~~~~~
+
+*Rabs* is designed for building large projects that can span several directories with arbitrary nesting. Each directory contains a :file:`build.rabs` file which specifies the targets to build within that directory, the instructions to build those targets (written in :doc:`/minilang`), and any dependencies.
+
+::
+   
+   .
+   ├── build.rabs
+   ├── folder 1
+   │   └── build.rabs
+   ├── folder 2
+   │   └── build.rabs
+   ├── folder 3
+   │   └── build.rabs
+   ├── file 1
+   └── file 2
+
+Each :file:`build.rabs` file introduces a new scope, which allows per-directory configurations. This scope also inherits the scope from the parent directory, allowing common functionality or settings to be defined in the root directory of the project.
+
+*Rabs* can be run from any directory within the project, in which case it will only build targets specified within that directory (or its subdirectories). The :file:`build.rabs` file in the project's root directory must start with special comment line:
+
+.. code-block:: mini
+   
+   -- ROOT --
+
+No patterns, only code
+~~~~~~~~~~~~~~~~~~~~~~
+
+Unlike many other build systems, *Rabs* does not use patterns to denote dependencies and build functions. Instead, every dependencies and build function must be explicitly created by code. 
+
+For example, a :file:`Makefile` may contain a rule like the following:
+
+.. code-block:: make
+
+   %.o : %.c
+      $(CC) -c $(CFLAGS) $< -o $@
+
+which describes how to create an object file (which has extension ``.o``) from a source file (ending in ``.c``). This rule will be used any time a file matching :file:`*.o` is required in the build *and* a file :file:`*.c` is present.
+
+This could be used to build a program:
+
+.. code-block:: make
+
+   program : program.o
+      $(CC) $< -o $@
+
+And *make* would automatically apply the pattern above to build :file:`program.o` from :file:`program.c`, assuming :file:`program.c` existed.
+
+The equivalent in a :file:`build.rabs` file looks like:
+
+.. code-block:: mini
+
+   var c_object := fun(Object) do
+      var Source := Object % "c"
+      Object[Source] => fun() execute(CC, "-c", CFLAGS, Source, "-o", Object)
+   end
+
+Note that there are two functions in the above code, one to create the dependency and build rule and the other to perform the actual build.
+
+This could be used to build a program:
+
+.. code-block:: mini
+
+   var Objects := [c_object(file("program.o"))]
+   
+   file("program")[Objects] => fun(Target) execute(CC, Objects, "-o", Target)
+

docs/targets.rst

@@ -29,8 +29,6 @@ Methods
 
 Every target supports the following methods:
 
-.. mini:method:: Target => BuildFunction
-
 .. code-block:: mini
 
    Target => BuildFunction

rabs.h

@@ -26,7 +26,7 @@ extern __thread build_thread_t *CurrentThread;
 
 ml_value_t *rabs_global(const char *Name);
 
-#define CURRENT_VERSION "2.0.6"
+#define CURRENT_VERSION "2.0.7"
 #define WORKING_VERSION "2.0.6"
 
 #endif