projects / proxmox.git / blame
| Commit | Line | Data |
|---|---|---|
| a6f21e76 FG |
1 | Local cargo config |
| 2 | ================== | |
| 8bd5e820 | 3 | |
| a6f21e76 FG |
4 | This repository ships with a ``.cargo/config`` that replaces the crates.io |
| 5 | registry with packaged crates located in ``/usr/share/cargo/registry``. | |
| 8bd5e820 | 6 | |
| a6f21e76 FG |
7 | A similar config is also applied building with dh_cargo. Cargo.lock needs to be |
| 8 | deleted when switching between packaged crates and crates.io, since the | |
| 8bd5e820 | 9 | checksums are not compatible. |
| a6f21e76 FG |
10 | |
| 11 | To reference new dependencies (or updated versions) that are not yet packaged, | |
| 12 | the dependency needs to point directly to a path or git source. | |
| b9e7824b WB |
13 | |
| 14 | Steps for Releases | |
| 15 | ================== | |
| 16 | ||
| 0719e1db FG |
17 | - Run ./bump.sh <CRATE> [patch|minor|major|<VERSION>] |
| 18 | -- Fill out changelog | |
| 19 | -- Confirm bump commit | |
| b9e7824b | 20 | - Build packages with `make deb`. |
| 0719e1db | 21 | -- Don't forget to commit updated d/control! |
| b89c56b9 WB |
22 | |
| 23 | Adding Crates | |
| 24 | ============= | |
| 25 | ||
| 26 | 1) At the top level: | |
| 27 | - Generate the crate: ``cargo new --lib the-name`` | |
| 28 | - Sort the crate into ``Cargo.toml``'s ``workspace.members`` | |
| b89c56b9 WB |
29 | |
| 30 | 2) In the new crate's ``Cargo.toml``: | |
| d3f2a86f WB |
31 | - In ``[package]`` set: |
| 32 | authors.workspace = true | |
| 33 | license.workspace = true | |
| 34 | edition.workspace = true | |
| 485ed1a2 | 35 | exclude.workspace = true |
| a9191c22 | 36 | repository.workspace = true |
| b89c56b9 WB |
37 | - Add a meaningful ``description`` |
| 38 | - Copy ``debian/copyright`` and ``debian/debcargo.toml`` from another subcrate. | |
| 0719e1db FG |
39 | |
| 40 | Adding a new Dependency | |
| 41 | ======================= | |
| 42 | ||
| 43 | 1) At the top level: | |
| 44 | - Add it to ``[workspace.dependencies]`` specifying the version and any | |
| 45 | features that should be enabled throughout the workspace | |
| 46 | ||
| 47 | 2) In each member's ``Cargo.toml``: | |
| 48 | - Add it to the desired dependencies section with ``workspace = true`` and no | |
| 49 | version specified. | |
| 50 | - If this member requires additional features, add only the extra features to | |
| 51 | the member dependency. | |
| 52 | ||
| 53 | Updating a Dependency's Version | |
| 54 | =============================== | |
| 55 | ||
| 56 | 1) At the top level: | |
| 57 | - Bump the version in ``[workspace.dependencies]`` as desired. | |
| 58 | - Check for deprecations or breakage throughout the workspace. | |
| 59 | ||
| 60 | Notes on Workspace Inheritance | |
| 61 | ============================== | |
| 62 | ||
| 63 | Common metadata (like authors, license, ..) are inherited throughout the | |
| 64 | workspace. If new fields are added that are identical for all crates, they | |
| 65 | should be defined in the top-level ``Cargo.toml`` file's | |
| 66 | ``[workspace.package]`` section, and inherited in all members explicitly by | |
| 67 | setting ``FIELD.workspace = true`` in the member's ``[package]`` section. | |
| 68 | ||
| 69 | Dependency information is also inherited throughout the workspace, allowing a | |
| 70 | single dependency specification in the top-level Cargo.toml file to be used by | |
| 71 | all members. | |
| 72 | ||
| 73 | Some restrictions apply: | |
| 74 | - features can only be added in members, never removed (this includes | |
| 75 | ``default_features = false``!) | |
| 76 | - the base feature set at the workspace level should be the minimum (possibly | |
| 77 | empty!) set required by all members | |
| 78 | - workspace dependency specifications cannot include ``optional`` | |
| 79 | - if needed, the ``optional`` flag needs to be set at the member level when | |
| 80 | using a workspace dependency |