Projects¶

Technically, a project is a directory containing one workshop definition or more.

To initialize a directory as a project, create a workshop definition in it and run workshop launch. Launching a workshop from a project establishes the relationship between the two that’s required to actually start a workshop. This is achieved with a hidden .lock file, which must remain in the project directory and must not be copied or stored externally, e.g., in a repository.

You can store workshop definitions in two ways:

If you use a single workshop in the project, store its definition in the project directory as workshop.yaml. This allows you to omit the workshop name in the CLI.
If your project involves multiple workshops, store their definitions in files with the same name as the workshops under the .workshop/ subdirectory of the project directory:
```
.workshop/foo.yaml
.workshop/bar.yaml
```
When multiple workshop definitions are present, you can’t omit the workshop name in commands.

Projects can also store SDK definitions in subdirectories of .workshop/:

.workshop/build-tools/sdk.yaml
.workshop/system-services/sdk.yaml

Such SDKs can be used by any workshop in the project.

When a workshop is then started with workshop start, the project directory is mounted to it as /project/; conversely, the workshop stop command unmounts it.

External changes to the project are tracked by the Workshop daemon. Thus, if the project is moved or copied, all workshops that reference it are updated, so you can continue working without interruption.

If the project is deleted by external means without first removing its workshops, any workshops that reference it enter the Error state; the only command applicable to them is workshop remove.

Note

There are more workshop CLI commands; some have a --project option that accepts a pathname to use as the project directory.

Projects¶

See also¶