- Scheme 92.6%
- Tree-sitter Query 7.4%
BLUE - Build Language User Extensible
- Features
- Quick Start
- A Simple Example
- Custom Commands
- Built-in Commands
- Examples
- Contributing
- Status
- Related Software
- Projects Using BLUE
- Contact
- License
Arch: https://builds.sr.ht/~old/blue/commits/main/arch.yml.svg Debian: https://builds.sr.ht/~old/blue/commits/main/debian.yml.svg Fedora: https://builds.sr.ht/~old/blue/commits/main/fedora.yml.svg Ubuntu: https://builds.sr.ht/~old/blue/commits/main/ubuntu.yml.svg Woodpecker: https://ci.codeberg.org/api/badges/14738/status.svg
BLUE is an acronym for Build Language User Extensible. It is a self-hosting build-system fully written in Guile.
As opposed to other build-systems, BLUE works as a library that can be used by projects to manage their builds. It is entirely self-contained and can be embedded into existing projects. It provides an optional clean and extensible CLI.
BLUE aims to reduce frictions from the build-system by providing a very-rich extensible API with clear error messages and documentation.
(define hello
(c-binary
(inputs "main.c")
(outputs "hello")))
(blueprint
(buildables (list hello)))Features
Core
- Self-hosting (BLUE builds itself)
- Timestamp dependency tracking
- Single dependency on Guile
- Extensible through a custom type system
- Declarative and functional
- Embeddable as a library
- Parallel builds using Guile fibers
- Out-of-tree builds
Computation System
BLUE features a lazy evaluation system with special reader syntax for delayed computations. This enables configuration values that depend on other values to be resolved at the right time, similar to how GNU Autotools handles directory variables.
;; #%~ delays evaluation
;; #%? asks the computation environment for a value
;; #%, undelays (evaluates at definition time)
(define my-path
#%~(string-append #%?prefix "/share"))
;; yield: /usr/local/share
(run-with-states '((prefix . "/usr/local"))
(run-computation my-path))
;;; yield: /usr/share
(run-with-states '((prefix . "/usr"))
(run-computation my-path))Language Support
- C/C++ (with automatic dependency detection via pkg-config)
- Guile Scheme modules
-
Multiple frontend languages
- Guile Scheme
- Wisp (TODO)
Developer Experience
- Syntax-highlighted source code in error messages
- S-expression diffing for debugging configuration changes
- Terminal hyperlinks for clickable file paths (in supported terminals)
- Profiling support (
--profile=stat,--profile=gc,--profile=trace) - Built-in REPL for interactive debugging (
blue repl) - Code coverage reporting with LCOV integration
Integration
- JSON serialization for external tool integration
- Emacs integration via blue.el
Quick Start
Requirements
The only dependency of BLUE is Guile >= 3.0.7.
Supported Platforms
- GNU Linux with epoll(2)
Installation
Get the sources.
Setup
Ensure dependencies are met.
In order to build this project a sufficient new version of Guile has to be installed, refer to requirements.
If using Guix, the recommended development environment can be instantiated through the following command:
guix time-machine -C channels.scm -- shell -m manifest.scmDirenv
Bootstrap
If not using the .envrc file, then BLUE needs to be bootstrapped. This can be
done by running the following commands:
mkdir build
cd build
../bootstrap
This creates the pre-inst-env wrapper script. Commands can be executed within
the BLUE environment by prefixing them with ./pre-inst-env:
./pre-inst-env blue configure
./pre-inst-env blue buildConfigure
BLUE itself requires a configuration to work.
blue configureThis caches the result of the system information in the BLUE store.
This step mimics the GNU Autotools workflow. Therefore, the user can expect to be able to configure the project through the standard directory variables mandated by the GNU project (e.g. '–prefix=<install-path>').
Hacking BLUE
BLUE can now build, check and install itself!
blue build -- check -- install -- installcheckA Simple Example
Here is a complete blueprint for building a C program with a static library:
(use-modules
(blue stencils c)
(blue types blueprint))
(define libhello
(c-binary
(inputs "hello.c")
(outputs "libhello.a")
(library? #t)
(shared? #f)))
(define hello
(c-binary
(inputs (list "main.c" libhello))
(outputs "hello")))
(blueprint
(buildables (list hello)))BLUE automatically handles dependency ordering, compiler flag propagation, and incremental rebuilds based on timestamps.
Custom Commands
Blueprints can define custom commands that integrate with BLUE's CLI:
(define-command (hello-command args)
((invoke "hello")
(category 'misc)
(synopsis "Print hello")
(help "Print hello on the terminal and exit."))
(display "hello\n"))
(blueprint
(commands (list hello-command)))
Then run with blue hello.
Built-in Commands
blue configure # Resolve dependencies and configuration
blue build # Build all buildables
blue check # Run all testables
blue clean # Remove build artifacts
blue repl # Start interactive REPL
blue help [COMMAND] # Show help for a commandUseful Options
blue --color=never ... # Disable colored output
blue --jobs=4 ... # Limit parallel jobs
blue --dry-run ... # Show what would be done
blue --profile ... # Profile the execution
blue --log-level=debug ... # Verbose loggingExamples
See EXAMPLES for internal documentation.
Templates
- test-hello
- Hello world
- test-hello-embedded
- Hello world with BLUE embedded
Contributing
See CONTRIBUTING.
Status
BLUE is currently in pre-alpha. The core functionality works and BLUE successfully builds itself, but APIs may change.
Projects Using BLUE
Contact
License
For your freedom and ours
BLUE is free software licensed under the LGPL-3.0-or-later.