Includium

A complete C preprocessor implementation in Rust.

API Documentation | CLI Documentation | Changelog

includium is a robust, well-tested C preprocessor that can process C/C++ source code with macros, conditional compilation, and includes. It supports target-specific preprocessing for different operating systems and compilers.

This repository contains both the core library and a command-line interface (includium-cli).

Features

Supported Platforms

Table of Contents

• Installation
• Usage
  • As a Library
  • As a CLI
• Development
  • Just Tasks
• Building from Source
• Advanced Usage
  • Custom Include Resolvers
  • #warning Handling
• Contributing
  • Roadmap
  • Reporting Issues
• License

Installation

Add includium to your Cargo.toml using

cargo add includium

or manually by editing Cargo.toml:

[dependencies]
includium = "0.1.0"

Usage

As a Library

[!WARNING] Compiler-specific macro definitions are approximations. While they match common behavior for GCC, Clang, and MSVC, edge cases may differ from real toolchains.

use includium::{preprocess_c_code, PreprocessorConfig};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let code = r#"
#define PI 3.14
#ifdef __linux__
const char* platform = "Linux";
#endif
    "#;

    let config = PreprocessorConfig::for_linux();
    let result = preprocess_c_code(code, &config)?;
    println!("{}", result);
    Ok(())
}

As a CLI

The includium-cli package provides a command-line interface for the C preprocessor. See the CLI documentation for detailed usage instructions.

Basic installation:

cargo install includium-cli

Basic usage:

# Preprocess a file
includium input.c -o output.i

# Cross-compile for Windows
includium input.c --target windows --compiler msvc -o win_output.i

Development

Just Tasks

This project uses Just for task automation. Available tasks:

Building from Source

1. Clone the repository:

   git clone https://github.com/walker84837/includium.git
   cd includium
   

2. Build the workspace:

   cargo build # or just build
   

3. Run tests:

   cargo test # or just test
   

Advanced Usage

[!NOTE] This section is intended for advanced users who need custom include resolution or fine-grained control over diagnostics and preprocessing behavior.

Custom Include Resolvers

use includium::Preprocessor;

let mut preprocessor = Preprocessor::new()
    .with_include_resolver(|path| {
        match path {
            "config.h" => Some("#define CONFIG_ENABLED 1".to_string()),
            "version.h" => Some("#define VERSION \"1.0.0\"".to_string()),
            _ => None,
        }
    });

#warning Handling

use includium::PreprocessorConfig;
use std::rc::Rc;

let warning_handler = Rc::new(|msg: &str| {
    eprintln!("Warning: {}", msg);
});

let config = PreprocessorConfig::for_linux()
    .with_warning_handler(warning_handler);

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Roadmap

• CLI (includium-cli)
• Integration tests
• Benchmarks with cargo bench
• CI with cross-platform tests for multiple compilers

Reporting Issues

If you find a bug or have a feature request, please open an issue with:

1. A clear description of the problem
2. Steps to reproduce
3. Expected vs actual behavior
4. Platform and compiler information

License

This project is licensed under the Mozilla Public License Version 2.0. See the LICENSE file for details.