ctbt

ctbt runs BT scripts and builds them into standalone programs: command-line tools, servers, build helpers, anything that is not a game. (Games are built with ctgame.)

Common commands

Run a script, passing it arguments:

ctbt run tool.bt --verbose input.txt

Build a standalone executable:

ctbt build -o hello hello.bt

Build a .ctbt file you can debug in an editor:

ctbt artifact --debug -o program.ctbt --target src/

The program

A program must have a main function that takes no parameters and returns void or int:

include "io";

infallible fn main() -> int {
    println("Hello!");
    return 0;
}

The program's exit status is the int that main returns (0 for void). If main fails, the program prints btlang: MESSAGE and exits with status 1. Command-line arguments are passed to the program; argument zero is the program's own path.

Subcommands

Subcommand	What it does
run	Compiles the script in memory and runs it. Every argument after the script goes to the program, including ones starting with -.
build (default)	Writes a standalone executable. ctbt hello.bt is the same as ctbt build hello.bt.
artifact	Writes a portable .ctbt file of compiled code, which you run with bt-run (below). With --debug it can be debugged.
associate	Windows only. Lets you open .bt files with ctbt run by double-clicking. associate --remove undoes it.

Inputs

Give one or more .bt files or folders. A file brings in everything it includes. A folder brings in every .bt file under it, skipping folders whose names start with . and folders named node_modules, build, build-* or cmake-*. --target FILE_OR_FOLDER names a single input instead.

ctbt finds include roots by looking for bt.module.json files, and game.json files with a module section, in the source's folder and every folder above it. --module-file adds one explicitly.

Options

Option	Default	Description
-o, --output PATH	The first source without .bt (.exe on Windows), or .ctbt for artifact, next to that source	Output file. Not used by run.
--target FILE_OR_FOLDER	none	Use this single input instead of a list. Not used by run.
--debug	off	Include what a debugger needs (source, local names, line numbers). Needed to debug with bt-dap or an editor. Not used by run.
--bttls	off	Include native TLS (HTTPS) support. Only for build and run, not with --debug, and only if your ctbt was built with it.
--jobs N	4	Number of files compiled in parallel, 1 to 32.
--module-file FILE	found automatically	A bt.module.json, or a game manifest whose module section maps include roots.

Warnings are printed as FILE:LINE:COLUMN: warning: MESSAGE and do not stop the build.

Scripts as commands

Linux: put #!/usr/bin/env -S ctbt run on the first line, save with LF line endings, and chmod +x the file. Then run it as ./tool.bt.

Windows: run ctbt associate once. .bt files then open with ctbt run. It only changes settings for your user, and does not replace a default you already chose for .bt files.

Running a .ctbt file

bt-run runs a file made by ctbt artifact:

bt-run program.ctbt input.txt

It does not accept .bt source; use ctbt run for that. Editors use bt-run to debug programs built with --debug.

Built executables

A built executable needs libwinpthread-1.dll next to it on Windows MinGW builds (ctbt copies it there); otherwise it is self-contained. ctbt build works on Windows and Linux.

Errors

Message	What to do
BT target must be an existing .bt file or directory: PATH	Check the path; files need a .bt extension.
no .bt files were found under 'DIR'	The folder has no BT sources (or they are in skipped folders).
run expects one source file; -o, --target and --debug are build options	Remove those options from run, or use build/artifact.
BT native entry 'main' was not found	Add a main function.
BT native entry 'main' must take no parameters / must return void or int	Change main's signature. Read arguments with the standard library instead.
could not open the adjacent native runtime stub or output executable	ctbt is missing files from its install folder, or the output path is not writable.
this ctbt build has no optional BtTLS provider	This ctbt was built without TLS support; drop --bttls.
--bttls currently supports the release runtime only / --bttls requires a native executable build	Use --bttls only with build or run, without --debug.
associate is supported on Windows; on Linux use a shebang	See Scripts as commands.
bt-run: PATH is BT source; ...	Compile it with ctbt artifact, or use ctbt run.
bt-run: BT debugging requires an artifact built with --debug	Rebuild the .ctbt with --debug.

Compile errors are printed as FILE:LINE:COLUMN: error: MESSAGE.

See also

BT language guide, bt-dap, Editor integrations