Elara6331/arsenm-dev-site
Archived
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Add syntax highlighting, edit theme, and revise AdvMake documentation

Browse Source
This commit is contained in:
Elara
2021-02-08 17:47:56 -08:00
parent 618bd6c407
commit cfbe873426
78 changed files with 10443 additions and 570 deletions
Download Patch File Download Diff File Expand all files Collapse all files

498
content/docs/advmake/build-files.md
View File

@@ -7,13 +7,13 @@ description: "Understanding AdvMake Build Files"
{{< button-gitlab color="OrangeRed" project="advmake" text="AdvMake" >}}
### Format
## Format
AdvMake uses [Starlark](https://github.com/bazelbuild/starlark) as the format for its build files.
Extra builtins are also defined for both convenience and extra functionality.
Modules are also defined for both convenience and extra functionality.
Starlark is a Python-like language meant for configuration files.
### Configuration
## 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.
@@ -33,210 +33,442 @@ 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()`.
### Builtins
As previously mentioned, AdvMake comes with extra builtins. Those are as follows:
## Modules
As previously mentioned, AdvMake comes with modules. Those are as follows:
#### `log()`
### `runtime`
The log function uses zerolog in go to log a message to STDOUT. It has two arguments.
The first is a string with the message to log, and the second is `level` which is optional
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
log("Info log") # Default level is info
log("Warn log", level="warn") # Warn level log
log("Debug log", level="debug") # Debug level log
log("Fatal log", level="fatal") # Fatal level log. This will exit the program when executed
x = encoding.Json.Load('{"encoding": "json"}')
# x["encoding"] == "json"
y = encoding.Hex.Load('546573740a')
# y == "Test"
```
---
#### `execute()`
#### `encoding.<Submodule>.Dump()`
The execute function runs a script using `sh -c`. This function has three arguments.
The first is required and is a string with the script to run, the second is `output`
which is optional. It can be set to `return`, `stdout`, or `both`, and the default is `both`.
The `output` argument controls where the script's output will be directed:
- `return`: Returns script output as string
- `stdout`: Prints script output to STDOUT, returning nothing
- `both`: Prints to STDOUT and returns as string
The third argument is `concurrent` which can be either `True` or `False`, default `False`.
If `concurrent` is set to `True`, all the lines in the script will be split and run concurrently
via goroutines. The maximum threads for goroutines can be controlled using the `GOMAXPROCS` environment
variable and is by default the amount of CPU cores present.
Dump a string formatted as the submodule format from a dictionary or string
Examples:
```python
user = execute("whoami") # This will print the username to STDOUT and set the user variable to it
user = execute("whoami", output="return") # This will set the user variable to the username but not print it
execute("""
cp file destination
mv destination destination-1
echo 'hello world'
""") # Example of a multiline script
execute("""
install -Dm755 program /usr/bin
install -Dm755 program.cfg /etc
""", concurrent=True) # Example of a concurrent multiline script
xDict = {"encoding": {"type": "toml"}}
x = encoding.Toml.Dump(xDict)
# x == '''
#
# [encoding]
# type = "toml"
#
# '''
y = encoding.Hex.Dump("Test")
# y = "546573740a"
```
---
#### `getEnv()`
### `file`
The getEnv function simply returns the value of the environment variable specified in its first argument.
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
term = getEnv("TERM") # Sets variable term to value of $TERM
print("Nice " + term) # Prints "Nice $TERM"
file.Exists("/etc/fstab") # True
```
---
#### `setEnv()`
#### `file.Content()`
The setEnv function sets an environment variable. It has three arguments.
The first is the key, it is the name of the environment variable.
The second is the new value, what the key should be set to.
The third is optional, it is `onlyIfUnset` and it can be set to `True` or `False`, default `False`
Definition: `file.Content(filepath)`
`onlyIfUnset` checks that the variable is not already set before setting it, this can be useful for
setting defaults.
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
setEnv("MY_ENV_VAR", "Hello, World") # Sets $MY_ENV_VAR to "Hello, World"
setEnv("CC", "gcc", onlyIfUnset=True) # Sets $CC to "gcc", but only if $CC is not already set
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"
```
---
#### `expandFile()`
#### `strings.HasSuffix()`
The expandFile function replaces all instances of $VAR with the value specified.
Definition: `strings.HasSuffix(string, suffix)`
expandFile has two arguments. The first accepts a filename to modify.
The second accepts a dictionary to act as mappings for value replacements.
Example:
```python
expandFile("a.txt", {"A": "Hello", "B": "World"}) # Replace $A with Hello and $B with world in file a.txt
```
---
#### `download()`
The download function downloads a file at a URL.
download has two arguments. The first is a URL, and the second is an optional
argument called `filename`. If `filename` is not provided, the filename will
be taken from the URL.
Check whether a string ends with a suffix.
Examples:
```python
download("https://www.arsenm.dev/logo-white.png") # Downloads logo-white.png
download("https://www.arsenm.dev/logo-white.png", filename="logo.png") # Downloads logo-white.png as logo.png
strings.HasSuffix("doc.pdf", ".pdf") # True
strings.HasSuffix("doc.pdf", ".md") # False
```
---
#### `lookPath()`
#### `strings.HasPrefix()`
The lookPath function uses go's `exec.LookPath()` to find the absolute path of a command.
It has a single argument which is the command to look for. If a command is not found, lookPath
returns `-1`.
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
lookPath("sh") # /bin/sh
lookPath("nonExistentCommand") # -1
shell.Setenv("X", "x") # $X = x
shell.Setenv("CC", "gcc") # if $CC unset, $CC = gcc
```
---
#### `userChoice()`
#### `shell.LookPath()`
The userChoice function presents the user with a choice. It has two arguments. The first
is a prompt to be displayed to the user, and the second is a list of choices.
Definition: `shell.LookPath(command)`
Example:
```python
userChoice("Choose command", ["find", "ls"])
# This returns:
# [1] "find"
# [2] "ls"
# Choose command:
```
The function will return the chosen object (if input to above is `1`, function returns `"find"`)
---
#### `input()`
The input function is a simple function that uses go's `fmt.Print()` and `fmt.Scanln()` to replicate
the functionality of python's `input()` function. It has a single argument, which is the prompt and returns
the inputted text.
Example:
```python
x = input("Name: ") # This will print "Name: " and then wait for input.
```
---
#### `fileExists()`
The fileExists function checks if a specified file exists and is accessible in the filesystem. It has a single
argument which is the path to the file being checked, and returns a boolean reflecting the state of the file.
Returns the path to the executable of the specified command. Returns `-1` if the command is not found in `PATH`.
Examples:
```python
if fileExists("/etc/passwd"):
print("/etc/passwd exists!") # /etc/passwd exists!
if fileExists("/abcdef"):
print("/abcdef exists!") # No output because /abcdef most likely does not exist
shell.LookPath('sh') # "/bin/sh"
shell.LookPath('nonExistentCommand') # -1
```
---
#### `getOS()`
### `net`
The getOS function returns the value of `runtime.GOOS`. It has no arguments.
The net module contains various network functions
Example:
---
#### `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
if getOS() == "linux":
print("This is Linux!")
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")
```
---
#### `getArch()`
### `log`
The getArch function returns the value of `runtime.GOARCH`. It has no arguments.
The log module contains functions to log events at various levels
Example:
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
if getArch() == "386":
print("x86 32-bit")
log.Info("Test log")
log.Fatal("Error")
```
---
#### `getCPUNum()`
### `fmt`
The getCPUNum function returns the amount of CPUs available to AdvMake. It has no arguments.
The fmt module exposes all the text functions from the golang fmt package except for all the `Fprint` and `Fscan` functions.
Example:
```python
print(getCPUNum() + " CPUs available!")
```
---
fmt.Sprintf("Print %s string", "formatted") # "Print formatted string"
```