DTrace on Windows

To use ucpp as an integrated lexer (reading files, preprocessing, and outputting a stream of C tokens), compile the code with STAND_ALONE undefined.

Follow these initialization steps:

1. Initialize Lexer: Call init_cpp() to initialize the lexer automaton.
2. Configure Globals: Set the following global variables:
   • no_special_macros: Set to non-zero to prevent defining special macros like __FILE__.
   • c99_compliant: Set to non-zero to define __STDC_VERSION__ as 199901L (default). Set to 0 to omit it.
   • c99_hosted: Set to 1 for hosted environment (default), 0 for non-hosted, or a negative value to not define __STDC_HOSTED__.
   • emit_defines and emit_assertions: Set to 0 during the initial setup step.
3. Initialize Tables: Call init_tables(). If you provide a non-zero argument, it will also initialize assertions.
4. Set Include Path: Call init_include_path() to reset the include path to your specified list of paths.

// Conceptual integration steps based on README
init_cpp();

no_special_macros = 0;
c99_compliant = 1;
c99_hosted = 1;
emit_defines = 0;
emit_assertions = 0;

init_tables(0); // 0 to not initialize assertions
init_include_path(my_paths, path_count);

To use ucpp as a preprocessor, follow these steps:

1. Set Global Variables: Configure the following globals:
   • emit_dependencies: Set to 1 to emit dependencies during preprocessing, or 2 to include system include files.
   • emit_defines: Set to non-zero to emit #define macro definitions.
   • emit_assertions: Set to non-zero to emit assertions.
   • emit_output: The FILE * where emitted items are sent.
   • transient_characters: Used for cross-compilation.
2. Set Initial Filename: Call set_init_filename(filename, is_real), where is_real is true if fopen() can work on the filename.
3. Initialize Lexer State:
   • Call init_lexer_state().
   • If outputting tokens, call init_lexer_mode(). Otherwise, set ls->flags to DEFAULT_CPP_FLAGS and ls->output to the target FILE *.
4. Configure Input: Set ls->input to the FILE * containing the source.
5. Configure Environment: Use add_incpath() for include paths, define_macro()/undef_macro() for macros, and make_assertion()/destroy_assertion() for assertions.
6. Enter Files: Call enter_file() (required if not in lexer mode or if LINE_NUM is set).
7. Execute:
   • Lexer Mode: Call lex() repeatedly. A non-zero return is an error. CPPERR_EOF indicates end-of-input.
   • Preprocessor Mode: Call cpp() repeatedly. A positive return is an error. CPPERR_EOF indicates end-of-file.
8. Finalize: Call check_cpp_errors() after end-of-file. In non-lexer mode, call flush_output().

To install ucpp as a standalone binary, follow these steps:

1. Extract: Uncompress the archive and extract the source files.
2. Configure tune.h: Edit tune.h to set compile-time options (e.g., LOW_MEM, UCPP_MMAP, PRAGMA_TOKENIZE) to suit your target architecture and performance needs.
3. Configure Makefile: Edit the Makefile to define CC and FLAGS variables.
4. Compile: Run the make command.
5. Manual Compilation: If make is unavailable, compile each file separately and link them. Crucial: You must define the macro STAND_ALONE when compiling cpp.c to create a standalone binary.

Note: You require an ISO-C90 (ANSI) C compiler suite with a standard library to compile ucpp.

# Standard build process
make

# If compiling manually without make, ensure STAND_ALONE is defined for cpp.c
# Example (conceptual):
gcc -DSTAND_ALONE -c cpp.c

When using a pre-C99 compiler or targeting a different machine architecture, you may need to adjust how ucpp evaluates #if expressions.

Character Constants

To ensure character constants are interpreted correctly in the source character set context, you can provide a conversion array.

• As a library component: Define a global variable transient_characters pointing to an array of 256 int values. transient_characters[x] should contain the value of the character whose value is x in the source character set.
• As a standalone tool: Hard-code the conversion table into eval.c and make transient_characters[] point to it statically.

Wide Character Signedness

By default, wide characters match the signedness of char on the build host. To override this, define:

• WCHAR_SIGNEDNESS 0 for unsigned wide characters.
• WCHAR_SIGNEDNESS 1 for signed wide characters.

Arithmetic Evaluation

ucpp supports two evaluation modes:

1. Native integer types: Uses one signed and one unsigned native type.
2. Emulated big integers: Represents numbers using two values of an unsigned type, supporting widths from 2 bits up to twice the native unsigned type size. This mode handles signed values using two's complement.

To enable error/warning reporting for implementation-defined or undefined arithmetic behavior (like overflows or division by zero), define ARITHMETIC_CHECKS in tune.h.