eLua toolchains

Toolchains for eLua

You need (at least) a toolchain if you decide to build eLua yourself. The toolchain must contain at least a compiler, an assembler, a linker and (most likely) a tool to extract binary data from the compiled image (in order to build the actual firmware). Also, a program that reports the sizes of different sections in the compiled image is often used to give an idea about the resource consumption of eLua. You can use as many toolchains as you want for a given target, as long as the build scripts know to handle them. This section outlines the different toolchain choices available for compiling eLua. Use the links below to navigate directly to your target of interest.

If you have a different toolchain, refer to the toolchain configuration paragraph in this document.

Toolcains for ARM and Cortex

You have multiple options when building eLua for ARM and Cortex CPUs:

Because building a toolchain is already covered in another section of the documentation, we'll focus on installing a pre-compiled toolchain here. ARM is a very popular architecture, and because of this there are a lot of toolchains available for download free of charge. One of the most popular ones comes from CodeSourcery, and we'll cover it here for a number of important reasons:

  • it has support for both "traditional" ARM targets and Cortex-M3 (Thumb2) targets
  • it comes with user-friendly installers for both Linux and Windows
  • it has fairly good documentation
  • eLua supports this toolchain for all its ARM and Cortex targets

Obtaining and installing the toolchain is very easy:

  1. go to the CodeSourcery download location for the toolchain.
  2. select from the table the current version in the "EABI" line (the link to the current version is just above the "All versions..." link).
  3. download and run the installer.

That's all! Make sure that the location of the toolchain is in your $PATH and build eLua with the toolchain=codesourcery option.

Toolchains for AVR32

Currently you have only one option for AVR32: download and install the toolchain from Atmel. Unfortuntely they don't provide an installer, just a bunch of Linux packages with some dependencies, so the installation process might be a bit tricky. These are the steps you should follow to install Atmel's AVR32 toolchain:

  • download the correct version for your Linux distribution (in this case Ubuntu) from here.
  • unzip the downloaded archive to a temporary directory, you'll get a bunch of .deb packages
  • install the packages from this command line (the package names are based on version 2.1.4 of the toolchain, change them as needed if you're using a different version):
    $ sudo dpkg -i libavr32ocd1_3.0.9-1_i386.deb libavr32sim_0.2.1-1_i386.deb 
    $ sudo dpkg -i libavrtools1_3.0.9-1_i386.deb libelfdwarfparser_2.0.7-1_i386.deb
    $ sudo dpkg -i avr32headers_1.9.11-1_all.deb
    $ sudo dpkg -i avr32parts_1.9.9-1_all.deb
    $ sudo dpkg -i avr32-binutils_2.17.atmel.1.2.6-2_i386
    $ sudo dpkg -i avr32-gcc-newlib_4.2.2-atmel.1.0.8-2_i386.deb
    $ sudo dpkg -i avr32program_3.0.4-1_i386.deb
    If dpkg complains about missing dependencies, install them as required and resume the installation process.

That's it. Your toolchain is already be in $PATH (since it installs itself in /usr/bin) so you should be ready to build eLua for AVR32.

Toolchains for i386

Currently the only tested procedure for building eLua for i386 is to build an i386 toolchain. Other toolchains might work equally well though, but none was tested so far.

Toolchain configuration in eLua (WIP)

The eLua build system makes provisions for specifying an unlimited number of toolchains for a given target, selectable via the build_elua toolchain=... option. The default structure of each of the toolchains supported by default is listed in the table below.

Toolchain Name Compiler Linker Assembler Size tool Image copy tool
Platform
ARM (ELF) arm-gcc arm-elf-gcc arm-elf-ld arm-elf-as arm-elf-size arm-elf-objcopy
ARM (EABI) codesourcery arm-none-eabi-gcc arm-none-eabi-ld arm-none-eabi-as arm-none-eabi-size arm-none-eabi-objcopy
Cortex (ELF) arm-gcc arm-elf-gcc arm-elf-ld arm-elf-as arm-elf-size arm-elf-objcopy
Cortex (EABI) codesourcery arm-none-eabi-gcc arm-none-eabi-ld arm-none-eabi-as arm-none-eabi-size arm-none-eabi-objcopy
AVR32 avr32-gcc avr32-gcc avr32-ld avr32-s avr32-size avr32-objcopy
i386 i686-gcc i686-elf-gcc i686-elf-ld nasm i686-elf-size i686-elf-objcopy

If you need to add a new toolchain or modify an existing one, take a look build_data.lua. A toolchain-related fragment of build_data.lua is shown below:

# List of toolchains
local toolchain_list = {
  # This defines a toolchain with the name "arm-gcc"
  [ 'arm-gcc' ] = {
    compile = 'arm-elf-gcc',
    link = 'arm-elf-ld',
    asm = 'arm-elf-as',
    bin = 'arm-elf-objcopy',
    size = 'arm-elf-size',
    cross_cpumode = 'little',
    cross_lua = 'float_arm 64',
    cross_lualong = 'int 32',
    version = '--version'
  },
  # Another toolchain, this time called "arm-eabi-gcc"
  [ 'arm-eabi-gcc' ] = {
    compile = 'arm-eabi-gcc',
    link = 'arm-eabi-ld',
    asm = 'arm-eabi-as',
    bin = 'arm-eabi-objcopy',
    size = 'arm-eabi-size',
    cross_cpumode = 'little',
    cross_lua = 'float 64',
    cross_lualong = 'int 32',
    version = '--version'
  },
................  
}

-- Toolchain to arch mapping
local toolchain_map = {
  arm = { 'arm-gcc', 'codesourcery', 'devkitarm', 'arm-eabi-gcc' },
  cortexm3 = { 'arm-gcc', 'codesourcery', 'devkitarm', 'arm-eabi-gcc' },
................
}

-- CPU to platform mapping also defines the platform architecture
-- which is used in turn to find the usable toolchains in toolchain_map
local platform_list =
{
  at91sam7x = { cpus = { 'AT91SAM7X256', 'AT91SAM7X512' }, arch = 'arm' },
  lm3s = { cpus = { 'LM3S1968', 'LM3S8962', 'LM3S6965', 'LM3S6918', 'LM3S9B92', 'LM3S9D92' }, arch = 'cortexm3' },
  ................
}

From this fragment it's easy to understand that there are two main places in build_data.lua that must be taken into account when dealing with toolchain:

  • the definition of toolchain_list. This is a list of all the supported toolchains with all their relevant components (compiler, linker, assembler, image copy tool and size tool).
  • the toolchain-to-architecture map in toolchain_map. The first element of this array will be automatically used if a toolchain=... option is not specified on the command line.

Please note that in order to add a new toolchain to eLua it's generally not enough to edit just build_data.lua. As different toolchains have different command line options, one should also edit the platform's build configuration file (src/platform/<platform name>/conf.lua) and make it aware of the new toolchain. The exact procedure for doing this is highly dependent on the toolchain and it's well beyond the scope of this tutorial.