构建eLua

构建eLua

如果你决定构建你自己的二进制镜像而不是下载一个的话，那么你将下载elua源代码。然后根据特定平台下的eLua构建说明唉设置你的构建环境。

配置构建镜像

eLua拥有灵活的构建系统，可以选择组件成为二进制镜像的一部分，并且可以设置静态配置选项。为了使用它，需要编辑一个配置文件（platform_conf.h）,此文件位于特定的目录下（src/platform/<platform_name>/platform_conf.h）配置参数的细节下面会说到。

配置组件

eLua组件有个特性可以依据功能性由eLua自身添加，不需要修改它的API。下面的例子就是关于组件的配置代码:

// *****************************************************************************
// Define here what components you want for this platform

#define BUILD_XMODEM
#define BUILD_SHELL
#define BUILD_ROMFS
#define BUILD_MMCFS
#define BUILD_TERM
#define BUILD_UIP
#define BUILD_DHCPC
#define BUILD_DNS
#define BUILD_CON_GENERIC
#define BUILD_ADC
#define BUILD_RPC

在eLua中可配置的组件有：

Name	Meaning
BUILD_XMODEM	Define 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). To enable: #define BUILD_XMODEM Static configuration data dependencies: CON_UART_ID, CON_UART_SPEED, CON_TIMER_ID
BUILD_SHELL	This builds 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. To enable the shell over a serial connection: #define BUILD_SHELL #define BUILD_CON_GENERIC To enable the shell over a TCP/IP connection: #define BUILD_SHELL #define BUILD_CON_TCP
BUILD_ROMFS	Enable the eLua read-only filesystem. See the ROMFS documentation for details about using the ROM file system. To enable: #define BUILD_ROMFS
BUILD_MMCFS	Enable the eLua SD/MMC FAT filesystem support. To enable: #define BUILD_MMCFS Static configuration data dependencies: MMCFS_TICK_HZ, MMCFS_TICK_MS, MMCFS_CS_PORT, MMCFS_CS_PIN, MMCFS_SPI_NUM
BUILD_TERM	Enable ANSI terminal support. It allows eLua to interact with terminals that support ANSI escape sequences (more details here). 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. To enable: #define BUILD_TERM Static configuration data dependencies: CON_UART_ID, CON_UART_SPEED, CON_TIMER_ID, CON_FLOW_TYPE, TERM_LINES, TERM_COLS
BUILD_UIP	Enable 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 theplatform interface documentation for details). To enable: #define BUILD_UIP Static configuration data dependencies: ELUA_CONF_IPADDR0…3, ELUA_CONF_NETMASK0…3, ELUA_CONF_DEFGW0…3, ELUA_CONF_DNS0…3
BUILD_DHCPC	If BUILD_UIP is enabled, you can enable this to include a DHCP client in the TCP/IP networking subsystem. To enable: #define BUILD_UIP #define BUILD_DHCPC
BUILD_DNS	If BUILD_UIP is enabled, you can enable this to include a minimal DNS resolver in the TCP/IP networking subsystem. To enable: #define BUILD_UIP #define BUILD_DNS
BUILD_CON_GENERIC	Generic console support (details here). 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). To enable: #define BUILD_CON_GENERIC Static configuration data dependencies: CON_UART_ID, CON_UART_SPEED, CON_TIMER_ID, CON_FLOW_TYPE
BUILD_CON_TCP	Console input/output over TCP/IP connections only (details here). Enable 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). To enable: #define BUILD_UIP #define BUILD_CON_TCP
BUILD_ADC	Define this to build support for ADC peripherals. This must be enabled to use the adc module or the adc platform interface. To enable: #define BUILD_ADC Static configuration data dependencies: ADC_BIT_RESOLUTION, ADC_TIMER_FIRST_ID, ADC_NUM_TIMERS, BUF_ENABLE_ADC, ADC_BUF_SIZE
BUILD_RPC	Define this to build support for LuaRPC. This must be enabled to use the rpc module. To enable: #define BUILD_RPC Static configuration data dependencies: (ONLY if built with boot=luarpc):RPC_UART_ID, RPC_TIMER_ID
BUILD_C_INT_HANDLERS	Enable generic interrupt support in the C code, check here for details. To enable: #define BUILD_C_INT_HANDLERS
BUILD_LUA_INT_HANDLERS	Enable generic interrupt support in the Lua code, check here for details. To enable: #define BUILD_LUA_INT_HANDLERS Static configuration data dependencies: PLATFORM_INT_QUEUE_LOG_SIZE
BUILD_LINENOISE	Enables linenoise support, check here for details. To enable: #define BUILD_LINENOISE Static configuration data dependencies: LINENOISE_HISTORY_SIZE_LUA, LINENOISE_HISTORY_SIZE_SHELL, LINENOISE_AUTOSAVE_FNAME
BUILD_RFS	Enables support for the remote file system, check here for details. To enable: #define BUILD_RFS Static configuration data dependencies: RFS_BUFFER_SIZE, RFS_UART_ID, RFS_UART_SPEED, RFS_TIMER_ID, RFS_FLOW_TYPE, RFS_TIMEOUT
BUILD_SERMUX	Enables support for the serial multiplexer, check here for details. To enable #define BUILD_SERMUX Static configuration data dependencies: SERMUX_PHYS_ID, SERMUX_PHYS_SPEED, SERMUX_FLOW_TYPE, SERMUX_NUM_VUART, SERMUX_BUFFER_SIZES

