[Tinycc-devel] draft of libtcc.3 manual page

[Marc Vertes]

A modest contribution to this very impressive project! Please consider 
it as a preliminary draft.  Bring your comments, fixes and suggestions.

Thanks
--
Marc Vertes

.\" Text automatically generated by txt2man-1.4.6
.TH libtcc 3 "December 17, 2002" "" ""
.SH NAME
\fBlibtcc \fP- backend to tcc - tiny C compiler
\fB
.SH SYNOPSIS
.nf
.fam C
#include <libtcc.h>
.PP
#define \fITCC_OUTPUT_MEMORY\fP 0
#define \fITCC_OUTPUT_EXE\fP 1
#define \fITCC_OUTPUT_DLL\fP 2
#define \fITCC_OUTPUT_OBJ\fP 3
.PP
typedef \fITCCState\fP struct \fITCCState\fP;
.PP
/* Init functions */
\fITCCState\fP *\fBtcc_new\fP(void);
void \fBtcc_delete\fP(\fITCCState\fP *\fIs\fP);
void \fBtcc_enable_debug\fP(\fITCCState\fP *\fIs\fP);
void \fBtcc_set_error_func\fP(\fITCCState\fP *\fIs\fP, void 
*\fIerror_opaque\fP, 
void (*\fIerror_func\fP)(void *\fIopaque\fP, const char *\fImsg\fP));
int \fBtcc_set_output_type\fP(\fITCCState\fP *\fIs\fP, int \fIoutput_type\fP);
.PP
/* Preprocessor functions */
int \fBtcc_add_include_path\fP(\fITCCState\fP *\fIs\fP, const char 
*\fIpathname\fP);
int \fBtcc_add_sysinclude_path\fP(\fITCCState\fP *\fIs\fP, const char 
*\fIpathname\fP);
void \fBtcc_define_symbol\fP(\fITCCState\fP *\fIs\fP, const char *\fIsym\fP, 
const char *\fIval\fP);
void \fBtcc_undefine_symbol\fP(\fITCCState\fP *\fIs\fP, const char *\fIsym\fP);
.PP
/* Compiler functions */
int \fBtcc_add_file\fP(\fITCCState\fP *\fIs\fP, const char *\fIfilename\fP);
int \fBtcc_compile_string\fP(\fITCCState\fP *\fIs\fP, const char *\fIbuf\fP);
.PP
/* Linker functions */
int \fBtcc_add_library_path\fP(\fITCCState\fP *\fIs\fP, const char 
*\fIpathname\fP);
int \fBtcc_add_symbol\fP(\fITCCState\fP *\fIs\fP, const char *\fIname\fP, 
unsigned long \fIval\fP);
int \fBtcc_output_file\fP(\fITCCState\fP *\fIs\fP, const char *\fIfilename\fP);
int \fBtcc_run\fP(\fITCCState\fP *\fIs\fP, int \fIargc\fP, char **\fIargv\fP);
int \fBtcc_relocate\fP(\fITCCState\fP *\fIs\fP);
void *\fBtcc_get_symbol\fP(\fITCCState\fP *\fIs\fP, const char *\fIname\fP);
.fam T
.fi
.SH DESCRIPTION

The libtcc library allows to use TCC as a backend for dynamic code
generation. It is able to perform all the steps to produce and run on
the fly a binary executable from C source code: preprocessing, compiling,
linking and run.
.SS INIT FUNCTIONS

