elua/doc/pt/faq.html

$$HEADER$$
<h3>Perguntas mais Frequentes de eLua</h3><p>Bem-vindo à FAQ oficial de <b>eLua</b><br /> 
Assumimos aqui que você já conhece o básico de <b>eLua</b> e que esta lista de perguntas (e respectivas respostas) poderão ser úteis.</p>

<ul>
  <li><a href="#learnlua">Como posso aprender Lua? É difícil?</a></li>
  <li><a href="#helpelua">Como posso ajudar o Projeto eLua?</a></li>
  <li><a href="#comercial">Posso usar eLua no meu projeto comercial de código fechado?</a></li>
  <li><a href="#fast">eLua é rápida o bastante para minha aplicação?</a></li>
  <li><a href="#minimum">Quais são os pré-requisitos mínimos para eLua?</a></li>
  <li><a href="#portability">Tenho usado os módulos da plataforma Lua (uart, spi, pwm, tmr...), posso realmente usar o mesmo código em todas as minhas diferentes plataformas?</a></li>
  <li><a href="#luaversions">Qual a diferença entre Lua Ponto-Flutuante e Lua Inteiro?</a></li>
  <li><a href="#windows">Todos os seus tutoriais fornecem instruções sobre como compilar eLua sob o Linux, mas parece que você usa muitas ferramentas do Windows. Como pode isso?</a></li>
  <li><a href="#cygwin">Voces irão fornecer intruções sobre como montar toolchains sob Cygwin no Windows?</a></li>
  <li><a href="#bytecode">Sei que um programa Lua pode ser compilado para bytecode, então fiz a compilação de um dos exemplos eLua com o luac e tentei executá-lo em minha placa eLua, mas não funcionou. Isso é um bug no eLua?</a></li>
  <li><a href="#outofmemory">Quando tento executar meus programas em Lua, recebo a mensagem de erro "falta de memória", o que devo fazer?</a></li>
  <li><a href="#rotables">Instalei o patch LTR, mas agora todas as tabelas dos meus módulos (math, io, string, spi e assim por diante) estão como somente para leitura. Terei que desinstalar o patch LTR, se quiser ter permissão de gravação nesses módulos?</a></li>
</ul>

<hr />

<a name="learnlua" /><h2>Como posso aprender Lua? É difícil?</h2>
<p>Lua é uma linguagem minimalista (e mesmo assim muito poderosa) e muito fácil de se aprender. Uma vêz
entendidos os conceitos básicos, você começará a programar em Lua imediatamente. A <a href="http://www.lua.org/">página de Lua na internet</a> é sua principal fonte de informação. 

Na <a href="http://www.lua.org/docs.html">página de documentação</a> do site, você vai encontrar o manual de referência e a primeira edição do excelente livro versão "Programando em Lua". Recomendamos que você adquira a segunda edição deste livro, já que você irá encontrar tudo que você realmente precisa aprender de Lua. Outra fonte muito interessante é
a <a href="http://lua-users.org/wiki/">wiki Lua</a>. Se você precisar de mais ajuda, consulte a <a href="http://www.lua.org/community.html">página da comunidade</a>. Lua tem uma comunidade muito amigável e bastante ativa.

<a name="helpelua" /><h2>Como posso ajudar eLua?</h2>
<p><b>eLua</b> tem muitas metas ambiciosas, por isso seria ótimo ter mais pessoas trabalhando
conosco. Dê uma olhada na <a href="status.html#roadmap">página roadmap</a>
e, se houver interesse em colaborar, não hesite em <a href="overview.html#contacts">contactar-nos</a>. Além disso, se você quiser fazer uma doação para o projeto (dinheiro, ou talvez uma placa para desenvolvimento) esteja certo que não iremos
recusar :) Seus reports de bugs encontrados em testes de <b>eLua</b> em suas
placas e suas idéias sobre recursos legais são tão valiosos quanto. Se assim for, não hesite em <a href="overview.html#contacts">nos contactar</a>.

<a name="comercial" /><h2>Posso usar eLua no meu projeto comercial de código fechado?</h2>
<p>A partir da versão 0.6, <b>eLua</b> é distribuída sob a licença MIT e
isto permite que seja usada em projetos comerciais e de código proprietário. 
Antes disso, foi distribuída sob a GPL, o que restringia seu a aplicações open source. 
Fique atento entretando, porque <b>eLua</b> atualmente contém algumas (poucas) bibliotecas de terceiros, cada uma com seus próprios termos de licença que podem ser mais restritos que do MIT. Veja a <a href="overview.html#license">licença eLua</a> para mais detalhes.</p> 

