mirror of
https://github.com/elua/elua.git
synced 2025-01-25 01:02:54 +08:00
178 lines
16 KiB
HTML
178 lines
16 KiB
HTML
$$HEADER$$
|
|
<h3>eLua Frequently Asked Questions</h3><p>Welcome to the official <b>eLua</b>
|
|
FAQ!<br />
|
|
It is assumed that you already know <a href="overview.html#whatis">what <b>eLua</b>
|
|
is</a>, so here's a list of questions (and their answers) that you might find useful.</p>
|
|
|
|
<ul>
|
|
<li><a href="#minimum">What are the minimum requirements for eLua?</a></li>
|
|
<li><a href="#learnlua">How can I learn Lua? Is it hard?</a></li>
|
|
<li><a href="#helpelua">How can I help eLua?</a></li>
|
|
<li><a href="#comercial">Can I use eLua in my comercial, closed source project?</a></li>
|
|
<li><a href="#fast">Is eLua fast enough?</a></li>
|
|
<li><a href="#portability">Since I'm using the <b>eLua</b> generic platform modules (uart, spi, pwm, tmr...), can I trust my peripheral code to run the same on all my platforms?</a></li>
|
|
<li><a href="#luaversions">What's the deal with floating-point Lua and
|
|
integer-only Lua?</a></li>
|
|
<li><a href="#wincomp">Is it possible to compile eLua under Windows?</a></li>
|
|
<li><a href="#windows">All your tutorials give instructions on how to compile eLua under Linux, yet you seem to use a lot of Windows tools. How come?</a></li>
|
|
<li><a href="#cygwin">Will you ever post instructions about how to compile toolchains under Cygwin in Windows?</a></li>
|
|
<li><a href="#bytecode">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?</a></li>
|
|
<li><a href="#outofmemory">I get "out of memory" errors when I run my Lua programs, what should I do?</a></li>
|
|
<li><a href="#rotables">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?</a></li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<a name="minimum" /><h2>What are the minimum requirements for eLua?</h2>
|
|
<p>It's hard to give a precise answer to this, because this is not only
|
|
dependable on the footprint of <b>eLua</b> or it's resource requirements but
|
|
on the final user applications as well. As a general rule, for
|
|
a 32-bit CPU, we recommend at least 256k of Flash and
|
|
at least 64k of RAM. However, this isn't a strict requirement. A
|
|
stripped down, integer-only version of eLua can definitely fit in 128k
|
|
of Flash and depending on your type of application, 32k of RAM might
|
|
prove just fine. We have built <b>eLua</b> for targets with less than 10K
|
|
RAM but you can't do much than blinking an LED with them. It really largely depends on your needs.</p>
|
|
|
|
<a name="learnlua" /><h2>How can I learn Lua? Is it hard?</h2>
|
|
<p>Lua is a minimalistic language (yet incredibly powerful!) which is quite easy to learn.
|
|
Once you understand the basic concepts you'll find yourself writing
|
|
Lua programs in notime. The main resource is the <a href="http://www.lua.org/">Lua homepage</a>. In the
|
|
<a href="http://www.lua.org/docs.html">documentation page</a> you'll find the reference manual and the first version of the excellent
|
|
"Programming in Lua" book. We recommend purchasing the second version of this book, since it's likely that this is all you'll ever need to learn
|
|
Lua. Another very good resource is the <a href="http://lua-users.org/wiki/">Lua wiki</a>. If you need more help, check the
|
|
<a href="http://www.lua.org/community.html">community page</a>. Lua has a very friendly and active community.
|
|
Most of all, Lua is FUN to learn and use :)</p>
|
|
|
|
<a name="helpelua" /><h2>How can I help eLua?</h2>
|
|
<p><b>eLua</b> has many ambitious goals, so it would be great to have more people working on it. Take a look at the
|
|
<a href="status.html#roadmap">roadmap page</a> and if you see something there that you'd like to work on, don't hesitate to
|
|
<a href="overview.html#contacts">contact us</a>. Also, if you'd like to make a donation to the project (money, or maybe a development board)
|
|
rest assured that wwe won't say no :) It also helps a lot if you test <b>eLua</b> on your own board and you find a bug or an
|
|
incomplete feature. Or if you just thought about a cool feature that you'd like to see in <b>eLua</b>.
|
|
If so, feel free to <a href="overview.html#contacts">contact us</a>.</p>
|
|
|
|
<a name="comercial" /><h2>Can I use eLua in my comercial, closed source project?</h2>
|
|
<p>Starting with version 0.6, <b>eLua</b> is distributed under a MIT license, so you can use it in your closed source projects. Prior to
|
|
this, it was
|
|
distributed under GPL, which restricted its usage to open source applications. Be careful though,
|
|
because <b>eLua</b> includes some
|
|
(few) 3rd party libraries,
|
|
each with its own licensing terms that might be more restrictive than MIT. See <a href="overview.html#license">the eLua license</a> for details.</p>
|
|
|
|
<a name="fast" /><h2>Is eLua fast enough?</h2>
|
|
<p>This pretty much depends on what you expect. If you expect your Lua code to run as fast as your compiled C code, this won't happen, simply because C
|
|
is a compiled language, while Lua is an interpreted language. That said, you'll be happy to know that Lua is one of the fastest interpreted languages
|
|
out there and also compiles it's programs to bytecodes for it's own
|
|
virtual machine to execute. If you really need both high speed and Lua, you can (very
|
|
easily in <b>eLua</b>) write your speed critical code sections in C and export them as a Lua module.
|
|
This way you get the best of both worlds.<br />
|
|
We don't have any official benchmarks about Lua speed on embedded devices but you might want to check the TV-B-Gone example on the <a href="examples.html">examples page</a>. TV-B-Gone is a "software remote control" application coded directly in <b>eLua</b>.
|
|
If you're familiar with the remote control protocols, you'll know that this kind of application is quite "real time" and delays in the order of
|
|
milliseconds or even less can make your software remote control fail. Yet this sample runs without problems on a 50MHz
|
|
Cortex-M3 in Thumb2 mode CPU. This should
|
|
give you a fairly intuitive view on the speed of <b>eLua</b>. Of course,
|
|
the project benefits from the incredible speed and performance of Lua.</p>
|
|
|
|
<a name="portability" /><h2>Since I'm using the eLua generic 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> brings an unprecedent level of
|
|
source code portability to the embedded world and 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>: some CPUs, like the Luminary Cortex CPUs, have rock solid 32-bit timers. You can do pretty much
|
|
everything you need with them. Most platforms have only 16-bit timers though, which imposes some limits on the range of delays you can achieve with them.
|
|
Make sure to use <a
|
|
href="en_refman_gen_tmr.html#tmr.getmindelay">tmr.getmindelay(id)</a> and <a
|
|
href="en_refman_gen_tmr.html#tmr.getmindelay">tmr.getmaxdelay(id)</a> 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 <a
|
|
href="en_refman_gen_tmr.html#tmr.setclock">tmr.setclock(id)</a>.
|
|
Important: when using timers, remember that if you're using XMODEM and/or the "term" module, one of them (generall TMR0) is
|
|
also 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-M3 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 <b>eLua</b> function can save you. You simply need you know your CPU architecture.</li>
|
|
<li><b>GPIO</b>: only some platforms 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 pull-up/dn operation 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 built 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
|
|
floating-point doubles. On embedded platforms this can be a problem, since the floating point
|
|
operations are generally emulated in software and this can be slow. This is why <b>eLua</b> gives you
|
|
the choice of "integer only Lua": a Lua with the default
|
|
number type changed to long integer. 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 ="wincomp /"><h2>Is it possible to compile eLua under Windows?</h2>
|
|
<p>Starting with version 0.7, compiling <b>eLua</b> under Windows is officialy supported, check <a href="building_win.html">here</a> for details.</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 everything 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 the right way to do it. Starting with v0.7, it is also possible to automatically build your ROM
|
|
file system with only compiled (bytecode) code. See <a
|
|
href="en_arch_romfs.html#mode">here</a> for details.</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.
|
|
The LTR patch is enabled by default for some target platforms.</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.
|
|
Starting with v0.7, it is also possible to automatically build your ROM
|
|
file system with only compiled (bytecode) code. See <a
|
|
href="en_arch_romfs.html#mode">here</a> for details.</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>
|
|
<li><b>use the emergency garbage collector (EGC)</b>: starting with version 0.7, <b>eLua</b> integrates Robert Jakabosky's excellent Emergency Garbage Collector
|
|
(EGC) patch. It can help a lot with low memory problems. See <a href="elua_egc.html">here</a> for details on how to use the EGC patch in <b>eLua</b>.</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$$
|
|
|