From c6efc901d2ed22e439b41303665485040b946f99 Mon Sep 17 00:00:00 2001 From: Raja Mukherji Date: Mon, 20 May 2019 07:42:40 +0100 Subject: [PATCH] Updates. --- docs/index.rst | 4 ++- docs/minilang.rst | 41 +++++++++++++++++++++++++ docs/quickstart.rst | 74 +++++++++++++++++++++++++++++++++++++++++++++ docs/targets.rst | 2 -- rabs.h | 2 +- 5 files changed, 119 insertions(+), 4 deletions(-) create mode 100644 docs/minilang.rst create mode 100644 docs/quickstart.rst diff --git a/docs/index.rst b/docs/index.rst index c38cba8..176dae3 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/minilang.rst b/docs/minilang.rst new file mode 100644 index 0000000..08f920d --- /dev/null +++ b/docs/minilang.rst @@ -0,0 +1,41 @@ +Minilang +======== + +.. warning:: + Minilang uses the `Hans-Boehm conservative garbage collector `_. 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*. \ No newline at end of file diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000..0d13900 --- /dev/null +++ b/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) + diff --git a/docs/targets.rst b/docs/targets.rst index a77e132..6e6e364 100644 --- a/docs/targets.rst +++ b/docs/targets.rst @@ -29,8 +29,6 @@ Methods Every target supports the following methods: -.. mini:method:: Target => BuildFunction - .. code-block:: mini Target => BuildFunction diff --git a/rabs.h b/rabs.h index 14927e0..5d21444 100644 --- a/rabs.h +++ b/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