配置模块

你也可以选择将要成为二进制镜像一部分的模块进行配置。不像组件，模块对eLua的API有直接的影响，所以小心的选择他们。禁止一个模块可以节省FLASH空间（RAM也龈可能减少），但是它将完全从eLua中移除掉使用此模块的可能性。

这些被构建的模块由LUA_PLATFORM_LIBS_ROM宏来定义。一个例子如下：

#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 )

每个模块由_ROM(module_name,module_init_function, module_map_array)宏定义，里面的3个说明如下：

• module_name：elua中使用的模块名
• module_init_function：用于elua运行时进行模块初始化的函数
• module_map_array：此模块中所有函数和常量的列表

记住这样的书写方式是针对LTR(the lua Tiny RAM pathc)的，并且它不是唯一的方式来指定需要构建的模块（尽管它是最常见的）。

静态配置数据

静态配置也就是编译时配置。静态配置参数被硬编码进二进制镜像中且在运行时不能更改。下面的表展示了静态配置参数和它们所表达的含义：

Name	Meaning
CON_UART_ID CON_UART_SPEED CON_TIMER_ID CON_FLOW_TYPE	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)t. The specified timer ID will be used for the console subsystem. These variables are also used by the XMODEM and TERM implementations. If CON_FLOW_TYPE is defined the specified flow control is applied to the console UART interface (see this link to find out how to specify the flow control). If not defined it defaults to no flow control.
TERM_LINES 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.
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 (refer to the timer module documentation for details). Define VTMR_NUM_TIMERS to 0 if this feature is not used.
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.
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.
MMCFS_SPI_NUM	Specify the SPI peripheral to be used by MMCFS. Only needed if MMCFS support is enabled.
PLATFORM_CPU_CONSTANTS	If 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.
BUF_ENABLE_ADC	If the 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.
ADC_BUF_SIZE	If the 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.
ADC_BIT_RESOLUTION	If the 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.
RPC_UART_ID	If the rpc module is enabled and boot mode is set to luarpc, this selects which uart luarpc will listen on for incoming client connections.
RPC_TIMER_ID	If the 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.
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 here for details about the EGC patch). If not specified, EGC_INITIAL_MODE defaults toEGC_NOT_ACTIVE (emergency garbage collector disabled) andEGC_INITIAL_MEMLIMIT defaults to 0.
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 here for details.
LINENOISE_HISTORY_SIZE_LUA	If linenoise support is enabled, this defines the number of lines kept in history for the Lua interpreter. Check here for details. If history support in Lua is not needed, define this as 0.
LINENOISE_HISTORY_SIZE_SHELL	If linenoise support is enabled, this defines the number of lines kept in history for the eLua shell. Check here for details. If history support in the eLua shell is not needed, define this as 0.
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 here for details. This macro is optional; if it’s not defined, the history will not be saved automatically.
RFS_BUFFER_SIZE	Size of the RFS buffer. Needs to be one of the BUF_SIZE_xxx constants defined in inc/buf.h
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.
RFS_UART_SPEED	Communication speed of the RFS UART interface.
RFS_TIMER_ID	The ID of a timer that will be used by RFS for internal operations
RFS_FLOW_TYPE	Flow control type on the serial RFS interface, see here for details. If not specified it defaults to 'no flow control'.
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.
BUILD_SERMUX	Enable serial multiplexer support in eLua.
SERMUX_PHYS_ID	The ID of the physical UART interface used by the serial multiplexer.
SERMUX_PHYS_SPEED	Communication speed of the multiplexer UART interface.
SERMUX_FLOW_TYPE	Flow control type on the physical serial multiplexer interface, see here for details. If not specified it defaults to 'no flow control'.
SERMUX_NUM_VUART	The number of virtual UART interfaces. This number can’t be higher than 8.
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 BUF_SIZE_xxx constants defined in inc/buf.h

