Skip to content

Latest commit

 

History

History
224 lines (163 loc) · 4.63 KB

docs.md

File metadata and controls

224 lines (163 loc) · 4.63 KB
layout
doc

Usage example

minimal setup

compiler(VERSION MIN 0.7.9)
project(example VERSION 0.1.0 AUTHOR "John")
-- VERSION and AUTHOR are optional

add("src/main.c3") -- assuming that this file exists

program(example)

Functions

compiler()

compiler() defines the compiler version

compiler(VERSION 0.7.5)
compiler(VERSION MIN 0.7.5)
compiler(VERSION MAX 0.7.9)
compiler(VERSION MIN 0.7.5 MAX 0.7.9)

project()

project() defines the basic project info and is required for the script to function.

project(example VERSION 0.1.0 AUTHOR "John")

require()

require() exits the build file if the requested file could not be found.

require(LIB "LLVM") -- creates a variable `lib_llvm`
require(EXE "git")  -- creates a variable `exe_git`

find()

unlike require(), find() does not exit the script if the file cannot be found.

find(LIB "LLVM") -- creates a variable `lib_llvm`
find(EXE "git")  -- creates a variable `exe_git`

ifdef()

ifdef() provides a body whose statements will be run if the variable is defined.

find(EXE "git")

ifdef(exe_git)
    ...
endif()

option()

option() lets you add compile options to the command.

option("--trust=full")
option("-D EXAMPLE")

task()

task() lets you define a task that can be run by the script.

task("example")
    ...
endtask()

It can then be run like this

c3build example

You can also chain multiple tasks

c3build clean install example

cmd()

cmd() lets you execute terminal commands.

cmd("chmod +x ./program")

program()

program() is what executes the compile command so it should always be at the end of the file.

project(example VERSION 0.1.0)
program(example) -- name must match with project name

you can also tell the compiler what to link with and it should be done this way

...
require(LIB "LLVM")

program(example LINK lib_llvm) -- name must match with project name

create()

create() allows you to create files and folders.

create(DIR "$(HOME)/example")
create(FILE "$(HOME)/example/test.txt")

copy()

copy() allows you to copy files and folders.

copy(DIR "./example" "$(HOME)/example")
copy(FILE "./test.txt" "$(HOME)/example/test.txt")

print()

print() allows you to print to the console.

print("example message")

remove()

remove() allows you to delete files and folders.

remove(DIR "$(HOME)/example")
remove(FILE "$(HOME)/example/test.txt")

add()

add() lets you add files to the compile command.

add("src/main.c3"
    "src/other.c3")
add("lib/") -- you can also add directories

Variables

when using require() or find() a variable gets created. The variable can be used to check if the executable or library was found and if so, it returns the path to the file. A variable can either be prefixed by lib_ or exe_ depending on the first parameter (LIB or EXE). Variables can be used in strings for the functions option, cmd, create, copy, print and remove with the following syntax: $(VAR_NAME)

Builtins

HOME - points to the home directory
PROJECT - points to the project name
VERSION - points to the project version
AUTHOR - points to the project author
OS_WINDOWS - can only be used for ifdef and will result in empty string if used otherwise
OS_DARWIN - can only be used for ifdef and will result in empty string if used otherwise
OS_LINUX - can only be used for ifdef and will result in empty string if used otherwise

Custom

You can also create variables like this

PERSON = "John"

print("Hello $(PERSON)")

Additionally, you can reference variables in other variables

FOO = "foo"
BAR = "bar"
FOO_BAR = "$(FOO)$(BAR)"

Variable Injection

c3build allows you to inject the AUTHOR and VERSION into c3. You can create constants in a file called c3build.c3 anywhere in your project like so ::: code-group

module version;

const VERSION = "@@VERSION@@";
const AUTHOR  = "@@AUTHOR@@";

::: Note that the constant names and module themselves are not important, only the string is.

Installing

As of now c3build does not offer any prebuilt binaries and must be built from source.

git clone https://github.com/c3build/c3-build-file.git
cd c3-build-file
./bootstrap.sh

or if on Windows

git clone https://github.com/c3build/c3-build-file.git
cd c3-build-file
./bootstrap.ps1

and that's it!