⇐ AdvMake Docs

# Build Files

AdvMake AdvMake

## Format#

AdvMake uses Starlark as the format for its build files. Modules are also defined for both convenience and extra functionality.

Starlark is a Python-like language meant for configuration files.

## Configuration#

Build files are by default called `AdvMakefile`, but that can be set via `-f`

An AdvMakefile example can be found at AdvMake’s repo as it uses AdvMake itself.

AdvMake runs functions exposed by starlark in the format `<name>_<target>`. To set the default name and target, the global variables `defaultName`, and `defaultTarget` must be set. Here is an example from AdvMake’s AdvMakefile:

    defaultName = "advmake"
    defaultTarget = "build"

This will tell AdvMake to run the function `advmake_build()` when run with no arguments.

If AdvMake is run with one argument (such as `advmake install`), it will use the default name with the specified target, so in that case, it would run `advmake_install()`.

If run with two arguments, AdvMake will use the first argument as the name and the second as the target. So, running `advmake hello world` would run the function `hello_world()`.

## Modules#

As previously mentioned, AdvMake comes with modules. Those are as follows:

### `runtime` #

The runtime module exposes some of golang’s runtime methods and variables.

#### `runtime.GOOS` #

Stores a string denoting the operating system being used.

Godoc

#### `runtime.GOARCH` #

Stores a string denoting the CPU architecture being used.

Godoc

#### `runtime.NumCPU()` #

Get the number of logical CPUs available to the current process

Godoc

#### `runtime.GOMAXPROCS()` #

Definition: `runtime.GOMAXPROCS(n)`

Get or set the value of the GOMAXPROCS environment variable. This variable controls the maximum number of CPUs that can execute. This function will set GOMAXPROCS to n and then return the previous value. If `n<1`, this function will not set the variable and will instead return the current setting

Godoc

### `encoding` #

The strings module contains functions for encoding and decoding various formats. This module contains submodules for the various formats

Available submodules:

- `Json`
- `Yaml`
- `Toml`
- `Hex`

#### `encoding.<Submodule>.Load()` #

Load a string formatted as the submodule format into a dictionary or string.

Examples:

    x = encoding.Json.Load('{"encoding": "json"}')
    # x["encoding"] == "json"
    y = encoding.Hex.Load('546573740a')
    # y == "Test"

#### `encoding.<Submodule>.Dump()` #

Dump a string formatted as the submodule format from a dictionary or string

Examples:

    xDict = {"encoding": {"type": "toml"}}
    x = encoding.Toml.Dump(xDict)
    # x == '''
    #
    # [encoding]
    #   type = "toml"
    #
    # '''
    y = encoding.Hex.Dump("Test")
    # y = "546573740a"

### `file` #

The file module contains functions for manipulation and checking of files

#### `file.Expand()` #

Definition: `file.Expand(file, mappings)`

Expand any instances of `$VAR` in a file according to provided mappings.

Examples:

`file.txt` before:

    I am running on $OS and architecture $arch

Code:

    file.Expand("file.txt", {"OS": runtime.GOOS, "arch": runtime.GOARCH})

`file.txt` after:

    I am running on linux and architecture x86_64

#### `file.Exists()` #

Definition: `file.Exists(filepath)`

Check whether a file exists

Example:

    file.Exists("/etc/fstab") # True

#### `file.Content()` #

Definition: `file.Content(filepath)`

Returns contents of a file as a string

Example:

file.txt:

    This is a file

Code:

    file.Content("file.txt") # "This is a file"

### `strings` #

The strings module contains functions for the manipulation of strings

#### `strings.Regex()` #

Definition: `strings.Regex(string, pattern, regex)`

Parse a string using a regular expression and return the result in the specified format.

Examples:

    x = strings.Regex("Hello, World", "$2, $1", "(.+), (.+)")
    # x == "World, Hello"
    y = strings.Regex("Hello, World", "$y, $x", "(?P<x>.+), (?P<y>.+)")
    # y == "World, Hello"
    z = strings.Regex("Hello, World", "$match, $2, $1", "(.+), (.+)")
    # z == "Hello, World, World, Hello"

#### `strings.HasSuffix()` #

Definition: `strings.HasSuffix(string, suffix)`

Check whether a string ends with a suffix.

Examples:

    strings.HasSuffix("doc.pdf", ".pdf") # True
    strings.HasSuffix("doc.pdf", ".md") # False

#### `strings.HasPrefix()` #

Definition: `strings.HasPrefix(string, prefix)`

