Working on the new build system

- Deleted the Python build files
- Main documentation updated with information about how to use build_elua
- CSS updated to provide a bit of free space at the top of <h2> headings.
- Added rpc-lua.lua
- Fixed cross-compilation errors

References to scons still exist in the docs, they'll have to be removed.

.gitignore

@@ -22,4 +22,4 @@ luac.cross*
 boards/*.h
 sdcard.img
 core
-
+luarpc*

doc/css/style1.css

@@ -54,6 +54,8 @@ h1, h2, h3, h4, h5 {
   font-weight:bold;
 }
 
+h2 { margin-top: 10px;}
+
 h3 {font-size:21px;}
 
 a[href]:link, a[href]:visited {

doc/en/building.txt

@@ -1,7 +1,11 @@
 // $$HEADER$$
 Building eLua
 -------------
-If you decide to build your own binary image instead of link:downloads.html"[downloading one], then you will need to download the source code 
+
+IMPORTANT: Starting with eLua 0.10, a new Lua-based build system replaces the previous Python based (scons) build system. You'll need to use the
+new build system to build eLua, as per the instructions link:#buildoptions[here].
+
+If you decide to build your own binary image instead of link:downloads.html[downloading one], then you will need to download the source code 
 (see link:downloads.html#source[here] for details) and follow the platform specific eLua build instructions (provided for link:building_unix.html[Linux]
 and link:building_win.html[Windows]) to setup your build environment.
 
@@ -325,94 +329,116 @@ One more thing you might want to configure for your build is the contents of the
 [[buildoptions]]
 Invoking the build system
 -------------------------
-Once you have everything in place, all you have to do is to invoke the build system (scons) with the right arguments. This is a fairly easy step, although it might look intimidating 
-because of the multitude of options than can be given to scons. They are used to fine tune the final image to your specific needs, but unless your needs are very special you won't need 
+Once you have everything in place, all you have to do is to invoke the build system (build_elua) with the right arguments. This is a fairly easy step, although it might look intimidating 
+because of the multitude of options than can be given to build_elua. They are used to fine tune the final image to your specific needs, but unless your needs are very special you won't need 
 to modify them, so don't worry about the apparent complexity. The examples at the end of this section will show how easy it is to use the build system in practice.
 
 ------------------------------------
-$ scons
-  [target=lua | lualong | lualonglong]
-  [cpu=<cpuname>]
+$ lua build_elua.lua
   [board=<boardname>]
+  [target=lua | lualong | lualonglong]
+  [allocator=newlib | multiple | simple]
+  [toolchain=<toolchain name>]
+  [optram=true | false]
+  [boot=standard | luarpc]
+  [romfs=verbatim | compress | compile]
   [cpumode=arm | thumb]
-  [allocator = newlib | multiple | simple]
-  [toolchain = <toolchain name>]
-  [optram = 0 | 1]
-  [romfs = verbatim | compress | compile]
+  [bootloader=none | emblod]
+  [output_dir=<directory>]
+  [romfs_dir=<directory>]
+  [board_config_file=<file>]
+  [skip_conf=true | false]
+  [-E | -S]
   [prog]
 ------------------------------------
 
-Your build target is specified by two paramters: *cpu* and *board*. "cpu" gives the name of your CPU, and "board" the name of the board. A board can be associated with more than 
-one CPU. This allows the build system to be very flexible. You can use these two options together or separately, as shown below:
-
-* **cpu=name**: build for the specified CPU. A board name will be assigned by the build system automatically.
-* **board=name**: build for the specified board. The CPU name will be inferred by the build system automatically.
-* **cpu=name board=name**: build for the specified board and CPU. The build script won't allow invalid CPU/board combinations.
-
-For board/CPU assignment, look at the beginning of the SConstruct file (the _platform_list_), it's self-explanatory. +
-The other options are as follows:
+Your build target is specified by *board*. The other options are as follows:
 
 * **target=lua | lualong | lualonglong**: specify if you want to build "regular" Lua (with floating point support). 32 bit integer only Lua (lualong) or 64 bit integer only Lua (lualonglong,
   starting with version 0.9).  The default is "lua". "lualong" and "lualonglong" run faster on targets that don't have a floating point co-processor, but they completely lack support for floating 
   point operations, they can only handle integers. Also, "lualonglong" doesn't support cross-compilation of Lua source files to bytecode (check link:arch_romfs.html#mode[here] for details).
 
-* **cpumode=arm | thumb**: for ARM targets (not Cortex) this specifies the compilation mode. Its default value is 'thumb' for AT91SAM7X targets and 'arm' for STR9, LPC2888 and LPC2468 targets.
-
 * **allocator = newlib | multiple | simple**: choose between the default newlib allocator (newlib) which is an older version of dlmalloc, the multiple memory spaces allocator (multiple)
   which is a newer version of dlmalloc that can handle multiple memory spaces, and a very simple memory allocator (simple) that is slow and doesn't handle fragmentation very well, but it 
   requires very few resources (Flash/RAM). You should use the 'multiple' allocator only if you need to support multiple memory spaces (for example boards that have external RAM). You should 
   use 'simple' only on very resource-constrained systems.
 
 * **toolchain=<toolchain name>**: this specifies the name of the toolchain used to build the image. See link:toolchains.html#configuration[this link] for details.
 
-* **optram=0 | 1**: enables of disables the LTR patch, see the link:arch_ltr.html[LTR documentation] for more details. The default is 1, which enables the LTR patch.
+* **optram=true | false**: enables of disables the LTR patch, see the link:arch_ltr.html[LTR documentation] for more details. The default is true, which enables the LTR patch. Keep LTR enabled
+  unless you have a very good reason to do otherwise, eLua might not function properly with LTR disabled.
 
-* *prog*: by default, the above 'scons' command will build only the 'elf' (executable) file. Specify "prog" to build also the platform-specific programming file where appropriate
-  (for example, on a AT91SAM7X256 this results in a .bin file that can be programmed in the CPU).
+* **boot = standard | luarpc**: Boot mode. 'standard' will boot to either a shell or lua interactive prompt. 'luarpc' boots with a waiting rpc server, using a UART & timer as specified in 
+  link:building.html#static[static configuration data] (*new in 0.7*).
 
 * **romfs = verbatim | compress | compile**: ROMFS compilation mode, check link:arch_romfs.html#mode[here] for details (*new in 0.7*).
 
-* **boot = standard | luarpc**: Boot mode. 'standard' will boot to either a shell or lua interactive prompt. 'luarpc' boots with a waiting rpc server, using a UART & timer as specified in 
-  link:building.html#static[static configuration data] (*new in 0.7*).
+* **cpumode=arm | thumb**: for ARM targets (not Cortex) this specifies the compilation mode. Its default value is 'thumb' for AT91SAM7X targets and 'arm' for STR9, LPC2888 and LPC2468 targets.
 
-The output will be a file named elua_**[target]**_**[cpu]**.elf (and also another file with the same name but ending in .bin/.hex if "prog" was specified for platforms that need these files 
-for programming). +
-If you want the equivalent of a "make clean", invoke "scons" as shown above, but add a "-c" at the end of the command line. +
+* **bootloader = none | emblod**: 'emblod' generates an image suitable for loading with the 'emblod' boot loader. AVR32 only.
 
-**A few examples:**
+* **output_dir=<directory>**: changes the directory where the firmware image will be written. The default is the root directory of the eLua source tree.
 
----------------------------
-$ scons cpu=at91sam7x256 -c
----------------------------
-Clear previously built intermediate files.
+* **romfs_dir=<directory>**: the directory with the link:arch_romfs.html[romfs] files. The default is "romfs".
 
-------------------------
-$ scons cpu=at91sam7x256
-------------------------
-Build eLua for the AT91SAM7X256 CPU. The board name is detected as sam7-ex256.
+* **board_config_file=<file>**: the configuration file for the board. This will ignore the configuration file generated by the Lua configurator and use the user-specified one instead. For more details
+  about the configurator, see link:configurator.html[this link].
 
+* **skip_conf=true | false**: don't call the Lua configurator at all, use whatever configuration file is present in the system instead. This can be used for manually editing the configuration file: run
+  the build normally (with skip_conf=false) once, edit the generated configuration header file, then run the build again with skip_conf=true.
 
-------------------------
-$ scons board=sam7-ex256
-------------------------
-Build eLua for the SAM7-EX256 board. The CPU is detected as AT91SAM7X256.
+* **-E | -S**: see the link:#singlefile[single file compilation] section below.
+
+* **prog**: by default, the above 'build_elua' command will build only the 'elf' (executable) file. Specify "prog" to build also the platform-specific programming file where appropriate
+  (for example, on a AT91SAM7X256 this results in a .bin file that can be programmed in the CPU).
+
+The output will be a file named elua_**board**.elf (and also another file with the same name but ending in .bin/.hex if "prog" was specified for platforms that need these files 
+for programming). +
+If you want the equivalent of a "make clean", invoke "build_elua" as shown above, but add a "-c" at the end of the command line. +
+
+**A few examples:**
+
+------------------------------------------
+$ lua build_elua.lua board=sam7-ex256 prog
+------------------------------------------
+Build eLua for the SAM7-EX256 board. Also, the bin/hex file(s) required for target programming are generated.
 
 -----------------------------------------
-$ scons board=sam7-ex256 cpu=at91sam7x512
+$ lua build_elua.lua board=lpc-h2888 prog
 -----------------------------------------
-Build eLua for the SAM7-EX256 board but "overwrite" the default CPU. This is useful when you'd like to see how the specified board would behave (in terms of resources) with a different 
-CPU. In the case of the SAM7-EX256 board, it's possible to switch the on-board AT91SAM7X256 CPU for an AT91SAM7X512 which has the same pinout but comes with more Flash/RAM memory.
-
-------------------------
-$ scons cpu=lpc2888 prog
-------------------------
-Build eLua for the lpc2888 CPU. The board name is detected as LPC-H2888. Also, the bin file required for target programming is generated. The allocator is automatically detected as "multiple".
+Build eLua for the lpc2888 CPU. The allocator is automatically detected as "multiple".
 
-------------------------------------------------
-$ scons cpu=lm3s8962 toolchain=codesourcery prog
-------------------------------------------------
+------------------------------------------------------------------
+$ lua build_elua.lua board=ek-lm3s8962 toolchain=codesourcery prog
+------------------------------------------------------------------
 Build the image for the Cortex LM3S8962 CPU, but use the CodeSourcery toolchain instead of the default toolchain (which is a "generic" ARM GCC toolchain, usually the one built by following
 the tutorials from this site.
 
+---------------------------------------
+$ lua build_elua.lua board=mbed prog -c
+---------------------------------------
+Clean the intermediary build files for the mbed board, as well as the outputs (firmware files).
+
+[[singlefile]]
+Single file compilation
+~~~~~~~~~~~~~~~~~~~~~~~
+For various reasons, it is often useful to compile a single file instead of the whole image. *build_elua* can do that by specifying the path toward a source file as a target name. It also provides
+options to precompile or generate the assembler source for single files. Examples:
+
+------------------------------------------
+$ lua build_elua.lua board=mbed src/main.c
+------------------------------------------
+Compile only src/main.c for the 'mbed' board.
+
+---------------------------------------------
+$ lua build_elua.lua board=mbed -E src/main.c
+---------------------------------------------
+Preprocess src/main.c, using 'mbed' as the target board.
+
+---------------------------------------------
+$ lua build_elua.lua board=mbed -E src/main.c
+---------------------------------------------
+Generate the assembler source file for src/main.c, using 'mbed' as the target board.
+
 // $$FOOTER$$
 

doc/en/building_unix.txt

@@ -2,28 +2,37 @@
 Building eLua in Linux
 ----------------------
 
+IMPORTANT: Starting with eLua 0.10, a new Lua-based build system replaces the previous Python based (scons) build system. You'll need to update
+your machine environment accordingly, as per the instructions below.
+
 Building eLua in Linux is fairly easy. This tutorial assumes that Ubuntu is used for building, however any distro should be fine, you just need to 
 convert the "apt-get" calls to your distro's package manager equivalent. You need a few packages installed to build eLua:
 
 
 * *a toolchain*: check link:toolchains.html[the toolchains page] for toolchain instructions. Please note that even if you already have a compiled toolchain, the differences in the Newlib configure flags (mainly the --disable-newlib-supplied-syscalls flags) might prevent eLua for building properly on your machine.
 
 
-* *Python*: it should be already installed. If it's not, use
-apt-get to install it:
+* *Lua*: it should be already installed. If it's not, use apt-get to install it:
 +
------------------------------
-$ sudo apt-get install python
------------------------------
+------------------------------
+$ sudo apt-get install lua5.1
+------------------------------
 
-* *scons* - eLua uses scons instead of make and makefiles, because we find scons much more "natural" and easier to use than make. To install it:
+* *luarocks*: a simple package manager for Lua. Again, use apt-get to install it:
 +
-----------------------------
-$ sudo apt-get install scons
-----------------------------
+-------------------------------
+$ sudo apt-get install luarocks
+-------------------------------
 
-* your toolchain's "bin" directory (this is generally something like /usr/local/cross-arm/bin, where /usr/local/cross-arm is the directory in which you installed your toolchain) must be in $PATH.
+* *luafilesystem, lpack, md5* - various Lua modules needed by the builder. Use luarocks to install them:
++
+-------------------------------------
+$ sudo luarocks install luafilesystem
+$ sudo luarocks install lpack
+$ sudo luarocks install md5
+-------------------------------------
 
+* your toolchain's "bin" directory (this is generally something like /usr/local/cross-arm/bin, where /usr/local/cross-arm is the directory in which you installed your toolchain) must be in $PATH.
 
 * if you're building for the i386 platform, you'll also need "nasm":
 +
@@ -39,9 +48,9 @@ sudo apt-get install build-essential
 +
 Then build the eLua cross compiler by executing this command:
 +
----------------------
-scons -f cross-lua.py
----------------------
+-----------------
+lua cross-lua.lua
+-----------------
 
 After you setup your build environment as described above, follow link:building.html#configuring[this tutorial] to build your eLua image.
 

doc/en/building_win.txt

@@ -2,6 +2,9 @@
 Building eLua in Windows
 ------------------------
 
+IMPORTANT: Starting with eLua 0.10, a new Lua-based build system replaces the previous Python based (scons) build system. You'll need to update
+your machine environment accordingly, as per the instructions below.
+
 Starting with version 0.7, building eLua in Windows is officially supported. The following instructions were tested in Windows 7 Professional, but they should work with little or no modification in any version of Windows 7, Vista or XP. You need to download and install a few things first:
 
 * *a toolchain*: building a GCC-based toolchain under Windows is possible but not easy. We found that the easiest thing to do is to download a pre-built toolchain and install it. Currently, all the targets supported by eLua (except i386) have at least one toolchain that runs under Windows:
@@ -11,20 +14,15 @@ Starting with version 0.7, building eLua in Windows is officially supported. The
 
 ** AVR32 has its own Windows based GNU toolchain that can be downloaded from Atmel link:http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4118[here].
 
-* *Python*:  my favourite Windows distribution of Python is link:http://www.activestate.com/activepython/[ActivePython]. Simply download it and install it. ActivePython
-2.6.4.8 will be used in this tutorial. Other Python distribution might work equally as well.
-
-* *scons*: download the Windows installer package from link:http://www.scons.org/download.php[here]. For this tutorial, scons 1.2.0 will be used. Remember to install scons *after* you install Python.
-
 * *lua*: a very good and versatile Lua distribution for Windows is "Lua for Windows", it can be downloaded from link:http://luaforwindows.luaforge.net/[here]. Besides Lua itself, it includes a lot of very useful Lua modules, so I highly recommend it. Version 5.1.4.30 of Lua for Windows will be used in this tutorial.
 
 * *git*: if you need to checkout the *eLua* source code from the link:https://github.com/elua/elua[project git repository], then you will need to install git for Windows.  The instructions at GitHub describing how to link:http://help.github.com/win-set-up-git/[set up git] for Windows should work well. You will only need the ssh key setup section if you want to push code to GitHub.  For a version of git that integrates with the Windows shell (similar to TortoiseSVN), check out link:http://code.google.com/p/tortoisegit/[TortoiseGIT].
 
 * *gcc*: if you want to use the ROMFS pre-compiled feature (see link:arch_romfs.html#mode[here] for details), then you will need to build an image for the eLua cross compiler, and you will need an i386 toolchain for this. I'm using MinGW for this task. It can be downloaded from link:http://www.mingw.org/[here]. This tutorial uses MinGW version 5.1.6. Note that you don't need to install MSYS; MinGW should be enough. Cygwin should work equally as well, or even Microsoft's Visual Studio (not tested). To build the cross compiler, run this command from the command line:
 +
------------------------
-$ scons -f cross-lua.py
------------------------
+-------------------
+$ lua cross-lua.lua
+-------------------
 
 Make sure that all the programs listed above are added to %PATH%. Most of them do this automatically, or have an option to do this automatically, but some (for example MinGW and SCons) do not and you will need to add them to %PATH% manually.