From d6ef4639c3bf9735cc931d1171be2ab30b46e59f Mon Sep 17 00:00:00 2001 From: madonuko Date: Wed, 11 Dec 2024 22:16:02 +0800 Subject: [PATCH 1/5] feat(pages/andaman/andax): move from terra/autoupdate --- pages/andaman/andax.mdx | 336 ++++++++++++++++++++++++++++++++ pages/andaman/configuration.mdx | 1 + pages/terra/autoupdate.mdx | 147 +------------- 3 files changed, 340 insertions(+), 144 deletions(-) create mode 100644 pages/andaman/andax.mdx diff --git a/pages/andaman/andax.mdx b/pages/andaman/andax.mdx new file mode 100644 index 0000000..4ea3b04 --- /dev/null +++ b/pages/andaman/andax.mdx @@ -0,0 +1,336 @@ +--- +title: AndaX +description: Scripting with Anda +--- + +# AndaX + +AndaX is a port of the [rhai] scripting language embedded into Andaman. +In short, AndaX is rhai but with extra functions and modules. These functions +make AndaX a very viable choice for pre/post scripts, performing automatic +updates (`anda update`) or just scripting in general. + +For documentations, playground and built-in functions in [rhai], check out their +website. + +This page contains documentation for additional functions and quirks in AndaX. + +you need SEMICOLONS! (`;`) + +## Running AndaX scripts + +To execute a script, use the `anda run myscript.rhai` command: + +```ansi + $ anda run --help +Run .rhai scripts + +Usage: anda run [OPTIONS] [SCRIPTS]... + +Arguments: + [SCRIPTS]... + +Options: + -l, --labels + -v, --verbose... Increase logging verbosity + -q, --quiet... Decrease logging verbosity + -h, --help Print help +``` + +The `--labels` flag can be used to pass in labels. For more information, read +the section [Working with Labels](#working-with-labels). + +As expected, the shebang `#!anda run` may be used. + +## Project Scripts + +Some scripts that exist in the same directory as `anda.hcl` will be executed +during `anda build`. The path to these scripts can be modified in `anda.hcl`: + +```hcl +project "project_name" { + // these are default values. Even when not given in the config file, anda will + // run them if they just exist in the same directory as the config. + pre_script = "pre.rhai" + post_script = "post.rhai" + + rpm { + pre_script = "rpm_pre.rhai" + post_script = "rpm_post.rhai" + } + + // this script is not executed during `anda build`. + // update = "update.rhai" +} +``` + +However, if these options are modified and the extension does not end with +`.rhai`, anda will run these files using `sh -c path/to/file`. + +For more information about `project.*.update` (`update.rhai`), check out the +[Autoupdate section](#autoupdate). + +For more information about the `anda.hcl` configuration file, check out the +[Configuration page](/andaman/configuration). + + +## Special Constants + +```ts +const USER_AGENT = "AndaX"; +const IS_WIN32 = false; // `cfg!(windows)` in rust +const ANDAX_VER = "0.1.3"; // `env!("CARGO_PKG_VERSION")` in rust +``` + +## Custom Functions + +### Networking + +```ts +// `get(link)` is basically a built-in `curl` +let html_content = get("https://fyralabs.com"); + +// if you want more control over how the request can be made: +let req = new_req("https://fyralabs.com"); +req.redirects(max_number_of_redirections_allowed); +req.head("Content-Type", "application/json"); +let html_result = req.get(); + +// github-related version tracking functions +let latest_ver = gh("group/repo_name"); +// for gh repos with tags but not releases, use gh_tag() instead: +let latest_tag = gh_tag("group/repo_name"); +let latest_commit = gh_commit("group/repo_name"); +// "main" refers to the branch here +let raw_readme_content = gh_rawfile("group/repo_name", "main", "README.md"); + +// the above gh functions are also available for gitlab, just replace `gh` with +// `gitlab`, and replace group/repo_name with repoid +// you can also specify the custom domain as the first argument: +// special: need to specify branch for gitlab commits +print(gitlab_commit("gitlab.gnome.org", "1551", "main")); +print(gitlab_tag("25716028")); +// WARN: there is no gitlab_rawfile(). + +// others +let pypi_latest = pypi("example"); +let max_stable_version = crates("anda"); +let max_version = crates_max("anda"); +let newest_version = crates_newest("anda"); +let npm_latest = npm("example"); +``` + +### JSON Operations + +```ts +let obj = json(`{"a": 1}`); +print(obj.a); // 1 +print(obj["a"]); // 1 +let arr = json_arr("[1,2,3]"); +print(arr[1]); // 2 +let str = to_json(obj); +let back_to_map_obj = from_json(str); +``` + +[Maps](https://rhai.rs/book/language/object-maps.html) are also known as +dictionaries in some other languages (like Python). + +### Regex Operations + +```ts +let found = find("(\\d{3})", "abc1c2345", 1); // gets regex group 1 +print(found); // 234 +let substituted = sub("(\\s+)", " ", "I hate spaces !!!"); +print(substituted); // I hate spaces !!! +``` + +### IO and Commands + +```ts +// `sh(command, opts)` is a very complicated function: +// +// ## `command` +// you can supply `command` as a string or an array of strings +// if `command` is a string, `sh -c ` will be used +// otherwise it'll just call `command[0]` with the arguments `command[1..]` +// +// ## `opts` +// `opts` is an `rhai::Map` with the following key-value pairs: (all optional) +// - `stdout`: possible values are "inherit" (default), "null" and "piped". +// - `stderr`: possible values are "inherit" (default), "null" and "piped". +// - `cwd`: path of current working directory as a string +// +// ## Errors +// If you didn't use the function correctly, you will receive the following error: +// +// #{ +// "outcome": "fatal", +// "ctx": #{ +// "kind": "bad_param_type", // or: "empty_cmd_arr" | "bad_stdio_opt" | "bad_stdio_type" +// "expect": "…", // expected type +// "found": "…", // actual type received +// }, +// } +// +// +// If you did use the function correctly but there are some problems running the command: +// (Note: this doesn't include cases where the command itself returns a non-zero exit code) +// +// #{ +// "outcome": "failure", +// "ctx": #{ +// "error": "…", // error message from the rust lib / operating system / idk +// }, +// } +// +// +// Otherwise, the function will return this: +// +// #{ +// "outcome": "success", +// "ctx": #{ +// "stdout": "…", +// "stderr": "…", +// "rc": 0, // or other integers (status code) +// }, +// } +// +// +// Here are some examples: +print(sh("echo hai", #{}).ctx.rc); // most likely 0, and prints out stdout to console in real time, so you will see `hai` then `0` +print(sh(["echo", "hai"], #{ "stdout": "piped" }).ctx.stdout); // hai +print(sh("ls -alh", #{ "cwd": "anda/tools/umstellar/" })); // prints out the command output in real time, then: `#{ "outcome": "success", "ctx": … }` + +for x in ls("/") { + if x == "bin" { + print("I found the `/bin` folder!"); + } +} +let foo = "bar"; +foo.write("bar.txt"); // this might be counterintuitive but the string "bar" is written into the file "bar.txt" +obj.write("tmp.json"); // object (maps) are turned into JSON automatically + +``` + +### Others + +```ts +// === Templates === +print(template(#{a: "value", b: "hai"}, "%{a} and %{b} @{random_rpm_spec_macro}")); +// value and hai %{random_rpm_spec_macro} +// Note that @{} are used to represent rpm macros (they unfortunate conflict) +// `@{` are converted to `%{` automatically. +print(template_file(#{...}, "path/to/a.hcl")); + +// === RPMBuild === +// use these functions with sh() :3 +anda::rpmbuild::cmd_srpm("test.spec", "sources"); // ["mock", "--buildsrpm", "--spec", "test.spec", "--sources", "sources", ...]; +anda::rpmbuild::cmd_rpm("test.spec", "sources"); // ["mock", "--rebuild", ...]; + +// === Anda-Config === +let cfg_map_obj = anda::cfg::load("path/to/anda.hcl"); + +// === Environment Variables === +let env_val = env("KEY"); +``` + +## Working with Labels + +Labels are one of the ways you may pass in runtime variables into the script. +Think of `awk -v var=val` / `awk --assign=var=val` / `nim --define:var=val`. + +To pass in labels, provide them as a comma-separated list to `--labels`. + +A label is a key-value entry, joined together using `=`. In the script, labels +can be accessed using the `labels` variable (a map): + +```ts +// assume run with `anda run myscript.rhai --labels a=1,b=2,c=x=y --labels d=hai` +print(labels["a"]); // 1 +print(labels.b); // 2 +print(labels.get("c")); // x=y +print(labels.remove("d")); // hai +print(labels.get("d") == ()); // true +``` + +## Autoupdate + +Andaman comes with an autoupdate system, readily available via `anda update`: + +```ansi + $ anda update --help +Update all projects + +Usage: anda update [OPTIONS] + +Options: + -l, --labels + Labels to pass to the scripts + + -f, --filters + Only run update scripts in project with the specified labels + + This should be a comma-separated list of filters. Each time `--filters=...` is specified, + the comma-separated list of key-values will be checked against a project. If missing or + different, the project will be ignored. However, specifying `--filters` multiple times + will create an "or" effect --- the project will not be ignored if it satisfies one of the + list of `--filters`. For example, `-f a=1,b=2 -f c=3` means the project needs to satisfy + either "a=1" and "b=2", or only "c=3". + + -e, --excludes + Exclude update scripts in project with the specified labels + + This should be a comma-separated list of excludes. Each time `--exclude=...` is specified, + the comma-separated list of key-values will be checked against the labels of a project, + and it will be ignored if all the key-values are present. In addition, specifying + `--exclude` multiple times will create an "or" effect --- a project will be excluded if it + satisfies one of the list of `--filters`. For example, `-e a=1,b=2 -e c=3` means projects + with "a=1" and "b=2" at the same time, or "c=3", are excluded. Projects with only "a=1" or + "b=2" are not excluded. + + This will always override `--filters`. + + -v, --verbose... + Increase logging verbosity + + -q, --quiet... + Decrease logging verbosity + + -h, --help + Print help (see a summary with '-h') +``` + +The `--labels` flag can be used to pass in labels. For more information, read +the section [Working with Labels](#working-with-labels). + +`anda update` execute all update scripts found in the repository recursively as +defined by the `project.*.update` entry in `anda.hcl` separately: + +```hcl +project "project_name" { + // the default value is "update.rhai" + update = "my_update_script.rhai" +} +``` + +Additionally, the `rpm` object is provided under `anda update`: + +```ts +// note that the `rpm` object is only available in `anda update`, but not `anda run`. +rpm.version(latest_ver); // note that version() resets the release back to 1 automatically +// Source0: https://github.com/FyraLabs/anda/archive/refs/tags/0.1.17.tar.gz +rpm.source(0, "https://github.com/FyraLabs/anda/archive/refs/tags/0.1.17.tar.gz"); +// %define abc hai bai +rpm.define("abc", "hai bai"); +// %global def give rabonuko a headpat! +rpm.global("def", "give rabonuko a headpat!"); +rpm.release(); // resets release to 1: `Release: 1%?dist` +rpm.release(3); // Release: 3%?dist +let spec_content = rpm.f; +rpm.f = new_spec_content; +// returns boolean that determine if the spec content is changed +rpm.changed(); +``` + + +[rhai]: https://rhai.rs diff --git a/pages/andaman/configuration.mdx b/pages/andaman/configuration.mdx index da442b8..42be810 100644 --- a/pages/andaman/configuration.mdx +++ b/pages/andaman/configuration.mdx @@ -32,6 +32,7 @@ project "project_name" { // the string quote is optional plugin_opts { } macros { } opts { } + extra_repos = ["https://link.to/repo"] } podman tagname { dockerfile = "" diff --git a/pages/terra/autoupdate.mdx b/pages/terra/autoupdate.mdx index 1427bf6..e3cd24e 100644 --- a/pages/terra/autoupdate.mdx +++ b/pages/terra/autoupdate.mdx @@ -82,150 +82,9 @@ You can obtain the branch name during runtime in Rhai using `labels.branch` (str #### Functions and Modules -In most cases, `rpm.version(gh("..."));` as a one-liner is enough to make it work™. However, you may also use the following functions: - -```ts -let html_content = get("https://fyralabs.com"); -let latest_ver = gh("group/repo_name"); -let latest_tag = gh_tag("group/repo_name"); // for gh repos with tags but not releases -let latest_commit = gh_commit("group/repo_name"); -// the above gh functions are also available for gitlab, just replace `gh` with `gitlab`, and replace group/repo_name with repoid -// you can also specify the custom domain as the first argument: -print(gitlab_commit("gitlab.gnome.org", "1551", "main")); // special: you need to specify branch for gitlab commits -print(gitlab_tag("25716028")); -let raw_readme_content = gh_rawfile("group/repo_name", "main", "README.md"); // main is the branch -let pypi_latest = pypi("example"); -let max_stable_version = crates("anda"); -let max_version = crates_max("anda"); -let newest_version = crates_newest("anda"); -let npm_latest = npm("example"); - -let env_val = env("KEY"); - -// === Requests === -let req = new_req("https://fyralabs.com"); -req.redirects(max_number_of_redirections_allowed); -req.head("Content-Type", "application/json"); -let html_result = req.get(); - -// === JSON Operations === -let obj = json("{\"a\":1}"); -print(obj.a); // 1 -print(obj["a"]); // 1 -let arr = json_arr("[1,2,3]"); -print(arr[1]); // 2 -let str = to_json(obj); -let back_to_map_obj = from_json(str); - -// === Regex Operations === -let found = find("(\\d{3})", "abc1c2345", 1); // gets regex group 1 -print(found); // 234 -let substituted = sub("(\\s+)", " ", "I hate spaces !!!"); -print(substituted); // I hate spaces !!! - -// === IO and Commands === - -// `sh(command, opts)` is a very complicated function: -// -// ## `command` -// you can supply `command` as a string or an array of strings -// if `command` is a string, `sh -c ` will be used -// otherwise it'll just call `command[0]` with the arguments `command[1..]` -// -// ## `opts` -// `opts` has to be an `rhai::Map`. inside the map, you may have the following key-value pairs: (all are optional) -// - `stdout`: possible values are "inherit" (default), "null" and "piped". -// - `stderr`: possible values are "inherit" (default), "null" and "piped". -// - `cwd`: path of current working directory as a string -// -// ## Errors -// If you didn't use the function correctly, you will receive the following error: -// -// #{ -// "outcome": "fatal", -// "ctx": #{ -// "kind": "bad_param_type", // or: "empty_cmd_arr" | "bad_stdio_opt" | "bad_stdio_type" -// "expect": "…", // expected type -// "found": "…", // actual type received -// }, -// } -// -// -// If you did use the function correctly but there are some problems running the command: -// (Note: this doesn't include cases where the command itself returns a non-zero exit code) -// -// #{ -// "outcome": "failure", -// "ctx": #{ -// "error": "…", // error message from the rust lib / operating system / idk -// }, -// } -// -// -// Otherwise, the function will return this: -// -// #{ -// "outcome": "success", -// "ctx": #{ -// "stdout": "…", -// "stderr": "…", -// "rc": 0, // or other integers (status code) -// }, -// } -// -// -// Here are some examples: -print(sh("echo hai", #{}).ctx.rc); // most likely 0, and prints out stdout to console in real time, so you will see `hai` then `0` -print(sh(["echo", "hai"], #{ "stdout": "piped" }).ctx.stdout); // hai -print(sh("ls -alh", #{ "cwd": "anda/tools/umstellar/" })); // prints out the command output in real time, then the rhai map: `#{ "outcome": "success", "ctx": … }` - -for x in ls("/") { - if x == "bin" { - print("I found the `/bin` folder!"); - } -} -let foo = "bar"; -foo.write("bar.txt"); // this might be counterintuitive but the string "bar" is written into the file "bar.txt" -obj.write("tmp.json"); // object (maps) are turned into JSON automatically - -// === Templates === -print(template(#{a: "value", b: "hai"}, "%{a} and %{b} @{random_rpm_spec_macro}")); -// value and hai %{random_rpm_spec_macro} -// Note that @{} are used to represent rpm macros (they unfortunate conflict) -// `@{` are converted to `%{` automatically. -print(template_file(#{...}, "path/to/a.hcl")); - -// === RPMBuild === -// use these functions with sh() :3 -anda::rpmbuild::cmd_srpm("test.spec", "sources"); // ["mock", "--buildsrpm", "--spec", "test.spec", "--sources", "sources", ...]; -anda::rpmbuild::cmd_rpm("test.spec", "sources"); // ["mock", "--rebuild", ...]; - -// === Anda-Config === -let cfg_map_obj = anda::cfg::load("path/to/anda.hcl"); -``` - -#### Special Variables - -```ts -// === RPM Operations === -// note that the `rpm` object is only available in `anda update`, but not `anda run`. -rpm.version(latest_ver); // note that version() resets the release back to 1 automatically -// Source0: https://github.com/FyraLabs/anda/archive/refs/tags/0.1.17.tar.gz -rpm.source(0, "https://github.com/FyraLabs/anda/archive/refs/tags/0.1.17.tar.gz"); -// %define abc hai bai -rpm.define("abc", "hai bai"); -// %global def give rabonuko a headpat! -rpm.global("def", "give rabonuko a headpat!"); -rpm.release(); // resets release to 1: `Release: 1%?dist` -rpm.release(3); // Release: 3%?dist -let spec_content = rpm.f; -rpm.f = new_spec_content; - -// === Labels and Constants === -const USER_AGENT = "AndaX"; -const IS_WIN32 = false; // `cfg!(windows)` in rust -const ANDAX_VER = "0.1.3"; // `env!("CARGO_PKG_VERSION")` in rust -``` +In most cases, `rpm.version(gh("..."));` as a one-liner is enough to make it work™. +Documentations for more functions are available in the [Andaman +devdocs](/andaman/andax#custom-functions). {/* From 88e3b2433b7035d491b4889edf26af83dcce5c39 Mon Sep 17 00:00:00 2001 From: madonuko Date: Wed, 11 Dec 2024 22:16:13 +0800 Subject: [PATCH 2/5] feat(terra): tidy up policies and srpm macros list --- pages/terra/contributing.mdx | 14 +++++++++----- pages/terra/policy.mdx | 8 ++++---- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/pages/terra/contributing.mdx b/pages/terra/contributing.mdx index 29d1c89..7cd0b74 100644 --- a/pages/terra/contributing.mdx +++ b/pages/terra/contributing.mdx @@ -181,11 +181,15 @@ We provide SPRM macros to ease packaging and better integrate into our workflow. These are provided in the `anda-srpm-macros` package, if you use them, make sure to add `anda-srpm-macros` as a `BuildRequires` in the spec file. -| Macro | Function | -| ------------------------------- | ----------------------------------------------------------------------------------------- | -| `%cargo_prep_online` | Enables internet access for `cargo`. Replaces `%cargo_prep` and should be used in `%prep` | -| `%cargo_license_online` | Replaces `%cargo_license` in `%build` | -| `%cargo_license_summary_online` | Replaces `%cargo_license_summary` in `%build` | +| Macro | Function | +| ------------------------------- | -------------------------------------------------------------------------- | +| `%cargo_prep_online` | Enables internet access for `cargo`. Replaces `%cargo_prep` and in `%prep` | +| `%cargo_license_online` | Replaces `%cargo_license` in `%build` | +| `%cargo_license_summary_online` | Replaces `%cargo_license_summary` in `%build` | +| `%go_prep_online` | Same as `go mod download` | +| `%go_build_online %goipath` | Builds a go package in `%build` | +| `%nim_prep` | Setting up `nimble` | +| `%nim_build` or `%nim_c` | Builds a package. Requires an argument to `src/pkgname` | [andaman]: https://github.com/FyraLabs/anda/ [rpm packaging guide]: https://rpm-packaging-guide.github.io/ diff --git a/pages/terra/policy.mdx b/pages/terra/policy.mdx index 6cc71e3..e215101 100644 --- a/pages/terra/policy.mdx +++ b/pages/terra/policy.mdx @@ -100,14 +100,16 @@ Terra's mock sandbox has networking enabled, so builders can download the depend We encourage the use of `mold`, which may speed up build times especially in large projects. You may enable it in C/++ projects by adding `-fuse-ld=mold` in `CFLAGS`/`CXXFLAGS`. +The `%with_mold` flag is enabled by default in `anda-srpm-macros`. `mold` is also preinstalled in the builders. + +You can disable `mold` in the following languages by using `%bcond_with mold`. + ### Rust - Do not use the tradtional Fedora `%cargo_prep` macro. Use `%cargo_prep_online` from `anda-srpm-macros` instead, and do not use the `%generate_buildrequires` macro, as it is useless. - It is encouraged to use `%cargo_license_online` and `%cargo_license_summary_online`, although they are not a strict requirement. - Avoid using both `%cargo_build` and `%cargo_install` in the same spec file as `cargo install` might cause a rebuild due to a bug. You should only include either one of them. In most cases, you can just omit `%cargo_build` entirely and it will just build fine. -You can enable `mold` by using `%bcond_without mold`. - Example: ``` %prep @@ -143,5 +145,3 @@ install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/ ### Nim Use the `%nim_prep` and `%nim_c src/pkgname` macros. - -add `mold` as a `BuildRequires` to enable mold automatically. From 8d6f5512418fb0f73d34881bc10bc76855ccb52d Mon Sep 17 00:00:00 2001 From: madonuko Date: Wed, 11 Dec 2024 23:01:20 +0800 Subject: [PATCH 3/5] fix(andaman,terra): formatting and random errors --- pages/andaman/andax.mdx | 130 ++++++++++++++++++++--------------- pages/terra/autoupdate.mdx | 9 +-- pages/terra/contributing.mdx | 12 ++-- 3 files changed, 88 insertions(+), 63 deletions(-) diff --git a/pages/andaman/andax.mdx b/pages/andaman/andax.mdx index 4ea3b04..4a5b563 100644 --- a/pages/andaman/andax.mdx +++ b/pages/andaman/andax.mdx @@ -3,6 +3,8 @@ title: AndaX description: Scripting with Anda --- +import { Callout } from "nextra/components"; + # AndaX AndaX is a port of the [rhai] scripting language embedded into Andaman. @@ -146,72 +148,92 @@ print(substituted); // I hate spaces !!! ### IO and Commands +#### `sh(command, opts)` + +**`command`** +You can supply `command` as a string or an array of strings. +If `command` is a string, `sh -c ` will be used. +Otherwise it'll just call `command[0]` with the arguments `command[1..]`. + +**`opts`** +`opts` is an `rhai::Map` with the following key-value pairs: (all optional) +- `stdout`: possible values are "inherit" (default), "null" and "piped". +- `stderr`: possible values are "inherit" (default), "null" and "piped". +- `cwd`: path of current working directory as a string + +**Errors** +If you didn't use the function correctly, you will receive the following error: +```ts +#{ + "outcome": "fatal", + "ctx": #{ + "kind": "bad_param_type", // or: "empty_cmd_arr" | "bad_stdio_opt" | "bad_stdio_type" + "expect": "…", // expected type + "found": "…", // actual type received + }, +} +``` +If you did use the function correctly but there are some problems running the command: +(Note: this doesn't include cases where the command itself returns a non-zero exit code) ```ts -// `sh(command, opts)` is a very complicated function: -// -// ## `command` -// you can supply `command` as a string or an array of strings -// if `command` is a string, `sh -c ` will be used -// otherwise it'll just call `command[0]` with the arguments `command[1..]` -// -// ## `opts` -// `opts` is an `rhai::Map` with the following key-value pairs: (all optional) -// - `stdout`: possible values are "inherit" (default), "null" and "piped". -// - `stderr`: possible values are "inherit" (default), "null" and "piped". -// - `cwd`: path of current working directory as a string -// -// ## Errors -// If you didn't use the function correctly, you will receive the following error: -// -// #{ -// "outcome": "fatal", -// "ctx": #{ -// "kind": "bad_param_type", // or: "empty_cmd_arr" | "bad_stdio_opt" | "bad_stdio_type" -// "expect": "…", // expected type -// "found": "…", // actual type received -// }, -// } -// -// -// If you did use the function correctly but there are some problems running the command: -// (Note: this doesn't include cases where the command itself returns a non-zero exit code) -// -// #{ -// "outcome": "failure", -// "ctx": #{ -// "error": "…", // error message from the rust lib / operating system / idk -// }, -// } -// -// -// Otherwise, the function will return this: -// -// #{ -// "outcome": "success", -// "ctx": #{ -// "stdout": "…", -// "stderr": "…", -// "rc": 0, // or other integers (status code) -// }, -// } -// -// -// Here are some examples: -print(sh("echo hai", #{}).ctx.rc); // most likely 0, and prints out stdout to console in real time, so you will see `hai` then `0` -print(sh(["echo", "hai"], #{ "stdout": "piped" }).ctx.stdout); // hai -print(sh("ls -alh", #{ "cwd": "anda/tools/umstellar/" })); // prints out the command output in real time, then: `#{ "outcome": "success", "ctx": … }` +#{ + "outcome": "failure", + "ctx": #{ + "error": "…", // error message from the rust lib / operating system / idk + }, +} +``` + +Otherwise, the function will return this: +```ts +#{ + "outcome": "success", + "ctx": #{ + "stdout": "…", + "stderr": "…", + "rc": 0, // or other integers (status code) + }, +} +``` +**Examples** +```ts +// shows most likely 0, and prints out stdout to console in real time, so you will see `hai` then `0` +print(sh("echo hai", #{}).ctx.rc); +// shows `hai` +print(sh(["echo", "hai"], #{ "stdout": "piped" }).ctx.stdout); +// prints out the command output in real time, then: `#{ "outcome": "success", "ctx": … }` +print(sh("ls -alh", #{ "cwd": "anda/tools/umstellar/" })); +``` + +#### `ls(dir)` + +Returns an array of strings (files, folders inside the given dir) + +**Examples** +```ts for x in ls("/") { if x == "bin" { print("I found the `/bin` folder!"); } } +``` + +#### `write(text, filepath)` + +Write `text` into `filepath`, overwriting existing content. +```ts let foo = "bar"; -foo.write("bar.txt"); // this might be counterintuitive but the string "bar" is written into the file "bar.txt" +foo.write("bar.txt"); // counterintuitive but the string "bar" is written into the file "bar.txt" obj.write("tmp.json"); // object (maps) are turned into JSON automatically ``` +#### `rhai-fs` + +Visit [the rhai book](https://rhai.rs/book/lib/rhai-fs.html) for the +documentation for `rhai-fs`. + ### Others ```ts diff --git a/pages/terra/autoupdate.mdx b/pages/terra/autoupdate.mdx index e3cd24e..7cca77c 100644 --- a/pages/terra/autoupdate.mdx +++ b/pages/terra/autoupdate.mdx @@ -26,7 +26,7 @@ rpm.version(ver); // updates the version in the spec file using `ver` you need SEMICOLONS! (`;`) -Updates are triggered every 10 minutes using `anda update`. +Updates are triggered every 10 minutes using `anda update{:ansi}`. Actually, the [full command](https://github.com/terrapkg/packages/blob/4767e5b9560f2986accaeb8447fbb4ea742041cf/.github/workflows/update.yml#L27-L31) @@ -39,7 +39,8 @@ Updates are triggered every 10 minutes using `anda update`. #### Nightly packages Nightly packages are updated every 24 hours using -`anda update -vv --filters nightly=1`. Their `anda.hcl` files should look something like this: +`anda update -vv --filters nightly=1{:ansi}`. +Their `anda.hcl` files should look something like this: ```hcl project pkg { @@ -55,7 +56,7 @@ project pkg { #### Per-branch auto-update scripts Terra supports updating a package for specific branches instead of updating a package for all branches. -This is achieved using `--filters updbranch=1 --labels branch=f40` (`f40` is replaced by the branch name). +This is achieved using `--filters updbranch=1 --labels branch=f41{:ansi}` (`f41` is replaced by the branch name). The update command is run every 30 minutes. The `anda.hcl` file should look like this: @@ -82,7 +83,7 @@ You can obtain the branch name during runtime in Rhai using `labels.branch` (str #### Functions and Modules -In most cases, `rpm.version(gh("..."));` as a one-liner is enough to make it work™. +In most cases, `rpm.version(gh("..."));{:ts}` as a one-liner is enough to make it work™. Documentations for more functions are available in the [Andaman devdocs](/andaman/andax#custom-functions). diff --git a/pages/terra/contributing.mdx b/pages/terra/contributing.mdx index 7cd0b74..be96451 100644 --- a/pages/terra/contributing.mdx +++ b/pages/terra/contributing.mdx @@ -28,7 +28,7 @@ Remember, it takes effort to create a package. If you ever need help, hop into ### Preparation - Install [Andaman] on your system and its mock configs - - `sudo dnf install anda terra-mock-configs` via Terra + - `sudo dnf install terra-mock-configs{:ansi}` via Terra - anda is also available via rust crates.io - Use `rust2rpm` for **Rust** packages - Use `pyp2rpm` for **Python** packages @@ -133,11 +133,13 @@ echo "this will also run when building pkg but for installing it into %{buildroo - Having anda installed, run the following command: -```sh -anda build -c terra-rawhide-x86_64 anda/fonts/lovelyfonttype-fonts/pkg +```ansi +anda build -c terra-rawhide-x86_64 anda/fonts/lovelyfonttype-fonts/pkg ``` -If you would like to use the `rpmbuild` mode instead (which will instead not set up a container), add `--rpm-builder=rpmbuild`. Remember to install the build dependencies using `dnf builddep path/to/pkgname.spec`! +If you would like to use the `rpmbuild` mode instead (which will instead not set +up a container), add `--rpm-builder=rpmbuild`. Remember to install the build +dependencies using `sudo dnf builddep path/to/pkgname.spec{:ansi}`! - You don't need to create `pkg`. It's not supposed to exist - Modify the architecture to match your machine @@ -159,7 +161,7 @@ See the "book" (more like guide) for [Rhai](https://rhai.rs/book/). - Create `update.rhai` inside the package folder. - See references from other packages. -- You also need to add `labels { nightly = "1" }` in anda.hcl for nightly packages. +- You also need to add `labels { nightly = "1" }{:hcl}` in anda.hcl for nightly packages. Remember to add semicolons in Rhai scripts! (`;`) From bc69e6b68da67b87f1e93b9be42eff3ecf0056ba Mon Sep 17 00:00:00 2001 From: madonuko Date: Thu, 12 Dec 2024 01:36:55 +0800 Subject: [PATCH 4/5] fix(terra/contributing): typo --- pages/terra/contributing.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/pages/terra/contributing.mdx b/pages/terra/contributing.mdx index be96451..b36da8c 100644 --- a/pages/terra/contributing.mdx +++ b/pages/terra/contributing.mdx @@ -183,15 +183,15 @@ We provide SPRM macros to ease packaging and better integrate into our workflow. These are provided in the `anda-srpm-macros` package, if you use them, make sure to add `anda-srpm-macros` as a `BuildRequires` in the spec file. -| Macro | Function | -| ------------------------------- | -------------------------------------------------------------------------- | -| `%cargo_prep_online` | Enables internet access for `cargo`. Replaces `%cargo_prep` and in `%prep` | -| `%cargo_license_online` | Replaces `%cargo_license` in `%build` | -| `%cargo_license_summary_online` | Replaces `%cargo_license_summary` in `%build` | -| `%go_prep_online` | Same as `go mod download` | -| `%go_build_online %goipath` | Builds a go package in `%build` | -| `%nim_prep` | Setting up `nimble` | -| `%nim_build` or `%nim_c` | Builds a package. Requires an argument to `src/pkgname` | +| Macro | Function | +| ------------------------------- | ---------------------------------------------------------------------- | +| `%cargo_prep_online` | Enables internet access for `cargo`. Replaces `%cargo_prep` in `%prep` | +| `%cargo_license_online` | Replaces `%cargo_license` in `%build` | +| `%cargo_license_summary_online` | Replaces `%cargo_license_summary` in `%build` | +| `%go_prep_online` | Same as `go mod download` | +| `%go_build_online %goipath` | Builds a go package in `%build` | +| `%nim_prep` | Setting up `nimble` | +| `%nim_build` or `%nim_c` | Builds a package. Requires an argument to `src/pkgname` | [andaman]: https://github.com/FyraLabs/anda/ [rpm packaging guide]: https://rpm-packaging-guide.github.io/ From 85e53cd4bd4be65afeec9727eba6b53dbe600f09 Mon Sep 17 00:00:00 2001 From: madonuko Date: Thu, 12 Dec 2024 18:17:26 +0800 Subject: [PATCH 5/5] chore: more formatting --- pages/andaman/andax.mdx | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/pages/andaman/andax.mdx b/pages/andaman/andax.mdx index 4a5b563..9963c4f 100644 --- a/pages/andaman/andax.mdx +++ b/pages/andaman/andax.mdx @@ -10,7 +10,7 @@ import { Callout } from "nextra/components"; AndaX is a port of the [rhai] scripting language embedded into Andaman. In short, AndaX is rhai but with extra functions and modules. These functions make AndaX a very viable choice for pre/post scripts, performing automatic -updates (`anda update`) or just scripting in general. +updates (`anda update{:ansi}`) or just scripting in general. For documentations, playground and built-in functions in [rhai], check out their website. @@ -21,7 +21,7 @@ This page contains documentation for additional functions and quirks in AndaX. ## Running AndaX scripts -To execute a script, use the `anda run myscript.rhai` command: +To execute a script, use the `anda run myscript.rhai{:ansi}` command: ```ansi  $ anda run --help @@ -39,7 +39,7 @@ Run .rhai scripts -h, --help Print help ``` -The `--labels` flag can be used to pass in labels. For more information, read +The *`--labels`* flag can be used to pass in labels. For more information, read the section [Working with Labels](#working-with-labels). As expected, the shebang `#!anda run` may be used. @@ -67,9 +67,9 @@ project "project_name" { ``` However, if these options are modified and the extension does not end with -`.rhai`, anda will run these files using `sh -c path/to/file`. +`.rhai`, anda will run these files using `sh -c path/to/file{:ansi}`. -For more information about `project.*.update` (`update.rhai`), check out the +For more information about `project.*.update{:hcl}` (`update.rhai`), check out the [Autoupdate section](#autoupdate). For more information about the `anda.hcl` configuration file, check out the @@ -261,7 +261,7 @@ let env_val = env("KEY"); Labels are one of the ways you may pass in runtime variables into the script. Think of `awk -v var=val` / `awk --assign=var=val` / `nim --define:var=val`. -To pass in labels, provide them as a comma-separated list to `--labels`. +To pass in labels, provide them as a comma-separated list to *`--labels`*. A label is a key-value entry, joined together using `=`. In the script, labels can be accessed using the `labels` variable (a map): @@ -277,7 +277,7 @@ print(labels.get("d") == ()); // true ## Autoupdate -Andaman comes with an autoupdate system, readily available via `anda update`: +Andaman comes with an autoupdate system, readily available via `anda update{:ansi}`: ```ansi  $ anda update --help @@ -322,11 +322,11 @@ Update all projects Print help (see a summary with '-h') ``` -The `--labels` flag can be used to pass in labels. For more information, read +The *`--labels`* flag can be used to pass in labels. For more information, read the section [Working with Labels](#working-with-labels). -`anda update` execute all update scripts found in the repository recursively as -defined by the `project.*.update` entry in `anda.hcl` separately: +`anda update{:ansi}` execute all update scripts found in the repository recursively as +defined by the `project.*.update{:hcl}` entry in `anda.hcl` separately: ```hcl project "project_name" { @@ -335,7 +335,7 @@ project "project_name" { } ``` -Additionally, the `rpm` object is provided under `anda update`: +Additionally, the `rpm` object is provided under `anda update{:ansi}`: ```ts // note that the `rpm` object is only available in `anda update`, but not `anda run`.