diff --git a/doc/en/building.html b/doc/en/building.html index a1322961..f489a3d1 100644 --- a/doc/en/building.html +++ b/doc/en/building.html @@ -2,235 +2,349 @@ Building eLua - + + +

Building eLua

-

If you decide to build your own eLua binary image (instead of downloading one) you need to check a few things first: +

If you decide to build your own eLua +binary image (instead of downloading +one) you need to check a few things first: +

+

For each platform, eLua assumes a certain +name for the toolchain components, as shown below.

-

For each platform, eLua assumes a certain name for the toolchain components, as shown below. -

-

If your toolchain uses different names, you have to modify the toolchain definition in SConstruct. See the toolchains instructions for details.

+

If your toolchain uses different names, you have to modify the +toolchain definition in SConstruct. See the toolchains instructions for +details.

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 to set the compile time (static) configuration. -To use it, you need to edit a single configuration file (platform_conf.h) located in the platform specific directory (src/platform/<platform name>/platform_conf.h). The configuration parameters are described in detail in the next paragraphs.

+

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 to set the compile time (static) configuration. +To use it, you need to edit a single configuration file (platform_conf.h) +located in the platform specific directory (src/platform/<platform +name>/platform_conf.h). The configuration parameters +are described in detail in the next paragraphs.

Configuring components

-

A component is a feature that can be enabled to add functionality to eLua itself, without modifying its API (which is the part that the programmer uses to write eLua programs). The components that can be configured in eLua are: +

A component is a feature that can be +enabled to add functionality to eLua itself, +without modifying its API (which is the part that the programmer uses +to write eLua programs). The components that can be +configured in eLua are: +

- - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + +
NameMeaningNameMeaning
BUILD_XMODEMDefine this to build support for XMODEM receive. If enabled, you can use the "recv" command from the shell to receive a Lua file (either source code - or precompiled byte code) and run in on the target. Works only over RS-232 connections (although in theory it's possible to make it work over any kind - of transport).BUILD_XMODEMDefine this to build support for XMODEM receive. If +enabled, you can use the "recv" command from the shell to receive a Lua +file (either source code or precompiled byte code) and run in on the +target. Works only over RS-232 connections (although in theory it's +possible to make it work over any kind of transport).
BUILD_SHELLThis build the eLua shell (see Using eLua for details on the shell). If the shell is not enabled, the code looks for - a file called /rom/autorun.lua and executes it. If this file is not found, a regular Lua intepreter is started on the target.BUILD_SHELLThis build the eLua shell (see Using eLua for details on the +shell). If the shell is not enabled, the code looks for a file called /rom/autorun.lua +and executes it. If this file is not found, a regular Lua intepreter is +started on the target.
BUILD_ROMFSEnable the eLua read-only filesystem. See the ##ROMFS documentation for details about using the ROM file system.BUILD_ROMFSEnable the eLua read-only +filesystem. See the ##ROMFS +documentation for details about using the ROM file system.
BUILD_TERMEnable ANSI terminal support. It allows eLua to interact with terminals that support ANSI escape sequences. Currently it works only over - RS-232 connections, although this is not a strict requirement. You need to enable this if you want to use the ##term module.BUILD_TERMEnable ANSI terminal support. It allows eLua +to interact with terminals that support ANSI escape sequences. +Currently it works only over RS-232 connections, although this is not a +strict requirement. You need to enable this if you want to use the ##term module.
BUILD_UIPEnable TCP/IP networking support. You need to enable this if you want to use the ##net module. Also, your platform must - implement the uIP support functions (see the ##platform interface documentation for details).BUILD_UIPEnable TCP/IP networking support. You need to enable +this if you want to use the ##net +module. Also, your platform must implement the uIP support +functions (see the ##platform +interface documentation for details).
BUILD_DHCPCIf BUILD_UIP is enabled, you can enable this to include a DHCP client in the TCP/IP networking subsystem.BUILD_DHCPCIf BUILD_UIP is enabled, you can enable this to include +a DHCP client in the TCP/IP networking subsystem.
BUILD_DNSIf BUILD_UIP is enabled, you can enable this to include a minimal DNS resolver in the TCP/IP networking subsystem.BUILD_DNSIf BUILD_UIP is enabled, you can enable this to include +a minimal DNS resolver in the TCP/IP networking subsystem.
BUILD_CON_GENERICGeneric console support. Enables console access (stdio/stdout/stderr) via a serial transport (currently RS-232, but others can be supported). - Enable this if you want to use console input/output over your RS-232 connection. Don't enable this if you need console input/ouput over Ethernet - (see the next option). - BUILD_CON_GENERICGeneric console support. Enables console access +(stdio/stdout/stderr) via a serial transport (currently RS-232, but +others can be supported). Enable this if you want to use console +input/output over your RS-232 connection. Don't enable this if you need +console input/ouput over Ethernet (see the next option).
BUILD_CON_TCPConsole input/output over TCP/IP connections only. Use this if you want to use your eLua board over a telnet session. - Don't enable this if you need console input/output over serial transports (see the previous option).BUILD_CON_TCPConsole input/output over TCP/IP connections only. Use +this if you want to use your eLua board over a +telnet session. Don't enable this if you need console input/output over +serial transports (see the previous option).
BUILD_ADCGeneric ADC support code. You need to enable this if you want to use the ##adc module, or simply the ADC functions - from the platform interface. You don't need it if you're not planning to use the ADC.BUILD_ADCGeneric ADC support code. You need to enable this if +you want to use the ##adc +module, or simply the ADC functions from the platform interface. You +don't need it if you're not planning to use the ADC.
-

Configuring modules

-

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: +

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: +

-