Check whether a string starts with a prefix.

Example:

    strings.HasPrefix("doc.pdf", "doc") # True

#### `strings.TrimSuffix()` #

Definition: `strings.HasSuffix(string, suffix)`

Remove suffix from string if it exists. If it does not exist, the string is returned unchanged.

Example:

    strings.TrimSuffix("doc.pdf", ".pdf") # "doc"

#### `strings.TrimPrefix()` #

Definition: `strings.TrimPrefix(string, prefix)`

Remove prefix from string if it exists. If it does not exist, the string is returned unchanged.

Example:

    strings.TrimPrefix("doc.pdf", "doc") # ".pdf"

#### `strings.TrimSpace()` #

Definition: `strings.TrimSpace(string)`

Trim leading and trailing white space, as defined by Unicode

Example:

    strings.TrimSpace("    Hi  ") # "Hi"

### `input` #

The input module prompts the user for input

#### `input.Prompt()` #

Definition: `input.Prompt(prompt)`

Print prompt and wait for input, returning on newline

Example:

    input.Prompt("Enter number: ")

#### `input.Choice()` #

Definition: `input.Choice(prompt, choices)`

Assign number to each choice and prompt user to choose one

Example:

    input.Choice("Choose greeting", ["Hi", "Hello", "Good morning"])

The above example looks like this to the user:

    [1] "Hi"
    [2] "Hello"
    [3] "Good Morning"
    Choose greeting:

When the user chooses a number, the function will return the associated string. So, if the user chooses 1, `"Hi"` will be returned.

### `url` #

The url module contains functions for the manipulation of URLs

#### `url.Parse()` #

Definition: `url.Parse(urlString)`

Parses a URL and returns its components

Example:

    parsed = url.Parse("https://www.arsenm.dev/docs/advmake/build-files")
    # parsed.Scheme == "https"
    # parsed.Host == "www.arsenm.dev"
    # parsed.Path == "/docs/advmake/build-files"

Godoc

### `shell` #

The shell module contains functions for accessing and utilizing the shell.

#### `shell.Exec()` #

Definition: `shell.Exec(command, output?, concurrent?)`

Runs a command or script using `sh -c`, sending the output to `STDOUT` and returning it unless set otherwise. It can also be concurrent.

Examples:

Code:

    x = shell.Exec("date +%r") # "12:00:00 AM"
    y = shell.Exec("date +%r", output='return') # "12:00:00 AM"
    z = shell.Exec("date +%r | base64", output='stdout') # None
    shell.Exec("""
    	sleep 1
    	sleep 2
    """, concurrent=True) # Sleeps for two seconds

STDOUT:

    12:00:00 AM
    MTI6MDA6MDAgQU0K

#### `shell.Getenv()` #

Definition: `shell.Getenv(key)`

Returns the value of an environment variable

Example:

    shell.Getenv('TERM') # "xterm"

Godoc

#### `shell.Setenv()` #

Definition: `shell.Setenv(key, value, onlyIfUnset?)`

Sets the value of an environment variable. It can be configured not to set the value if it is already set

Examples:

    shell.Setenv("X", "x")  # $X = x
    shell.Setenv("CC", "gcc") # if $CC unset, $CC = gcc

#### `shell.LookPath()` #

Definition: `shell.LookPath(command)`

Returns the path to the executable of the specified command. Returns `-1` if the command is not found in `PATH`.

Examples:

    shell.LookPath('sh') # "/bin/sh"
    shell.LookPath('nonExistentCommand') # -1

### `net` #

The net module contains various network functions

#### `net.Download()` #

Download a file from a URL, optionally specifying the filename. It will show progress if the `Content-Length` header is present.

Examples:

    net.Download("https://minio.arsenm.dev/advmake/0.0.1/advmake-linux-x86_64")
    net.Download("https://minio.arsenm.dev/advmake/0.0.1/advmake-linux-x86_64", filename="advmake")

### `log` #

The log module contains functions to log events at various levels

The available levels are:

- `Info`
- `Debug`
- `Warn`
- `Fatal`

#### `log.<Level>()` #

Definition: `log.<Level>(message)`

Logs a message at the specified level. The fatal level quits after logging the message.

Examples:

    log.Info("Test log")
    log.Fatal("Error")

### `fmt` #

The fmt module exposes all the text functions from the golang fmt package except for all the `Fprint` and `Fscan` functions.

    fmt.Sprintf("Print %s string", "formatted") # "Print formatted string"

Godoc