Crate turtle_build

Expand description

§Turtle

Ninja-compatible build system for improved end-user experience written in Rust.

§Goals

Memory safe implementation of the Ninja build system in Rust
Modest, comprehensible, and customizable build/error outputs
- Turtle never shows any information that is inscrutable to end-users.
- This is important for users of high-level programming languages who do not know how compilers and build systems work.

§Install

cargo install turtle-build

§Usage

turtle

For more information, see turtle --help.

§Features

Ninja-compatible build file syntax and command line options 🥷
Content hash-based rebuild
Description-only outputs
- Turtle never shows commands of build rules but only descriptions because they are incomprehensible to end-users.
Source mapping
- Turtle maps outputs in error messages to source filenames defined as srcdep variables defined in build directives to make them understandable to end-users.
--log-prefix option
- It changes log prefixes attached to every line of logs from Turtle itself (e.g. --log-prefix my-build-system for a log of my-build-system: build failed.)
--quiet option
- It suppresses error messages from Turtle itself on expected build errors. This is useful when you are spawning Turtle as a child process of some higher-level build system.

§Compatibility with Ninja

Turtle aims to support full syntax of the Ninja build files. It also supports basic command line arguments but is not going to implement all the original options (e.g. -t option.)

§Syntax

build statement
- Explicit outputs
- Explicit inputs
- Implicit outputs
- Implicit inputs
- Order-only inputs
- phony rule
rule statement
default statement
include statement
subninja statement
pool statement
Global variables
Build-local variables
in and out special variable
in_newline special variable

§Command line arguments

-f custom build file option
-j job limit option
-k keep-going option
-n dry-run option
-C change-directory option

§Others

Circular build dependency detection
Circular build file dependency detection
builddir special variable
Dynamic dependencies
- Implicit inputs
- Implicit outputs
- Circular build dependency detection
C/C++ header dependencies
- depfile option
- deps option
rspfile and rspfile_content options
Windows support

§Technical notes

Unlike traditional build systems, Turtle parallelizes builds naturally in a way similar to parallel graph reduction, where a graph is rewritten in parallel until it is reduced to a final result. This is made possible by Rust’s ecosystem of futures and stackless coroutines.

Here is how parallel builds work in Turtle:

Turtle spawns futures for all builds of default targets.
Depending on builds’ configuration, they spawn more futures or resolve their futures.
- If they require some input targets to be built first, they spawn those builds for input targets all in parallel.
Those futures are scheduled and run in parallel by an asynchronous runtime in Rust.
Builds complete when all the futures are resolved.

Currently, Turtle uses a topological sort algorithm only to detect dependency cycles but not for scheduling of build jobs.

§Similar projects

§License

Dual-licensed under MIT and Apache 2.0.

Structs§

Context: A context.
DatabaseError: A database error.
FjallDatabase: A Fjall database.
LogDatabase: A log database.
Module: A module.
OsCommandRunner: A command runner backed by an operating system.
OsConsole: A console backed by an operating system.
OsFileSystem: A file system backed by an operating system.
PathPool: A path pool.
RedbDatabase: A redb database.
RunOptions: Run options.

Enums§

BuildError: A build error.
Statement: A statement.

Traits§

Console: A console.
Database: A database.
FileSystem: A file system.

Functions§

clean_dead: Cleans dead outputs.
compile: Compiles modules.
job_limit: Guesses a job limit from a processor count.
load: Loads a root module and its dependency modules.
parse: Parses a module.
run: Runs builds.