Building eLua

Building eLua

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 here.

If you decide to build your own binary image instead of downloading one, then you will need to download the source code (see here for details) and follow the platform specific eLua build instructions (provided for Linux and Windows) to setup your build environment.

Then follow the instructions below to configure and build your eLua binary image.

Configuring the build image

Starting with eLua 0.10, the build is configured by using the special configurator component, see here for more details.

Invoking the build system

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.

$ 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]
  [bootloader=none | emblod]
  [output_dir=<directory>]
  [romfs_dir=<directory>]
  [board_config_file=<file>]
  [skip_conf=true | false]
  [config_only=true | false]
  [build_mode=keep_dir | build_dir_linearized]
  [build_dir=<directory>]
  [disp_mode=all | summary | minimal]
  [-E | -S]
  [-h]
  [prog]

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 here for details).

  • 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 this link for details.

  • optram=true | false: enables of disables the LTR patch, see the 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.

  • 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 static configuration data (new in 0.7).

  • romfs = verbatim | compress | compile: ROMFS compilation mode, check here for details (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.

  • bootloader = none | emblod: emblod generates an image suitable for loading with the emblod boot loader. AVR32 only.

  • output_dir=<directory>: changes the directory where the firmware image will be written. The default is the root directory of the eLua source tree.

  • romfs_dir=<directory>: the directory with the romfs files. The default is "romfs".

  • board_config_file=<file>: the configuration file for the board. The builder will not search the board configuration file in the standard paths, using the user-specified one instead. For more details about the configurator, see 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 board’s generated configuration file. For more details, see this link.

  • config_only= true | false: execute only the configurator, then exit. This can be used for manually editing the board’s generated configuration file. For more details, see this link.

  • -E | -S: see the single file compilation section below.

  • build_mode=keep_dir | build_dir_linearized: keep the intermediary build outputs (for example the object files) in the same directory as the source file they come from (keep_dir, default) or in a single directory (build_dir_linearized).

  • build_dir=<directory>: change the directory used by the builder for intermediate files in build_dir_linearized mode (see above). The default is .build.

  • disp_mode=all | summary | minimal: display all the messages from the build tools (all), display only the target being built and show the messages from the build tools only in case of an error or warning (summary) or display just errors and warnings (minimal). The default is summary.

  • -h: shows progam usage.

  • 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.

$ lua build_elua.lua board=lpc-h2888 prog

Build eLua for the lpc2888 CPU. The allocator is automatically detected as "multiple".

$ 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).

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 -S src/main.c

Generate the assembler source file for src/main.c, using mbed as the target board.