Projects and the fb command

What you’ll build

A package named greet: a folder with a project.toml and its code, which greets people by name and has tests that check it. On the way you’ll use each of fb’s commands for working on a package. A single .fb file is enough for a small program, as the earlier tutorials showed; a package is how a program grows to several files, gets tests, and uses other packages.

Make a package

fb new makes a folder with a package in it:

fb new greet
cd greet

     Created package greet in greet

The folder holds three files. .gitignore keeps fb’s build/ folder out of Git. project.toml names the package and gives its version:

[project]
name = "greet"
version = "0.1.0"

main.fb is the package’s main file, whose top-level code is the program:

Import std.core

Print("Hello, world!")

Hello, world!

Run it

In the package’s folder, fb run needs no file name: it builds the package the current folder is in, then runs it. fb says what it’s building and running, then the program’s output follows:

fb run

   Compiling greet v0.1.0 (C:/Users/ada/greet)
    Finished debug build in 0.68s
     Running greet.exe
Hello, world!

Arguments after -- go to the program, as in fb run -- Ada.

Add a function and its tests

A test is a function marked @Test, which takes nothing and returns nothing. Expect, from std.test, checks a condition and fails the test when it’s false. fb test builds the package with its tests and runs them, instead of the main file’s top-level code.

[project]
name = "greet"
version = "0.1.0"

Import std.core
Import std.test

Function Greeting(name: String): String
    If name == "" Then Return "Hello!"
    Return "Hello, {name}!"
End Function

Print(Greeting("Ada"))

@Test
Function GreetsByName()
    Expect(Greeting("Ada") == "Hello, Ada!")
End Function

@Test
Function GreetsNobody()
    Expect(Greeting("") == "Hello!")
End Function

     Running 2 tests
test greet.main.GreetsByName ... ok
test greet.main.GreetsNobody ... ok

test result: ok. 2 passed; 0 failed; 0 skipped; 0 filtered out; finished in 0.02s

Each test is named by its package, its module, and its function. A failed Expect shows the condition as written, where it is, and each side of the comparison. fb test --filter Nobody runs only the tests whose names have Nobody in them.

Check, format, and document

Three more commands work on the whole package:

• fb check finds every error the compiler would, without building anything, so it’s fast.
• fb fmt formats the package’s files in place: four-space indents, one space around operators, and lines up to 100 columns wide. fb fmt --check lists the files it would change, for CI.
• fb doc writes the package’s Public declarations as JSON, each with its /// comment, for documentation tools. greet has none, since nothing in it is Public.

fb check
fb fmt

fb check says what it checked. fb fmt prints nothing when every file is formatted already, and a line for each file it changes:

    Checking greet v0.1.0 (C:/Users/ada/greet)
    Finished check in 0.58s

Build it to ship

fb build builds the package into build/, as build/greet.exe on Windows and build/greet on macOS and Linux. A debug build checks for integer overflow and has full debug information. fb build --release optimizes the program, and is the build to give to others: an executable that runs on its own.

fb build --release

   Compiling greet v0.1.0 (C:/Users/ada/greet)
    Finished release build in 0.65s

What you learned

• fb new makes a package: a project.toml, a main.fb, and a .gitignore.
• In a package’s folder, fb’s commands work on that package without a file name.
• @Test functions and std.test’s Expect make tests, which fb test runs.
• fb check checks a package, fb fmt formats it, and fb doc describes its Public API.
• fb build --release builds an optimized executable into build/.