]>
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 |