Please note that this notation is specific to LTR (the Lua Tiny RAM 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 ##LTR section for more information about LTR.

-

For the full list of modules that can be enabled or disabled via platform_conf.h check ##the eLua reference manual.

+
  • 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 Lua +Tiny RAM 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 ##LTR +section for more information about LTR.

    +

    For the full list of modules that can be enabled or disabled +via platform_conf.h check ##the +eLua reference manual.

    Static configuration data

    -

    "Static configuration" reffers 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. +

    "Static configuration" reffers 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. +

    - - + + - - + + - - + + - - + + - - + + - - + + - - + + -
    NameMeaningNameMeaning
    CON_UART_ID
    CON_UART_SPEED    		Used to configure console input/output over UART. The specified UART id will be used for console input/output, at the specified speed. The data format is always 8N1 (8 data bits, no parity, - 1 stop bits) at this point.CON_UART_ID
    +CON_UART_SPEED    		Used to configure console input/output over UART. The +specified UART id will be used for console input/output, at the +specified speed. The data format is always 8N1 (8 data bits, no parity, +1 stop bits) at this point.
    XMODEM_TIMER_IDDefines the id of the timer used by XMODEM to handle timeouts (if XMODEM is enabled in the build). At this point, the XMODEM subsystem uses the same UART id as the one specified by - CON_UART_ID.XMODEM_TIMER_IDDefines the id of the timer used by XMODEM to handle +timeouts (if XMODEM is enabled in the build). At this point, the XMODEM +subsystem uses the same UART id as the one specified by CON_UART_ID.
    TERM_TIMER_ID
    TERM_LINES
    TERM_COLS
    TERM_TIMEOUT
    		Used to configure the ANSI terminal support (if enabled in the build). Used to specify (respectively): the timer id used by the "term" implementation to handle timeouts, the number of - lines and columns of the ANSI terminal, and the ANSI input timeout (used as a inter-char timeout when a key sends more than one code to the ANSI subsystem, for example the up, down, left - and right keys on a PC keyboard).TERM_TIMER_ID
    +TERM_LINES
    +TERM_COLS
    +TERM_TIMEOUT
    +    		Used to configure the ANSI terminal support (if enabled +in the build). Used to specify (respectively): the timer id used by the +"term" implementation to handle timeouts, the number of lines and +columns of the ANSI terminal, and the ANSI input timeout (used as a +inter-char timeout when a key sends more than one code to the ANSI +subsystem, for example the up, down, left and right keys on a PC +keyboard).
    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.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.
    VTMR_NUM_TIMERS
    VTMR_FREQ_HZ    		Specify the virtual timers configuration for the platform (reffer to ##the timer module documentation for details). Define VTMR_NUM_TIMERS to 0 if this feature is not used.VTMR_NUM_TIMERS
    +VTMR_FREQ_HZ    		Specify the virtual timers configuration for the +platform (reffer to ##the timer module +documentation for details). Define VTMR_NUM_TIMERS to 0 if +this feature is not used.
    PLATFORM_CPU_CONSTANTSIf the ##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. -     		PLATFORM_CPU_CONSTANTSIf the ##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.

    -

    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 ROMFS documentation for details on how to do this.

    + + +

    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 ROMFS +documentation for details on how to do this.

    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 aparent 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]
-  [cpu=at91sam7x256 | at91sam7x512 | i386 | str912fw44 | lm3s8962 | 
-       lm3s6965 | lm3s6918 | lpc2888 | str711fr2 | at32uc3a0512 | stm32f103ze
-  [board=ek-lm3s8962 | ek-lm3s6965 | eagle-100 | str9-comstick | sam7-ex256 | 
-         lpc-h2888 | mod711 | pc | atevk1100 | stm3210e-eval ]
-  [cpumode=arm | thumb] 
-  [allocator = newlib | multiple | simple]
-  [toolchain = <toolchain name>]
-  [optram = 0 | 1]
-  [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:

    +

    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 +aparent 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]
     [cpu=at91sam7x256 | at91sam7x512 | i386 | str912fw44 | lm3s8962 | 
     lm3s6965 | lm3s6918 | lpc2888 | str711fr2 | at32uc3a0512 | stm32f103ze
     [board=ek-lm3s8962 | ek-lm3s6965 | eagle-100 | str9-comstick | sam7-ex256 | 
     lpc-h2888 | mod711 | pc | atevk1100 | stm3210e-eval ]
     [cpumode=arm | thumb] 
     [allocator = newlib | multiple | simple]
     [toolchain = <toolchain name>]
     [optram = 0 | 1]
     [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:

    -

    For board/CPU assignment look at the beginning of the SConstruct file (the platform_list array), it's self-explanatory.
    +

  • 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 array), it's +self-explanatory.
    The other options are as follows:

    -

    -

    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. "scons -c" is also recommended after you reconfigure your build image, -as scons seems to "overlook" the changes to these files on some occasions.

    - +
  • 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 lack a floating point co-processor (which is the case for +all current eLua targets) 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 and LPC2888 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. The default value is +'newlib' for all CPUs except 'lpc2888' and 'at32uc3a0512', since the +LPC-H2888 and ATEVK1100 board come with external SDRAM memory and thus +are an ideal target for 'multiple'. 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=0 | 1: enables of disables the +LTR patch, see the ##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).
    • + +

    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. "scons -c" is +also recommended after you reconfigure your build image, as scons seems +to "overlook" the changes to these files on some occasions.

    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.

    - +

    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. The CPU is detected as +AT91SAM7X256.

    $ scons board=sam7-ex256 cpu=at91sam7x512
    -

    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 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 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 -the tutorials from this site

    . - - - +

    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

    +. + \ No newline at end of file