Golem Application Manifest
The Golem Application Manifest document format is used by golem-cli
, usually stored in files named golem.yaml
, which can help working with components. Currently, the Application Manifest covers:
- defining components and their metadata, including:
- component type
- location of user defined and generated WIT folders
- location of built and composed WASM binaries
- build commands
- Initial File System
- defining component dependencies for using Worker to Worker communication
- building components
- deploying components
The Application Manifest uses YAML format, see the reference for more information on the schema and for the field reference.
Application Manifest Quickstart
Application manifest documents can be explicitly passed as golem-cli
arguments, but the recommended way to use them is with auto discovery mode: when golem-cli
is called with an application manifest compatible command it keeps searching for golem.yaml
documents in current working directory and parent directories. Once it found the top level golem.yaml
document, more documents are searched using the includes field.
Once all manifest documents are found, the paths in them are resolved based on their directory, and then the documents are merged. For the field specific merge rules see the field reference.
Using composable templates
Golem example projects can be created with golem-cli new
command, these are stand-alone project, usually containing one component. To help with setting up multi-component projects, the CLI now includes a new command, new-app-component
, which can be used in empty or existing projects to add new components. E.g.: let's add a new cpp and ts component in a new and empty directory:
mkdir app-demo
cd app-demo
golem-cli new-app-component --language cpp app:component-a
golem-cli new-app-component --language ts app:component-b
When using the new-app-component
command, it will create:
- common directory for the given language (
common-cpp
andcommon-ts
):- this directory contains the languages specific Application Manifest Template, which defines how to build the components
- can be used for shared subprojects
- might contain other shared configurations
- directory for components for the given language (
components-cpp
andcomponents-ts
) - directory called
common-wit-deps
for common WIT dependencies, and populates it with WASI and Golem packages - depending on the language it might add
common-adapters
.
Now that we added our components, let's use the app
command list our project metadata:
$ golem-cli app
Build components with application manifests
Usage: golem-cli app [OPTIONS] [COMMAND]
Commands:
build Run component build steps
clean Clean outputs
help Print this message or the help of the given subcommand(s)
Options:
-a, --app <APP>
Application manifest to be used, can be defined multiple times
-c, --component-name <COMPONENT_NAME>
Selects a component, can be defined multiple times
-b, --build-profile <BUILD_PROFILE>
Selects a build profile
-o, --offline
When set to true will use offline mode where applicable (e.g. stub cargo builds), defaults to false
-h, --help
Print help
Components:
app:component-a
Selected: yes
Source: /Users/<...>/app-demo/components-cpp/app-component-a/golem.yaml
Template: cpp
Profiles: debug, release
app:component-b
Selected: yes
Source: /Users/<...>/app-demo/components-ts/app-component-b/golem.yaml
Template: ts
Custom commands:
npm-install
Because the ts components use npm, we have to use npm install
before building the components. We can also see that this has a wrapper custom command in the manifest called npm-install
. Let's use that, then build our components:
$ golem-cli app npm-install
<..>
$ golem-cli app build
Collecting sources
Found sources: /Users/<...>/app-demo/common-cpp/golem.yaml, /Users/<...>/app-demo/common-ts/golem.yaml, /Users/<...>/app-demo/components-cpp/app-component-a/golem.yaml, /Users/<...>/app-demo/components-ts/app-component-b/golem.yaml, /Users/<...>/app-demo/golem.yaml
Collecting components
Found components: app:component-a, app:component-b
Resolving application wit directories
Resolving component wit dirs for app:component-a (/Users/<...>/app-demo/components-cpp/app-component-a/wit, /Users/<...>/app-demo/components-cpp/app-component-a/wit-generated)
Resolving component wit dirs for app:component-b (/Users/<...>/app-demo/components-ts/app-component-b/wit, /Users/<...>/app-demo/components-ts/app-component-b/wit-generated)
Selecting profiles, no profile was requested
Selected default profile debug for app:component-a using template cpp
Selected default build for app:component-b using template ts
<...>
Linking RPC
Copying app:component-a without linking, no static WASM RPC dependencies were found
Copying app:component-b without linking, no static WASM RPC dependencies were found
Then we can check that the components are built:
$ ls golem-temp/components
app_component_a_debug.wasm app_component_b.wasm
To deploy (add or update) or components we can use
$ golem-cli component add
or
$ golem-cli component update
in the project root folder, and the CLI will add or update all or components.
If we want to only update some components, we can do so by explicitly selecting them with the --component-name
flag, or we can implicitly select them by changing our current working directory, e.g.:
$ cd components-cpp
$ golem-cli app
<...>
Components:
app:component-a
Selected: yes
Source: /Users/noise64/workspace/examples/app-demo/components-cpp/app-component-a/golem.yaml
Template: cpp
Profiles: debug, release
app:component-b
Selected: no
Source: /Users/noise64/workspace/examples/app-demo/components-ts/app-component-b/golem.yaml
Template: ts
<...>
Notice, how only app:component-a is selected in the above example, the same selection logic is used when adding or updating components.