The function \fBtcc_new\fP() returns a \fITCCState\fP structure (TCC
compilation context), dynamically allocated, or NULL in case of error. 
This function must be called prior to all others.
.PP
The function \fBtcc_delete\fP() releases a compilation context \fIs\fP, 
previously
created by \fBtcc_new\fP().
.PP
The function \fBtcc_enable_debug\fP() adds debug information in the generated 
code of compilation context \fIs\fP. It is equivalent to the use of \fB-g\fP 
option in \fBcc\fP(1).
.PP
The function \fBtcc_set_error_func\fP() sets \fIerror_func\fP as the 
error/warning
display callback for the compilation context \fIs\fP.
.PP
The function \fBtcc_set_output_type\fP() sets the output type of generated
code for the compilation context \fIs\fP. It must be called before any
compilation. \fIoutput_type\fP can be set to one of the following:
.IP \(bu 3
\fITCC_OUTPUT_MEMORY\fP: output will be ran in memory (no output file) 
(default).
.IP \(bu 3
\fITCC_OUTPUT_EXE\fP: output is an executable binary file.
.IP \(bu 3
\fITCC_OUTPUT_DLL\fP: output is a dynamic shared library file.
.IP \(bu 3
\fITCC_OUTPUT_OBJ\fP: output is a an object file.
.SS PREPROCESSOR FUNCTIONS

The functions \fBtcc_add_include_path\fP() and \fBtcc_add_sysinclude_path\fP() 
append
\fIpathname\fP to the list of directories searched for include files, for the
compilation context \fIs\fP. They are equivalent to \fB-I\fP option of 
\fBcpp\fP(1).
.PP
The function \fBtcc_define_symbol\fP() defines preprocessor macro \fIsym\fP to 
the value \fIval\fP
for the compilation context \fIs\fP. It is equivalent to \fB-D\fP option of 
\fBcpp\fP(1).
.PP
The function \fBtcc_undefine_symbol\fP() undefines preprocessor macro 
\fIsym\fP, for the
application context \fIs\fP. It is equivalent to \fB-U\fP option of 
\fBcpp\fP(1).
.SS COMPILE FUNCTIONS

The function \fBtcc_add_file\fP() adds \fIfilename\fP in the generated
object. \fIfilename\fP can be either a C file, a dynamic shared library,
an object file, a static library or an ld script.
.PP
The function \fBtcc_compile_string\fP() compiles the \fIbuf\fP string 
containing C
source, into the compilation context \fIs\fP. Returns non-zero if error.
.SS LINK FUNCTIONS

The function \fBtcc_add_library_path\fP() is equivalent to \fB-Lpathname\fP 
option in \fBcc\fP(1)
command line.
.PP
the function \fBtcc_add_library\fP() is equivalent to \fB-l\fP \fBcc\fP(1) 
option.
.PP
The function \fBtcc_add_symbol\fP() adds a symbol to the compiled program
.PP
The function \fBtcc_output_file\fP() outputs an executable, library or object
file into \fIfilename\fP. Do not call \fBtcc_relocate\fP() before.
.PP
The function \fBtcc_run\fP() links and runs \fBmain\fP() function and returns 
its
value. Do not call \fBtcc_relocate\fP() before.
.PP
The function \fBtcc_relocate\fP() performs all relocations. Needed before
using \fBtcc_get_symbol\fP(). Returns non-zero if link error.
.PP
The function \fBtcc_get_symbol\fP() returns the symbol address corresponding
to \fIname\fP, or error.
.SH EXAMPLE

The following program is an example of using tcc as a backend for code
generator:
.PP
.nf
.fam C
   #include <stdlib.h>
   #include <stdio.h>
   #include <libtcc.h>

   /* this function is called by the generated code */
   int add(int a, int b) { return a + b; }

   /* This is the dynamic code C source string */
   char code[] = "int foo(int n) { "
   "printf(\\"add(%d, %d) = %d\\\\n\\", n, n*2, add(n, n*2)); }"

   int main(int argc, char **argv) {
        TCCState *s;
        int (*func)(int);

        if ((s = tcc_new) == 0) exit(1);
        tcc_set_output_type(s, TCC_OUTPUT_MEMORY);
        tcc_compile_string(s, code);
        tcc_add_symbol(s, "add", (unsigned long)&add);
        tcc_relocate(s);
        func = tcc_get_symbol(s, "foo");
        func(32);
        tcc_delete(s);
        return 0;
    }

.fam T
.fi
.SH SEE ALSO
\fBtcc\fP(1), \fBcc\fP(1), \fBcpp\fP(1), \fBgcc\fP(1), \fBld\fP(1)
.SH COPYRIGHT
libtcc is copyright (C) 2001, 2002 by Fabrice Bellard
.PP
Permission is granted to make and distribute verbatim copies of this
manual page provided the copyright notice and this permission notice
are preserved on all copies.
.PP
Permission is granted to copy and distribute modified versions of
this manual page under the conditions for verbatim copying, provided
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.
.PP
Permission is granted to copy and distribute translations of this
manual page into another language, under the above conditions for
modified versions, except that this permission notice may be stated in
a translation approved by the Foundation.
.SH AUTHORS
This program was written by Fabrice Bellard <address@hidden>.
It may be freely distributed under the terms of the GNU General Public
License. There is ABSOLUTELY NO WARRANTY for this program.
.PP
This manual page has been contributed by Marc Vertes <address@hidden>.