121 lines
3.5 KiB
Markdown
121 lines
3.5 KiB
Markdown
# Slovo Local Package And Workspace Guide
|
|
|
|
Sanjin Gumbarevic<br>
|
|
hermeticum_lab@protonmail.com
|
|
|
|
This guide documents the current beta local package model. It is intentionally
|
|
smaller than a package manager: Slovo supports closed local workspaces,
|
|
package metadata, local path dependencies, package-qualified imports, and
|
|
deterministic project-wide tooling.
|
|
|
|
Remote registries, lockfiles, semantic-version solving, package publishing,
|
|
optional/dev/target dependencies, feature flags, build scripts, package
|
|
archives, and stable package ABI/layout promises are not part of the current
|
|
beta contract.
|
|
|
|
## Workspace Manifest
|
|
|
|
A workspace root contains `slovo.toml` with a `[workspace]` section:
|
|
|
|
```toml
|
|
[workspace]
|
|
members = ["packages/app", "packages/mathlib"]
|
|
default_package = "app"
|
|
```
|
|
|
|
`members` is required and must be a non-empty array of relative paths that stay
|
|
under the workspace root. Paths are normalized before package loading, so
|
|
spelling the same member twice is invalid.
|
|
|
|
`default_package` is optional. When more than one package has its configured
|
|
entry module, `glagol build` and `glagol run` use `default_package` to select
|
|
the entry package. Without it, build/run require exactly one package with an
|
|
entry module.
|
|
|
|
## Package Manifest
|
|
|
|
Each member contains its own `slovo.toml`:
|
|
|
|
```toml
|
|
[package]
|
|
name = "app"
|
|
version = "0.1.0"
|
|
source_root = "src"
|
|
entry = "main"
|
|
|
|
[dependencies]
|
|
mathlib = { path = "../mathlib" }
|
|
```
|
|
|
|
`name` must be lowercase ASCII and may contain digits or `-` after the first
|
|
letter. `version` currently uses literal `MAJOR.MINOR.PATCH` numeric shape.
|
|
The version is metadata for manifests and generated documentation; it is not
|
|
used for solving dependency constraints.
|
|
|
|
`source_root` defaults to `src`. `entry` defaults to `main`. Source roots and
|
|
dependency paths must stay inside the workspace/package boundary after
|
|
normalization and canonical path checks.
|
|
|
|
Dependencies are local path records only. The dependency key must match the
|
|
target package name:
|
|
|
|
```toml
|
|
mathlib = { path = "../mathlib" }
|
|
```
|
|
|
|
## Imports
|
|
|
|
Within a workspace, a package imports a dependency module through the package
|
|
name and module name:
|
|
|
|
```slo
|
|
(module main)
|
|
|
|
(import mathlib.math (add_one))
|
|
|
|
(fn main () -> i32
|
|
(add_one 41))
|
|
```
|
|
|
|
Only exported declarations are visible across package boundaries. Packages do
|
|
not imply automatic imports, glob imports, aliases, re-exports, or registry
|
|
resolution.
|
|
|
|
## Tooling
|
|
|
|
The project-wide commands operate over the closed workspace graph:
|
|
|
|
```bash
|
|
glagol check path/to/workspace
|
|
glagol test path/to/workspace
|
|
glagol fmt --check path/to/workspace
|
|
glagol fmt --write path/to/workspace
|
|
glagol doc path/to/workspace -o docs-out
|
|
glagol build path/to/workspace -o app-bin
|
|
glagol run path/to/workspace
|
|
glagol clean path/to/workspace
|
|
```
|
|
|
|
`glagol doc <workspace>` emits a deterministic workspace summary with members,
|
|
packages, and local package dependency edges before the module sections.
|
|
|
|
## Diagnostics
|
|
|
|
The package/workspace gate covers these user-facing error families:
|
|
|
|
- missing member manifests
|
|
- duplicate normalized workspace members
|
|
- invalid member or dependency paths
|
|
- invalid package names and versions
|
|
- duplicate package names
|
|
- missing local path dependencies
|
|
- dependency key/name mismatches
|
|
- package dependency cycles
|
|
- private cross-package imports
|
|
- ambiguous workspace build/run entry packages
|
|
- missing or invalid `default_package` references
|
|
- selected default packages that lack their configured entry module
|
|
|
|
These diagnostics are part of the beta package discipline surface, but the
|
|
exact text remains subject to beta refinement before stable `1.0.0`.
|