mirror of
https://github.com/elua/elua.git
synced 2025-01-08 20:56:17 +08:00
350 lines
17 KiB
HTML
350 lines
17 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
|
|
<html><head>
|
|
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
|
|
<meta http-equiv="Content-Language" content="en-us"><title>Building eLua</title>
|
|
|
|
<link rel="stylesheet" type="text/css" href="../style.css">
|
|
</head>
|
|
<body style="background-color: rgb(255, 255, 255);">
|
|
<h3>Building eLua</h3>
|
|
<p>If you decide to build your own <b>eLua</b>
|
|
binary image (instead of <a href="downloads.html">downloading
|
|
one</a>) you need to check a few things first:
|
|
</p>
|
|
<ul>
|
|
<li>you're using Linux. Compiling under windows should be
|
|
possible, however this isn't tested. We are in Ubuntu, so what
|
|
we use is "apt-get". If you're using a distro with a different
|
|
package
|
|
manager you'll need to translate the "apt-get" calls to your specific
|
|
distribution.</li>
|
|
<li>you have a toolchain (compiler, linker, assembler and
|
|
standard C libraries) for your target. Check <a href="toolchains.html">##the toolchains page</a> for
|
|
toolchain instructions. Please note that even if you already have a
|
|
compiled toolchain, the differences in the Newlib configure flags
|
|
(mainly the --disable-newlib-supplied-syscalls flags) might prevent <b>eLua</b>
|
|
for building properly on your machine.</li>
|
|
<li>you set your platform configuration options properly. Check
|
|
the next paragraph for instructions on how to configure your build.</li>
|
|
<li>Python - It should be already installed. If it's not, use
|
|
apt-get to install it:
|
|
<pre><code>$ sudo apt-get install python</code></pre>
|
|
</li>
|
|
<li>Scons - <b>eLua</b> uses scons instead of make
|
|
and makefiles, because we find scons much more "natural" and easier to
|
|
use than make. To install it:
|
|
<pre><code>$ sudo apt-get install scons</code></pre>
|
|
</li>
|
|
<li>your toolchain's "bin" directory (this is generally
|
|
something like /usr/local/cross-arm/bin, where /usr/local/cross-arm is
|
|
the directory in which you installed your toolchain) must be in $PATH.
|
|
</li>
|
|
<li>if you're building for the i386 platform, you'll also need
|
|
"nasm":
|
|
<pre><code>$ sudo apt-get install nasm</code></pre>
|
|
</li>
|
|
</ul>
|
|
<p>For each platform, <b>eLua</b> assumes a certain
|
|
name for the toolchain components, as shown below.
|
|
</p>
|
|
<p>If your toolchain uses different names, you have to modify the
|
|
toolchain definition in SConstruct. See the <a href="toolchains.html">toolchains instructions</a> for
|
|
details.</p>
|
|
<h3>Configuring the build image</h3>
|
|
<p><b>eLua</b> has a very flexible build system that
|
|
can be used to select the components that are going to be part of the <b>eLua</b>
|
|
binary image and to set the compile time (static) configuration.
|
|
To use it, you need to edit a single configuration file (<i>platform_conf.h</i>)
|
|
located in the platform specific directory (<i>src/platform/<platform
|
|
name>/platform_conf.h)</i>. The configuration parameters
|
|
are described in detail in the next paragraphs.</p>
|
|
<h2>Configuring components</h2>
|
|
<p>A <b>component</b> is a feature that can be
|
|
enabled to add functionality to <b>eLua</b> itself,
|
|
without modifying its API (which is the part that the programmer uses
|
|
to write <b>eLua</b> programs). The components that can be
|
|
configured in <b>eLua</b> are:
|
|
</p>
|
|
<table class="table_center">
|
|
<tbody>
|
|
<tr>
|
|
<th style="text-align: left;">Name</th>
|
|
<th style="text-align: center;">Meaning</th>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">BUILD_XMODEM</td>
|
|
<td>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).</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">BUILD_SHELL</td>
|
|
<td>This build the <b>eLua</b> shell (see <a href="using.html">Using eLua</a> for details on the
|
|
shell). If the shell is not enabled, the code looks for a file called <i>/rom/autorun.lua</i>
|
|
and executes it. If this file is not found, a regular Lua intepreter is
|
|
started on the target.</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">BUILD_ROMFS</td>
|
|
<td>Enable the <b>eLua</b> read-only
|
|
filesystem. See the <a href="romfs.html">##ROMFS
|
|
documentation</a> for details about using the ROM file system.</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">BUILD_TERM</td>
|
|
<td>Enable ANSI terminal support. It allows <b>eLua</b>
|
|
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 <a href="m_term.html">##term module</a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">BUILD_UIP</td>
|
|
<td>Enable TCP/IP networking support. You need to enable
|
|
this if you want to use the <a href="m_net.html">##net
|
|
module</a>. Also, your platform must implement the uIP support
|
|
functions (see the <a href="platform_interface.html">##platform
|
|
interface</a> documentation for details).</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">BUILD_DHCPC</td>
|
|
<td>If BUILD_UIP is enabled, you can enable this to include
|
|
a DHCP client in the TCP/IP networking subsystem.</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">BUILD_DNS</td>
|
|
<td>If BUILD_UIP is enabled, you can enable this to include
|
|
a minimal DNS resolver in the TCP/IP networking subsystem.</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">BUILD_CON_GENERIC</td>
|
|
<td>Generic 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). </td>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">BUILD_CON_TCP</td>
|
|
<td>Console input/output over TCP/IP connections only. Use
|
|
this if you want to use your <b>eLua</b> board over a
|
|
telnet session. Don't enable this if you need console input/output over
|
|
serial transports (see the previous option).</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">BUILD_ADC</td>
|
|
<td>Generic ADC support code. You need to enable this if
|
|
you want to use the <a href="m_adc.html">##adc</a>
|
|
module, or simply the ADC functions from the platform interface. You
|
|
don't need it if you're not planning to use the ADC.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<h2>Configuring modules</h2>
|
|
<p>You can also choose the modules that are going to be part of
|
|
the <b>eLua</b> image. Unlike components, the modules have
|
|
a direct impact on the <b>eLua</b> 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 <b>eLua</b>.</p>
|
|
<p>The modules included in the build are specified by the
|
|
LUA_PLATFORM_LIBS_ROM macro. An example is given below: </p>
|
|
<pre><code>#define LUA_PLATFORM_LIBS_ROM\<br> _ROM( AUXLIB_PIO, luaopen_pio, pio_map )\<br> _ROM( AUXLIB_TMR, luaopen_tmr, tmr_map )\<br> _ROM( AUXLIB_PD, luaopen_pd, pd_map )\<br> _ROM( AUXLIB_UART, luaopen_uart, uart_map )\<br> _ROM( AUXLIB_TERM, luaopen_term, term_map )\<br> _ROM( AUXLIB_PWM, luaopen_pwm, pwm_map )\<br> _ROM( AUXLIB_PACK, luaopen_pack, pack_map )\<br> _ROM( AUXLIB_BIT, luaopen_bit, bit_map )\<br> _ROM( AUXLIB_CPU, luaopen_cpu, cpu_map )\<br> _ROM( LUA_MATHLIBNAME, luaopen_math, math_map )</code></pre>
|
|
<p>Each module is defined by a <b>_ROM( module_name,
|
|
module_init_function, module_map_array )</b> macro, where:
|
|
</p>
|
|
<ul>
|
|
<li><b>module_name</b> is the name by which the
|
|
module can be used from Lua</li>
|
|
<li><b>module_init_function</b> is a function
|
|
called by the Lua runtime when the module is initialized</li>
|
|
<li><b>module_map_array</b> is a list of all the
|
|
functions and constants exported by a module</li>
|
|
</ul>
|
|
<p>Please note that this notation is specific to LTR (the <b>L</b>ua
|
|
<b>T</b>iny <b>R</b>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 <a href="">##LTR
|
|
section</a> for more information about LTR.</p>
|
|
<p>For the full list of modules that can be enabled or disabled
|
|
via <i>platform_conf.h</i> check <a href="">##the
|
|
eLua reference manual</a>.</p>
|
|
<h2>Static configuration data</h2>
|
|
<p>"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.
|
|
</p>
|
|
<table class="table_center">
|
|
<tbody>
|
|
<tr>
|
|
<th style="text-align: left;">Name</th>
|
|
<th style="text-align: center;">Meaning</th>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">CON_UART_ID<br>
|
|
CON_UART_SPEED</td>
|
|
<td>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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">XMODEM_TIMER_ID</td>
|
|
<td>Defines 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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">TERM_TIMER_ID<br>
|
|
TERM_LINES<br>
|
|
TERM_COLS<br>
|
|
TERM_TIMEOUT<br>
|
|
</td>
|
|
<td>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).</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">ELUA_CONF_IPADDR0..3<br>
|
|
ELUA_CONF_NETMASK0..3<br>
|
|
ELUA_CONF_DEFGW0..3<br>
|
|
ELUA_CONF_DNS0..3</td>
|
|
<td>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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">VTMR_NUM_TIMERS<br>
|
|
VTMR_FREQ_HZ</td>
|
|
<td>Specify the virtual timers configuration for the
|
|
platform (reffer to <a href="">##the timer module
|
|
documentation</a> for details). Define VTMR_NUM_TIMERS to 0 if
|
|
this feature is not used.</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="color: rgb(255, 102, 0);">PLATFORM_CPU_CONSTANTS</td>
|
|
<td>If the <a href="">##cpu module</a>
|
|
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 (<i>_C(<constant
|
|
name></i>). For example:
|
|
<pre><code>#define PLATFORM_CPU_CONSTANTS\<br> _C( INT_GPIOA ),\<br> _C( INT_GPIOB ),\<br> _C( INT_GPIOC ),\<br> _C( INT_GPIOD ),\<br> _C( INT_GPIOE )<br></code></pre>
|
|
After compilation, you can access these constants using <i>cpu.INT_GPIOx</i>.
|
|
Note that the implementation of this feature needs virtually no RAM at
|
|
all, so you can define as many constants as you want here. </td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>The rest of the static configuration data parameters are meant
|
|
to be modified mainly by developers and thus they're not listed here.<br>
|
|
One more thing you might want to configure for your build is the
|
|
contents of the ROM file system. See the <a href="">ROMFS
|
|
documentation</a> for details on how to do this.</p>
|
|
<h3>Invoking the build system</h3>
|
|
<p>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.
|
|
</p>
|
|
<pre><code>$ scons <br> [target=lua | lualong]<br> [cpu=at91sam7x256 | at91sam7x512 | i386 | str912fw44 | lm3s8962 | <br> lm3s6965 | lm3s6918 | lpc2888 | str711fr2 | at32uc3a0512 | stm32f103ze<br> [board=ek-lm3s8962 | ek-lm3s6965 | eagle-100 | str9-comstick | sam7-ex256 | <br> lpc-h2888 | mod711 | pc | atevk1100 | stm3210e-eval ]<br> [cpumode=arm | thumb] <br> [allocator = newlib | multiple | simple]<br> [toolchain = <toolchain name>]<br> [optram = 0 | 1]<br> [prog]<br></code></pre>
|
|
<p>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:</p>
|
|
<ul>
|
|
<li><b>cpu=name</b>: build for the specified CPU. A
|
|
board name will be assigned by the build system automatically.</li>
|
|
<li><b>board=name</b>: build for the specified
|
|
board. The CPU name will be inferred by the build system automatically.</li>
|
|
<li><b>cpu=name board=name</b>: build for the
|
|
specified board and CPU. The build script won't allow invalid CPU/board
|
|
combinations.</li>
|
|
</ul>
|
|
<p>For board/CPU assignment look at the beginning of the
|
|
SConstruct file (the <i>platform_list</i> array), it's
|
|
self-explanatory.<br>
|
|
The other options are as follows:</p>
|
|
<ul>
|
|
<li><b>target=lua | lualong</b>: 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 <b>eLua</b> targets) but it completely lacks
|
|
support for floating point operations, it can only handle integers.</li>
|
|
<li><b>cpumode=arm | thumb</b>: 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.</li>
|
|
<li><b>allocator = newlib | multiple | simple</b>:
|
|
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.
|
|
</li>
|
|
<li><b>toolchain=<toolchain name></b>:
|
|
this specifies the name of the toolchain used to build the image. See <a href="toolchains.html#configuration">this link</a> for
|
|
details.</li>
|
|
<li><b>optram=0 | 1</b>: enables of disables the
|
|
LTR patch, see the <a href="">##LTR documentation</a>
|
|
for more details. The default is 1, which enables the LTR patch.</li>
|
|
<li><b>prog</b>: 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). </li>
|
|
</ul>
|
|
<p>The output will be a file named elua_<i>[target]</i>_<i>[cpu]</i>.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).<br>
|
|
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.</p>
|
|
<p><b>A few examples:</b></p>
|
|
<pre><code>$ scons cpu=at91sam7x256 -c <br></code></pre>
|
|
<p>Clear previously built intermediate files.</p>
|
|
<pre><code>$ scons cpu=at91sam7x256<br></code></pre>
|
|
<p>Build eLua for the AT91SAM7X256 CPU. The board name is
|
|
detected as sam7-ex256.</p>
|
|
<pre><code>$ scons board=sam7-ex256<br></code></pre>
|
|
<p>Build eLua for the SAM7-EX256 board. The CPU is detected as
|
|
AT91SAM7X256.</p>
|
|
<pre><code>$ scons board=sam7-ex256 cpu=at91sam7x512<br></code></pre>
|
|
<p>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).</p>
|
|
<pre><code>$ scons cpu=lpc2888 prog </code></pre>
|
|
<p>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".</p>
|
|
<pre><code>$ scons cpu=lm3s8962 toolchain=codesourcery prog</code></pre>
|
|
<p>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</p>
|
|
.
|
|
</body></html> |