The manifest.

Finding the manifest#

• Project commands (build, run, check, test, format, doc, clean, add, remove) look for silk.toml in the current directory, then in each parent directory, and use the first one found.

• --manifest-path <file> names the manifest instead. It must be the file, not its directory.

• With no manifest anywhere up the tree, the command stops:

No silk.toml found from /home/you; run `silk init` to create a package here, or `silk init <name>` for a new folder

• Paths inside the manifest are relative to the directory that holds it.

• A manifest with only a [workspace] table is a workspace root. See Workspaces.

A minimal manifest#

silk init hello writes this:

[package]
name = "hello"
version = "0.1.0"
silk-version = "0.1.0"

The root module is src/main.silk without saying so: the source starts in src and the root module is main.silk. Only name is required, so [package] with a name alone is a whole manifest.

silk init --lib adds kind = "library" and exports = ["lib"], and its root module is src/lib.silk. See Libraries and exports.

[package]#

A library is Silk source for other packages to import: silk build checks it and makes no file. The other library kinds make an archive or a shared library. package.include is reserved and refused as not supported yet.

The package identity is name@version, such as hello@0.1.0. Diagnostics, [config] values and symbol maps use it.

[build]#

[config]#

Values for the package's parameters, the pub param declarations in its root module. A key is the root module's path without .silk, then the parameter's name, and the value is plain TOML that Silk checks against the parameter's declared type:

[config]
main.port = 8080
main.weights = [3, 4]

An integer, a boolean, a string or an array of them is a value. Every build receives these values, and a profile's own config wins over them. See Package parameters in the reference.

[native]#

Every link and sources entry takes an optional os: "macos", "linux", "windows", "wasi" or a list of them. Build outputs and native linking covers all of these keys.

[[generate]]#

Generators that silk generate runs. Builds never run them; their outputs are committed.

A workspace manifest can declare generators too. See Build plans and generated code.

[component]#

Only a wasm32-wasip2 executable reads it. Without the table, the component uses the WASI command world the std lib carries.

[unstable]#

Settings that may still change shape before they settle.

composition takes runtimes, defaults, components, retention and requirements. requirements, when it lists anything, is refused. The entries of its lists take only these keys:

Build outputs and native linking covers what they do.

[dependencies]#

One entry per dependency. The key is the name the package imports it by. A path dependency names a directory; a git dependency names a repository and a commit.

[dependencies]
pricing = { path = "../pricing" }
text_utils = { path = "../text-utils", package = "text-utils" }
vector = { git = "https://example.com/geometry.git", rev = "fb09a5d023a80e50a973adb896a198ab4daab4db", path = "vector" }

The other sources and their settings (url, version, tag, branch, hash, optional, workspace) are refused as not supported yet. A git dependency is pinned with rev, never with tag or branch. See Dependencies for git dependencies, fetching and the naming rules.

[profiles.<name>]#

A named profile is a complete build configuration. Select it with --profile <name> or [build].profile. Two profiles exist without a table: dev builds for the host without optimization and with debug information, and release builds for the host with optimization = "speed" and no debug information. A [profiles.dev] or [profiles.release] table replaces the built-in one.

Profile names start with an ASCII letter, then letters, digits, _ or -. Targets and profiles explains what each field does today and which combinations are refused.

[workspace]#

A manifest may hold both [package] and [workspace]. See Workspaces.

[release]#

Read only by silk change, the release notes command. Its keys (repository, directory, version-file) are described with that command in the Tools section. Builds ignore the table. It was called [changes] before; a manifest that still uses that name is refused.

[tool.<name>]#

Settings that belong to other tools, such as an editor. The compiler never reads or checks them.

Reserved tables#

[dev-dependencies], [target], [lints], [test], [bench] and [bin] are names a later release will read. Today they are refused with LINE: <table> is not supported yet, so no manifest relies on them being ignored.

Earlier spellings#

Before 0.1.0 some keys had other names. A manifest that still writes one is refused at its line, with the name to use:

Invalid Silk project manifest /home/you/hello/silk.toml:4: build.artifact is an earlier spelling; write package.kind

root = "src/main.silk" becomes nothing at all, since that is the default. root = "main.silk" next to the manifest becomes source = ".".

Errors#

The compiler checks the whole manifest before it compiles anything, and stops at the first problem. Manifest errors exit with status 2.

Invalid Silk project manifest /home/you/hello/silk.toml:8: build.artefact is not a supported field

Most errors name the line after the path, here line 8 of silk.toml. A few, such as a missing [package] table, name only the file.

When an unknown key is close to a key the table takes, within a third of its length in single-letter edits, the message names that key:

Invalid Silk project manifest /home/you/hello/silk.toml:2: package.nmae is not a supported field; did you mean package.name?

build.artefact above gets no suggestion, because the close key build.artifact is an earlier spelling, not a supported key. Keys inside profiles get no suggestion either. A key inside an inline table or array that spans several lines is named at its own line, not at the line that opens the value.

Problems in [dependencies] other than an unknown key, and in exports, are manifest errors too, as in LINE: dependency `foo` of app@0.1.0: no readable silk.toml at /home/you/nothere and LINE: exports of app@0.1.0: nope is not a module of the package. A bad [native].link entry or function-order path prints as silk: invalid native link input: ... (exit 1); see Build outputs and native linking. See Dependencies and Libraries and exports.

Profile problems name the profile and the key. A bad value is quoted after the key:

Invalid Silk project manifest /home/you/hello/silk.toml:9: InvalidInput: profiles.fast.optimization = "fast"

LINE is the line of the key, or of the table header when the problem is the table itself, as for a bad profile name. A [config] value of the wrong type, or one for a parameter the module does not declare, is refused with SEM0214 at the line of its key; see Package parameters in the reference. The compiler finds a key by its whole path, so a key named like one on an earlier line, such as a profile's runtime = { kind = "default", name = "x" } below [package] name, is reported at its own line. The message names the key without array indexes. Targets and profiles lists every refused combination.

Keys that are not checked#

Unknown keys are refused everywhere the compiler reads: the top level, [package], dependency entries, [build], [native] with its sources, archive and override entries, platform-supply and its support entries, [[generate]] entries, [component], [unstable], composition and the entries of its lists, [workspace], profiles with their cpu, entry and runtime tables, and bindings with their value and origin tables. A misspelled [packge] table or a descripton key stops the build, with did you mean package? or did you mean package.description?.

Two tables are not checked: [release], which builds ignore and silk change reads, and [tool.<name>], which belongs to other tools.

See also#

Dependencies, Libraries and exports, Workspaces, Targets and profiles, Build outputs and native linking, Build plans and generated code; Package parameters in the reference; chapters 11 and 12 of the book.