Tools

project.toml

A package's manifest, every key in it, and what each one does.

A folder with a project.toml is a package. fb new writes one; this page lists every table and key it can have.

[project]
name = "shop"
version = "0.3.0"
description = "Prices, stock, and orders for a small shop"
license = "MIT"
repository = "https://github.com/ada/shop"
keywords = ["retail", "inventory"]

[dependencies]
colors = "1.4"
report = { path = "../report" }
charts = { version = "0.2", link = "beside" }
tools = { version = "2", registry = "company" }

[native]
sqlite3 = { static = "libs/sqlite3" }
m = { system = "m" }
codec = { dynamic = "native/{target}/codec" }

[format]
width = 120

[registries]
company = { index = "https://packages.example.com/index/" }

A key fb doesn’t know is a warning, and a value of the wrong kind is an error at its line.

[project]

Key
`name`	Required. The package’s name, an identifier: letters, digits, and `_`, not starting with a digit, not a keyword, and not `std`. Its modules’ names start with it. To publish it, the registry also asks for lowercase, starting with a letter, and at most 64 characters, as the package policy says.
`version`	Required. Three numbers, like `"0.3.0"`, and maybe a pre-release after a `-`, like `"2.0.0-beta.1"`.
`type`	`"executable"` or `"library"`. Without it, a package with a main file is an executable, and one without is a library.
`main`	The main file, a `.fb` file in the package’s folder. Without it, `"main.fb"`. A library has none.
`description`	A line about the package, which the registry shows. Publishing needs it.
`license`	The package’s license, as an SPDX expression, like `"MIT"` or `"MIT OR Zlib"`. Publishing needs it.
`license_file`	The license’s file, when it isn’t `LICENSE`, `LICENSE.md`, `LICENSE.txt`, or `COPYING`.
`readme`	The readme’s file, when it isn’t `README.md`, `README`, or `README.txt`.
`repository`, `homepage`, `documentation`	`https://` URLs the registry links.
`keywords`	Up to five words the registry’s search finds the package by, each lowercase letters, digits, and `-`, up to 32 characters.
`fb`	The versions of fb the package builds with, as a range, like `">=1.2"`. A registry’s resolver skips versions of the package this fb isn’t in.

[dependencies]

Each key is a dependency’s name, which its modules are imported by: Import colors for the colors package. Its value is a version range from a registry, or a table:

Key
`version`	The range of the registry’s versions it takes.
`path`	A local package’s folder, from this one’s, in place of a version.
`registry`	A registry `[registries]` names, when it isn’t futureblitz.dev.
`link`	`"embed"`, the default, builds the package into the executable. `"beside"` builds it as a library file beside the executable: `charts.dll` on Windows, `libcharts.so` on Linux, and `libcharts.dylib` on macOS. Only the program’s own project.toml decides; a library’s `link` is ignored, with a warning.

Every package in a program agrees on one version of each dependency, which fb.lock records. Two packages of one name, and packages that depend on each other in a cycle, are errors.

[native]

C libraries the package’s Extern "C" Lib "<name>" blocks call, each by its name: letters, digits, and _, -, ., or +, not starting with -.

Value
`"libs/sqlite3"`, or `{ static = "libs/sqlite3" }`	A static library, linked into the executable. The path is from the package’s folder: the file itself, or without its `lib` prefix and extension, as `libs/libsqlite3.a`, `libs/sqlite3.a`, or `libs/sqlite3.lib`.
`{ system = "m" }`	A library the system has, found by its name, as a C linker’s `-lm` finds it.
`{ dynamic = "native/{target}/codec" }`	A shared library: `codec.dll` on Windows, `libcodec.so` on Linux, and `libcodec.dylib` on macOS. fb copies it beside the executable, which loads it from there.

A program links every static library of its packages, its own first, then each dependency’s in its project.toml’s order. {target} in a path is the target being built for: windows-x64, linux-x64, linux-arm64, macos-arm64, or macos-x64. A package that ships its libraries prebuilt keeps one folder for each. Using a C library shows each kind.

[format]

Key
`width`	The line width `fb fmt` formats to, from 40 to 1000 columns. Without it, 100.

[registries]

Registries other than futureblitz.dev, each by the name a dependency’s registry uses:

Key
`index`	The registry’s index: an `https://` URL, an `http://` one on this machine only, or a folder, for a registry on disk.

A [registries] entry named futureblitz replaces futureblitz.dev’s own index, for a mirror. Registries and mirrors says more.

Report an issue with this page or with FutureBlitz on GitHub.