Project Management¶

FastC projects are configured with fastc.toml and can be scaffolded with CLI commands.

Creating Projects¶

fastc new¶

Create a new project in a new directory:

fastc new my_project
cd my_project

fastc init¶

Initialize a project in an existing directory:

mkdir my_project
cd my_project
fastc init

Project Types¶

Specify the project type with -t or --type:

# Binary application (default)
fastc new my_app -t binary

# Library
fastc new my_lib -t library

# FFI wrapper library
fastc new my_wrapper -t ffi-wrapper

Build Templates¶

Choose a build system template with --template:

# GNU Make (default)
fastc new my_project --template make

# CMake
fastc new my_project --template cmake

# Meson
fastc new my_project --template meson

Project Structure¶

Binary Project¶

my_project/
├── fastc.toml          # Project configuration
├── Makefile            # Build script (or CMakeLists.txt/meson.build)
├── src/
│   └── main.fc         # Entry point
└── build/              # Output directory

Library Project¶

my_lib/
├── fastc.toml
├── Makefile
├── src/
│   └── lib.fc          # Library source
└── build/

fastc.toml¶

The project configuration file.

Minimal Configuration¶

[package]
name = "my_project"

Full Configuration¶

[package]
name = "my_project"
version = "0.1.0"
type = "binary"         # binary, library, or ffi-wrapper

[build]
include_dirs = ["include", "vendor"]
link_libs = ["pthread", "ssl"]

[dependencies]
# Git dependency with tag
mylib = { git = "https://github.com/user/mylib", tag = "v1.0.0" }

# Git dependency with branch
utils = { git = "https://github.com/user/utils", branch = "main" }

# Git dependency with specific commit
core = { git = "https://github.com/user/core", rev = "abc123" }

# Local path dependency
local = { path = "../local_lib" }

Package Section¶

Field	Description	Default
`name`	Project name	Required
`version`	Semantic version	`0.1.0`
`type`	Project type	`binary`

Build Section¶

Field	Description
`include_dirs`	Additional include directories for C compiler
`link_libs`	Libraries to link

Dependencies Section¶

Specify dependencies with their source:

[dependencies]
# Tag (recommended for releases)
dep1 = { git = "https://...", tag = "v1.0.0" }

# Branch (for development)
dep2 = { git = "https://...", branch = "main" }

# Commit (for exact reproducibility)
dep3 = { git = "https://...", rev = "abc123def456" }

# Local path (for development)
dep4 = { path = "../sibling_project" }

Lock File¶

fastc.lock records exact dependency versions:

# This file is auto-generated by fastc. Do not edit.

[[package]]
name = "mylib"
version = "1.0.0"
source = "git+https://github.com/user/mylib?tag=v1.0.0"
resolved = "abc123def456789"

[[package]]
name = "utils"
version = "0.5.0"
source = "git+https://github.com/user/utils?branch=main"
resolved = "xyz789abc123"

Commit this file for reproducible builds.

Modules¶

Multi-file projects use the module system:

src/main.fc¶

mod utils;        // Loads src/utils.fc
mod math;         // Loads src/math/mod.fc

fn main() -> i32 {
    return helper();
}

src/utils.fc¶

fn helper() -> i32 {
    return 42;
}

Module Resolution¶

For mod foo;, FastC looks for:

src/foo.fc - Single file module
src/foo/mod.fc - Directory module

Build System Integration¶

Makefile (default)¶

.PHONY: all clean

all: build/main

build/main.c: src/main.fc
    fastc compile $< -o $@ --emit-header

build/main: build/main.c
    $(CC) -I$(FASTC_RUNTIME) $< -o $@

clean:
    rm -rf build/

CMakeLists.txt¶

cmake_minimum_required(VERSION 3.10)
project(my_project)

# Custom command to run fastc
add_custom_command(
    OUTPUT ${CMAKE_BINARY_DIR}/main.c
    COMMAND fastc compile ${CMAKE_SOURCE_DIR}/src/main.fc -o ${CMAKE_BINARY_DIR}/main.c
    DEPENDS ${CMAKE_SOURCE_DIR}/src/main.fc
)

add_executable(main ${CMAKE_BINARY_DIR}/main.c)
target_include_directories(main PRIVATE $ENV{FASTC_RUNTIME})

meson.build¶

project('my_project', 'c')

fastc = find_program('fastc')

main_c = custom_target('main_c',
    input: 'src/main.fc',
    output: 'main.c',
    command: [fastc, 'compile', '@INPUT@', '-o', '@OUTPUT@']
)

executable('main', main_c)

Workflow¶

Development¶

# Create project
fastc new my_project
cd my_project

# Edit code
vim src/main.fc

# Check for errors
fastc check src/main.fc

# Build and run
fastc run

# Format code
fastc fmt src/main.fc

Release¶

# Build release
fastc build --cc --release

# Run release
./build/main