Packaging a crate for Debian
============================
-To get set up, run::
+To get set up, run at Debian unstable (recommended)::
apt update && apt install debcargo
from ``src/<rust-crate-name>`` to ``src/<rust-crate-name>-<old-version>``, then
adapt it as needed.
+You will need excellent reasons to do this. It should be done only for core crates
+used by many other crates or programs for which the upgrade path is complex.
+For example, if the API significantly changed and requires a lot of work.
+
+Instead, please consider:
+* Downgrading or upgrading the dependency.
+* If it doesn't exist, open an issue on the upstream issue tracker to
+ encourage them to upgrade.
+* If possible/relevant, disable a feature if it uses it.
+* Wait until upstream upgraded.
+
To prepare a release
--------------------
An explanation of this, plus more recipes, can be found on the `sbuild wiki
page <https://wiki.debian.org/sbuild>`_.
+If you need to pass additional options to sbuild, like "--arch=i386", then set
+the SBUILD_OPTS environment variable.
+
Normally, ``./build.sh`` will fail early if not all the build dependencies are
available in your local apt cache. If you are packaging a large dependency tree
however, to avoid many round-trips through NEW it is possible to bypass this
The extra arguments after ``./build.sh B <args>`` is extra deb files to pass to
sbuild to use as dependencies. In this case, ``librust-A*.deb`` should have
-been built by the previous step.
+been built by the previous step. Alternatively, use the environment variable
+``EXTRA_DEBS``, like so: ::
+
+ $ EXTRA_DEBS=librust-A*.deb ./build.sh B
+ $ EXTRA_DEBS=librust-A.deb,librust-B.deb ./build.sh C
After everything is built successfully, you can ``dput`` all of them and then
push all the ``pending-*`` branches as normal.
obvious so documentation is less necessary, and dependent crates all do it
correctly already.)
+Setting collapse_features in debcargo.conf
+------------------------------------------
+
+Rust and Debian have a two different levels of abstraction when handling dependencies and the
+relationship between them. In rust the lowest level is a feature, and in Debian it's the binary
+package.
+
+This means that the following dependency chain is not a problem in rust:
+
+- crate A with feature AX depends on crate B with feature BY
+- crate B with feature BX depends on crate A with feature AY
+
+This is a perfectly valid situation in the rust+cargo ecosystem. Notice that
+there is no dependency cycle on the per-feature level, and this is enforced by
+cargo; but if collapse_features is used then package A+AX+AY would cyclicly
+depend on package B+BX+BY.
+
+This is reflected in the Debian packages by producing `Provides` lines for all combinations
+of features, and this can become a quite large section.
+
+Setting `collapse_features = true` in debcargo.toml removes this behaviour and is recommended,
+but it can lead to dependency cycles of debian packages, if that happens those must be
+broken up by having some or all of the packages set this feature to false.
+
Changed orig tarballs
---------------------
Generally we'll be uploading a dozen crates or so at once. Submitting ITPs for
these is unnecessary since we're the only ones uploading and there is no chance
of conflict. It would only be spam for the bug tracker. Please instead
-co-ordinate uploads on the ``#debian-rust`` IRC channel.
+coordinate uploads on the ``#debian-rust`` IRC channel.
Testing
-------
* https://blog.hackeriet.no/packaging-rust-part-II/
Now are they, those two blog posts, parked here. Waiting for better integration.
+
+
+Developing Rust code using Debian-packaged crates
+=================================================
+
+While perhaps not the stated intention, the Rust ecosystem in Debian
+is actually quite usable for developing Rust code in general. Thanks
+to `source replacement
+<https://doc.rust-lang.org/cargo/reference/source-replacement.html>`_,
+Cargo can be configured to use only local, Debian-provided packages by
+placing something like the following in ``~/.cargo/config.toml`` (for
+user-wide effect) or in a given project's ``.cargo/config.toml``::
+
+ [net]
+ offline = true
+
+ [source]
+
+ [source.crates-io]
+ replace-with = "debian"
+
+ [source.debian]
+ directory = "/usr/share/cargo/registry"
+
+In this state, Cargo will only look for crates installed as Debian
+packages on the local system.
projects / debcargo-conf.git / blobdiff