構建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工具鏈）。

水平有限，若有錯誤，給出指正。