FixBuild Documentation

Back to summary

Build scripts

You can build applications using either a build script or just by invoking FixBuild manually using the build parameters. For more information run fixbuild -h.

Build scripts use a partially declarative approach to set the build properties. You can also add your own actions written in FixScript and using the provided simple functions for common tasks. Or, instead, you can just write a normal console program for maximum control. FixBuild works in two modes, either you can build applications manually using the parameters, this mode is used when there is any parameter present with a single dash. Otherwise a file named build.fix is searched in the current and parent directories to execute.

An example of a build script:

use "build";

build {
    verbose: true,
    exclude: ["test", "another"],
    sources: ".",
    resources: "res",
    main: "test/main",
    binary: "example",
    binary_windows32: "example_win32",
    targets: ["windows32", "linux32"],
    gui: true
};

prepare
{
	// runs before any other action (including parsing of parameters)
}

prebuild
{
	// runs before any task and after parsing of parameters
}

postbuild
{
	// runs after a successful build (all tasks) with no errors
}

postbuild-fail
{
	// runs after an unsuccessful build
}

cleanup
{
	// runs after all actions are done (will not run if prepare fails)
}

task example "this will show in --help as a description"
{
	// a custom task named 'example'
}

default task another-example (dep1, dep2)
{
	// a custom task named 'another-example', which is set as a default instead of 'build'
	// it depends on tasks dep1 and dep2
}

task -internal-task ""
{
	// tasks with empty descriptions are removed from --help
}

There are three predefined tasks, build (builds executables for current platform and is the default action), dist (builds executables for all platforms) and clean (cleans generated files). If you define tasks with these names, they will be run after doing the implicit action.

The task names can contain characters, digits and dashes (in any order, including beginning).

You can use @nofail annotation before calling a function to suppress any exceptions. It is just a nicer syntax for var (r, e) = func(...).

Build options

Importing scripts

By default all library scripts are provided internally by FixBuild. There is a build: namespace for build related scripts. Currently only the build:build (the token processor) and the build:common (the common library) scripts are provided. As a shorthand, referencing build script from the initial build.fix script aliases to build:build.

You can also import scripts from files relative to the build script. Simply use a "path/:script" when importing. The important bit is the /: for accessing the files. All the scripts are imported into a global namespace (the script portion of it). To import files in the current directory just use this form: "./:script". The imported scripts refer to their directory implicitly. You can override the internal libraries as long as the scripts from the files are loaded first.

Common functions

These functions are automatically made available by the build token processor. In case you need to import them manually use build:common script name.

function get_builds(): Dynamic[String][String]

Returns the list of builds. These are represented as a hash where the key is the output file name and the value is another hash with the build properties. This list is returned by reference and you can change it.

function get_executable(): String

Returns the executable as passed to the generated main function. The string is returned by reference and you can change it.

function get_arguments(): String[]

Returns the arguments. This list is returned by reference and you can change it.

function get_current_target(): String

Returns the current target name.

function get_available_targets(): String[]

Returns the list of available target names.

function register_task(name: String, func)
function register_task(name: String, func, desc: String)
function register_task(name: String, func, desc: String, deps: String[])


Registers a new task for running. The given function must not have any parameters. You can optionally pass a description and a list of dependencies.

function get_task_list(): String[]

Returns a list of tasks.

function get_task_description(name: String): String

Returns the description of a task.

function set_task_description(name: String, desc: String)

Sets the description of a task.

function get_task_dependencies(name: String): String[]

Returns the list of task dependencies. This list is returned by reference and you can change it.

function get_default_task(): String

Returns the name of the default task.

function set_default_task(name: String)

Sets the name of the default task.

function run_task(name: String): Boolean
function run_task(name: String, force: Boolean): Boolean


Runs the task with given name. Tasks run only once unless forced. Returns true when the task was run.

function show_help()

Outputs a help screen based on the registered tasks.

function build(values: Dynamic[String])

Builds an application using the given properties.

function needs_update(dest: String or String[], src: String or String[]): Boolean

Returns true when the destination needs to be updated because it's either missing or the sources files are newer. Both the destination and the source can be either a single file (string) or array of files (strings).

function makedir(name: String or String[])

Creates a directory and any missing parent directories.

function removedir(name: String or String[])

Removes a directory if it's present.

function remove(name: String or String[])

Removes a file if it's present.

function touch(name: String or String[])

Touches a file (creates a new empty file or updates the modification time to the current time).

function basename(fname: String): String

Strips a path from a file name.

function copy(src: String, dest: String)

Copies a file from source to destination. The destination is overwritten, no metadata such as modification time is preserved.

function matches(pattern: String, value: String): Boolean
function matches_dir(pattern: String, value: String): Boolean


Returns true when the given value matches the pattern. The pattern is a simple string that must match the value exactly with two wildcard characters: ? matches any character and * matches any number of characters (zero or more). The directory variant splits both the pattern and the value by / and tests each part separately (the number of parts must be the same to match).

function find(pattern: String): String[]
function find(pattern: String, dir: String): String[]
function find(pattern: String, dir: String, excludes: String[]): String[]


Returns a list of paths for file names that match given pattern. Optionally you can specify the directory to search from. The pattern is the same as described in the matches function. The excludes are using the directory variant of the pattern.

function run(command: String or String[])
function run(command: String or String[], dir: String)


Runs a command. It is preferred that an array of arguments is used to avoid problems with files with spaces and other problems. When the command is passed as a string there is no escaping support, the string is just split by spaces. Optionally you can specify a directory from where to run the program (it will be set as the current directory for the new process).

function exit()
function exit(code: Integer)


Terminates the current process (optionally with an exit code).

function is_windows(): Boolean
function is_linux(): Boolean
function is_macos(): Boolean
function is_haiku(): Boolean
function is_wasm(): Boolean


Current operating system detection functions.

function get_fixbuild_version(): String

Returns the FixBuild version.

function get_fixbuild_path(): String

Returns path to the FixBuild binary.