31 releases
0.4.8 | Dec 7, 2023 |
---|---|
0.4.7 | Oct 17, 2023 |
0.4.6 | Jul 11, 2023 |
0.4.4 | Nov 16, 2022 |
0.3.1 | Feb 5, 2022 |
#112 in Development tools
479 downloads per month
140KB
4K
SLoC
Turtle
Ninja-compatible build system for high-level programming languages written in Rust
Goals
- Safe (no
unsafe
) and fast implementation of the Ninja build system in Rust - Modest, comprehensive, and customizable build/error outputs
- Turtle never shows any information that is not understandable to end-users.
- This is important for users of high-level programming languages who do not know how compilers and build systems work.
Turtle is originally written for the Pen programming language. Therefore, we support only dynamic dependencies but not C/C++ header dependencies currently. Your contribution is welcome! 😄
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 the former is hard for end-users to digest.
- Source mapping
- Turtle maps outputs in error messages to source filenames defined as
srcdep
variables defined inbuild
directives to make them understandable to end-users.
- Turtle maps outputs in error messages to source filenames defined as
--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 ofmy-build-system: build failed
.)
- It changes log prefixes attached to every line of logs from Turtle itself (e.g.
--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.
- Console output handling similar to Rust's Cargo
- Turtle shows outputs of build jobs running currently at the bottom of logs. So it's easy to track what is going on during builds.
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
andout
special variable
Command line arguments
-
-f
custom build file option -
-j
job limit option -
-k
keep-going 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
-
- Windows support
Technical notes
Something different from the traditional build systems and notable in Turtle is that it solves parallel builds similar to parallel graph reduction naturally, where you modify graph structures in parallel and reduce it into a solution, thanks to an ecosystem of futures and stackless coroutines in Rust.
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.
Turtle is powered by the following neat projects and others!
- tokio: Asynchronous runtime for Rust
- sled: Embedded database in Rust
- petgraph: Graph algorithms in Rust
Similar projects
License
Dual-licensed under MIT and Apache 2.0.
Dependencies
~11–19MB
~251K SLoC