$$HEADER$$

Gerando eLua

Se você chegou a conclusão que fica melhor gerar o seu próprio arquivo binário eLua (ao invés de baixá-lo), então será necessário verificarmos algumas coisas antes:

você está usando Linux. É possível a compilação em windows, no entanto, ainda não foi testada. Usamos Ubuntu e o comando que utilizamos é o "apt-get". Caso você esteja com uma distro que possua um gerenciador de pacotes diferente, você terá que alterar o comando "apt-get" para um compatível com a sua distro.
você possui um toolchain (compilador, linker e bibliotecas de assembler e C padrão) para o seu hardware. Dê uma olhada na página toolchains para obter ajuda. É importante observar que, mesmo que você já tenha um toolchain compilado, diferenças nos parâmetros de configuração da NewLib (principalmente os --disable-newlib-supplied-syscalls flags) podem gerar problemas e impedir que eLua seja gerada na sua máquina.
você configurou a sua plataforma corretamente. Leia o próximo parágrafo para obter instruções de como configurar a geração de eLua.
Python - Este deve estar previamente instalado. Caso contrário, execute o apt-get para instalá-lo:
```
$ sudo apt-get install python
```
Scons - eLua usa scons ao invés do make e makefiles, porque achamos que o scons é muito mais "natural" e fácil de usar do que o make. Para instalá-lo:
```
$ sudo apt-get install scons
```
o diretório "bin" do seu toolchain (normalmente algo como /usr/local/cross-arm/bin, onde /usr/local/cross-arm é o diretório de sua instalação toolchain) e deve estar definido no $PATH.
se você está gerando para a plataforma i386, precisará também do "nasm":
```
$ sudo apt-get install nasm
```

Para cada plataforma, eLua assume um nome para os componentes do toolchain, como relacionado abaixo.

Se seu toolchain utiliza nomes diferentes, entã você terá que modificar a definição do toolchain no SConstruct. Leia as instruções para maiores detalhes.

Configurando a imagem gerada

eLua possui um sistema de geração de sua imagem bastante flexível, e que pode ser usado para selecionar os componentes desejados que farão parte do arquivo binário de eLua e também para configuração(estática) durante a compilação. Para usá-lo, será necessário editar somente um único arquivo (platform_conf.h) localizado no diretório da plataforma que está sendo utilizada (src/platform/<platform name>/platform_conf.h). Os parâmetros de configuração estão descritos em detalhes nos próximos parágrafos.

Configurando os componentes

Um componente é um recurso que pode ser habilitado para adicionar funcionalidade a eLua, sem modificar sua API (rotinas usadas pelos programadores para escrever programas em eLua). Segue abaixo um exemplo da configuração de um componente em platform_conf.h:

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

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

Os componentes que podem ser configurados em eLua são:

