Prebuilt native modules
A package with a native module ([native.NAME] with a build table in agentica.toml) can ship one prebuilt library per target, so that its users need no C compiler. The reusable workflow native-prebuilt.yml of this repository makes those files:
- it builds the module on the five targets with the toolchains of Agentica's own releases: zig cc against glibc 2.28 on
linux-x86_64andlinux-arm64, Apple clang withMACOSX_DEPLOYMENT_TARGET=12.0onmacos-x86_64andmacos-arm64, and MSYS2 UCRT64 gcc onwindows-x86_64; - the compiler gets the same arguments as Agentica's own build of the
buildtable, thenextra-args, and the library is stripped; - it checks each library: glibc 2.28 at most and only glibc's libraries with no RPATH on Linux,
minos12.0 and only system libraries on macOS, only Windows and UCRT DLLs on Windows, and one export,agentica_native_init; then it loads it in a plain process; - it runs
agentica native source NAMEand uploadslib{name}-{api}-{target}{ext}to the releasenative-<source>of your repository, which it creates when it is missing (on the tagnative-<source>when that exists, else at the commit of the run); - it prints the
prebuiltrow with itssha256table, ready to paste under[native.NAME], in the job summary.
The files are named by the source key, which covers the build table and the files of native/. When the committed agentica.toml has a prebuilt row with this key and API, the row pins the release: each file it names must be there with its sha256, or the run fails, and the files are kept. A target the row leaves out, or every target when there is no row, gets the fresh build; it replaces a file of the same name only in a run on the default branch or on the tag native-<source>, and elsewhere the run fails. Every check comes before the first upload. The job summary always shows the row of the fresh build, and after an upload the row of the release. A run for a pull request never uploads, whatever the caller passes.
Use #
Call it from a workflow of your repository, pinned by commit. The build jobs read only; the upload job takes the permissions of your job, and uploading needs contents: write. Give a pull request a job of its own with dry-run: true and contents: read:
on:
push:
tags: ['native-*']
pull_request:
paths: ['native/**', 'agentica.toml']
workflow_dispatch:
permissions:
contents: read
jobs:
check:
if: github.event_name == 'pull_request'
uses: agentica-lang/packages/.github/workflows/native-prebuilt.yml@COMMIT
with:
module: db_sqlite
agentica-version: 0.34.0
agentica-sha256: SHA256_OF_THE_LINUX_X86_64_ARCHIVE
dry-run: true
upload:
if: github.event_name != 'pull_request'
permissions:
contents: write
uses: agentica-lang/packages/.github/workflows/native-prebuilt.yml@COMMIT
with:
module: db_sqlite
agentica-version: 0.34.0
agentica-sha256: SHA256_OF_THE_LINUX_X86_64_ARCHIVEA run by hand can build any branch once the workflow file is on the default branch: gh workflow run native-prebuilt.yml --ref BRANCH. A push of the tag native-<source> runs it too (agentica native source NAME prints the key): a run on a tag native-* that is not the key of its sources fails before it uploads.
Then commit the printed row, for example:
[native.db_sqlite]
build = { sources = ["native/db_sqlite.c"] }
prebuilt = { url = "https://github.com/OWNER/REPO/releases/download/native-{source}/lib{name}-{api}-{target}{ext}", source = "…", api = "1.4", sha256 = { linux-x86_64 = "…", linux-arm64 = "…", macos-x86_64 = "…", macos-arm64 = "…", windows-x86_64 = "…" } }Adding the row does not change the source key, since the key covers only the build table and native/.
Inputs #
| Input | What it is |
|---|---|
module | The NAME of [native.NAME] (required). |
directory | The folder of agentica.toml, . by default. |
agentica-version, agentica-sha256 | The Agentica release that builds, and the sha256 of its linux-x86_64 archive from its SHA256SUMS. The header and the native API come from it. |
agentica-commit | Instead of a release, a full commit SHA of agentica-lang/agentica, built in the job. |
prepare | A bash command run in directory before each build, such as a script that fetches a pinned source. $PYTHON names a Python 3 on every runner. |
extra-args | Compiler arguments after those of the build table, split at spaces with no quoting, such as -DSTATIC third_party/lib.c. |
dry-run | true builds and prints the row, but uploads nothing. |
The outputs are source, api and prebuilt (the row).
Only native/ and the build table make the source key. prepare must not change them (the run fails when a file there, ignored ones too, has other bytes after it), and a source it fetches, extra-args or a new toolchain gives new files only with a change to native/: write the pin of a fetched source (its version and hash) in a file of native/.