<a name="fast" /><h2>eLua é rápida o bastante para minha aplicação?</h2>
<p>Isso depende muito de suas expectativas. Se você espera que o seu código
em Lua rode tão rápido quanto o seu código C compilado isso não irá acontecer, simplesmente porque C é uma linguagem compilada enquanto a Lua é uma linguagem interpretada. Dito isso, você vai ficar feliz em saber que a Lua é uma das linguagens interpretadas mais rápidas que existem por aí. Se você realmente precisa de muita velocidade e de Lua, você pode (muito
facilmente em eLua) escrever as seções críticas em seções de código C e exportá-los como um módulo Lua. Desta forma, você terá o melhor de dois mundos.<br />


   Atualmente não temos nenhuma referência oficial sobre a velocidade de Lua em dispositivos embarcados mas você
   pode dar uma olhada no exemplo TV-B-Gone na página <a href="examples.html">examplos</a>. TV-B-Gone é uma aplicação de controle remoto escrita em <b>eLua</b>. 
  Se você estiver familiarizado com os protocolos de controle remoto, você vai saber que esse tipo de aplicação é executada em "tempo real" e atrasos na ordem de milisegundos ou até menos
   podem fazer o seu software de controle remoto falhar. No entanto, este exemplo é executado sem problemas em uma CPU
   Cortex-M3 50MHz (em modo Thumb2). Este exemplo deve fornecer-lhe uma visão bastante intuitiva sobre a velocidade da eLua.

<a name="minimum" /><h2>What are the minimum requirements for eLua?</h2>
<p>It's hard to give a precise answer to this. As a general rule for
a 32-bit CPU, we recommend at least 256k of Flash (program memory) and
at least 64k of RAM. However, this isn't a strict requirement. A
stripped down, integer-only version of eLua can definetely fit in 128k
of Flash, and depending on your type of application, 32k of RAM might
prove just fine. It largely depends on your needs.</p>

<a name="portability" /><h2>Since I'm using the Lua platform modules (uart, spi, pwm, tmr...), can I trust my peripheral code to run the same on all my
  platforms?</h2>
<p>Unfortunately, no. While <b>eLua</b> makes it possible to have a common code on different platforms using the <a href="arch_platform.html">platform interface</a>,
  it can't possibly provide the same functionality on all platforms, since all MCUs are not created equal. It is very recommended 
  (and many times imperative) to have an understanding of the peripherals on your particular MPU before you start writing your code. 
  This, of course, is not particular to <b>eLua</b>, but it's especially important since the platform interface might give the impression that it 
  offers an uniform functionality over all platforms, when in fact the only thing in common is often just the interface itself (that is, the methods and 
  variables you can access in a given module). <b>eLua</b> tries to help here by giving you an error when you try to access a physical resource that is 
  not available (for example a timer, a PWM channel, or a PIO pin/port), but it doesn't try to cover all the possible platform-related issues, since this 
  would increase the code size and complexity too much. These are some caveats that come to mind (note that these are only a few examples, the complete 
  list is much longer):</p>
<ul>
  <li><b>timers</b>: from all the platforms on which <b>eLua</b> runs, only the Luminary Cortex CPUs has rock solid 32-bit timers. You can do pretty much 
  everything you need with them. All the other platforms have 16-bit timers, which imposes some limits on the range of delays you can achieve with them. 
  Make sure to use tmr.mindelay(id) and tmr.maxdelay(id) to check the actual resolution of your timers, and adapt your code accordingly. To 'compensate' 
  for this, it's not possible to change the base timer frequency on the Cortex CPUs, but it is possible on most other platforms :) So be sure to also check 
  the result of tmr.setclock(id)</li>
  <li>also, when using timers, remember that if you're using XMODEM and/or the "term" module, one of them (generall TMR0) is used by both of them. So, if 
  you change the TMR0 base clock in your code, be sure to restore the original setting before returning to the <b>eLua</b> shell.</li>
  <li><b>PWM</b>: the Cortex CPUs have 6 PWM channels, but channels 0/1, 2/3 and 4/5 respectively share the same base clock setting. So, when you're
  changing the base clock for channel 1, you're also changing the base clock for channel 0; if channel 0 was already running, you won't like
  what will happen next. This time no eLua function can save you, you simply need you know your CPU architecture.</li>
  <li><b>GPIO</b>: only some platform have internal pullups for the GPIO pins (others might also have pulldowns). However, in this case you're safe, as 
  <b>eLua</b> will signal an error if you try to execute a pullup operatin on a platform that does not support it.</li>
</ul>
<p>The lesson here is clear: understand your platform first!</p>