Nome	Descrição
BUILD_XMODEM	Estabelece a função de recepção XMODEM. Se habilitada, você pode usar o comando "recv" do shell para receber um arquivo Lua (tanto código fonte quanto código précompilado) e executá-lo no seu hardware. Funciona somente com conexões RS-232 (apesar de que, em teoria, é possível fazê-lo funcionar em qualquer tipo de protocolo de transporte). Para habilitar: `#define BUILD_XMODEM` Dependências da configuração de dados estáticos: CON_UART_ID, CON_UART_SPEED, CON_TIMER_ID
BUILD_SHELL	Etabelece a função de gerar um shell de eLua (veja usando eLua para detalhes sobre o shell). Caso o shell não esteja habilitado, o código busca o arquivo chamado /rom/autorun.lua e executa-o. Se este arquivo não for encontrado, um interpretador Lua é iniciado automaticamente no seu hardware. Para habilitar o shell usando uma conexão serial: `#define BUILD_SHELL #define BUILD_CON_GENERIC` Para habilitar o shell usando uma conexão TCP/IP: `#define BUILD_SHELL #define BUILD_CON_TCP`
BUILD_ROMFS	Habilita o sistema de arquivos eLua somente para leitura. Veja a documentação ROMFS para maiores detalhes sobre como usar este sistema de arquivos. Para habilitar: `#define BUILD_ROMFS`
BUILD_TERM	Habilita o suporte ao terminal ANSI. Este recurso permite que eLua interaja com terminais que suportem sequências ANSI (mais detalhes aqui). Atualmente, este recurso funciona somente em conexões R-232, apesar desta não ser uma obrigação estrita. Você precisa habilitar este recurso, caso seja necessário usar o term module. Para habilitar: `#define BUILD_TERM` Dependências da configuração de dados estáticos: CON_UART_ID, CON_UART_SPEED, CON_TIMER_ID, TERM_LINES, TERM_COLS
BUILD_UIP	Habilita o suporte para o TCP/IP. Você precisa habilitar este recurso, caso seja necessário usar o net module. Além disso, sua plataforma deve implementar o suporte para as funções uIP (veja a documentação platforminterface para mais detalhes). Para habilitar: `#define BUILD_UIP` Dependências da configuração de dados estáticos: ELUA_CONF_IPADDR0..3, ELUA_CONF_NETMASK0..3, ELUA_CONF_DEFGW0..3, ELUA_CONF_DNS0..3
BUILD_DHCPC	Se BUILD_UIP está ativado, você pode habilitar este recurso para incluir um cliente DHCP na rede TCP/IP. Para habilitar: `#define BUILD_UIP #define BUILD_DHCPC`
BUILD_DNS	Se BUILD_UIP está ativado, você pode habilitar este recurso para incluir um servidor DNS mínimo na rede TCP/IP. Para habilitar: `#define BUILD_UIP #define BUILD_DNS`
BUILD_CON_GENERIC	Suporte genérico para console (detalhes aqui). Habilita o acesso a console (stdio/stdout/stderr) via protocolo de transporte serial (atualmente RS-232, mas outros podem ser suportados). Ative este recurso caso você queira usar uma console de entrada/saída com sua conexão RS-232. Não ative este recurso caso você queira usar uma console de entrada/saída com Ethernet (veja a próxima opção). Para habilitar: `#define BUILD_CON_GENERIC` Dependências da configuração de dados estáticos: CON_UART_ID, CON_UART_SPEED, CON_TIMER_ID
BUILD_CON_TCP	Console de entrada/saída sobre uma conexão TCP/IP (detalhes aqui). Use este recurso se você quiser usar sua placa eLua sobre uma conexão telnet. Não ative este recurso caso você precise de uma console com protocolo de transporte serial (veja a opção anterior). Para habilitar: `#define BUILD_UIP #define BUILD_CON_TCP`
BUILD_ADC	Suporte genérico para código ADC. Você precisa ativar este recurso caso queira usar o módulo adc, ou simplesmente as funções ADC da interface da plataforma. Por outro lado, você não precisa ativar este recurso caso não esteja pensando em usar as funções ADC. Para habilitar: `#define BUILD_ADC`

Configurando os módulos

Você pode selecionar os módulos que farão parte do arquivo imagem de eLua. Ao contrário dos componentes, os módulos têm um impacto direto na API de eLua, logo tenha cuidado ao selecioná-los. Ao desativar um módulo, você gera um espaço de memória flash (e possivelmente RAM), mas também irá remover completamente a possibilidade de usar este módulo de eLua.

Os módulos incluídos na geração são epecificados pela macro LUA_PLATFORM_LIBS_ROM. Veja um exemplo abaixo:

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

Cada módulo é definido por uma macro _ROM( module_name, module_init_function, module_map_array ), onde:

module_name é o nome pelo qual o módulo pode ser usado a partir de eLua
module_init_function é uma função chamada pelo programa Lua em tempo de execução quando o módulo é inicializado
module_map_array é uma lista de todas as funções e constantes exportadas pelo módulo

Por favor, observe que esta notação é específica para LTR (o patch Lua Tiny RAM) e não é a única forma de especificar a lista dos módulos incluídos na geração (apesar desta ser uma forma comum). Verifique a seção LTR para mais informações sobre LTR.

Para uma lista completa de todos os módulos que podem ser ativados ou desativados via platform_conf.h, veja the eLua reference manual.

Dados da configuração estática

"Configuração estática" refere-se a configuração durante o tempo de compilação. Os parâmetros da configuração estática estão gravados na imagem do firmware e não podem ser alterados em tempo de execução. A tabela abaixo relaciona os parâmetros de configuração estática e suas semânticas.

