80 lines
2.8 KiB
ReStructuredText
80 lines
2.8 KiB
ReStructuredText
Local cargo config
|
|
==================
|
|
|
|
This repository ships with a ``.cargo/config`` that replaces the crates.io
|
|
registry with packaged crates located in ``/usr/share/cargo/registry``.
|
|
|
|
A similar config is also applied building with dh_cargo. Cargo.lock needs to be
|
|
deleted when switching between packaged crates and crates.io, since the
|
|
checksums are not compatible.
|
|
|
|
To reference new dependencies (or updated versions) that are not yet packaged,
|
|
the dependency needs to point directly to a path or git source.
|
|
|
|
Steps for Releases
|
|
==================
|
|
|
|
- Run ./bump.sh <CRATE> [patch|minor|major|<VERSION>]
|
|
-- Fill out changelog
|
|
-- Confirm bump commit
|
|
- Build packages with `make deb`.
|
|
-- Don't forget to commit updated d/control!
|
|
|
|
Adding Crates
|
|
=============
|
|
|
|
1) At the top level:
|
|
- Generate the crate: ``cargo new --lib the-name``
|
|
- Sort the crate into ``Cargo.toml``'s ``workspace.members``
|
|
|
|
2) In the new crate's ``Cargo.toml``:
|
|
- In ``[package]`` set:
|
|
authors.workspace = true
|
|
license.workspace = true
|
|
edition.workspace = true
|
|
exclude.workspace = true
|
|
- Add a meaningful ``description``
|
|
- Copy ``debian/copyright`` and ``debian/debcargo.toml`` from another subcrate.
|
|
|
|
Adding a new Dependency
|
|
=======================
|
|
|
|
1) At the top level:
|
|
- Add it to ``[workspace.dependencies]`` specifying the version and any
|
|
features that should be enabled throughout the workspace
|
|
|
|
2) In each member's ``Cargo.toml``:
|
|
- Add it to the desired dependencies section with ``workspace = true`` and no
|
|
version specified.
|
|
- If this member requires additional features, add only the extra features to
|
|
the member dependency.
|
|
|
|
Updating a Dependency's Version
|
|
===============================
|
|
|
|
1) At the top level:
|
|
- Bump the version in ``[workspace.dependencies]`` as desired.
|
|
- Check for deprecations or breakage throughout the workspace.
|
|
|
|
Notes on Workspace Inheritance
|
|
==============================
|
|
|
|
Common metadata (like authors, license, ..) are inherited throughout the
|
|
workspace. If new fields are added that are identical for all crates, they
|
|
should be defined in the top-level ``Cargo.toml`` file's
|
|
``[workspace.package]`` section, and inherited in all members explicitly by
|
|
setting ``FIELD.workspace = true`` in the member's ``[package]`` section.
|
|
|
|
Dependency information is also inherited throughout the workspace, allowing a
|
|
single dependency specification in the top-level Cargo.toml file to be used by
|
|
all members.
|
|
|
|
Some restrictions apply:
|
|
- features can only be added in members, never removed (this includes
|
|
``default_features = false``!)
|
|
- the base feature set at the workspace level should be the minimum (possibly
|
|
empty!) set required by all members
|
|
- workspace dependency specifications cannot include ``optional``
|
|
- if needed, the ``optional`` flag needs to be set at the member level when
|
|
using a workspace dependency
|