<a name="luaversions" /><h2>What's the deal with floating-point Lua and integer only Lua?</h2>
<p>Lua is build around a number type. Every number in Lua will have this type. By default, this number type is a double. This means that even if your 
  program only does integer operations, they will still be treated as doubles. On embedded platforms this is a problem, since the floating point 
  operations are generally emulated in software, thus they are very slow. This is why <b>eLua</b> gives you "integer only Lua": a Lua with the default 
  number type changed to long. The advantages are increased speed and smaller code size (since we can force Newlib to "cut" the floating point code from 
  printf/scanf and friends, which has quite a strong impact on the code size) and increased speed. The downside is that you'll loose the ability to do 
  any floating point operations (although a separate module that will partially overcome this limitation will be provided in the future).</p>

<a name="windows" /><h2>All your tutorials give instructions on how to compile eLua under Linux, yet you seem to use a lot of Windows tools. How come?</h2>
<p>It's true that we do all the <b>eLua</b> development under Linux, since we find Linux an environment much more suited for development. At the same
  time it's true that most of the tools that come with my development boards run under Windows. So we choose to use the best of both world: Bogdan runs 
  Linux under a <a href="http://www.virtualbox.org">VirtualBox</a> emulator, and does verything else under Windows. Dado does everything on 
  Linux and runs Windows under <a href="http://www.vmware.com">VMWare</a>. Both options are nice if you master your environment. To make 
  everything even more flexible, Bogdan keeps his VirtualBox Ubuntu image on an external WD passport disk that he can carry with him wherever he goes, 
  so he can work on eLua whenever he has a bit of spare time :)</p>

<a name="cygwin" /><h2>Will you ever post instructions about how to compile toolchains under Cygwin in Windows?</h2>
<p>Bogdan: If I ever have way too much spare time on my hands, yes. Otherwise, no. There are many reasons for this. As I already mentioned, I favour Linux 
  over Windows when it comes to developing applications. Also, I noticed that the GNU based toolchains are noticeable slower on Cygwin than on Linux, so 
  experimenting with them can prove frustrating. Also, compiling under Linux and Cygwin should be quite similar,so try starting from my Linux based 
  tutorials, they might work as well on Cygwin.</p>

<a name="bytecode" /><h2>I know that Lua can be compiled to bytecode, so I compiled one of the eLua examples with luac and tried to run it on my eLua
  board, but it didn't work. Is this a bug in eLua?</h2>
<p>This is not a bug in <b>eLua</b>, it's a bit more subtle than that. See <a href="using.html#cross">the cross-compile section</a> for a full discussion
  about this problem and its fix.</p>

<a name="outofmemory" /><h2>I get "out of memory" errors when I run my Lua programs, what should I do?</h2>
<p>There are a number of things you can try to overcome this:</p>
<ul>
  <li><b>enable the LTR patch</b>: you can get very significant improvements if you enable the LTR patch in your <b>eLua</b> image. See 
  <a href="arch_ltr.html">here</a> for more details about LTR, and <a href="building.html">here</a> for instructions about enabling LTR.</li>
  <li><b>precompile your source to bytecode</b>: if you use bytecode instead of source code Lua won't need to compile your source, so you save some RAM.</li>
  <li><b>try to avoid using too many strings</b>: strings are immutable in Lua. That means that a statement like <i>s = s .. "\n"</i> (where s is a string) 
  will create a new string each time it's called. If this happens a lot (for example in a loop), your memory will quickly run out because of all the
  strings. If you really need to do frequent string operations, put them in a table and then use 
  <a href="http://www.lua.org/manual/5.1/manual.html#5.5">table.concat</a> to make a string from your table.</li>
  <li><b>control Lua's garbage collection manually</b>: if you're still running out of memory, try calling <i>collectgarbage('collect')</i> from your code, 
  which will force a garbage collection and thus might free some memory.</li>
</ul>

<a name="rotables" /><h2>I enabled the LTR patch, but now all my module tables (math, io, string, spi and so on) are read only. Do I have to
  disable LTR if I want write access to these modules?</h2>
<p>You don't really have to disable LTR to get write access to your rotables, you can use some simple Lua "tricks" instead. Let's suppose that you need
  write access to the <b>math</b> module. With LTR enabled, <b>math</b> is a rotable, so you can't change its keys/values. But you can use metatables
  to overcome this limitation:</p>
<pre><code>local oldmath = math
math = { __index = oldmath }
setmetatable( math, math )
</code></pre>
<p>This way you can use <i>math</i> in "write mode" now (since it is a regular table), but you can still access the keys from the original <i>math</i>
  rotable. Of course, if you need write access to <b>all</b> your modules (or to most of them) it makes more sense to disable LTR instead, but from our 
  observations this doesn't happen in practice.</p>
$$FOOTER$$