1 - About Luatcc

Luatcc is a Lua binding for libtcc, which is the core library of TCC, the Tiny C Compiler. Primary goal of this module is to be an illustration for the Gem Interpreted C Modules from the book Lua Programming Gems. As this module may be of interest independently from the book, I made it available here.

Luatcc features a module loader that allows to load C modules directly from sources. To activate the loader you just have to load the tcc.loader module, which will install itself in Lua 5.1 package system.

libtcc binding is not complete. Only the functions necessary to implement the C source module loader have been bound. Also it is very low level (it maps directly to libtcc C API). However I'm open to suggestions or requests to add more bindings or to implement a higher level interface in the future. Just ask :-)

Support

All support is done through the Lua mailing list.

Feel free to ask for further developments. I can't guarantee that I'll develop everything you ask, but as this module currently exists only for pedagogical purpose and is not actually used there is very little chance that I develop it anymore if you don't ask me to.

Credits

This module is written and maintained by Jérôme Vuarand. It is originally based on lua-tcc module by Javier Guerra and has been extended to support a bigger part of libtcc API and to work as a Lua module loader.

Luatcc is available under a MIT-style license.

2 - Download

Luatcc sources are available in its Mercurial repository:

hg clone http://hg.piratery.net/luatcc/

Tarballs of the latest code can be downloaded directly from there: as gz, bz2 or zip.

3 - Installation

Build instructions

To build Luatcc edit Makefile to configure the install directories and options, then run make in the top directory:

$ vi Makefile
$ make
$ make test
$ make install

TCC

To use Luatcc you need TCC. The recommended version is 0.9.25. Luatcc does work with 0.9.24 and 0.9.23, but you need to uncomment a line in the Makefile because there is no way to detect the 0.9.25 API change automatically. TCC is available at:

Testing the module

In the test subdirectory you will find some test programs to check that everything is working properly. They are run by the "make test" target, look at each testx.lua file to have an idea of what each test does.

4 - Manual

Here you can find a list of the functions present in the module and how to use them. Luatcc main module follows Lua 5.1 package system, see the Lua 5.1 manual for further explanations.

4.1 - Module functions

These functions are global to the module.

tcc.new ()

Returns a new TCC compiling context. This context can be used to compile C code and dynamically execute it.

     local context = tcc.new()

4.2 - Context methods

These functions are the method of the compiler context returned by tcc.new.

context:add_include_path (path)

Adds an include path to the context. #include directives in compiled sources will look for header files in paths provided by that function and some system-wide paths defined when compiling TCC.

context:compile (source [, chunkname])

Compiles a C source file inside the context. Optionnal chunkname argument can be a string that will be displayed in error messages (typically it will be the source file from which source is extracted, if any).

     context:compile[[
          #include <lua.h>
          int hello(lua_State* L)
          {
               lua_pushstring(L, "Hello World!");
               return 1;
          }
     ]]

context:add_library_path (path)

Adds a library path to the context. context:add_library will look for libraries in the paths provided by that function and in some system-wide paths defined when compiling TCC.

context:add_library (libraryname)

Adds a library to the context. This can be used to load static libraries or import libraries for dynamically loaded libraries. libraryname is the short name of the library (for example short name of liblua51.a is "lua51").

context:relocate ()

Performs the actual linking of the compiled sources and libraries present in the context. This function returns nothing, to access externally accessible symbols from the linked code use context:get_symbol.

     context:relocate()

context:get_symbol (symbolname)

This function looks for a symbol in the compiled code present in the context. The symbol is cast to a lua_CFunction, and returned as a function. You have to make sure that the symbol matches lua_CFunction, otherwise calling the returned function has unexpected behaviour (which is likely to be a crash).

     local hello = context:get_symbol("hello")
     print(hello()) -- Should output "Hello World!"

4.3 - C source module loader

Luatcc features a new module loader. That loader will load C modules directly from source files. To activate the loader, you juste have to load the tcc.loader submodule:

     require("tcc.loader")
Loading the tcc.loader submodule automatically installs the loader in Lua package system. Any further call to require will use the loader.

The C source module loader looks for C source files according to the path in package.tccpath, which default value is "./?.c". Just like for package.path and package.cpath, the interrogation marks will be replaced with the module name, in which all dots have been replaced with a "directory separator" (such as "/" in Unix).

Error reporting is done the same way than with the predefined module loaders. Also the C source module loader has the lowest priority, it is invoked last if no other loader can locate a module. To change loader priority you have to manually alter the package.loaders table.