BFC Compiler

Architecture · Backend guide · CLI reference · API documentation

BFC is a Brainfuck compiler written in C23. It parses Brainfuck source code, builds and optimizes an intermediate representation, and emits target-specific assembly.

The project is intentionally small and self-contained. It uses only the C standard library and platform toolchains; no third-party runtime libraries are required.

Current status

BFC currently supports assembly generation for:

• aarch64-apple-darwin
• x86_64-apple-darwin

The target parser also recognizes Linux and Windows target triples, but those backends are not yet implemented.

The compiler currently emits assembly with -S. The final assemble-and-link stage that produces a native executable is planned but not yet complete.

Features

• C23 implementation
• Clang-style command-line interface
• Brainfuck tokenization with source locations
• Optional semicolon line comments
• Bracket validation and diagnostics
• Nested intermediate representation
• Repeated-operation optimization
• Repeated pointer-movement optimization
• Clear-loop optimization for [-] and [+]
• Target-triple selection
• macOS AArch64 backend
• macOS x86-64 backend
• AddressSanitizer-enabled debug builds
• Doxygen-compatible source documentation

Requirements

To build BFC:

• A C23-capable compiler
  • Clang is currently the primary tested compiler
  • GCC may work if it supports the required C23 and GNU attribute features
• GNU Make or a compatible make
• macOS for executing and linking the currently implemented backends

Optional:

• Doxygen, for generating HTML documentation
• clang-format, for make format and make format-check
• clang-tidy, for make tidy

Building

The default configuration is debug:

make

Explicit debug build:

make debug

Release build:

make release

Generated binaries are placed under:

build/debug/bfc
build/release/bfc

Clean build output:

make clean

Code-quality tools

Format all C sources and headers using .clang-format:

make format

Check formatting without changing files:

make format-check

Run the checks configured in .clang-tidy:

make tidy

These targets are optional developer tools and are not part of the normal compiler build.

Automated builds

The repository includes a GitHub Actions workflow at:

.github/workflows/build.yml

The workflow builds release binaries on native GitHub-hosted runners for:

Platform	Architecture
Linux	x86-64
Linux	AArch64
macOS	x86-64
macOS	AArch64
Windows	x86-64
Windows	ARM64

The cross-platform build workflow runs when:

• a commit is pushed to main
• a pull request targets main
• it is started manually

Tags matching v* trigger the separate release workflow.

Each successful job uploads a packaged build artifact containing the compiler binary, LICENSE, and VERSION. Workflow artifacts are retained for 14 days.

The workflow builds the bfc compiler executable for each host platform. This is separate from code-generation backend support. A Linux or Windows build of bfc does not imply that BFC can emit Linux or Windows assembly; only the targets listed as implemented under Supported target triples are currently usable for code generation.

Usage

bfc [options] <file.bf>

Emit assembly for the host target

./build/debug/bfc -S hello.bf

Default output:

hello.bf.s

Choose the output path

./build/debug/bfc -S hello.bf -o hello.s

Select a target

./build/debug/bfc \
    --target aarch64-apple-darwin \
    -S \
    hello.bf \
    -o hello-aarch64.s

./build/debug/bfc \
    --target x86_64-apple-darwin \
    -S \
    hello.bf \
    -o hello-x86_64.s

Display help

./build/debug/bfc --help

Display the version

./build/debug/bfc --version

Example programs

The examples/ directory contains small Brainfuck programs demonstrating compiler behavior:

File	Behavior
hello.bf	Prints Hello World!
echo.bf	Echoes input until EOF
comments.bf	Demonstrates semicolon line comments
multiply.bf	Uses a loop to compute 6 × 7 and prints *
nested_loops.bf	Uses nested loops to compute and print A

Generate assembly for an example:

./build/debug/bfc -S examples/hello.bf -o hello.s

Command-line options

Option	Description
-h, --help	Display help
-v, --version	Display the compiler version
-S, --assembly	Emit assembly and stop
-o, --output <file>	Set the output path
-t, --target <triple>	Select the target triple
--fno-comments	Disable semicolon line-comment handling
--	Stop parsing command-line options

For complete CLI documentation, see docs/cli.md.

Supported target triples

Target triple	Status
aarch64-apple-darwin	Implemented
x86_64-apple-darwin	Implemented
aarch64-unknown-linux-gnu	Recognized; backend not implemented
x86_64-unknown-linux-gnu	Recognized; backend not implemented
aarch64-pc-windows-msvc	Recognized; backend not implemented
x86_64-pc-windows-msvc	Recognized; backend not implemented
i386-pc-windows-msvc	Recognized; backend not implemented

If no target is supplied, BFC selects the host architecture and operating system.

Brainfuck semantics

BFC currently uses:

• 30,000 cells
• 8-bit wrapping cells
• One byte per cell
• EOF input converted to zero
• Nested loop blocks in the IR

Semicolon comments are enabled by default:

+++++ ; this text is ignored
.

Use --fno-comments to disable that extension.

Optimizations

Implemented optimizations include:

• Coalescing adjacent cell operations
• Coalescing adjacent pointer movements
• Clear-loop recognition for [-] and [+]

Documentation

Project documentation is available under docs/:

• docs/architecture.md
• docs/backends.md
• docs/cli.md

Generate Doxygen HTML documentation with:

make docs

Generated documentation is written to:

docs/doxygen/html/

The generated HTML is not committed to the repository.

Project structure

.
├── .github/
│   └── workflows/
│       ├── build.yml
│       ├── docs.yml
│       └── release.yml
├── docs/
├── examples/
├── include/
├── src/
├── tests/
├── .clang-format
├── .clang-tidy
├── Doxyfile
├── LICENSE
├── Makefile
├── README.md
└── VERSION

Roadmap

• Add the assemble-and-link stage
• Add Linux x86-64 code generation
• Add Linux AArch64 code generation
• Add Windows code-generation backends
• Expand integration and regression tests
• Add additional Brainfuck-specific optimizations
• Add target-aware external toolchain selection

License

BFC is licensed under the GNU General Public License v3.0.

See LICENSE for the complete license text.