(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.
Then follow the instructions below to configure and build your eLua binary image.
[[configuring]]
Configuring the build image
---------------------------
eLua has a very flexible build system that can be used to select the components that are going to be part of the eLua
binary image and also to set the compile time (static) configuration. To use it, you need to edit a single configuration file
You can also choose the modules that are going to be part of the eLua image. Unlike components, the modules have a direct impact on the
eLua API, so choose them carefully. Disabling a module will save Flash space (and potentially RAM) but will also completely remove the
possibility of using that module from eLua.
The modules included in the build are specified by the *LUA_PLATFORM_LIBS_ROM* macro. An example is given below:
-------------------------------------------------
#define LUA_PLATFORM_LIBS_ROM\
_ROM( AUXLIB_PIO, luaopen_pio, pio_map )\
_ROM( AUXLIB_TMR, luaopen_tmr, tmr_map )\
_ROM( AUXLIB_PD, luaopen_pd, pd_map )\
_ROM( AUXLIB_UART, luaopen_uart, uart_map )\
_ROM( AUXLIB_TERM, luaopen_term, term_map )\
_ROM( AUXLIB_PWM, luaopen_pwm, pwm_map )\
_ROM( AUXLIB_PACK, luaopen_pack, pack_map )\
_ROM( AUXLIB_BIT, luaopen_bit, bit_map )\
_ROM( AUXLIB_CPU, luaopen_cpu, cpu_map )\
ROM( LUA_MATHLIBNAME, luaopen_math, math_map )
-------------------------------------------------
Each module is defined by a **_ROM( module_name, module_init_function, module_map_array )** macro, where:
* *module_name* is the name by which the module can be used from Lua.
* *module_init_function* is a function called by the Lua runtime when the module is initialized.
* *module_map_array* is a list of all the functions and constants exported by a module.
Please note that this notation is specific to LTR (the **L**ua **T**iny **R**AM patch) and it's not the only way to specify
the list of modules included in the build (although it is the most common one). Check the link:arch_ltr.html#config[LTR section]
for more information about LTR.
For the full list of modules that can be enabled or disabled via _platform_conf.h_ check link:refman_gen.html[the reference manual].
[[static]]
Static configuration data
~~~~~~~~~~~~~~~~~~~~~~~~~
"Static configuration" refers to the compile-time configuration. Static configuration parameters are hard-coded in the firmware image and can't be changed
at run-time. The table below lists the static configuration parameters and their semantics.
specified speed. The data format is always 8N1 (8 data bits, no parity, 1 stop bits)t. The specified timer ID will be used for the console subsystem. These
TERM_COLS |Used to configure the ANSI terminal support (if enabled in the build). Used to specify (respectively) the number of lines and
columns of the ANSI terminal.
o|ELUA_CONF_IPADDR0...3 +
ELUA_CONF_NETMASK0..3 +
ELUA_CONF_DEFGW0..3
ELUA_CONF_DNS0..3 |Used by the TCP/IP implementation when the DHCP client is not enabled, or when it is enabled but can't be contacted. Specifies
the IP address, network mask, default gateway and DNS server. Only needed if BUILD_UIP is enabled.
o|VTMR_NUM_TIMERS +
VTMR_FREQ_HZ |Specify the virtual timers configuration for the platform (refer to link:refman_gen_tmr.html[the timer module documentation] for details). Define VTMR_NUM_TIMERS to 0
if this feature is not used.
o|MMCFS_TICK_HZ +
MMCFS_TICK_MS |Specify the rate at which SD/MMC timer function _disk_timerproc()_ are being called by the platform. On most platforms MMCFS_TICK_HZ will match VTMR_FREQ_HZ.
Only needed if MMCFS support is enabled.
o|MMCFS_CS_PORT +
MMCFS_CS_PIN |Specify the port and pin to be used as chip select for MMCFS control of an SD/MMC card over SPI. Only needed if MMCFS support is enabled.
o|MMCFS_SPI_NUM |Specify the SPI peripheral to be used by MMCFS. Only needed if MMCFS support is enabled.
o|PLATFORM_CPU_CONSTANTS |If the link:refman_gen_cpu.html[cpu module] is enabled, this defines a list of platform-specific constants (for example interrupt masks) that can be accessed
using the *cpu.<constant name>* notation. Each constant name must be specified instead of a specific costruct (__ _C(<constant name>__ ). For example:
#define PLATFORM_CPU_CONSTANTS
_C( INT_GPIOA ),\
_C( INT_GPIOB ),\
_C( INT_GPIOC ),\
_C( INT_GPIOD ),\
_C( INT_GPIOE )
After compilation, you can access these constants using _cpu.INT_GPIOx_. Note that the implementation of this feature needs virtually no RAM at all, so you can define as many constants
as you want here.
o|BUF_ENABLE_ADC |If the link:refman_gen_adc.html[adc module] is enabled, this controls whether or not the ADC will create a buffer so that more than one sample per channel can be
held in a buffer before being returned through *adc.getsample* or *adc.getsamples*. If disabled, only one conversion result will be buffered. This option does NOT affect the behavior
of the moving average filter.
o|ADC_BUF_SIZE |If the link:refman_gen_adc.html[adc module] is enabled, and BUF_ENABLE_ADC is defined, this will define the default buffer length allocated at startup. This does
not limit buffer sizes, it only defines the default length. Appropriate values range from BUF_SIZE_2 to BUF_SIZE_32768, with the numeric component at the end being in powers of 2.
o|ADC_BIT_RESOLUTION |If the link:refman_gen_adc.html[adc module] is enabled, this will define the number of bits per adc conversion result. This is used to determine the maximum conversion
value that can be returned by the ADC.
o|RPC_UART_ID |If the link:refman_gen_rpc.html[rpc module] is enabled and boot mode is set to luarpc, this selects which uart luarpc will listen on for incoming client connections.
o|RPC_TIMER_ID |If the link:refman_gen_rpc.html[rpc module] is enabled and boot mode is set to luarpc, this selects which timer will be used with the uart selected with RPC_UART_ID.
o|EGC_INITIAL_MODE +
EGC_INITIAL_MEMLIMIT |**(version 0.7 or above)**Configure the default (compile time) operation mode and memory limit of the emergency garbage collector link:elua_egc.html[here] for details
about the EGC patch). If not specified, *EGC_INITIAL_MODE* defaults to *EGC_NOT_ACTIVE* (emergency garbage collector disabled) and *EGC_INITIAL_MEMLIMIT* defaults to 0.
o|PLATFORM_INT_QUEUE_LOG_SIZE |If Lua interrupt support is enabled, this defines the base 2 logarithm of the size of the interrupt queue. Check link:inthandlers.html[here] for details.
o|LINENOISE_HISTORY_SIZE_LUA |If linenoise support is enabled, this defines the number of lines kept in history for the Lua interpreter. Check link:linenoise.html[here] for details. If history
support in Lua is not needed, define this as 0.
o|LINENOISE_HISTORY_SIZE_SHELL |If linenoise support is enabled, this defines the number of lines kept in history for the eLua shell. Check link:linenoise.html[here] for details. If history
support in the eLua shell is not needed, define this as 0.
o|LINENOISE_AUTOSAVE_FNAME |If linenoise support is enabled, the history will automatically be saved everytime the Lua interpreter exits in the filename specified
by this macro. Check link:linenoise.html[here] for details. This macro is optional; if it's not defined, the history will not be saved automatically.
o|RFS_BUFFER_SIZE |Size of the RFS buffer. Needs to be one of the *BUF_SIZE_xxx* constants defined in _inc/buf.h_
o|RFS_UART_ID |The ID of the UART that will be used by RFS. This is the physical connection over which the PC directory will be shared.
o|RFS_UART_SPEED |Communication speed of the RFS UART interface.
o|RFS_TIMER_ID |The ID of a timer that will be used by RFS for internal operations
o|RFS_FLOW_TYPE |Flow control type on the serial RFS interface, see link:arch_platform_uart.html#flow_control_type[here] for details.
If not specified it defaults to \'no flow control'.
o|RFS_TIMEOUT |RFS operations timeout (in microseconds). If during a RFS operation no data is received from the PC side for the
specified timeout, the RFS operation terminates with error.
o|BUILD_SERMUX |Enable serial multiplexer support in eLua.
o|SERMUX_PHYS_ID |The ID of the physical UART interface used by the serial multiplexer.
o|SERMUX_PHYS_SPEED |Communication speed of the multiplexer UART interface.
o|SERMUX_FLOW_TYPE |Flow control type on the physical serial multiplexer interface, see link:arch_platform_uart.html#flow_control_type[here] for details.
If not specified it defaults to \'no flow control'.
o|SERMUX_NUM_VUART |The number of virtual UART interfaces. This number can't be higher than 8.
o|SERMUX_BUFFER_SIZES |An array of *SERMUX_NUM_VUART* integers that specify the buffer sizes for the virtual
UART interfaces. Note that a virtual UART *MUST* have a buffer associated with it. The sizes are specified as
The rest of the static configuration data parameters are meant to be modified mainly by developers and thus they're not listed here. +
One more thing you might want to configure for your build is the contents of the ROM file system. See the link:arch_romfs.html[ROMFS documentation] for details on how to do this.
[[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
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.
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.
* **target=lua | lualong**: specify if you want to build "regular" Lua (with floating point support) or integer only Lua (lualong). The default is "lua". "lualong" runs faster on
targets that don't have a floating point co-processor, but it completely lacks support for floating point operations, it can only handle integers.
* **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.
* *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).
* **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*).
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. +
**A few examples:**
---------------------------
$ scons cpu=at91sam7x256 -c
---------------------------
Clear previously built intermediate files.
------------------------
$ scons cpu=at91sam7x256
------------------------
Build eLua for the AT91SAM7X256 CPU. The board name is detected as sam7-ex256.
------------------------
$ scons board=sam7-ex256
------------------------
Build eLua for the SAM7-EX256 board. The CPU is detected as AT91SAM7X256.
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.
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".
------------------------------------------------
$ scons cpu=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
