# FixBuild Documentation

Back to summary

## Build scripts

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

Build scripts use a partially declarative approach to set 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 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

Property | Type | Parameter | Description
--- | --- | --- | ---
verbose | boolean | -v | enables verbose mode
noprocessors | boolean | -np | disables running of token processors
nocompress | boolean | -nc | disables compression of the scripts
exclude | array of strings | -ex | excludes given file names and directories from processing
sources | string | -src | specifies a directory with the sources (the current directory is used by default)
resources | string | -res | embeds resources from given directory
main | string | -m | the name of the main script (must be specified)
targets | array of strings | -t | a list of platform targets, either full list, or list of disallowed targets (by prepending them with '`-`')
binary | string | -o | the output executable file (defaults to the same name as the main script)
binary_<target> | string | -o | alternative executable file for specific platform target
gui | boolean | -g | enables building of a GUI application (experimental)

### 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 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)
function run_task(name: String, force: Boolean)
`
  Runs the task with given name. Tasks are run only once unless forced.
`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 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
`
  Current operating system detection functions.