# Workspaces and package graphs

> Organize multiple Alice packages, share libraries, and build members in dependency order.

Canonical: https://alice-lang.org/documentation/tools/workspaces/

[Documentation index](https://alice-lang.org/documentation/llms.txt) · [Complete book](https://alice-lang.org/llms-full.txt)

## Define members

A workspace groups packages with their own manifests:

```toml
# alice.toml at the repository root
[workspace]
members = ["geometry", "apps/*"]
```

A trailing `/*` expands to subdirectories that contain `alice.toml`. Each member keeps its `src/`, tests, and package metadata.

```text
repository/
  alice.toml
  alice.lock
  geometry/alice.toml
  geometry/src/geometry.al
  apps/console/alice.toml
  apps/console/src/main.al
```

## Create a workspace

```sh
alice new curiosities --workspace
cd curiosities
alice new geometry --lib
alice new viewer
```

Creating a package within a workspace registers it in `members`. Inspect the root manifest after scaffolding so its member list matches the repository layout you want.

## Reference another member

In the consuming package:

```toml
[dependencies]
geometry = { workspace = true }
```

The name must resolve to an existing member. A workspace is a build/dependency grouping, not a namespace import: the consuming source still uses the library's declared namespaces and types.

## Build and run

`alice build` at the workspace root builds members in dependency order. A dependency cycle is not a valid package graph.

`alice run` chooses the single executable member when there is only one. If several exist, select one:

```sh
alice run viewer
```

You can also pass a workspace path and member from elsewhere, such as `alice run samples Breakout` in the compiler checkout.

## Shared lock, separate outputs

The workspace lock file records resolved NuGet versions. Each package keeps its own generated `.alice/` project and `bin/`/`obj/` outputs. Commit source manifests and the workspace lock; regenerate outputs through the CLI.

C# projects can consume generated Alice projects, but generate them before MSBuild tries to follow that reference. The [interop guide](https://alice-lang.org/documentation/guides/dotnet.md) explains this boundary.

## Continue reading

- Previous: [The alice.toml manifest](https://alice-lang.org/documentation/tools/manifest.md)
- Next: [The interactive REPL](https://alice-lang.org/documentation/tools/repl.md)