> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/TinyCC/tinycc/llms.txt
> Use this file to discover all available pages before exploring further.

# Initialization

> Creating and configuring a TCC compilation context

Before you can compile code with libtcc, you need to create and configure a compilation context (`TCCState`).

## Creating a compilation context

### tcc\_new

Creates a new TCC compilation context.

```c theme={null}
TCCState *tcc_new(void);
```

**return** `TCCState*`

Pointer to the newly created compilation context, or `NULL` if allocation fails.

**Example:**

```c theme={null}
TCCState *s = tcc_new();
if (!s) {
    fprintf(stderr, "Could not create TCC state\n");
    exit(1);
}
```

> [!WARNING]
>
> You must call `tcc_set_output_type()` before any compilation.

## Destroying a compilation context

### tcc\_delete

Frees a TCC compilation context and all associated resources.

```c theme={null}
void tcc_delete(TCCState *s);
```

**s** `TCCState*` *required*

The compilation context to free.

**Example:**

```c theme={null}
tcc_delete(s);
```

## Setting output type

### tcc\_set\_output\_type

Sets the output type for the compilation. **Must be called before any compilation.**

```c theme={null}
int tcc_set_output_type(TCCState *s, int output_type);
```

**s** `TCCState*` *required*

The compilation context.

**output\_type** `int` *required*

The type of output to generate. One of:

* `TCC_OUTPUT_MEMORY` (1) - Run code in memory
* `TCC_OUTPUT_EXE` (2) - Executable file
* `TCC_OUTPUT_DLL` (4) - Dynamic library
* `TCC_OUTPUT_OBJ` (3) - Object file
* `TCC_OUTPUT_PREPROCESS` (5) - Only preprocess

**return** `int`

Returns 0 on success, -1 on error.

**Example:**

```c theme={null}
if (tcc_set_output_type(s, TCC_OUTPUT_MEMORY) < 0) {
    fprintf(stderr, "Failed to set output type\n");
    return 1;
}
```

## Configuring paths

### tcc\_set\_lib\_path

Sets the path where TCC will look for its internal libraries and include files.

```c theme={null}
void tcc_set_lib_path(TCCState *s, const char *path);
```

**s** `TCCState*` *required*

The compilation context.

**path** `const char*` *required*

Path to the TCC library directory (typically contains `include/` and `lib/`).

**Example:**

```c theme={null}
tcc_set_lib_path(s, "/usr/local/lib/tcc");
```

### tcc\_add\_include\_path

Adds a directory to the include file search path.

```c theme={null}
int tcc_add_include_path(TCCState *s, const char *pathname);
```

**s** `TCCState*` *required*

The compilation context.

**pathname** `const char*` *required*

Path to add to the include search path.

**return** `int`

Returns 0 on success.

**Example:**

```c theme={null}
tcc_add_include_path(s, "/usr/local/include");
tcc_add_include_path(s, "./my_headers");
```

### tcc\_add\_sysinclude\_path

Adds a system include path to the default system include paths.

```c theme={null}
int tcc_add_sysinclude_path(TCCState *s, const char *pathname);
```

**s** `TCCState*` *required*

The compilation context.

**pathname** `const char*` *required*

System include path to add.

**return** `int`

Returns 0 on success.

## Setting options

### tcc\_set\_options

Sets compiler options as if passed on the command line. Multiple calls are supported.

```c theme={null}
int tcc_set_options(TCCState *s, const char *str);
```

**s** `TCCState*` *required*

The compilation context.

**str** `const char*` *required*

Command-line style options (e.g., "-Wall -O2").

**return** `int`

Returns 0 on success, -1 on error.

**Example:**

```c theme={null}
tcc_set_options(s, "-Wall -Werror");
tcc_set_options(s, "-nostdinc");
```

## Error handling

### tcc\_set\_error\_func

Sets a custom error and warning callback.

```c theme={null}
typedef void TCCErrorFunc(void *opaque, const char *msg);
void tcc_set_error_func(TCCState *s, void *error_opaque, TCCErrorFunc *error_func);
```

**s** `TCCState*` *required*

The compilation context.

**error\_opaque** `void*`

User data pointer passed to the error callback (can be `NULL`).

**error\_func** `TCCErrorFunc*`

Callback function for errors and warnings. If `NULL`, errors are printed to stderr.

**Example:**

```c theme={null}
void handle_error(void *opaque, const char *msg) {
    FILE *fp = (FILE*)opaque;
    fprintf(fp, "TCC Error: %s\n", msg);
}

tcc_set_error_func(s, stderr, handle_error);
```

## Preprocessor configuration

### tcc\_define\_symbol

Defines a preprocessor symbol.

```c theme={null}
void tcc_define_symbol(TCCState *s, const char *sym, const char *value);
```

**s** `TCCState*` *required*

The compilation context.

**sym** `const char*` *required*

Symbol name. Can be "sym=val" form, or just "sym".

**value** `const char*`

Symbol value. If `NULL` and `sym` doesn't contain '=', defaults to "1".

**Example:**

```c theme={null}
tcc_define_symbol(s, "DEBUG", NULL);           // #define DEBUG 1
tcc_define_symbol(s, "VERSION", "2.0");         // #define VERSION 2.0
tcc_define_symbol(s, "MAX_SIZE=1024", NULL);   // #define MAX_SIZE 1024
```

### tcc\_undefine\_symbol

Undefines a preprocessor symbol.

```c theme={null}
void tcc_undefine_symbol(TCCState *s, const char *sym);
```

**s** `TCCState*` *required*

The compilation context.

**sym** `const char*` *required*

Symbol name to undefine.

**Example:**

```c theme={null}
tcc_undefine_symbol(s, "NDEBUG");
```

## Custom memory allocator

### tcc\_set\_realloc

Sets a custom memory allocator for all TCC allocations. This is a global setting.

```c theme={null}
typedef void *TCCReallocFunc(void *ptr, unsigned long size);
void tcc_set_realloc(TCCReallocFunc *my_realloc);
```

**my\_realloc** `TCCReallocFunc*`

Custom realloc-style function. If `NULL`, uses the default allocator.
The function should free memory when `size` is 0.

> [!WARNING]
>
> This must be called before creating any `TCCState` instances, as it affects all TCC memory allocation globally.

**Example:**

```c theme={null}
void *my_realloc(void *ptr, unsigned long size) {
    if (size == 0) {
        free(ptr);
        return NULL;
    }
    return realloc(ptr, size);
}

tcc_set_realloc(my_realloc);
```

## Complete initialization example

```c theme={null}
#include "libtcc.h"
#include <stdio.h>

void error_handler(void *opaque, const char *msg) {
    fprintf(stderr, "TCC: %s\n", msg);
}

int main() {
    TCCState *s;
    
    // Create new state
    s = tcc_new();
    if (!s) {
        fprintf(stderr, "Failed to create TCC state\n");
        return 1;
    }
    
    // Configure error handling
    tcc_set_error_func(s, NULL, error_handler);
    
    // Set paths
    tcc_set_lib_path(s, "/usr/local/lib/tcc");
    tcc_add_include_path(s, "./include");
    
    // Set compiler options
    tcc_set_options(s, "-Wall");
    
    // Define preprocessor symbols
    tcc_define_symbol(s, "MY_APP", NULL);
    tcc_define_symbol(s, "VERSION", "\"1.0\"");
    
    // Set output type (required before compilation)
    tcc_set_output_type(s, TCC_OUTPUT_MEMORY);
    
    // Now ready to compile...
    
    tcc_delete(s);
    return 0;
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.