README.md
1# Roboleaf configuration files interpreter
2
3Reads and executes Roboleaf product configuration files.
4
5## Usage
6
7`rbcrun` *options* *VAR=value*... [ *file* ]
8
9A Roboleaf configuration file is a Starlark script. Usually it is read from *file*. The option `-c` allows to provide a
10script directly on the command line. The option `-f` is there to allow the name of a file script to contain (`=`).
11(i.e., `my=file.rbc` sets `my` to `file.rbc`, `-f my=file.rbc` runs the script from `my=file.rbc`).
12
13### Options
14
15`-d` *dir*\
16Root directory for load("//path",...)
17
18`-c` *text*\
19Read script from *text*
20
21`--perf` *file*\
22Gather performance statistics and save it to *file*. Use \
23` go tool prof -top`*file*\
24to show top CPU users
25
26`-f` *file*\
27File to run.
28
29## Extensions
30
31The runner allows Starlark scripts to use the following features that Bazel's Starlark interpreter does not support:
32
33### Load statement URI
34
35Starlark does not define the format of the load statement's first argument.
36The Roboleaf configuration interpreter supports the format that Bazel uses
37(`":file"` or `"//path:file"`). In addition, it allows the URI to end with
38`"|symbol"` which defines a single variable `symbol` with `None` value if a
39module does not exist. Thus,
40
41```
42load(":mymodule.rbc|init", mymodule_init="init")
43```
44
45will load the module `mymodule.rbc` and export a symbol `init` in it as
46`mymodule_init` if `mymodule.rbc` exists. If `mymodule.rbc` is missing,
47`mymodule_init` will be set to `None`
48
49### Predefined Symbols
50
51#### rblf_env
52
53A `struct` containing environment variables. E.g., `rblf_env.USER` is the username when running on Unix.
54
55#### rblf_cli
56
57A `struct` containing the variable set by the interpreter's command line. That is, running
58
59```
60rbcrun FOO=bar myfile.rbc
61```
62
63will have the value of `rblf_cli.FOO` be `"bar"`
64
65### Predefined Functions
66
67#### rblf_file_exists(*file*)
68
69Returns `True` if *file* exists
70
71#### rblf_wildcard(*glob*, *top* = None)
72
73Expands *glob*. If *top* is supplied, expands "*top*/*glob*", then removes
74"*top*/" prefix from the matching file names.
75
76#### rblf_regex(*pattern*, *text*)
77
78Returns *True* if *text* matches *pattern*.
79
80#### rblf_shell(*command*)
81
82Runs `sh -c "`*command*`"`, reads its output, converts all newlines into spaces, chops trailing newline returns this
83string. This is equivalent to Make's
84`shell` builtin function. *This function will be eventually removed*.
85