Nome	Descrição
CON_UART_ID CON_UART_SPEED CON_TIMER_ID	Usado para configurar console de entrada/saída sobre a UART. Um id específico da UART será usado para a console de entrada/saída, a uma velocidade específica. O formato dos dados é sempre é 8N1 (8 bits de dados, sem paridade, 1 stop bit) neste ponto. O timer ID especificado será usado para o subsistema da console. Essas variáveis são usadas também pelas implementações do XMODEM e do TERM.
TERM_LINES TERM_COLS	Usado para configurar o suporte ao terminal ANSI (caso esteja habilitado). Usado para especificar (respectivamente) o número de linhas e colunas do terminal ANSI.
ELUA_CONF_IPADDR0..3 ELUA_CONF_NETMASK0..3 ELUA_CONF_DEFGW0..3 ELUA_CONF_DNS0..3	Usado pelo protocolo TCP/IP caso o cliente DHCP não esteja ativado, ou quando mesmo ativado, este náo tenha como ser contactado. Especifique o endereço IP, a máscara de rede, o gateway padrão e o servidor DNS. Necessário somente quando o BUILD_UIP for habilitado.
VTMR_NUM_TIMERS VTMR_FREQ_HZ	Especifique a configuração dos timers virtuais da plataforma (acesse a documentação do módulo timer para detalhes). Defina VTMR_NUM_TIMERS como 0 caso este recurso não seja utilizado.
PLATFORM_CPU_CONSTANTS	Se o cpu module estiver ativado, este define uma relação de constantes da plataforma específica(por exempo máscaras de interrupção) que podem ser acessadas usando a notaço cpu.<constant name>. Os nomes de cada constante devem ser especificados ao invés de uma construção específica (_C(<constantname>). Por exemplo: `#define PLATFORM_CPU_CONSTANTS\ _C( INT_GPIOA ),\ _C( INT_GPIOB ),\ _C( INT_GPIOC ),\ _C( INT_GPIOD ),\ _C( INT_GPIOE )` Após a compilação, você poderá acessar essas constantes usando cpu.INT_GPIOx. Observe que a implementação desses recursos não precisa de memória RAM, logo você poderá definir quantas constantes desejar.

Os parâmetros da configuração estática restantes foram deixados para serem alterados pelos desenvolvedores e por este motivo, não estão relacionados aqui.
Outra coisa que você poderá querer configurar é o conteúdo do sistema de arquivo de sua ROM. Veja a documentação ROMFS para detalhes de como fazer isso.

Iniciando o "build system"

Agora, que você está com tudo em seu lugar, resta então executar o "build system" (scons) com os argumentos corretos. Este é um passo fácil, apesar da aparência intimidadora devido as múltiplas opções existentes no scons. São usadas para se ajustarem às suas necessidades específicas, mas a menos que suas necessidades sejam muito especiais, você não precisará modificá-las, logo não se preocupe com a aparente complexidade. Os exemplos no fim desta seção mostrarão como é fácil usar o "build system" na prática.

$ scons 
 [target=lua | lualong]
 [cpu=at91sam7x256 | at91sam7x512 | i386 | str912fw44 | lm3s8962 | 
 lm3s6965 | lm3s6918 | lpc2888 | str711fr2 | at32uc3a0512 | stm32f103ze
 [board=ek-lm3s8962 | ek-lm3s6965 | eagle-100 | str9-comstick | sam7-ex256 | 
 lpc-h2888 | mod711 | pc | atevk1100 | stm3210e-eval ]
 [cpumode=arm | thumb] 
 [allocator = newlib | multiple | simple]
 [toolchain = <toolchain name>]
 [optram = 0 | 1]
 [prog]

Seu hardware está especificado por dois parâmetros: cpu e placa. "cpu" representa o nome da cpu, e "placa" o nome de sua placa. Uma placa pode ser associada a mais de uma CPU. Esta característica permite ao "build system" ter bastante flexibilidade. Você pode usar estas duas opções juntas ou separadas, como mostrado a seguir:

cpu=name: gera para uma CPU específica. Um nome para a placa será gerado automaticamente pelo sistema.
board=name: gera para uma placa específica. Um nome para a CPU será inferido automaticamente pelo sistema.
cpu=name board=name: gera para uma placa e uma CPU. O script de geração não permitirá combinações invalidas de CPU/placa.

Veja no inicio do arquivo SConstruct (platform_list) como configurar os parâmetros placa/CPU, são auto-explicativos.
As outras opções são mostradas a seguir:

target=lua | lualong: especifica se você deseja gerar Lua como "regular" (com suporte a ponto flutuante) ou somente "inteiro longo" (lualong). O default é "lua". "lualong" roda mais rápido em hardware que não possua co-processador para ponto flutuante (o que é o caso de todos os atuais hardwares que rodam eLua) mas não permite o suporte para operações de ponto flutuante, somente opera com inteiros.
cpumode=arm | thumb: para CPUs ARM (não use Cortex) especifica o modo de compilação. O valor default é 'thumb' para as CPUs AT91SAM7X e 'arm' para as CPUs STR9 e LPC2888.
allocator = newlib | multiple | simple: escolha entre o valor default (newlib) que é uma versão mais antiga do alocador dlmalloc, o alocador mútiplo de espaços de memória (multiple) que é uma versão mais recente do dlmalloc que permite tratar múltiplos espaços de memória, e um alocador de memória muito simples (simple) que é lento e não trata muito bem fragmentação, mas requer muito pouco recurso (Flash/RAM). Você só deve usar o alocador 'multiple' nos casos em que prescise de a espaços múltiplos de memória. O valor default é 'newlib' para todas as CPUs exceto a 'lpc2888' e a 'at32uc3a0512', desde que a LPC-H2888 e a placa ATEVK1100 venham com memória externa SDRAM e dessa maneira se tornam o hardware ideal para o uso do 'multiple'. Você deve utilizar 'simple' somente em sistemas com muita restrição de recursos de hardware.
toolchain=<toolchain name>: especifica o nome do toolchain usado para gerar a imagem. Veja este link para mais detalhes.
optram=0 | 1: habilita ou desabilita o patch LTR, veja a documentação LTR pra mais detalhes. O valor default é 1, que habilita o patch LTR.
prog: por default, o comando 'scons' acima gerará somente o arquivo 'elf' (executável). Quando necessário, acrescente o parâmetro "prog" para gerar também um arquivo de programação da plataforma específica (por exemplo, usando o AT91SAM7X256, este parâmetro resulta na geração de um arquivo .bin que poderá ser programado nesta CPU).

O resultado será um arquivo chamado elua_[target]_[cpu].elf (se o parâmetro "prog" foi especificado, no caso de plataformas que precisam deste parâmetro para programação, um outro arquivo também é gerado com o mesmo nome, porém terminando com .bin/.hex).
Se você deseja um comando equivalente a um "make clean", execute o "scons" como mostrado acima, mas acrescente um "-c" ao final da linha de comando. "scons -c" é também recomendado após você reconfigurar sua imagem gerada, já que o scons parece omitir as mudanças feitas nestes arquivos em alguns momentos.

Alguns exemplos:

$ scons cpu=at91sam7x256 -c

Apaga os arquivos gerados anteriormente.

$ scons cpu=at91sam7x256

Gera eLua para uma CPU AT91SAM7X256. O nome da placa é detectado como sendo a sam7-ex256.

$ scons board=sam7-ex256

Gera eLua para uma placa SAM7-EX256. A CPU AT91SAM7X256 é detectada.

$ scons board=sam7-ex256 cpu=at91sam7x512

Gera eLua para a placa SAM7-EX256, porém define uma CPU específica. Isto é interessante quando você gostaria de saber como a placa especificada se comportará (em termos de recursos) com uma CPU diferente (no caso da placa SAM7-EX256 é possível mudar a CPU AT91SAM7X256 por uma AT91SAM7X512 a qual possui a mesma pinagem mas vem com mais memória Flash/RAM).

$ scons cpu=lpc2888 prog

Gera eLua para a CPU lpc2888. A placa é detectada como LPC-H2888. Aém disso, é gerado um arquivo bin necessário para a programação da CPU. O parâmetro allocator é detectado automaticamente como "multiple".

$ scons cpu=lm3s8962 toolchain=codesourcery prog

Gera a imagem para a CPU Cortex LM3S8962, mas usa o CodeSourcery toolchain ao invés do toolchain default (que é a toolchain "genérica" ARM GCC, normalmente a única gerada seguindo as instruções dos tutoriais deste site.

$$FOOTER$$