|
| 1 | +# Workspace Structure |
| 2 | + |
| 3 | +All dist projects, regardless of how many packages they may contain, are |
| 4 | +considered workspaces. A minimalist dist project would be a workspace that |
| 5 | +contains a single package. |
| 6 | + |
| 7 | +This guide walks through the structure of a dist workspace, but if you're more interested in seeing one in action, you can skip ahead to the [simple workspace guide][simple-guide]. |
| 8 | + |
| 9 | +Dist has two types of configuration: |
| 10 | + |
| 11 | +- **Workspace**: Configuration that should apply to any projects in a single repo |
| 12 | +- **Package**: Configuration that should apply to one specific project |
| 13 | + |
| 14 | +The vast majority of configuration for dist is workspace configuration. Because |
| 15 | +we understand language-specific config manifests like `Cargo.toml` and |
| 16 | +`package.json`, package configuration ususally does not require any additional |
| 17 | +files. Dedicated package configuration, in `dist.toml` files, is typically only needed when using dist's ["custom builds"][custom-builds] mode. |
| 18 | + |
| 19 | +## Workspace configuration |
| 20 | + |
| 21 | +A workspace file may be: |
| 22 | + |
| 23 | +* `dist-workspace.toml` |
| 24 | +* (deprecated in 0.23.0) `Cargo.toml` (Rust users only, goes in `[workspace.metadata.dist]`) |
| 25 | + |
| 26 | +### Specifying The Members Of Your Workspace |
| 27 | + |
| 28 | +Create a `workspace.members` field in your `dist-workspace.toml` that points to |
| 29 | +an array of strings. Each string is prefaced with a type: |
| 30 | + |
| 31 | +- `npm`: this indicates a package that is specified by a `package.json` |
| 32 | +- `cargo`: this indicates a package (or nested workspace) that is specified by a `Cargo.toml`. You do not need to specify cargo workspace members individually, you can simply refer to the workspace. |
| 33 | +- `dist`: this indicates a package that is specified by a `dist.toml` |
| 34 | + |
| 35 | +For example: |
| 36 | + |
| 37 | +```toml |
| 38 | +[workspace] |
| 39 | +members = [ |
| 40 | + "npm:path/to/npm/packagejson/dir/", |
| 41 | + "cargo:path/to/workspace/cargotoml/dir/", |
| 42 | + "dist:path/to/distoml/dir/" |
| 43 | +] |
| 44 | +``` |
| 45 | + |
| 46 | +## Package configuration |
| 47 | + |
| 48 | +A package file may be: |
| 49 | + |
| 50 | +* `dist.toml` |
| 51 | +* `dist-workspace.toml` |
| 52 | +* `Cargo.toml` (for a Rust package) |
| 53 | +* `package.json` (for an npm package) |
| 54 | + |
| 55 | +In the case of a `Cargo.toml` and `package.json`, we'll do our best to find basic package |
| 56 | +info like package name, version, repository, binaries among the native language-specific config. |
| 57 | + |
| 58 | +However these files do not natively support dist-specific config, so you may |
| 59 | +need to place a dist config *next* to them to specify additional dist-specific |
| 60 | +config. If we see the language-specific package file, we will automatically |
| 61 | +check for a neighbouring dist config and merge its contents in. If you wish to |
| 62 | +"shadow" or change a value that is present in your package manifest -- you can |
| 63 | +use the dist config file to "override" it. |
| 64 | + |
| 65 | +For a `Cargo.toml` you can instead use `[package.metadata.dist]`. However to |
| 66 | +override values in the `[package]` field, you would need to create a dist |
| 67 | +config file.. |
| 68 | + |
| 69 | + |
| 70 | +## Specifying The Members Of Your Workspace |
| 71 | + |
| 72 | +If you have a pure Cargo project, and are using `[workspace.metadata.dist]`, you don't |
| 73 | +need to specify project members at all -- we'll just find all the packages with our |
| 74 | +native understanding of Cargo. |
| 75 | + |
| 76 | +For everyone else, your dist-workspace.toml will need to contain a `workspace.members` field enumerating paths to all your packages -- although again for a Cargo member you |
| 77 | +don't actually enumerate the packages, you just point to the Cargo workspace |
| 78 | +and we'll find all the packages in that workspace: |
| 79 | + |
| 80 | +```toml |
| 81 | +[workspace] |
| 82 | +members = [ |
| 83 | + "npm:path/to/npm/packagejson/dir/", |
| 84 | + "cargo:path/to/workspace/cargotoml/dir/", |
| 85 | + "dist:path/to/distoml/dir/" |
| 86 | +] |
| 87 | +``` |
| 88 | + |
| 89 | +## Which Packages Are Distable |
| 90 | + |
| 91 | +When you ask cargo-dist to release a version of your workspace (by specifying a |
| 92 | +version, either with a tag or via workflow dispatch), we will release all "distable" packages with the |
| 93 | +given version. |
| 94 | + |
| 95 | +The set of distable packages isn't just "all the packages in your dist workspace" |
| 96 | +because we support natively importing entire language-specific workspaces, which may |
| 97 | +include tons of libraries you aren't interested in, or example/test applications. |
| 98 | + |
| 99 | +By default we assume a package is distable, and then run through a set of criteria |
| 100 | +to try to disqualify it: |
| 101 | + |
| 102 | +* If the package is "empty", it's not distable |
| 103 | + * By default, we check for whether the package defines binaries |
| 104 | + * If you have enabled `cdylibs/cstaticlibs` we check for those as well |
| 105 | +* If the package has `dist=false` set, it's not distable |
| 106 | + * For a cargo project, If dist isn't specified, the `publish` field in |
| 107 | + `Cargo.toml` will be inherited, with a default value of `true`. Setting |
| 108 | + `dist=true` can therefore be used to ignore `publish=false` in `Cargo.toml`. |
| 109 | + |
| 110 | +[custom-builds]: ../custom-builds.md |
| 111 | +[simple-guide]: ./simple-guide.md |
0 commit comments