mirror of
https://github.com/elua/elua.git
synced 2025-01-08 20:56:17 +08:00
89acc4910b
- build_release.lua changed to use the new build system - checked for proper compilation of all known configurations (boards/known/) - fixed various small issues in the builder/utils library - added 'disp_mode=minimal'
155 lines
9.0 KiB
Plaintext
155 lines
9.0 KiB
Plaintext
// $$HEADER$$
|
|
Building eLua
|
|
-------------
|
|
|
|
IMPORTANT: Starting with eLua 0.10, a new Lua-based build system replaces the previous Python based (scons) build system. You'll need to use the
|
|
new build system to build eLua, as per the instructions link:#buildoptions[here].
|
|
|
|
If you decide to build your own binary image instead of link:downloads.html[downloading one], then you will need to download the source code
|
|
(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]]
|
|
[[confmodules]]
|
|
[[static]]
|
|
Configuring the build image
|
|
---------------------------
|
|
Starting with eLua 0.10, the build is configured by using the special configurator component, see link:configurator.html[here] for more details.
|
|
|
|
[[buildoptions]]
|
|
Invoking the build system
|
|
-------------------------
|
|
Once you have everything in place, all you have to do is to invoke the build system (build_elua) 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 build_elua. 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.
|
|
|
|
------------------------------------
|
|
$ lua build_elua.lua
|
|
[board=<boardname>]
|
|
[target=lua | lualong | lualonglong]
|
|
[allocator=newlib | multiple | simple]
|
|
[toolchain=<toolchain name>]
|
|
[optram=true | false]
|
|
[boot=standard | luarpc]
|
|
[romfs=verbatim | compress | compile]
|
|
[cpumode=arm | thumb]
|
|
[bootloader=none | emblod]
|
|
[output_dir=<directory>]
|
|
[romfs_dir=<directory>]
|
|
[board_config_file=<file>]
|
|
[skip_conf=true | false]
|
|
[config_only=true | false]
|
|
[build_mode=keep_dir | build_dir_linearized]
|
|
[build_dir=<directory>]
|
|
[disp_mode=all | summary | minimal]
|
|
[-E | -S]
|
|
[-h]
|
|
[prog]
|
|
------------------------------------
|
|
|
|
Your build target is specified by *board*. The other options are as follows:
|
|
|
|
* **target=lua | lualong | lualonglong**: specify if you want to build "regular" Lua (with floating point support). 32 bit integer only Lua (lualong) or 64 bit integer only Lua (lualonglong,
|
|
starting with version 0.9). The default is "lua". "lualong" and "lualonglong" run faster on targets that don't have a floating point co-processor, but they completely lack support for floating
|
|
point operations, they can only handle integers. Also, "lualonglong" doesn't support cross-compilation of Lua source files to bytecode (check link:arch_romfs.html#mode[here] for details).
|
|
|
|
* **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=true | false**: enables of disables the LTR patch, see the link:arch_ltr.html[LTR documentation] for more details. The default is true, which enables the LTR patch. Keep LTR enabled
|
|
unless you have a very good reason to do otherwise, eLua might not function properly with LTR disabled.
|
|
|
|
* **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*).
|
|
|
|
* **romfs = verbatim | compress | compile**: ROMFS compilation mode, check link:arch_romfs.html#mode[here] for details (*new in 0.7*).
|
|
|
|
* **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.
|
|
|
|
* **bootloader = none | emblod**: 'emblod' generates an image suitable for loading with the 'emblod' boot loader. AVR32 only.
|
|
|
|
* **output_dir=<directory>**: changes the directory where the firmware image will be written. The default is the root directory of the eLua source tree.
|
|
|
|
* **romfs_dir=<directory>**: the directory with the link:arch_romfs.html[romfs] files. The default is "romfs".
|
|
|
|
* **board_config_file=<file>**: the configuration file for the board. The builder will not search the board configuration file in the standard paths, using the user-specified one instead. For more details
|
|
about the configurator, see link:configurator.html[this link].
|
|
|
|
* **skip_conf=true | false**: don't call the Lua configurator at all, use whatever configuration file is present in the system instead. This can be used for manually editing the board's generated
|
|
configuration file. For more details, see link:configurator.html#config_manually[this link].
|
|
|
|
* **config_only= true | false**: execute only the configurator, then exit. This can be used for manually editing the board's generated configuration file. For more details, see
|
|
link:configurator.html#config_manually[this link].
|
|
|
|
* **-E | -S**: see the link:#singlefile[single file compilation] section below.
|
|
|
|
* **build_mode=keep_dir | build_dir_linearized**: keep the intermediary build outputs (for example the object files) in the same directory as the source file they come from (*keep_dir*, default) or in a
|
|
single directory (*build_dir_linearized*).
|
|
|
|
* **build_dir=<directory>**: change the directory used by the builder for intermediate files in *build_dir_linearized* mode (see above). The default is *.build*.
|
|
|
|
* **disp_mode=all | summary | minimal**: display all the messages from the build tools (*all*), display only the target being built and show the messages from the build tools only in case of an error or
|
|
warning (*summary*) or display just errors and warnings (*minimal*). The default is *summary*.
|
|
|
|
* *-h*: shows progam usage.
|
|
|
|
* **prog**: by default, the above 'build_elua' 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_**board**.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 "build_elua" as shown above, but add a "-c" at the end of the command line. +
|
|
|
|
**A few examples:**
|
|
|
|
------------------------------------------
|
|
$ lua build_elua.lua board=sam7-ex256 prog
|
|
------------------------------------------
|
|
Build eLua for the SAM7-EX256 board. Also, the bin/hex file(s) required for target programming are generated.
|
|
|
|
-----------------------------------------
|
|
$ lua build_elua.lua board=lpc-h2888 prog
|
|
-----------------------------------------
|
|
Build eLua for the lpc2888 CPU. The allocator is automatically detected as "multiple".
|
|
|
|
------------------------------------------------------------------
|
|
$ lua build_elua.lua board=ek-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.
|
|
|
|
---------------------------------------
|
|
$ lua build_elua.lua board=mbed prog -c
|
|
---------------------------------------
|
|
Clean the intermediary build files for the mbed board, as well as the outputs (firmware files).
|
|
|
|
[[singlefile]]
|
|
Single file compilation
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
For various reasons, it is often useful to compile a single file instead of the whole image. *build_elua* can do that by specifying the path toward a source file as a target name. It also provides
|
|
options to precompile or generate the assembler source for single files. Examples:
|
|
|
|
------------------------------------------
|
|
$ lua build_elua.lua board=mbed src/main.c
|
|
------------------------------------------
|
|
Compile only src/main.c for the 'mbed' board.
|
|
|
|
---------------------------------------------
|
|
$ lua build_elua.lua board=mbed -E src/main.c
|
|
---------------------------------------------
|
|
Preprocess src/main.c, using 'mbed' as the target board.
|
|
|
|
---------------------------------------------
|
|
$ lua build_elua.lua board=mbed -S src/main.c
|
|
---------------------------------------------
|
|
Generate the assembler source file for src/main.c, using 'mbed' as the target board.
|
|
|
|
// $$FOOTER$$
|
|
|