Module tcc

Provides semi-high-level bindings for libtcc, the library interface of the Tiny C Compiler.

Source on GitHub

Info:

  • License: LGPL

Functions

load ([lib="[lib]tcc"[, home_path=$CONFIG_TCCDIR]]) Load the libtcc dynamic library.
new ([add_paths=true]) Create a new TCC compilation context (State).
args (...) Convert all passed strings to argc and argv arguments that can be passed to State:run.

Tables

OUTPUT Output types used by State:set_output_type
RELOCATE Relocation constants used by State:relocate

Fields

TCC_VERSION Compatible version of TCC (currently 0.9.26)
home_path Path to the TCC home, containing the lib and include directories.
clib C library namespace of the dynamically loaded libtcc.

Class State

State:delete () Free the compilation context and associated resources.
State:set_home_path (path) Set the home path of TCC used by this context.
State:set_error_func (error_func) Set the error/warning display callback.
State:set_options (args) Set one or multiple command line arguments for the compiler.

Preprocessor

State:add_include_path (path) Add an include path.
State:add_sysinclude_path (path) Add a system include path.
State:define_symbol (name[, value]) Define a preprocessor symbol with an optional value.
State:undefine_symbol (name) Undefine a preprocessor symbol.

Compiling

State:add_file (file_path) Add a file.
State:compile_string (source) Compile a string containing a C source.

Linking commands

State:set_output_type (output_type) Set the output type.
State:add_library_path (path) Add a library path.
State:add_library (name) Add a library to be linked against.
State:add_symbol (name, value) Add a pointer symbol to the compiled program.
State:output_file (file_path) Output a compiled executable, library or object file to a path.
State:run ([argc[, argv]]) Link and run the main() function and return its return code.
State:relocate (ptr) Do all relocations needed for using State:get_symbol.
State:get_symbol (name) Return the pointer to a symbol or NULL if it was not found.


Functions

load ([lib="[lib]tcc"[, home_path=$CONFIG_TCCDIR]])
Load the libtcc dynamic library.

If the environment variable CONFIG_TCCDIR is set, home_path will be set to its value. It can be overriden by passing the home_path parameter.

If home_path is set, it will be searched for the library before the default paths.

Parameters:

  • lib string name of the libtcc library, defaults to libtcc on Windows and tcc on other platforms due to naming issues (default "[lib]tcc")
  • home_path string path to the TCC home (default $CONFIG_TCCDIR)

Returns:

    table the tcc module itself (to allow for chaining)

Usage:

    local tcc = require("tcc").load("tcc", "/lib/tcc")
new ([add_paths=true])
Create a new TCC compilation context (State).

If add_paths is not false and home_path is set, call State:set_home_path on it, State:add_sysinclude_path on home_path/include and State:add_library_path on home_path/lib.

Parameters:

  • add_paths bool whether to set the home path on the new State (default true)

Returns:

    State the new compilation context
args (...)
Convert all passed strings to argc and argv arguments that can be passed to State:run.

Parameters:

  • ... string any number of string arguments

Returns:

  1. cdata(int) number of passed arguments
  2. cdata(char**) passed arguments as an array of C strings

Usage:

    state:run(tcc.args("foo", "bar"))

Tables

OUTPUT
Output types used by State:set_output_type

Fields:

  • MEMORY output will be run in memory (default)
  • EXE executable file
  • DLL dynamic library
  • OBJ object file
  • PREPROCESS only preprocess (used internally)
RELOCATE
Relocation constants used by State:relocate

Fields:

  • SIZE return required memory size for relocation
  • AUTO allocate and manage memory internally

Fields

TCC_VERSION
Compatible version of TCC (currently 0.9.26)
home_path
Path to the TCC home, containing the lib and include directories. Usually set automatically by tcc.load.
clib
C library namespace of the dynamically loaded libtcc. Set by tcc.load.

Class State

A TCC compilation context.
State:delete ()
Free the compilation context and associated resources. Usually called automatically when the State is garbage-collected.
State:set_home_path (path)
Set the home path of TCC used by this context. Usually called automatically by new.

Originally named set_lib_path but renamed for consistency and clarity.

Parameters:

State:set_error_func (error_func)
Set the error/warning display callback.

The passed output strings will be formatted like <file or "tcc">:[<line>:] <severity> <message>.

Parameters:

  • error_func function(string) function to be called
State:set_options (args)
Set one or multiple command line arguments for the compiler.

Parameters:

Returns:

    bool success

Preprocessor

State:add_include_path (path)
Add an include path.

Parameters:

  • path string include path to be added

Returns:

    bool success
State:add_sysinclude_path (path)
Add a system include path. Usually called automatically by new.

Parameters:

  • path string system include path to be added

Returns:

    bool success
State:define_symbol (name[, value])
Define a preprocessor symbol with an optional value.

Parameters:

  • name string name of the symbol
  • value string optional value of the symbol (optional)
State:undefine_symbol (name)
Undefine a preprocessor symbol.

Parameters:

  • name string name of the symbol

Compiling

State:add_file (file_path)

Add a file. This includes:

  • C files to be compiled
  • DLLs, object files and libraries to be linked against
  • ld scripts

Parameters:

  • file_path string path to the file to be added

Returns:

    bool success
State:compile_string (source)
Compile a string containing a C source.

Parameters:

  • source string source code to be compiled

Returns:

    bool success

Linking commands

State:set_output_type (output_type)
Set the output type.

Must be called before any compilation.

Parameters:

Returns:

    bool success
State:add_library_path (path)
Add a library path. Equivalent to the -Lpath option.

Parameters:

  • path string library path to be added

Returns:

    bool success
State:add_library (name)
Add a library to be linked against. Equivalent to the -lname option.

Parameters:

  • name string name of the library to be linked against

Returns:

    bool success
State:add_symbol (name, value)
Add a pointer symbol to the compiled program.

Parameters:

  • name string name of the symbol
  • value cdata(void*) pointer of the symbol

Returns:

    bool success

See also:

State:output_file (file_path)
Output a compiled executable, library or object file to a path. Do not call State:relocate before.

Parameters:

  • file_path string output file path

Returns:

    bool success
State:run ([argc[, argv]])
Link and run the main() function and return its return code. Do not call State:relocate before.

Parameters:

  • argc cdata(int) number of passed arguments (optional)
  • argv cdata(char**) arguments as an array of C-strings (optional)

Returns:

    cdata(int) return code

See also:

Usage:

    local argv = ffi.new("char*[2]")
argv[0] = "foo"
argv[1] = "bar"
state:run(2, argv)
State:relocate (ptr)
Do all relocations needed for using State:get_symbol. This can be done either within internally managed memory (by passing RELOCATE.AUTO) or within an user-managed memory chunk that is at least of the size that is returned by passing RELOCATE.SIZE.

Parameters:

  • ptr cdata(void*) pointer to a memory chunk or one of the members of RELOCATE

Returns:

    bool success

Or

    number required memory size if RELOCATE.SIZE was passed

Usage:

    local size = state:relocate(tcc.RELOCATE.SIZE)
local mem = ffi.new("char[?]", size)
state:relocate(mem)
State:get_symbol (name)
Return the pointer to a symbol or NULL if it was not found.

Parameters:

  • name string name of the symbol

Returns:

    cdata(void*) pointer to the symbol

See also:

generated by LDoc 1.4.3 Last updated 2016-12-31 16:17:51