Modules
Each file is a module. import Models from "models" loads models.agc and
gives it the alias Models, and import Util from "../lib/util" loads
../lib/util.agc. The path has no extension. A path ending in .agc, an empty
path, a path ending in /, or a last part containing a dot ("models.rb",
".", "..") is CHECK-IMPORT-PATH, so a module file name has no dot apart
from .agc: json.tools.agc cannot be imported; rename it json_tools.agc.
Relative paths resolve from the importing file, not the working directory. Each
file is linked once. Cycles are CHECK-IMPORT-CYCLE, missing or unreadable
files are CHECK-IMPORT-IO, and invalid paths are CHECK-IMPORT-PATH; each is
located at the import.
Public and private names #
A declaration is public, unless it comes after a private line: every
declaration above it (constant, struct, enum, type alias, function, module
block) is public, and every declaration after it is private to the file. A file
with no private is public as a whole. Imports are never public.
LIMIT = 10
def open(id: Int) -> Int = connect(id)
private
BUFFER = 4096
def connect(id: Int) -> Int = id + BUFFERprivateis the nameprivatealone on its line, at the level of the declarations of a file or a module block; elsewhere it is an ordinary name.private def fisPARSE-TOP-LEVEL-STATEMENT. A blank line comes before and after it (PARSE-MISSING-BLANK-LINE);agentica fmtkeeps it where it is.- A file or block has at most one
private; a second one isPARSE-SECOND-PRIVATEat it. There is nopublicto switch back. exportbefore a declaration (export def,export struct,export enum,export type,export NAME = ...,export module) isPARSE-UNEXPECTED-TOKENat theexport, in a file, a module block or an extern block. A re-export (export Alias.name, below) is the only use ofexport; it is public and goes aboveprivate.- Reaching a private name (
M.helper,import {helper} from "m",Counter.step) isCHECK-IMPORT-NAMEat the name, with a help that says it is private and how to make it public: move it aboveprivate. For a name that the module only imports, the help names the re-export that would pass it on (export Url.parse). For astd/module or a package, which the user does not edit, the help only says that the name is private.
A type alias is public in the same way as a struct, enum, function or constant.
An importer can use Models.Names or import it
by name with import {Names} from "models"; type aliases can also be renamed to
another capitalized name. Aliases can name private types in public signatures;
importers can use values of the alias but cannot name or construct the private
type. Local names stay unqualified. Import aliases are uppercase and cannot
collide with declarations, other aliases, imported names or builtin names.
A module can pass on a name it imports with a re-export (below).
Unused imports #
An import alias that its file never uses is CHECK-UNUSED-IMPORT, located at
the alias, with the help remove import Alias from "path". A use is any place
that writes a name with the alias first: a call, a &function value, a type
(in an annotation, a signature, a field or a block parameter), a construction,
an enum constructor or a pattern, an enum type and a constant (Alias.NAME),
and the alias of a re-export (export Alias.name). A regex literal counts as a
use of the std/regex import and a <<~EAG template as a use of the std/eag
import, since each needs it in some form. A use inside a function that nothing
calls counts: the rule is about the text of the file. An import
has no effect besides its names, so removing an unused one never changes what a
program does. The rule holds for every file, pkg/ libraries and std/
included: a package with a stray import fails the build of every program that
uses it.
An alias written without its member (u: User, User(name: "Ana"), or
Domain.Some(1) with Domain an alias) is CHECK-IMPORT-NAME at the alias,
with the help write User.<Type>, not an unused import. A file with a call
Alias.name whose first part is no alias, no name of the file and no builtin
module (a mistyped alias) gets CHECK-UNKNOWN-NAME from the checker instead.
The first alias never used is reported, imports in source order and files in
link order (the root first), after that file’s own resolve errors. Any command
that builds or checks a program (check, run, compile, test) reports it.
The query commands (type-at, refs, symbol, --partial) do not report it
in the file they are asked about, since an editor adds an import before it
writes the first use; the files that file imports keep the rule.
Importing names #
import {User, greet} from "models" brings the exported names User and
greet into the file, to be used bare, wherever the name can stand: User in
annotations and signatures, User(name: "Ana") to construct, greet(user) or
user |> greet() to call (parentheses are required, as for a function of the
file), &greet for a function value, and for an enum Option, the type
Option[T], the values Option.None and Option.Some(value) and the patterns
Option.Some(v). Variants are not imported on their own: import the enum. A
function, struct, enum, type alias and constant can all be imported this way.
The two forms mix: a file may import a module with an alias and, on another
line, import names from it, and two lines with the same path are fine (the file
is loaded once). A module imported only by names has no alias, so Models. is
not available for it.
An entry may rename: import {greet as hello, User as Account, Names as Labels} from "models" binds local names for those exports. It exists so that two
modules that export the same name can both be imported by name, and so that a
long name can be shortened. A struct, enum or alias is renamed to a type name (a
capital first letter), a function to a lowercase name, a constant to another
constant name (capitals and underscores), and anything else is
CHECK-IMPORT-RENAME, located at the new name. The original name is not bound
unless another entry imports it, {greet as hello, greet as hi} binds two names
for one function, and messages that print a name show the original name. as is
contextual here too, and the original always comes first, so {as as as_text}
renames a function called as.
A name from an import list joins the names of the file, as a declaration does.
It must not be the name of a declaration of the file, of an alias, of another
imported name (in the same list or in another import line, and the same name
from the same module twice), of a builtin function such as puts or ok, or of
a reserved type name such as Int or JSON; each is CHECK-REDEFINED-NAME,
located at the name in the braces (at the new name of a rename). A name that
the module does not export, or that is private, is CHECK-IMPORT-NAME at the
name, with the help for a private name (above) or a did you mean help over
the exports only. These checks run when
the file is loaded, so they are reported at the import, before any use of the
name. A name used as the wrong kind (an
imported struct as the enum of a pattern) is CHECK-TYPE-MISMATCH, as with an
alias.
Unused names of an import list are not reported.
Re-exports #
A module can pass on a name it imports, so a small facade file can collect the API of several files:
# web.agc
import Url from "url"
import Parts from "http_parts"
export Url.parse
export Url.Address
export Parts.header_valueexport Alias.name (a function, a constant) and export Alias.TypeName (a
struct, enum or type alias) add the name to the exports of the file. There is
no renaming (as) and no wildcard (export Url.*): a facade that wants
another name writes a wrapper function. export is followed by a type name
and a dot only for a re-export; it is not used before a declaration. A
re-export is public: it goes above private, and one after it is
CHECK-DECL-ORDER.
- The alias must be an import of this file (
import Url from "url"; a module imported only by names has no alias), otherwiseCHECK-IMPORT-NAMEat the alias. The module must export the name, otherwiseCHECK-IMPORT-NAMEat the name, with adid you meanhelp over the exports. A private name is not re-exportable. - The name must not be the name of a declaration of the file, of another
re-export or of an import alias of the file:
CHECK-REDEFINED-NAMEat the name. So the alias of a facade must differ from the names it re-exports:import Value from "value"withexport Value.Valueis an error; writeimport V from "value"andexport V.Value. - It is the same declaration, not a copy. A program that imports both
web.agcandurl.agcseesWeb.AddressandUrl.Addressas one type, and&Web.parseand&Url.parseare the same function. A re-export of a re-export leads to the original declaration, and a re-exported enum brings its variants (Web.Option.Some(x)). A re-exported constant is read asWeb.LIMIT. - Inside the file the name is still
Url.parse: a re-export adds no local name. - A
std/module may also re-export a builtin record, enum or handle type of a std-only module (HttpWire,LogRegistry,RegexEngine), which needs no import:export LogRegistry.Eventinstd/loggermakesLogger.Eventthat builtin record, andexport HttpWire.Clientinstd/httpmakesHTTP.Clientthat handle. Outsidestd/such a re-export isCHECK-UNKNOWN-NAMEat the module name; a name of the module that is no record, enum or handle type isCHECK-IMPORT-NAMEat the name. - Re-exports come with the imports, may follow each other and the imports
directly, and after a declaration need the blank line
(
PARSE-MISSING-BLANK-LINE); they are with the public constants inCHECK-DECL-ORDER, after the imports: animportafter a re-export is out of order. A##doc before a re-export isPARSE-DETACHED-DOC: the doc stays on the original.
Constants #
A public constant (LIMIT = 100, above private) is visible, and
import {LIMIT} from "limits" brings it in by name, like any other exported
name (it can be renamed to another constant name:
import {LIMIT as MAX_ITEMS} from "limits"). A constant is read by its bare
name, wherever an expression can stand, in the file that declares it and in a
file that imports it by name. An importer that has the module under an alias
reads an exported constant as Limits.LIMIT, like an exported function:
Limits.NAMES.size, Limits.CONFIG.with(port: 81) and "#{Limits.LIMIT}" work
as for a bare constant. A private constant, and a name the module does not
export, are CHECK-IMPORT-NAME at the member, with a did you mean help for a
near export, as for a function. A constant is no function and no type:
Limits.LIMIT() and x: Limits.LIMIT are CHECK-TYPE-MISMATCH. An imported
name must not collide with a constant of the file, and two constants of the same
name are CHECK-REDEFINED-NAME, as for any declaration. A constant is never
changed, so there is no shared state between modules: the value an importer
reads is the value the declaring file computed.
Only the root file supplies the executable main() -> Void; imported main
functions do not run. Imported calls and tasks share the program’s step budget
and resource ownership. There are no wildcard imports, mutable module state or
receiver attachment.
Module blocks #
module Name ... end at the top level of a file groups declarations under a
name, so one file can hold several named modules. It is a namespace only:
# agents.agc
module Counter
enum Msg
Add(Int)
Get
end
def start(initial: Int) -> Int = step(initial, Msg.Add(1))
private
def step(count: Int, msg: Msg) -> Int
case msg
Msg.Add(n) -> count + n
Msg.Get -> count
end
end
end- The name is capitalized and follows the rules of an import alias: it must
not be the name of a declaration, an alias, an imported name or a builtin
name (
CHECK-REDEFINED-NAME, at the name; at the import when an import line takes it).module namewith a lowercase name is not a block. - Inside, a block holds what a file holds, with the same layout rules (the
blank lines and
CHECK-DECL-ORDER): constants, structs, enums, type aliases and functions, generic ones included. An import, a re-export or an extern block inside isPARSE-UNEXPECTED-TOKEN; a block inside a block isPARSE-NESTED-MODULE, at the innermodule. A block may be empty. In the file it ranks with the structs and enums forCHECK-DECL-ORDER. - Scope is lexical: the body sees the imports of the file, its top-level
declarations (private ones too) and the other blocks, and its own names
bare. One name means one thing in a scope, so a block may not declare a name
that the file declares or imports, or the name of a block
(
CHECK-SHADOWED-NAME, at the name). Two blocks may declare the same name (A.startandB.start): neither sees the other’s names bare. - A block has its own
privateline, with the rules of a file: what is above it is public, the rest is private to the block, and a block without one is public as a whole. - Outside the block (the rest of the file and importers) only its public
names are visible, written
Counter.start,Counter.Msg.Add(5),Counter.LIMIT,Counter.Box[Int]. A private name isCHECK-IMPORT-NAME, as for a name a file does not export. Uses inside a block count forCHECK-UNUSED-IMPORT. - A public block (above the file’s
private) lets an importer use it:import {Counter} from "agents"bindsCounteras an alias (import {Counter as C}renames it), andimport Agents from "agents"readsAgents.Counter.start(0),Agents.Counter.Msg.Add(5)and the typeAgents.Counter.Msg. Any other block is private to its file. - Only the root file’s top-level
mainruns, so a block may not declaremain(CHECK-MAIN, at the name). There is no mutable module state, andextern modulekeeps its meaning.
Standard library and external libraries #
import Queue from "std/queue"loads the standard library embedded at build time. Nothing needs to be installed, and local files or external roots cannot shadow it. Embedded modules may use relative imports insidestd/, with..as long as the path stays instd/.std/internal/holds code thatstd/modules share and that is not API (std/analysiscompiles the pure core of the front end from there). Only astd/module may import it; any other file getsCHECK-IMPORT-IO.agentica docandoutlineof it fail as for a missing module:cannot read(QUERY-USAGEinoutline, exit 2).import Tools from "pkg/acme/tools"searches foracme/tools.agcin order:agc_libs/beside the root program, or besideagentica.tomlwhen the project has a manifest (not beside a dependency); the absolute roots inAGENTICA_PATH(:-separated,;on Windows), in order;$XDG_DATA_HOME/agentica/lib/(default~/.local/share/agentica/lib/; on Windows%LOCALAPPDATA%/agentica/lib/); then/usr/local/share/agentica/lib/and/usr/share/agentica/lib/(none on Windows). A first part (acme) that the manifest declares as a dependency is a package instead, and the search does not run for it (see Packages below).
The first existing file wins, and an error in that file does not fall back to
another root. Empty AGENTICA_PATH entries are ignored; a relative entry is
CHECK-IMPORT-PATH. A root is absolute when it starts with / (on Windows: a
drive path such as C:\libs or C:/libs, a UNC path such as
\\server\share\libs, or a path that starts with / or \; C:libs is
relative). On Windows the other separator is part of the entry, and
XDG_DATA_HOME and HOME are not read: an unset or relative LOCALAPPDATA
leaves the user root out. Library paths use forward slashes and reject empty,
., .., backslash and colon components. After symlink resolution, the target
must stay inside its root. These checks apply to namespaced imports only:
imports are not a filesystem sandbox. A missing module is CHECK-IMPORT-IO.
Diagnostics inside an embedded module name its source, such as std/queue.agc.
Packages (agentica.toml and agentica.lock) #
A package is a git repository of .agc files. A project uses packages when an
agentica.toml (the manifest) is in the folder of the root file or in a folder
above it; the nearest one counts, and its folder is the project folder. The
search goes up to the root of the file system, so an agentica.toml in a shared
parent folder (such as /tmp) is read and checked for every script below it,
and a bad one there is PKG-MANIFEST-INVALID for each of them. Without a
manifest nothing changes. A build reads the manifest and the lock and loads
packages only from deps/ beside agentica.toml, which agentica install
writes (see below). A build never runs git and never uses the network, and it
never reads the package cache. agentica add and agentica update write the
lock (see below).
name = "notes"
[dependencies]
sqlite = { git = "https://github.com/owner/sqlite-ac", tag = "v1.2.0" }
json5 = { git = "https://gitlab.com/someone/json5", ref = "3f2a9c1" }
postgres = { git = "https://github.com/owner/packages", tag = "postgres-0.1.0", subdir = "postgres" }
[style]
max_line_width = 119import Sqlite from "pkg/sqlite/db"- The manifest knows
name,agentica,[dependencies],[native],[style],[workspace](below) and[tool], a table of tables ([tool.NAME]) that other tools own: Agentica reads nothing inside them and checks only thattooland eachtool.NAMEis a table. Outside[tool], an unknown key at any level, a value of the wrong form, or a TOML syntax error isPKG-MANIFEST-INVALID. Atoolortool.NAMEthat is not a table is alsoPKG-MANIFEST-INVALID.nameis optional and follows the rule of a dependency name below.max_line_widthis an integer of 1 or more.blank_line_after_endis a boolean, false by default; any other value isPKG-MANIFEST-INVALIDatstyle.blank_line_after_end. agentica = "0.31.0"(optional) is the oldest Agentica the project or package works with: one SemVer version, read as a minimum, in the order of semver.org §11 (0.31.0-alpha.2 < 0.31.0-alpha.10 < 0.31.0-beta.1 < 0.31.0; build metadata+...is ignored). Anything else, a range included, isPKG-MANIFEST-INVALIDatagentica.install,check,run,testand every command that loads the project check the key of the project and of each locked package against the running version, andaddandupdatethat of each package they resolve; a newer one isPKG-AGENTICA-TOO-OLDatagenticaof that manifest. A member of a workspace (below) also checks the key of the workspace root’s manifest, before the root’s other keys. The key is read and checked right after the TOML parse, before any other key and before the lock, so a manifest written for a newer Agentica reports the version it needs rather than a key this one does not know.run -- FILE.agcb,fmtandlintdo not check it. The running version is theVERSIONfile as written when the binary was built, so a build of master between releases reports the last release.- With
max_line_width = N,agentica checkand every command that checks a program report a line of more than N characters (Unicode code points; a CR before the line feed does not count; comments count) asCHECK-LINE-TOO-LONG, from its first character past N to its end, after the type check passes. It covers the same files asblank_line_after_end(below), and in a file it comes before that rule.agentica fmtlays out in N columns (119 without the key) and, withblank_line_after_end, adds the empty lines that rule asks for. - With
blank_line_after_end = true,agentica checkand every command that checks a program require an empty line (only spaces or tabs) after each line whose code is onlyend, in the files below the folder of that manifest that have noagentica.tomlof their own nearer. A file outside that folder (../shared/util.agc),std/, a package, theagc_libs/of the folder, any otherpkg/library folder (and what its files import by a relative path), and a file in a folder with its own manifest are not checked, even when the root imports them. A link counts where its real path is. The key of a nested manifest is not honored: a build reads only the manifest of its root. A trailing# commenton theendline is allowed, but a comment line after theendis not an empty line, so it needs one too, also before a closingendand at the end of the file. A line that breaks it isCHECK-BLANK-LINE-AFTER-END, at theend, reported after the type check passes. A line that starts withend,else,elsif,),]or}needs no empty line before it. The end of the file needs none either: the lastendmay have no final line break, one, or extra empty lines, in a module file and in the main file. Anendwith more on its line (end),end + xs) is not covered, and anendin a string, a heredoc or a comment never counts. - A dependency is a local name and an inline table. The name is the key: a
lowercase letter, then lowercase letters, digits,
_and-, at most 64 characters. It is the segment afterpkg/in an import and has nothing to do with the URL, so moving a repository changes only itsgitline. The table hasgit, anhttps://host/owner/repoURL (an optional.gitat the end; a lowercase host with no port and no user name; exactly an owner and a repository, each with only letters, digits,.,_and-, not.,..or starting with-, not ending in.and not a Windows device name such asconornul), and exactly one oftag(1 to 128 letters, digits and the characters.,_,+and-; no/, and not starting with.or-) orref(7 to 64 lowercase hex digits of a commit), and optionallysubdir(next item), or apathinstead of all of those (the item after the next). A branch, a version range or another key isPKG-MANIFEST-INVALID, at the key path (dependencies.sqlite.branch).override = trueandgroup = "test"are the only other keys (their items below). subdirsays that the package is a folder of the repository, not the repository itself, so one repository can hold many packages. It is a relative path of plain folder names joined by/("postgres","libs/sql"). Each name has only letters, digits,.,_and-, and is not empty, hidden (so no.or..),agc_libs(in any case), ending in.or a Windows device name such ascon; the whole path has at most 128 characters. Anything else, a leading or final/and a value that is not text included, isPKG-MANIFEST-INVALIDatdependencies.<name>.subdir. The folder is the package: its files are the files of the package, its ownagentica.tomlis the manifest of the package, and relative imports cannot leave it (CHECK-IMPORT-PATH), as they cannot leave the repository of a package withoutsubdir. A project installs only the folders it declares. A package that needs another folder of its own repository declares it like any other dependency (the samegit, its ownsubdirand pin). Versions use prefixed tags (postgres-0.1.0).path = "../sqlite"is a dependency on a folder of this machine: relative to the folder of the manifest, or absolute; not empty, with no control character, at most 1024 characters. It excludesgit,tag,refandsubdir(PKG-MANIFEST-INVALIDatdependencies.<name>), and the folder must hold anagentica.toml(elsePKG-MANIFEST-INVALIDatdependencies.<name>.path, as for a workspace member). Like a workspace member it is neither fetched, cached nor copied todeps/: the build reads the files from the folder, with no hash check, so an edit there is seen by the next build, and theagentica.tomlof the folder declares its dependencies as for any package. Its lock entry hasnameandpathas written, and nogit,commitorhash(any of them isPKG-LOCK-INVALID). Its answer isin place NAME@pathfrominstallandadded NAME@pathfromaddandupdate. A package can be published, so apathis allowed only in the manifest of the root project: in the manifest of a package (fetched, or a workspace member) it isPKG-ROOT-ONLYatdependencies.<name>.path.override = truein a dependency of the root manifest makes its source win for that name everywhere in the tree, with any of the sources above (apathtoo, to try a local copy of a transitive dependency). A package that asks for another source of the name is not aPKG-SOURCE-CONFLICT, and the source it asks for is never fetched or compared; the files of the name are the root’s, for the project and for every package. Only the root manifest may say it: in the manifest of a package it isPKG-ROOT-ONLYatdependencies.<name>.override, andfalseis the same as leaving it out. The lock entry hasoverride = trueafter its other keys; the root manifest and the lock must agree (PKG-LOCK-STALEat the manifest), and the lock key must betrue(elsePKG-LOCK-INVALIDatpackage[n].override).install,addandupdateend their answer with one line for each overridden package,overridden NAME@VERSION, andaddandupdateadd(another source asked by A, B)when packages asked for another source.PKG-SOURCE-CONFLICThas a help that suggestsoverride = truein the root manifest.group = "test"(Bundler’sgroup: :test) puts a dependency in the test group: only the tests of the project import it.testis the only group; any other value isPKG-MANIFEST-INVALIDatdependencies.<name>.group. The project locks, fetches and installs its test group like any dependency, with the same lock entry (no key says the group). Only a test build imports it: the*_test.agcfiles and the step program thatagentica testcompiles, with the files they import.agentica check, the queries (type-at,refs) andstd/analysisdecide by the name of the file: a*_test.agcfile or asteps.agc, so a step program given asagentica test --steps other.agcis a test only underagentica test. In any other build an import of it from a file of the project isCHECK-IMPORT-PACKAGEat the import. The test group of a package is its own: a project that depends on the package does not resolve, fetch or lock it, does not check it against its lock, and the files of the package cannot import it (CHECK-IMPORT-PACKAGE). A name of the test group that another package needs is one source in the build, as for any name.- A repository of packages can be a workspace, like an npm workspace. Its root
agentica.tomlhas a[workspace]table withrepository, thegitURL of the repository (the rules of a dependency’sgit), andmembers, a non-empty list of the folders of its packages. A member is written like asubdir, appears once, and holds its ownagentica.toml. An unknown key, a missing key, a bad value or a member that fails these rules isPKG-MANIFEST-INVALIDatworkspace.repository,workspace.membersorworkspace.members[n]. - A project is in a workspace when its folder (the folder of its nearest
manifest) is the root of the workspace or a member. The root is the nearest
agentica.toml, going up from the project folder, that has a[workspace]table. The project is in it when its folder is that root, or its path from the root is one of themembers; only then is the table checked in full. A table that does not list the project, even a broken one, is the same as no table for it (a project that is the root itself reports a broken table). The search stops at the root of the file system, and a project whose folder is directly inside a folder nameddepsis a package ofdeps/and is never in a workspace. A manifest above the project that cannot be read or parsed is skipped. The[workspace]table of a package that is in the cache or indeps/is never read, so it is not checked. - In a workspace, a dependency whose
gitis therepository(with or without a.gitat the end) and whosesubdiris a member is a workspace member, wherever the manifest that declares it is: the project’s own or a package’s. It keeps itsgit,tagorrefandsubdirin the manifest, which is what a user outside the repository resolves, but it is neither fetched nor copied todeps/: the build reads its files from the member’s folder, with no hash check, so an edit there is seen by the next build. The folder’s ownagentica.tomldeclares its dependencies as for any package, and its files keep the rules of a package (relative imports stay inside the folder). The lock entry of a member hasworkspace = truein place ofcommitandhash, and needssubdir; acommitor ahashwith it, aworkspacethat is nottrueor a missingsubdirisPKG-LOCK-INVALID. The lock must say the same as the workspace: a member locked as a fetched package, or a package locked as a member for a project that is not in the workspace, isPKG-LOCK-STALEat the project’s manifest andPKG-SOURCE-CONFLICTat a package’s.install,addandupdateremove adeps/folder that has the name of a member. Outside the repository nothing changes: the same dependency is fetched and locked with a commit and a hash. - The import is
pkg/<name>/<module path>, with no extension:"pkg/sqlite/util/json"loadsutil/json.agcof the package.pkg/sqlitewith no module isCHECK-IMPORT-PATH. A name that the manifest of the importing file declares is a package, and it comes first: it shadows a library of the same name in thepkg/roots,agc_libs/included. Its files come only fromdeps/<name>/besideagentica.toml, one flat folder for each locked package, including the ones that packages import (the lock is one list, so one folder for each name). A name that is not declared is thepkg/library search above, unchanged. Since the prefix ispkg/, a package import never clashes with a local file or folder. - Which manifest decides: the manifest of the project for the files of the
project (and of the
pkg/libraries it loads), the manifest of the package itself, read from its folder indeps/, for the files of a package. A package file imports only the packages its own manifest declares; apkg/name it did not declare isCHECK-IMPORT-PACKAGE, and the project cannot import the dependencies of a package unless it declares them too. A package file imports its own modules by relative paths that stay inside the package: a../that leaves it, a hidden folder,_build/,agc_libs/ordeps/of the package, areCHECK-IMPORT-PATH. - A manifest that declares a dependency needs
agentica.lockbeside it (PKG-LOCK-MISSING). Only the lock of the project is read; theagentica.lockof a package never is. The lock is TOML:version = 1(a missingversionor any other value isPKG-LOCK-INVALID), then one[[package]]for every package of the build, direct or not, one entry for each name (a name twice isPKG-LOCK-INVALID):name,git,subdir(only when the dependency has one),tagorref(as in the manifest),commit(40 or 64 lowercase hex digits; it starts with theref) andhash(sha256:and 64 lowercase hex digits),workspace = truefor a member of the workspace of the project, orpathin place of the git source for apathdependency, thenoverride = truefor an overridden name. A bad lock isPKG-LOCK-INVALID, a badsubdirtoo, atpackage[n].subdir. Every dependency of the manifest must be in the lock with the samegit(with or without a.gitat the end), the samesubdir(or none) and the sametagorref, or the samepath, and the sameoverride, or the lock isPKG-LOCK-STALE. The same check runs on the manifest of every locked package that is indeps/: a name the lock lacks isPKG-LOCK-STALE, and a name with another source than the lock isPKG-SOURCE-CONFLICT; both are reported atdependencies.<name>of that manifest. One name with two different sources anywhere in the tree (the project and a package, or two packages) isPKG-SOURCE-CONFLICT, unless the project overrides the name (the item onoverride); the source is thegit, thesubdirand the pin; there are no versions to compare and no ranges to solve. Both checks run once for every command that loads code, before any file is read, so a conflict is reported whether or not an import reaches that package. A package that is not indeps/, one whose folder cannot be listed and one whose manifest is not a regular file are left for the import that loads them (so a conflict in them shows only then). A manifest that is a symbolic link, a folder or a pipe isPKG-SYMLINKand is never opened. The build never writes the lock. - Manifest and lock errors have no source span. They name the file and the key
path, such as
dependencies.sqlite.gitorpackage[1].hash([n]counts from 0); a TOML syntax error has the line and column instead. In the plain form the key path replaces the source lines (= key: ...); in--aiit is thekey:line; in--jsonit iskey_path, andrangeis the start of the file. A failure about the file as a whole (a lock that is missing, a file that cannot be read) has no key: the plain and--aiforms show the file name alone, and--jsonhas nokey_pathand arangeat line 0, column 0. - The package cache is a download cache, so that a commit is never fetched
twice;
install,addandupdatefill it and writedeps/from it. It holds one folder for each commit:$XDG_CACHE_HOME/agentica/pkg/<host>/<owner>/<repo>/<commit>/, from thegitURL of the lock. Two names for one repository are two packages, each with its own lock entry. A package with asubdirhas the folder<commit>@<subdir>instead, each/of thesubdirwritten@(asubdirnever holds one), and that folder holds only the files of thesubdirfolder. Two folders of one repository and commit are two cache folders, and a change in another folder of the repository changes neither.XDG_CACHE_HOMEcounts when it is absolute, else~/.cacheis used (no cache whenHOMEis unset too). On Windows the folder is%LOCALAPPDATA%/agentica/cache/pkg/(no cache when it is unset or relative;XDG_CACHE_HOMEandHOMEare not read). A declared package that is not indeps/isCHECK-IMPORT-PACKAGE, whose help says to runagentica install. agentica installfills the cache from the lock, writesdeps/(below) and never writes the lock. It takes no argument; the project is the nearestagentica.tomlgoing up from the working folder (none isPKG-MANIFEST-MISSING), and the lock is checked against the manifest as a build checks it (PKG-LOCK-STALE). For each locked package, in the order of the file: a folder of the commit that is in the cache and has the locked hash is left alone and git does not run; a folder with another hash isPKG-HASH-MISMATCHand is never overwritten; else the package is fetched. The fetch runs the systemgit(its config, SSH keys and credential helpers apply; aurl.<base>.insteadOfsetting applies to thegitvalue, which the lock keeps as written): a depth-1 fetch of the tag, or of the locked commit for aref, into a temporary bare repository with no hooks and no working tree. The fetched commit must be the lockedcommit, elsePKG-TAG-MOVED. The files are read from the commit tree withgit ls-treeandgit cat-file, so.gitattributeschanges nothing. Only the files the hash covers and theagentica.tomlat the root are copied. With asubdir, the tree read is that folder of the commit: the fetch is the same, but nothing outside the folder is listed, read or written; asubdirthat the commit lacks, or that is a file, a symbolic link or a submodule there, isPKG-FETCHatpackage[n].subdir. A symbolic link or submodule named*.agcoragentica.toml, or innative/, isPKG-SYMLINK, two copied paths that differ only in case arePKG-PATH-COLLISION(only case: not Unicode normalisation or Windows device names, which the hash still catches), a file over 1 MiB, or all files over 16 MiB, isPKG-FETCHnaming the file, and the hash of the copy must be the locked hash (PKG-HASH-MISMATCH). The copy is built in a hidden.tmp-*folder of the cache root and renamed into place in one step (a killed install may leave that folder; delete it). git may ask for a password on a terminal; each read of its output has a 5 minute deadline. A git that cannot start or fails, a missing tag or commit, an unsafe path and a cache that cannot be written arePKG-FETCH. These failures nameagentica.lockand the key of the entry (package[1].tag,package[1].hash;package[1].gitwhen git itself failed;package[1]for the others). The first failure stops the command. When every package is in the cache, the manifest of each is checked against the lock (PKG-LOCK-STALE,PKG-SOURCE-CONFLICT), and only then isdeps/written, so a cache or a manifest that fails those checks writes nothing there. A failure in the middle of the copy (a full disk, say) leavesdeps/partly updated: each package folder is either the old one or the new one, andagentica installfinishes the rest. The answer isfetched NAME@VERSION,in the cache NAME@VERSION, for a workspace memberin the workspace NAME@workspaceor, for apath,in place NAME@pathfor each package, thenoverridden NAME@VERSIONfor each overridden package; with no package but host artifacts ready,1 native artifact ready(orN native artifacts ready); elsenothing to install. The command starts git even under--deny-run, which only limits programs.agentica add NAME URL --tag TAG(or--ref COMMIT,--subdir DIRand--group test) andagentica update [NAME]write the lock; they are the only commands that do. Both work on the project of the working folder (no manifest isPKG-MANIFEST-MISSING), read the lock without checking it against the manifest, and fetch asinstalldoes (the samegit, the same checks, the same cache), so they may startgitand need the network for what is new. The lock they write has one entry for every package of the build and no other: the dependencies of the manifest, then those in the manifest of each package they settle, and so on; one name with two sources isPKG-SOURCE-CONFLICT, at the manifest that asked second. A locked entry with the source the manifest names is kept, and only its files are put in the cache if they are missing; anything else is fetched, and the commit and the hash are read from what git gave; a fetch error of such a pin names the manifest that asks for it anddependencies.<name>.git(or.tag,.ref,.subdir), the same codes asinstall. Nothing is written when a step before the lock fails, and the lock is written before the manifest anddeps/after both: ifdeps/cannot be written,agentica installwrites the locked packages into it (it removes no folder). A file that cannot be written isPKG-WRITE; each file is written to a new file beside it that is renamed into place, and the old one is put back if a step fails. A manifest that changed while the packages were fetched is not overwritten (PKG-WRITE, nothing written), and a manifest that cannot be written after the lock was says so in the help:agentica updatemakes the lock match it again. The lock is sorted by name (justversion = 1when it is empty), in the layout above, so it has the same bytes when nothing changed.addtakes the local name, thehttps://URL and--tagor--ref, in that order, then--subdir DIRif the package is a folder of the repository and--group testfor the test group. The commit of--refis the whole id (40 or, for SHA-256, 64 digits), since git fetches no abbreviation (a package whose manifest asks for a part of an id that the lock lacks isPKG-FETCHatdependencies.<name>.refof that manifest). The tag of a SHA-1 repository is fetched; a SHA-256 repository takes--ref. A name, URL, tag or commit that the manifest would refuse, or any other words, are a usage error (exit code 2). A name that is a dependency already isPKG-DEPENDENCY-EXISTS. The manifest gets one new line,NAME = { git = "URL", tag = "TAG" }(withsubdir = "DIR"and thengroup = "test"last when asked), after the last entry of[dependencies](or in a new[dependencies]table at the end of the file); no other byte changes, so comments, blank lines, the order of the keys and the line endings stay. The new text is read as a manifest before it is saved, and a layout the edit cannot handle (the table written asdependencies = {}, say) isPKG-MANIFEST-EDIT: write the line by hand.updatetakes no word or the name of a dependency of the manifest (elsePKG-DEPENDENCY-UNKNOWN). It fetches the tag pins again, all of them or the one named, and takes the commit they point to now, so a moved tag is the new commit and hash in the lock. A pin that is a commit is not fetched again. It also fixes a lock that is missing or stale (a manifest edited by hand) and drops the packages that nothing asks for any more. A project with no dependency and no lock gets none.- Both refresh
deps/asinstallwrites it, for every package of the new lock, and remove the folder of a package that the old lock had and the new one lacks. Ifdeps/cannot be written, the lock is saved already and the help says to runagentica installto write the locked packages intodeps/. - A workspace member is locked with no fetch, whether or not its tag exists,
and its manifest is read from its folder; its version is
workspace. - The answer lists
added NAME@VERSION,updated NAME@VERSION(another commit or pin) andremoved NAME, one per line, ornothing to update; a package with asubdiradds(folder DIR)afterNAME@VERSION. With--jsona success prints{"ok":true}.
deps/holds the files of each locked package that is not a workspace member, direct or not, indeps/<name>/besideagentica.toml, likemix deps.get: the files the hash covers and theagentica.tomlof the package (for asubdir, of that folder only: the cache holds nothing else).install,addandupdatecopy them from the cache into a hidden.tmp-*folder ofdeps/, hash the copy against the lock (PKG-HASH-MISMATCHatpackage[n].hash), and swap it for the olddeps/<name>/in two renames, so the old folder stays if a step fails. The folder of a locked package is replaced when it is not a real folder (a link, say) or its.agcfiles differ from the lock (an edited, added or missing file), and runninginstallagain is how to restore it. A real folder whose.agcfiles have the locked hash is left as it is, so its files keep their times, and so do other files in it (a note, say). Hidden.tmp-*and.old-*entries ofdeps/left by a killed command are removed first when they are older than ten minutes (a younger one may belong to a command that is still running), judged by their own time and never through a link. The new folder has the ordinary mode (not the private one of the staging folder). APKG-WRITEthat could not put an old folder back names the.old-*folder that holds it;installwrites the package again from the cache, and the next command removes that folder once it is older than ten minutes. A folder of a package thatupdateoradddropped from the lock is moved aside and removed without following links (a link is removed as a link). Nothing else indeps/is touched, and the tool writes no.gitignorethere: a project may commitdeps/or ignore it.deps/itself must be a real folder: a symbolic link isPKG-SYMLINK, and a file or a write that fails isPKG-WRITE(the file and no key); nothing is written through a link.agc_libs/is not touched: it stays for the libraries of thepkg/search. Whenagentica test,check,fmt,lintandsymbolwalk a folder, they skip thedeps/beside anagentica.toml(installed packages are not the tests or modules of the project; a path that names a folder ofdeps/reads it) and_build/at any depth, where agentica writes its caches. These two names are exact.- A build reads
deps/<name>/of a declared name and hashes it against the lock: one that differs (an edited file, an added.agcfile, a missing one) isPKG-HASH-MISMATCHat the import, and nothing else is used instead; a folder that is not there, or an entry that is not a folder, isCHECK-IMPORT-PACKAGE. The stored names of the files do not depend on where they were read. A link to a folder atdeps/<name>is followed when a build reads it (the hash covers what is behind it);installreplaces the link itself. A name the project does not declare is thepkg/library search. - The hash covers the
.agcfiles of the package folder and every file of itsnative/folder at the root, but dotfiles,Thumbs.dbanddesktop.ini(for asubdir, that folder of the repository, so a change in another folder does not change it). Their paths are relative to it, written with/, in bytewise order; for each file, its path, a zero byte, its size in decimal, a zero byte and its bytes. The hash issha256:and the SHA-256 of that stream in hex (OpenSSL.Digest.sha256). Hidden folders and_build/(any depth),agc_libs/anddeps/at the root and files that are not.agc(outsidenative/) are left out (.agc,agc_libs,_build,depsandnativeare compared without regard to case, sox.AGCis hashed andAGC_LIBS/is left out on every system). Theagentica.tomlof a package is left out too, so it can only choose among the names of the lock, except whennative/holds a file that is not.agcor the manifest has a top-level[native]table: it then decides which file is opened, so it is added to the stream with the pathagentica.toml, and the hash of any other package is unchanged. The first time a build loads a package, it hashes the folder ofdeps/and compares the result with the lock (PKG-HASH-MISMATCH); a symbolic link named*.agc, a link namednativeat the root, or any link innative/, isPKG-SYMLINK, and a FIFO, socket or device named*.agcor innative/isCHECK-IMPORT-IO. A package that no import reaches is not hashed. A build changes nothing indeps/. The bytecode cache ofagentica FILE.agchashes only the files a program reads, so a new unused file in adeps/folder is caught bycheckor--no-cache, not by a cached run. A committeddeps/needs noinstallto build. - Native libraries. A package declares them in its own manifest, one table
[native.NAME]for each library, whereNAMEfollows the rule of a dependency name and is whatextern "NAME"writes in the files of the package. Under it, one key for each system the library exists on:linux,macosorwindows(any other key isPKG-MANIFEST-INVALID; a macOS file is a universal binary, andlinuxis any Linux the VM supports). Its value is an inline table with exactly one offile, a path in thenative/folder of the package (plain folder names, as asubdir; the files ofnative/are copied and hashed with the package, so the lock covers all systems, and each is at most 1 MiB),system, a name for the system loader (no/,\or:; at most 128 characters) or an absolute path, or a list of them (1 to 16), for a library the system has (winsqlite3.dll), or a download{ url, sha256, member }(an https URL, or http to 127.0.0.1 or [::1]; 64 lowercase hex digits; a safe relative TAR or ZIP member): the archive is verified by its SHA-256 and the member is cached, pinned per system in[[native-artifact]]and fetched byinstallandupdatefor the host only. Another key, both shapes or a half-written download arePKG-MANIFEST-INVALIDat the key path (native.sqlite3.linux.file).[native.sqlite3] linux = { system = "libsqlite3.so.0" } macos = { system = "libsqlite3.dylib" } windows = { file = "native/windows/sqlite3.dll" }- In a file of the package,
extern "NAME"with aNAMEthat its manifest declares means the entry of the running system, chosen when the file is compiled: afilebecomes the absolute path of the file indeps/<package>/, which the VM opens as it opens any absolute library (no search, andLD_LIBRARY_PATHplays no part); asystementry stays as written. ANAMEit does not declare stays as written. Nothing else in the program changes, and--deny-nativeand--sandboxrefuse the program as for anyextern. - A
systemlist names candidates in order of preference, for a library that lives at different places on one system, such as Homebrew’s on macOS:When the file is compiled, the first absolute path that is a file is chosen, else the first bare name, else the first path (the program then fails to open it, as[native.libpq] macos = { system = ["libpq.5.dylib", "/opt/homebrew/lib/libpq.5.dylib"] }extern "/missing.so"does). A macOS path such as/usr/lib/libz.dyliblives in the dyld shared cache, not on disk, so it does not count as existing: list it knowingly, before or after a path that does. The choice is the machine’s: the manifest is hashed as written, the lock holds no choice, and the bytecode cache misses when a candidate appears or goes away. A relative path (lib/x.so,C:x.dll), an empty list or an item that is not a string isPKG-MANIFEST-INVALIDat the key path of the item (native.libpq.macos.system[1]). The working directory is never searched. - A package that declares the library but has no entry for the running
system is
PKG-NATIVE-PLATFORM, and afilethat the package lacks isPKG-NATIVE-MISSING, when a file of the package that is compiled uses thatNAME. Both name theagentica.tomlof the package and the key path (native.NAME,native.NAME.linux.file), so a package works on the systems it names and is refused only where it is used on another. - A library that is a
fileis checked by the hash of the package when the package is first loaded, so a changed file isPKG-HASH-MISMATCH. The entry of the bytecode cache ofagentica FILE.agcalso holds the digest of the manifest and of every file ofnative/(a library may load a sibling), so a change to one is a cache miss and the build runs again. The bytecode thatagentica compilewrites names the file by its path on this machine, andagentica run -- file.agcbopens whatever is at that path, with no hash check. - The manifest of the project has the same
[native]table, used by the project’s own files, with the files relative to the project folder (a package author’s tests run with the package as the project). The project’s files are not hashed. A workspace member is read from its folder with no hash, as its.agcfiles are. buildandoptionalare the keys of[native.NAME]that are not a system.buildgives the C sources of a native module (extern module), which the project, a workspace member, apathdependency and a fetched package build instead of using their system entry. A fetched package is never compiled indeps/: when a file first uses the library, the files its hash covers are read once and checked against the hash of its lock row (PKG-HASH-MISMATCHatnative.NAME.build), and the files ofnative/among them are copied into a private build folder and compiled there. So the code that is built is the code of the locked commit: a file the hash leaves out (a dotfile,Thumbs.db) is not copied, and a header outsidenative/is not found.checknever builds, but a copy that differs from the lock is stillPKG-HASH-MISMATCHwhen the package is loaded.[native.stats] build = { sources = ["native/stats.c"], defines = ["NDEBUG"], libs = ["m"] }sources(1 to 256) are.cfiles innative/, as afileis;defines(at most 64) areNAMEorNAME=VALUE, a C name and a value of letters, digits and_ . + -;libs(at most 32) are names for-l, of the same letters, not starting with-. Anything else isPKG-MANIFEST-INVALIDat the key path of the item (native.stats.build.defines[0]), and so is a Windows device name (con,nul,com1) as the name of a library to build (atnative.NAME). A source that is not a regular file ofnative/isPKG-NATIVE-MISSINGat its item. For a package read in place, every entry ofnative/is read, hidden ones included, when a file first uses the library; anativethat is not a folder, a link, a pipe or a device in it, or more than 4096 files or 1024 folders, isPKG-NATIVE-BUILDatnative.NAME.build. A fetched package reads only the files its hash covers, within the limits of a fetch (1 MiB a file, 16 MiB in all; more isPKG-NATIVE-BUILDthere), so its hidden files are in neither the copy nor the key.- A run,
compile,testandinstallrun the user’s C compiler on the C ofnative/;checkand the queries never do. Under any--deny-*flag or--sandbox, in front oftestor after it, the VM refuses native code, so no compiler starts: a run or a test file that uses the library isRUNTIME-NATIVE-DENIED(the bytecode cache keeps such programs apart, so a hit and a miss agree), andcompile, whose output may run without the flag, isPKG-NATIVE-BUILD. A run,compileandtestbuild a library when a file of the program first uses it, so a library that no file uses is never built;installbuilds them all for the project, its members and itspathdependencies, and none of a fetched package, so installing one needs no C compiler. The compiler is the words ofCC(split at spaces, with no quoting), elsecc(gccon Windows), started with an argument list and no shell, in the package folder. Every build gets-std=c11 -O2 -fvisibility=hidden, the folder of theagentica_native.hthat the binary carries, the defines (-DNAME=VALUE, one argument each) and the system’s flags: Linux-fPIC -shared -Wl,-z,defs, macOS-dynamiclibwith the install name@rpath/libNAME.dylib(the host architecture only; an undefined symbol is a link error there by default), Windows-shared -static-libgcc; then the sources and the-llibraries. The manifest names no compiler and no other flag. - The library goes to
<package cache>/native-build/<key>/libNAME.so(.dylib,NAME.dll), never into the package. The key is the SHA-256 of the files ofnative/, the table, the compiler words, the first lines of its--versionand-dumpmachine, the header, andCPATH,C_INCLUDE_PATH,CPLUS_INCLUDE_PATHandLIBRARY_PATH. Headers of your own must live undernative/: system headers, installed libraries and the rest of the environment are not part of the key, so to build again after they change, remove the entry or change a file undernative/. The files ofnative/are hashed again after the compile, and a change during it stores nothing (PKG-NATIVE-BUILD). The entry is made in a private folder and renamed into place with its receipt (the SHA-256 of the library); an entry or anative-buildfolder that is not private to the user, or a library that is not the one its receipt names, isPKG-NATIVE-BUILD, and so is a compiler that cannot start, fails or makes no library. Its standard error is printed as it is (the start of it in the message with--jsonand--ai), and a new build printsbuilt native NAME: PATHon stderr. The bytecode cache ofagentica FILE.agcwatches, for each package that builds, every file ofnative/and its names (hidden ones too), the built libraries,CCand the four search variables, so an edit or a new file innative/builds again. A compiler replaced at the same path is seen only when the program is compiled again. optional = truebesidebuildmakes the module optional: when the build fails (no compiler, a compile error, an unusable build cache), a run,compile,testandinstallgo on without it, after the warningPKG-NATIVE-UNBUILTatnative.NAME.buildon stderr, once a run: the linewarning: native module NAME not built: REASON; the package runs without it, with--jsonthe object of the problem with"warning": true, with--aiits block withwarningas the first line.Native.load("NAME")then giveserrorand a call of the module isRUNTIME-NATIVE-LOAD. The bytecode cache stores no program whose module block names it, so every run compiles the program again and tries the build again, with its warning; a program thatcompilewrote without it never opens it. A missing source, a link innative/, a copy that differs from the lock and the--deny-*flags fail as for a required module.optionalwithoutbuild, or not a boolean, isPKG-MANIFEST-INVALIDatnative.NAME.optional.
- In a file of the package,
- The stored name of a package file in the
.agcbfile ispkg/<name>@<tag>/path/in/package.agc, such aspkg/sqlite@v1.2.0/db.agc(the path is from the package folder, without thesubdir); for a package pinned by arefit ispkg/<name>@<first 12 digits of the commit>/.... So the bytes do not depend on the folder of the project. Diagnostics inside a package name the real file indeps/.
Decided against (packages).
- Semver and a major-version rule, and a
v2path segment (it clashes with folders in the repository): one name has one source, and two majors can be used under two names. dev_dependencies: there is one list of dependencies.owner/repo/modas the import form (it clashes with local folders and needs an ambiguity rule) and./for relative imports: the form ispkg/<name>/<module>.- Hashing only at install: every build hashes each package it loads, so a
changed file of
deps/is caught. - A
fileslist in the manifest: only.agcfiles and the files ofnative/are used and hashed. - A
JSON.Valuevalue or typed decoding forToml.parse: the result is the enumToml.Value, which keeps the types of TOML and works withcase.