mirror of
https://git.proxmox.com/git/proxmox
synced 2025-08-14 13:13:20 +00:00
README: extend Adding Cates section, convert to markdown
(conveted with pandoc and some minor manual fixups) Mention that the crates should activate `doc_cfg, doc_auto_cfg` and ideally `#[deny(unsafe_op_in_unsafe_fn)]` and `#[deny(missing_docs)]`. Signed-off-by: Wolfgang Bumiller <w.bumiller@proxmox.com>
This commit is contained in:
Wolfgang Bumiller
parent
f7e130d5b5
commit
7379bdfb9c
97
README.md
Normal file
97
README.md
Normal file
@ -0,0 +1,97 @@
|
|||||||
|
# Local cargo config
|
||||||
|
|
||||||
|
This repository ships with a `.cargo/config.toml` 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.
|
||||||
|
|
||||||
|
# Quickly installing all packages from apt
|
||||||
|
|
||||||
|
To a void too many manual installations when `mk-build-deps` etc. fail, a quick
|
||||||
|
way to install all the main packages of this workspace is to run:
|
||||||
|
|
||||||
|
# apt install $(make list-packages)
|
||||||
|
|
||||||
|
# Steps for Releases
|
||||||
|
|
||||||
|
- Run `./bump.sh <CRATE> [patch|minor|major|<VERSION>]`
|
||||||
|
- Fill out changelog
|
||||||
|
- Confirm bump commit
|
||||||
|
- Build packages with `make <crate>-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
|
||||||
|
edition.workspace = true
|
||||||
|
exclude.workspace = true
|
||||||
|
homepage.workspace = true
|
||||||
|
license.workspace = true
|
||||||
|
repository.workspace = true
|
||||||
|
rust-version.workspace = true
|
||||||
|
|
||||||
|
If a separate ``exclude`` is need it, separate it out as its own
|
||||||
|
block above the inherited fields.
|
||||||
|
- Add a meaningful `description`
|
||||||
|
- Copy `debian/copyright` and `debian/debcargo.toml` from another subcrate.
|
||||||
|
|
||||||
|
3. In the new crate\'s `lib.rs`, add the following preamble on top:
|
||||||
|
|
||||||
|
#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
|
||||||
|
|
||||||
|
4. Ideally (but optionally) in the new crate\'s `lib.rs`, add the following
|
||||||
|
preamble on top as well:
|
||||||
|
|
||||||
|
#![deny(unsafe_op_in_unsafe_fn)]
|
||||||
|
#![deny(missing_docs)]
|
||||||
|
|
||||||
|
# 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
|
||||||
94
README.rst
94
README.rst
@ -1,94 +0,0 @@
|
|||||||
Local cargo config
|
|
||||||
==================
|
|
||||||
|
|
||||||
This repository ships with a ``.cargo/config.toml`` 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.
|
|
||||||
|
|
||||||
Quickly installing all packages from apt
|
|
||||||
========================================
|
|
||||||
|
|
||||||
To a void too many manual installations when ``mk-build-deps`` etc. fail, a
|
|
||||||
quick way to install all the main packages of this workspace is to run:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
# apt install $(make list-packages)
|
|
||||||
|
|
||||||
Steps for Releases
|
|
||||||
==================
|
|
||||||
|
|
||||||
- Run ./bump.sh <CRATE> [patch|minor|major|<VERSION>]
|
|
||||||
-- Fill out changelog
|
|
||||||
-- Confirm bump commit
|
|
||||||
- Build packages with `make <crate>-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
|
|
||||||
edition.workspace = true
|
|
||||||
exclude.workspace = true
|
|
||||||
homepage.workspace = true
|
|
||||||
license.workspace = true
|
|
||||||
repository.workspace = true
|
|
||||||
rust-version.workspace = true
|
|
||||||
If a separate 'exclude' is need it, separate it out as its own block above
|
|
||||||
the inherited fields.
|
|
||||||
- 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
|
|
||||||
Loading…
Reference in New Issue
Block a user