The fb command

fb builds, runs, tests, formats, and documents FutureBlitz programs. Each command takes a .fb file, a package’s folder, or nothing, for the package the current folder is in, from it up. fb help <command> shows a command’s options, and fb --version says which fb it is, its commit, and its target, like fb 0.1.0 (abc1234, windows-x64).

Every command takes --color <when>, auto, always, or never, for its own output, and -h or --help.

fb new

fb new [options] <folder>

Makes a package in <folder>, named by the folder’s name, which has to be an identifier: a project.toml, a main.fb that imports std.core and prints “Hello, world!”, and a .gitignore of build/. The folder mustn’t be there yet, or must be empty. fb new . names the package after the current folder.

fb check

fb check [options] [file.fb | package folder]

Checks a program for errors without building it. On a library, it checks each of its .fb files as a module of its own.

fb build

fb build [options] [file.fb | package folder]

Compiles a program into an executable: a package’s goes to <folder>/build/<name>, and a file outside a package’s beside it, with the platform’s extension. On a library, it writes the library’s prebuilt .fblib and its .fbi interface file. After a build that links any of std’s bundled C libraries, it lists them with their licenses.

fb run

fb run [options] [file.fb | package folder] [-- <arguments>]

Builds the program as fb build does, then runs it. What follows -- goes to the program.

fb test

fb test [options] [file.fb | package folder | std]

Builds a package’s tests, its @Test Functions, its tests/ folder’s, and its doc comments’ examples, and runs them in parallel in one process, with a summary, and in a debug build the leaks of each test. fb test std runs the examples in the standard library’s docs. See testing.

fb fmt

fb fmt [options] [files and folders]

Formats .fb files in place, a folder’s and its folders’ but for hidden ones and a package’s build/, or the current package’s without any. Lines are as wide as project.toml’s [format] width, or 100. It changes only the space between tokens and where long lines break, and leaves a file that doesn’t parse as it is, with its errors.

fb doc

fb doc [options] [file.fb | package folder | std]

Writes a package’s public API as JSON, with its /// doc comments, to build/<name>.json, or for std, std.json in the current folder. It warns about each link in a doc comment that names nothing, and each doc comment on nothing. This site’s std reference is made from fb doc std’s JSON.

fb bindgen

fb bindgen <header.h> [options]

Reads a C header with libclang and writes a FutureBlitz module of its declarations, with an Extern block of its functions. See C libraries.

Environment