476 lines
9.6 KiB
Markdown
476 lines
9.6 KiB
Markdown
---
|
|
title: "Build Files"
|
|
draft: false
|
|
description: "Understanding AdvMake Build Files"
|
|
---
|
|
{{< button-gitea color="green" project="advmake" text="AdvMake" >}}
|
|
{{< button-gitlab color="OrangeRed" project="advmake" text="AdvMake" >}}
|
|
|
|
|
|
## Format
|
|
AdvMake uses [Starlark](https://github.com/bazelbuild/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:
|
|
```python
|
|
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.
|
|
|
|
{{< button text="Godoc" bgcolor="#00ACD7" fgcolor="white" icon="cib:go" link="https://pkg.go.dev/runtime#GOOS" >}}
|
|
|
|
---
|
|
|
|
#### `runtime.GOARCH`
|
|
|
|
Stores a string denoting the CPU architecture being used.
|
|
|
|
{{< button text="Godoc" bgcolor="#00ACD7" fgcolor="white" icon="cib:go" link="https://pkg.go.dev/runtime#GOARCH" >}}
|
|
|
|
---
|
|
|
|
#### `runtime.NumCPU()`
|
|
|
|
Get the number of logical CPUs available to the current process
|
|
|
|
{{< button text="Godoc" bgcolor="#00ACD7" fgcolor="white" icon="cib:go" link="https://pkg.go.dev/runtime#NumCPU" >}}
|
|
|
|
---
|
|
|
|
#### `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
|
|
|
|
{{< button text="Godoc" bgcolor="#00ACD7" fgcolor="white" icon="cib:go" link="https://pkg.go.dev/runtime#GOMAXPROCS" >}}
|
|
|
|
|
|
---
|
|
|
|
### `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:
|
|
```python
|
|
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:
|
|
```python
|
|
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:
|
|
```text
|
|
I am running on $OS and architecture $arch
|
|
```
|
|
|
|
Code:
|
|
```python
|
|
file.Expand("file.txt", {"OS": runtime.GOOS, "arch": runtime.GOARCH})
|
|
```
|
|
|
|
`file.txt` after:
|
|
|
|
```text
|
|
I am running on linux and architecture x86_64
|
|
```
|
|
|
|
---
|
|
|
|
#### `file.Exists()`
|
|
|
|
Definition: `file.Exists(filepath)`
|
|
|
|
Check whether a file exists
|
|
|
|
Example:
|
|
```python
|
|
file.Exists("/etc/fstab") # True
|
|
```
|
|
|
|
---
|
|
|
|
#### `file.Content()`
|
|
|
|
Definition: `file.Content(filepath)`
|
|
|
|
Returns contents of a file as a string
|
|
|
|
Example:
|
|
|
|
file.txt:
|
|
```text
|
|
This is a file
|
|
```
|
|
|
|
Code:
|
|
```python
|
|
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:
|
|
```python
|
|
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:
|
|
```python
|
|
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:
|
|
```python
|
|
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:
|
|
```python
|
|
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:
|
|
```python
|
|
strings.TrimPrefix("doc.pdf", "doc") # ".pdf"
|
|
```
|
|
|
|
---
|
|
|
|
#### `strings.TrimSpace()`
|
|
|
|
Definition: `strings.TrimSpace(string)`
|
|
|
|
Trim leading and trailing white space, as defined by Unicode
|
|
|
|
Example:
|
|
```python
|
|
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:
|
|
```python
|
|
input.Prompt("Enter number: ")
|
|
```
|
|
|
|
---
|
|
|
|
#### `input.Choice()`
|
|
|
|
Definition: `input.Choice(prompt, choices)`
|
|
|
|
Assign number to each choice and prompt user to choose one
|
|
|
|
Example:
|
|
```python
|
|
input.Choice("Choose greeting", ["Hi", "Hello", "Good morning"])
|
|
```
|
|
The above example looks like this to the user:
|
|
```text
|
|
[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:
|
|
```python
|
|
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"
|
|
```
|
|
|
|
{{< button text="Godoc" bgcolor="#00ACD7" fgcolor="white" icon="cib:go" link="https://pkg.go.dev/net/url#URL" >}}
|
|
|
|
---
|
|
|
|
### `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:
|
|
```python
|
|
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:
|
|
```text
|
|
12:00:00 AM
|
|
MTI6MDA6MDAgQU0K
|
|
```
|
|
|
|
---
|
|
|
|
#### `shell.Getenv()`
|
|
|
|
Definition: `shell.Getenv(key)`
|
|
|
|
Returns the value of an environment variable
|
|
|
|
Example:
|
|
```python
|
|
shell.Getenv('TERM') # "xterm"
|
|
```
|
|
|
|
{{< button text="Godoc" bgcolor="#00ACD7" fgcolor="white" icon="cib:go" link="https://pkg.go.dev/os#Getenv" >}}
|
|
|
|
---
|
|
|
|
#### `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:
|
|
```python
|
|
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:
|
|
```python
|
|
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:
|
|
```python
|
|
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:
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
fmt.Sprintf("Print %s string", "formatted") # "Print formatted string"
|
|
```
|
|
|
|
{{< button text="Godoc" bgcolor="#00ACD7" fgcolor="white" icon="cib:go" link="https://pkg.go.dev/fmt" >}} |