Reference
narra.toml
narra.toml
narra.toml marks the top of a package and holds its settings. This page lists every table and key, its type, its default, and the error code for a wrong value. The last part covers narra.lock.
narrac reads a small part of TOML: tables ([name]), arrays of tables ([[name]]), key = value lines, comments that start with #, and these values:
- A string in double quotes (
"text") or single quotes ('text'). A double-quoted string takes the escapes\n,\t,\r,\",\\and\uXXXX. - An array of strings, which may continue over several lines.
- An inline table, in
[dependencies]and[overrides]only. A trailing comma is an error.
A line outside these forms is an error: E0405 for [[name] without the closing ]], E0406 for [name without ], E0408 for a line in a known table with no =. A table the loader does not know is skipped. A key the loader does not know in [package] is skipped when its value can be read as one of the values above. [link] and [workspace] reject unknown keys.
An error in narra.toml names the file and line, as in narra.toml:3:1: version "1.0" is not MAJOR.MINOR.PATCH. The text output does not show the code. narrac check --json prints it in the code field, and narrac explain CODE prints the message.
Tables
| Table | Needed | Holds |
|---|---|---|
[package] |
yes, except in a workspace root | The name and version. |
[[binary]] |
no | One program to build. |
[dependencies] |
no | Packages to download. |
[overrides] |
no | Replacement repositories, in the root only. |
[exports] |
no | The modules other packages may import. |
[link] |
no | Where the C compiler looks for libraries. |
[fmt] |
no | Options for narrac fmt. |
[workspace] |
no | The member packages of a workspace. |
package
[package]
name = "app"
version = "0.1.0"
| Key | Type | Default | Meaning |
|---|---|---|---|
name |
string | none | The package name. It is the first part of every import path of the package. Required. |
version |
string | "" |
MAJOR.MINOR.PATCH, three numbers in the range of int. Needed when another package depends on this one. |
Errors:
| Code | Cause |
|---|---|
| E0410 | name is not a string, or not letters, digits and _ that start with a letter. |
| E0411 | name is std, which names the standard library. |
| E0412 | version is not a string. |
| E0414 | There is no name. A workspace root with no [package] table needs none. |
| E0431 | version is not MAJOR.MINOR.PATCH, for example "1.0". |
| E0409 | A value is not a string, an array or an inline table (a bare number, for example), or a string is not closed. This holds for any key of a known table. |
binary
[[binary]]
name = "app"
entry = "cli.run"
Each [[binary]] table makes one program. A package with no [[binary]] is a library: narrac build stops with package app has no [[binary]]; it is a library. Several tables make several programs.
| Key | Type | Default | Meaning |
|---|---|---|---|
name |
string | none | The name of the executable. Required. |
entry |
string | none | The module and the function that starts the program, as "module.function". The module path is relative to src/. The form "app/cli.run", with the package name in front, also works. Required. |
The function is export function run(args: Array<string>): int, or the same with async. Its result is the exit code.
Errors:
| Code | Cause |
|---|---|
| E0412 | name or entry is not a string. |
| E0415 | A table has no name or no entry. |
| E0416 | Two tables have the same name. |
| E0420 | The module has no function with the name in entry. narrac build reports this. |
In a workspace, two members that each have a binary of one name are E0488 when you build the root or run that name.
dependencies
[dependencies]
json = { git = "https://example.com/narra-json", version = "1.2.0" }
core = { workspace = true }
A dependency is a git repository tagged with its versions. The key is the package name and the first part of its import paths.
| Key of the inline table | Type | Meaning |
|---|---|---|
git |
string | A URL or a local path of the repository. |
version |
string | The lowest version the package accepts, as MAJOR.MINOR.PATCH. The tag is v followed by the version. |
workspace |
boolean | true names a member of the same workspace. It takes no other key, and nothing is downloaded. |
git and version are both required. narrac build resolves the dependencies, writes narra.lock and loads the sources of each one. A package may import only itself, std and the packages in its own [dependencies].
Errors:
| Code | Cause |
|---|---|
| E0430 | git or version is missing. |
| E0431 | version is not MAJOR.MINOR.PATCH. |
| E0432 | The table has a key other than git and version, or repeats one. |
| E0433 | The name is std or the name of this package. |
| E0434 | Two dependencies have one name. |
| E0435 | The value is not an inline table of strings, or it has a trailing comma. |
| E0436 | The name is not letters, digits and _ starting with a letter. |
| E0483 | workspace has a value other than true, or another key stands beside it. |
| E0484 | workspace = true names a package that is not a member, or the package is not in a workspace. |
| E0450 | A git dependency has the name of a workspace member, or two packages require one name from two repositories. |
| E0463 | A package imports a package it does not list in [dependencies]. |
| E0462 | A dependency has no .nra file in src/. |
The errors E0440 to E0458 come from fetching and resolving. Four examples:
- E0440: git is not on
PATH. - E0442: the repository has no tag for the version.
- E0444: there is no cache folder.
- E0453: the manifest of a checkout names another package.
The cache folder is $NARRA_CACHE, or $HOME/.cache/narra when the variable is not set.
overrides
[overrides]
json = { git = "https://example.com/my-json-fork", version = "1.2.0" }
An override has the same form as a dependency, without workspace. It replaces the repository and the version of that package wherever any package in the build asks for it. Only the root narra.toml of a build may have this table.
Errors:
| Code | Cause |
|---|---|
| E0430, E0431, E0432, E0433, E0434, E0435, E0436 | The same as for a dependency. |
| E0483 | An entry has workspace. |
| E0454 | A manifest other than the root has [overrides]. |
| E0455 | An entry names a package that nothing requires. |
| E0456 | An entry names a version with no tag in its repository. |
exports
[exports]
"json" = "src/index.nra"
"json/stream" = "src/streaming/reader.nra"
Without this table, every file under src/ is open to importers, by its path. With it, another package may import only the keys. The files of the package itself still import each other by their real paths.
| Part | Type | Meaning |
|---|---|---|
| key | string | The import path other packages write. It is the package name, or starts with the package name and /. |
| value | string | The module file. It starts with src/, ends with .nra and must exist. |
Errors:
| Code | Cause |
|---|---|
| E0470 | A key does not start with the package name. |
| E0471 | A value is not a string, is not a path such as src/index.nra, or names a file the package does not have. |
| E0472 | Two entries have one key. |
| E0473 | Another package imports a path that is not a key. The message lists the keys. |
| E0474 | A package imports a module under std/internal/ or std/ext/. |
link
[link]
search = ["/opt/homebrew/lib"]
| Key | Type | Default | Meaning |
|---|---|---|---|
search |
array of strings | [] |
Folders the C compiler searches for libraries (-L). A relative path starts at the package folder. |
The libraries themselves come from the from of the extern blocks in the code, not from this table.
Errors:
| Code | Cause |
|---|---|
| E0413 | search is not an array of strings. |
| E1000 | The table has a key other than search. |
fmt
[fmt]
printWidth = 80
tabWidth = 4
useTabs = false
trailingComma = "none"
Only narrac fmt reads this table. A file takes the [fmt] of the nearest narra.toml above it. A member of a workspace with no [fmt] takes the one of the workspace root. A narra.toml with neither [package] nor [fmt] is skipped. Without any table, the defaults apply.
| Key | Type | Default | Meaning |
|---|---|---|---|
printWidth |
integer, 1 or more | 100 |
The line length the formatter stays within. |
tabWidth |
integer, 1 or more | 2 |
The columns of one level of indentation. |
useTabs |
boolean | false |
Indent with tabs instead of spaces. |
trailingComma |
"all" or "none" |
"all" |
Whether a split list ends with a comma. |
An unknown key or a wrong value stops narrac fmt with a message such as error narra.toml:4: unknown key indent in [fmt]. This error has no code.
workspace
[workspace]
members = ["packages/*", "tools/lint", "!packages/scratch"]
A narra.toml with this table makes its folder a workspace root. Each member is a package with its own narra.toml. All members share one narra.lock at the root.
| Key | Type | Default | Meaning |
|---|---|---|---|
members |
array of strings | none | Member folders, relative to the root. * stands for one whole folder name. An entry that starts with ! removes the folders it matches. Required. |
A root that also has a [package] table is a member of its own workspace. A package whose folder no entry lists is standalone.
Errors:
| Code | Cause |
|---|---|
| E0480 | members is missing, is not an array of strings, or an entry is not a relative path with * only as a whole segment and no ... Another key in the table is also E0480. |
| E0481 | A member has no narra.toml, or has a [workspace] of its own. |
| E0482 | Two members have one name. |
| E0485 | A narra.lock is inside a member. |
| E0488 | Two members have a binary of one name. |
| E0489 | A flag such as -dependents names a path that is not a member folder. |
| E0490 | Members depend on each other in a cycle through workspace = true. |
narra.lock
narrac build writes narra.lock next to narra.toml when the package has dependencies. In a workspace it sits at the root. Do not edit it, and commit it. A build that changes nothing leaves the file as it was.
# narra.lock: written by narrac. Do not edit.
[[package]]
name = "json"
git = "https://example.com/narra-json"
version = "1.2.0"
tag = "v1.2.0"
commit = "e1a35bc9764c4a9942dfdbeed1dd37fa72867774"
content = "ce02a3c70c6646dffa850079de004723b3e03a6c"
Each [[package]] table has these keys, in this order, and the tables are sorted by name:
| Key | Meaning |
|---|---|
name |
The package name. |
git |
The repository. It is not empty. |
version |
The selected version, MAJOR.MINOR.PATCH. |
tag |
The tag the version came from: v<version>, or <name>/v<version> in a repository that tags each package. |
commit |
The full commit hash of the tag, 40 or 64 lowercase hex digits. |
content |
The git tree hash of that commit, in the same form. |
Errors:
| Code | Cause |
|---|---|
| E0437 | A line is not [[package]] or key = "value", or a value is not well formed. |
| E0438 | An entry has an unknown, missing or repeated key, or a tag that does not belong to its version. |
| E0439 | Two entries have one name. |
| E0443 | The cached copy has no recorded hash, or another tree hash than the lock records. |
| E0452 | The repository has other hashes than the lock records, for example after someone moved a tag. |
| E0460 | The lock names a dependency that is not in the cache. narrac lsp reports this. |
| E0461 | The lock has no entry for a dependency. narrac lsp reports this. |
When the lock and the manifests name different repositories for a package, the build prints notice: <name> was locked from <old URL> and now resolves from <new URL> and rewrites the lock. This is not an error.