A “Workspace” is a core concept in using
A workspace root is declared by the existence of
and a workspace root is necessary context for doing any module evaluations.
The workspace has several responsibilities:
A Workspace must be one of the parent directories of your CWD in order for
most of the
stellar commands to work.
.timelessdir is the WorkspaceRoot.
module.tlmay be in the same dir. There is nothing special about this.
workspace.tlfile that marks workspaces; the
.timelessdir is the only indicator.
module.tlwith no workspace – it just doesn’t run; an enclosing Workspace is still required.
Module names are determined by using the relative path of the
within the workspace directory –
A module may also be anonymous (effectively, if the
.timeless dir and the
module.tl file are in the same directory). In this case, everything works
the same, except it is not possible to generate candidate releases or use
this module in a recursive build (since there is no name to refer to it by).
(PRs welcome. When this feature is implemented, back-compat is simply that
the current behavior is effectively
"*": "*" – the path equals the module name.)
// TODO: “candidates” system should be defined in Design chapters
Candidate releases are stored in the
When evaluating a module,
so long as the moduleName can be determined (see above section about module names)
and the candidates system hasn’t been explicitly disabled,
the exports from the module will automatically be stored in a release named “candidate”,
in a file of the standard catalog format under the
Any import which takes the shape of
"candidate" being the key magic word – will resolve using these candidate releases.
Note: Commands like
stellar emerge --recursive automatically generate and use
the candidates releases automatically.