FCC — Finite Compiler Collection

FCC is a multi-language compiler collection framework written in C# (.NET 8). It packages support for multiple programming languages into a single tool, similar to GCC, Clang, or .NET's Roslyn.

By default FCC does not ship with any frontends or backends. Those are plugged in via ICompilerBackend / ICompilerFrontend interfaces (see Backends & Frontends).

FCC/
├── fcc/                         # CLI entry point
│   └── Program.cs               #   fcc <input.cpp> [output.oir]
├── libs/
│   ├── ObjectIR.Core/           #   Core IR library (object-oriented IR)
│   ├── CppToObjectIR/           #   C++ → ObjectIR frontend
│   └── CppToObjectIR.Tests/     #   C++ frontend test suite
├── ObjectIR.Programming/        #   Type-system library (G#/GS project)
├── Docs/                        #   This documentation
├── examples/                    #   Sample C++ programs
├── repro/                       #   Repro cases / regression tests
└── FCC.sln                     #   Visual Studio solution file

FCC is organised in layers. Each layer depends only on layers below it.

Source text (.cpp, .cs, …)
        │
        ▼
  Frontend (e.g. CppToObjectIR)
        │  Lex → Parse → CodeGen
        ▼
  ObjectIR.Core.AST
        │
        ├──► ModuleSerializer     → JSON / BSON / text
        ├──► ModuleComposer       → merged Module
        │       └──► DependencyResolver
        └──► FobIrCompiler        → .fob binary (compact binary format)

fcc input.cpp output.oir
  1. Read input.cpp
  2. Resolve #include directives in the same directory
  3. Lex + Parse C++ → AST
  4. Build a member type registry from AST + headers
  5. Compile AST → ObjectIR Module
  6. Serialise Module → .oir (FOB binary) file

• .NET10 SDK (or later)

git clone https://git.finite.ovh/FCC
cd FCC
dotnet build FCC.slnx

dotnet run --project fcc -- examples/test.cpp output.oir

This compiles a C++ file into a .oir (FOB binary) file. You can also pipe the output through any registered backend for code generation.

fcc <input> [output] [-o <output>] [--target fob|bir|textir|json] [-I <path>] [-D <define>]

Output targets:

fcc build [<project.fccproj>] [args...]
fcc <project.fccproj>

When fcc build is run without a project path, FCC scans the current directory for a single .fccproj file. If exactly one is found, it is used automatically.

Project files use an XML format modelled after .csproj:

<Project Sdk="FCC">
  <PropertyGroup>
    <OutputName>MyApp</OutputName>
    <OutputPath>bin</OutputPath>
    <TargetFormat>fob</TargetFormat>
  </PropertyGroup>

  <ItemGroup>
    <Compile Include="src/**/*.cpp" />
    <Compile Include="src/**/*.h" />
    <IncludePath Include="include" />
    <Define Include="DEBUG" />
  </ItemGroup>
</Project>

PropertyGroup settings:

ItemGroup elements:

Paths in project files are resolved relative to the project directory. Glob patterns (*, ?) are supported in Compile Include attributes.

Exit codes:

# Compile a C++ file to FOB binary
fcc examples/test.cpp

# Compile to human-readable IR text
fcc examples/test.cpp --target textir -o output.ir.txt

# Compile with include paths
fcc examples/test.cpp -I examples/include

# Build a project
fcc build examples/sample.fccproj

# Auto-discover project in current directory
cd examples && fcc build

# Override target format for a project build
fcc build sample.fccproj --target json

The C++ frontend compiles a subset of C++ into ObjectIR. It lives in libs/CppToObjectIR/ and is structured as a classic three-phase compiler:

Source text
    │
    ▼
  Lexer (libs/CppToObjectIR/Lexing/)
    │  Tokenizes: keywords, identifiers, operators, literals, skips # directives
    │  56 token kinds covering C++ type keywords, control flow, OOP, and operators
    ▼
  Parser (libs/CppToObjectIR/Parsing/)
    │  Produces a C++ AST (libs/CppToObjectIR/Ast/)
    │  30+ AST node types: classes, structs, enums, namespaces, methods,
    │  fields, statements (if/while/for/do-while/try-catch/throw),
    │  expressions (binary, unary, call, member access, new, cast, ternary)
    ▼
  IrCodeGenerator (libs/CppToObjectIR/CodeGen/)
    │  Walks the AST and emits ObjectIR instructions
    │  Handles: type mapping (C++ → IR), std::cout chains, type inference
    ▼
  ObjectIR.Core.Module

ObjectIR.Core is the heart of FCC — an object-oriented intermediate representation designed from the ground up for OO languages. Think LLVM IR, but for classes, interfaces, generics, and virtual dispatch.

Full documentation lives in libs/ObjectIR.Core/docs/:

Module "TodoApp" version 1.0.0

interface IItem {
    method GetId() -> int32
    method GetDescription() -> string
}

class TodoItem : IItem {
    private field id: int32
    private field description: string

    constructor(id: int32, description: string) {
        ldarg this
        ldarg id
        stfld TodoItem.id
        ret
    }

    method GetId() -> int32 implements IItem.GetId {
        ldarg this
        ldfld TodoItem.id
        ret
    }
}

Key properties:

• Stack-based IL (like CIL/bytecode)
• First-class structured control flow — IfInstruction, WhileInstruction, ForEachInstruction, TryInstruction as IR nodes, not raw branch targets
• Visitor pattern for instruction passes — implement IInstructionVisitor
• Fluent builder — IRBuilder for constructing modules in C# code
• Cross-module composition — ModuleComposer merges modules, resolves dependency order, detects cycles
• Multiple serialisation formats — human-readable text, JSON/BSON for interop, compact FOB binary for distribution

FCC is designed as a compiler collection — one tool that can handle many languages. Support for new languages is added through two interfaces (defined in the ObjectIR.Programming library):

interface ICompilerBackend {
    void Compile(string path);               // compile one module
    void CompileAll(string path, List<string> files);  // batch compile
}

interface ICompilerFrontend {
    // (defined in ObjectIR.Programming)
}

Because FCC has no built-in understanding of ObjectIR types, the standard library, or language-specific semantics, compiler manufacturers should use the ObjectIR.Programming library for type checking.

Note: ObjectIR.Programming is a separate repository. The type checker and type system are being developed there.

1. Implement ICompilerBackend
2. Register it with the FCC runtime
3. The fcc CLI will use it when generating final output

1. Implement ICompilerFrontend
2. Your frontend receives source text and returns an ObjectIR Module
3. The fcc CLI dispatches to the right frontend based on file extension

The examples/ directory contains sample C++ programs:

The repro/ directory contains regression test cases:

See Docs/COMPLETE_EXAMPLE.md for a full todo-list application written in ObjectIR text format, demonstrating:

• Class hierarchies and interface implementation
• Generic collections (List<T>)
• Constructors with parameters
• Conditional logic and loops
• String operations
• The C# Builder API equivalent
• Backend considerations (C#, JS, C++, Java)

# Restore and build everything
dotnet restore FCC.sln
dotnet build FCC.sln

# Run the C++ frontend tests
dotnet test libs/CppToObjectIR.Tests

# Compile a test file
dotnet run --project fcc -- examples/test.cpp