剩下的一些静态参数主要由开发者修改所以没有陈述在上面的列表里面。

还有一件事就是你需要配置ROM文件系统内容。

调用构建系统

一旦你整理好所有事情，你需要做的就是使用正确的参数调用构建系统（scons）。这是一个相当简单的步骤，尽管它看起来有点吓人，因为有很多参数需要传递给scons。它们是用来根据你特定的需要微调你最终的二进制镜像文件。但是除非你的需要很特别那么就不需要修改他们，所以不要担心表面上的复杂性。下面的代码就是调用构建的例子。

$ scons
  [target=lua | lualong]
  [cpu=<cpuname>]
  [board=<boardname>]
  [cpumode=arm | thumb]
  [allocator = newlib | multiple | simple]
  [toolchain = <toolchain name>]
  [optram = 0 | 1]
  [romfs = verbatim | compress | compile]
  [prog]

你构建的目标由cpu和board两个参数决定。“cpu”给出CPU的名字，“board”给出开发板的名字。一个开发办可能与多个CPU拥有联系。这允许构建系统拥有灵活性。你可以一起使用这两个选项或者分开使用。如下所示：

• cpu=name:构建指定的CPU。开发板名会由构建系统自动分配。
• board=name：构建指定的开发板。CPU的名字由构建系统自动推断。
• cpu=name board=name:构建指定的CPU和开发板。这样构建的脚本将不允许非法的CPU和开发板组合。

关于 board/cpu的分配，请看Sconstruct（the platform_list）文件开始的部分，这里就不再解释了。

其他的参数如下：

• target = lua | lualong，指定你是想带浮点数支持还是只是整数支持。默认的是lua。“lualong”在目标板上运行的更快因为它们没有浮点数协同处理器。但是它完全缺少对浮点数操作的支持，只能处理整数。
• cpumode = arm | thumb:针对ARM目标（不是cortex）此定义了编译模式，对AT91SAM7X默认是Thumb模式，对STR9,LPC2888,LPC2468目标默认是arm模式。
• allocator=newlib | multiple | simple:选择默认的分配器（newlib）这是一个老版本的dlmalloc。多重内存分配器（multiple）是一个新的dlmalloc版本可以处理多重内存空间。还有一个简单的分配器（simple），它非常慢而且不能处理碎片，但是它只需要很少的资源（Flash|RAM）。当你拥有多个内存空间你需要使用多重分配器（比如开发板上有外部RAM）你应该使用简单分配器在资源有限的系统中。
• toolchain = <toolchain name>:定义了用于构建镜像文件的工具链名字。
• oprram = 0 | 1:使能或禁能LTR补丁。默认是1，就是使用LTR补丁。
• prog:默认的话，上面的scons命令只会生成elf文件。指定“prog”构建生成特定平台的编程文件（比如，在AT91SAM7X256中生成的是bin文件，此文件可以运行在CPU中）
• romfs = veratim | compress| compile:ROMFS编译模式。
• boot = standard | luarpc : 启动模式。标准模式会启动个shell或者一个lua解释器。luarpc启动一个等待的rpc服务器，由串口和定时器指定。

 

输出文件会命名为elua_[target}_[cpu].elf(或者其它拥有同样名字但不同格式的文件，比如“.bin\.hex”，如果prog指定了的话。)

如果你想使用一个等价于“make clean”的命令，调用“scons”如下，但是添加一个“-c”命令行末尾。

下面是几个例子：

$ scons cpu=at91sam7x256 -c

清除掉先前构建的中间文件。

$ scons cpu=at91sam7x256

构建elua针对AT91SAM7X256平台。

$ scons board=sam7-ex256

构建elua指定开发板为SAM7-EX256，CPU被分配为AT91SAM7X256。

scons board=sam7-ex256 cpu=at91sam7x512

构建elua指定开发板为SAM7-EX256但是覆盖掉默认的CPU。这是非常有用的当你想看见指定开发板上不同CPU的表现时。在SAM7-EX256开发板上，可以在AT91SAM7X256和AT91SAM7X512两者之间切换。

$ scons cpu=lpc2888 prog

构建eLua针对LPC2888.CPU。平台名字分配为LPC-H2888，当然，针对目标CPU的编程文件bin文件也会产生。分配器也会自动的分配为多重分配器。

$ scons cpu=lm3s8962 toolchain=codesourcery prog

构建镜像文件针对Cortex LM3S8962处理器，但是使用CodeSourcery工具链代替默认的工具链（通用的ARM GCC工具链）。

水平有限，如有错误，给出指正。