3 Packaging a crate for Debian
4 ============================
6 To get set up, run at Debian unstable (recommended)::
8 apt update && apt install debcargo
10 Then for each new package:
12 To package a new crate, or to update an existing crate
13 ------------------------------------------------------
17 ./new-package.sh <rust-crate-name> # or
18 ./update.sh <rust-crate-name>
20 and follow its instructions.
22 Note that ``new-package.sh`` is just a symlink to ``update.sh``, to help newcomers.
24 To package a co-installable older version of a crate
25 ----------------------------------------------------
27 To maintain an old version of a crate alongside the latest one, first make sure
28 the latest version is packaged by doing all of the above, then run::
30 ./new-package.sh <rust-crate-name> <old-version> # or
31 ./update.sh <rust-crate-name> <old-version>
33 and follow its instructions. To save time, you can first copy anything relevant
34 from ``src/<rust-crate-name>`` to ``src/<rust-crate-name>-<old-version>``, then
42 ./release.sh <rust-crate-name> # or
43 ./release.sh <rust-crate-name> <old-version> # as appropriate
44 DISTRO=experimental ./release.sh <rust-crate-name> # to target another distro
46 This prepares the necessary Debian files in ``build/``, and creates a git
47 branch to manage the packaging until it is accepted in Debian itself. You need
48 to run additional commands after this - more specific instructions are given to
49 you about this, by the script after you run it.
51 Holding packages at old versions
52 --------------------------------
54 If you need to keep the latest version in Debian at an older version than is
55 released on crates.io, e.g. to upload an important bugfix without being blocked
56 on having to package all the dependencies of the newest version, you can::
58 REALVER=<old-version> ./update.sh <rust-crate-name> # then
59 REALVER=<old-version> ./release.sh <rust-crate-name>
61 Repackaging the existing revision
62 ---------------------------------
64 In order to build a package A already in ``debcargo-conf/src``
65 in the exact version which is present here, do the following::
71 If this package is already in the archive and you want to recreate that
72 exactly, you will need to use the exact same version of debcargo that was
73 used previously. This version is mentioned in ``debian/changelog``.
79 To set up a suitable build environment for ``./build.sh``::
81 $ sudo apt-get install devscripts reprepro debootstrap sbuild dh-cargo schroot autopkgtest
82 $ sudo sbuild-createchroot --include=eatmydata,ccache,gnupg,dh-cargo,cargo,lintian,perl-openssl-defaults \
83 --chroot-prefix debcargo-unstable unstable \
84 /srv/chroot/debcargo-unstable-amd64-sbuild http://deb.debian.org/debian
86 An explanation of this, plus more recipes, can be found on the `sbuild wiki
87 page <https://wiki.debian.org/sbuild>`_.
89 If you need to pass additional options to sbuild, like "--arch=i386", then set
90 the SBUILD_OPTS environment variable.
92 Normally, ``./build.sh`` will fail early if not all the build dependencies are
93 available in your local apt cache. If you are packaging a large dependency tree
94 however, to avoid many round-trips through NEW it is possible to bypass this
95 check and build all the packages together. Suppose package B depends on package
96 A, then you can run something like::
98 $ export IGNORE_MISSING_BUILD_DEPS=1
100 $ ( cd build && ./build.sh A )
101 # push pending and checkout master
103 $ ( cd build && ./build.sh B librust-A*.deb )
105 The extra arguments after ``./build.sh B <args>`` is extra deb files to pass to
106 sbuild to use as dependencies. In this case, ``librust-A*.deb`` should have
107 been built by the previous step. Alternatively, use the environment variable
108 ``EXTRA_DEBS``, like so: ::
110 $ EXTRA_DEBS=librust-A*.deb ./build.sh B
111 $ EXTRA_DEBS=librust-A.deb,librust-B.deb ./build.sh C
113 After everything is built successfully, you can ``dput`` all of them and then
114 push all the ``pending-*`` branches as normal.
120 ``pending-*`` branches are managed by ``./release.sh``, so please don't manage
121 them yourself as you will interfere with the working of that script. The
122 intention is that they should only differ from the master branch by 1 commit,
123 i.e. the ``dch -r`` commit created by ``./release.sh``.
125 If you want to create separate non-master branches, that is fine - just don't
126 call them ``pending-*`` and don't run ``./release.sh`` on those branches. If you
127 want to test your crate, instead run::
129 cd build && [SOURCEONLY=1] ./build.sh <rust-crate-name> [<old-version>]
131 omitting or not omitting the stuff in [] as needed.
133 Like many other Debian git repositories, we don't follow "feature branch"
134 practises here. We generally don't package just 1 or 2 rust crates at a time,
135 but all of its dependencies and sometimes some reverse-dependencies too. So
136 normally we'll be touching a few dozen packages at once. In this context, it's
137 good to merge often, to avoid conflicts with someone else that might also need
138 to touch those too in the next few days.
140 To match a release (i.e. a ``.deb`` or a ``.dsc`` file) to a commit, find the
141 commit message that actually says "Release package X". This will usually be a
145 Expert mode & packaging multiple packages
146 =========================================
148 You should get used to the single-packaging workflow a bit first, including
149 doing a few `test builds <#build-environment>`_ of your package. Otherwise the
150 instructions below may seem a bit opaque.
152 1. ``rm -rf build/* && sbuild-update -udr debcargo-unstable-amd64-sbuild`` -
153 clears out your build directory, making the subsequent steps a bit faster.
154 2. ``./update.sh <CRATE>`` for all your relevant packages
155 3. Do any manual updates.
156 4. ``cd build`` then ``IGNORE_MISSING_BUILD_DEPS=1 ./build.sh <CRATE> *.deb``
157 for all your relevant packages, in dependency order.
158 5. Deal with any issues that come up.
159 6. Push your updates to our git.
160 7. Run ``dev/list-rdeps <CRATE> [<CRATE> ...]`` on all the crates you updated.
161 Any reverse-dependencies that are affected, also need to be updated and you
162 should repeat steps 1-7 (including this step) for them as well, until this
163 step lists no new packages that are affected.
164 8. ``./release.sh <CRATE>`` for all the packages you updated, running the build
165 again if necessary. It may be possible to do this out of dependency order,
166 assuming you didn't have to make significant changes in step (5). If you
167 did, then this step also has to be done in dependency order.
168 9. Push your ``pending-*`` branches to our git.
170 I like to have 4 shell windows open for this:
172 1. To do the manual updates.
173 2. To explore git, to remember what step you're on and to lookup previous
175 3. To explore the build directory, e.g. logs and crate source code.
176 4. To run a build. Try to have one running here at all times, for the next
177 package you didn't look at yet, to save time waiting.
179 There are also various scripts in ``dev/*`` that might help you. They should
180 have a couple lines at the top of the source code describing their
181 functionality and some brief usage instructions.
183 Whew, thanks for all your work!
186 General packaging tips
187 ======================
189 Dependencies on clippy
190 ----------------------
192 Patch away dependencies on "clippy" unless it is a "real" dependency. Usually
193 crates only use clippy to lint themselves and it is not a "real" dependency
194 in the sense that they actually import clippy's code for what they do.
196 If you want to be sure, ``rg clippy`` and check that all the usages of it are
197 inside ``cfg_attr`` declarations. If so, then just get rid of it.
202 See redox-syscall for examples on how to deal with these.
204 If this is unclear, ask on IRC.
206 Architecture-specific crates
207 ----------------------------
209 This is a bit harder. Usually there are two options:
211 1. The crate should build a dummy/no-op version of itself "out-of-the-box"
212 on the architectures it doesn't work on.
213 2. Dependent crates should depend on it with a platform-specific dependency,
214 see https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies
216 (1) involves less burden for others, both for dependent crates and for us
217 packagers, since we don't have to override d/rules to ignore test failures on
218 non-working architectures. You should communicate to upstream that this is
219 the preferred approach.
221 In the case of (2), the crate should document exactly what conditional should
222 be used, and keep this documentation up-to-date. This allows us to easily
223 determine if dependent crates are using the correct conditional. You will then
224 have to override d/rules for this crate, see src/simd for an example.
226 You should file a bug upstream if the crate does neither (1) nor document the
227 conditions for (2), e.g. https://github.com/hsivonen/simd/issues/25
229 (Actually the above applies even for "OS-specific crates" but then (2) is
230 obvious so documentation is less necessary, and dependent crates all do it
233 Setting collapse_features in debcargo.conf
234 ------------------------------------------
236 Rust and Debian have a two different levels of abstraction when handling dependencies and the
237 relationship between them. In rust the lowest level is a feature, and in Debian it's the binary
240 This means that the following dependency chain is not a problem in rust:
242 - crate A with feature AX depends on crate B with feature BY
243 - crate B with feature BX depends on crate A with feature AY
245 This is a perfectly valid situation in the rust+cargo ecosystem. Notice that
246 there is no dependency cycle on the per-feature level, and this is enforced by
247 cargo; but if collapse_features is used then package A+AX+AY would cyclicly
248 depend on package B+BX+BY.
250 This is reflected in the Debian packages by producing `Provides` lines for all combinations
251 of features, and this can become a quite large section.
253 Setting `collapse_features = true` in debcargo.toml removes this behaviour and is recommended,
254 but it can lead to dependency cycles of debian packages, if that happens those must be
255 broken up by having some or all of the packages set this feature to false.
257 Changed orig tarballs
258 ---------------------
260 Sometimes the orig.tar generated by debcargo might change e.g. if you are using
261 a newer version of debcargo and one of the dependencies relating to generating
262 the tarball was updated and its behaviour changed - compression settings,
263 tarball archive ordering, etc. This will cause your upload to get REJECTED by
264 the Debian FTP archive for having a different orig.tar. In this case, set
265 ``REUSE_EXISTING_ORIG_TARBALL=1`` when running ``./release.sh``.
270 Don't file ITPs for library crates, but do file them for binary crates.
272 Generally we'll be uploading a dozen crates or so at once. Submitting ITPs for
273 these is unnecessary since we're the only ones uploading and there is no chance
274 of conflict. It would only be spam for the bug tracker. Please instead
275 co-ordinate uploads on the ``#debian-rust`` IRC channel.
280 Debian has two types of tests:
282 1. pre-install tests run in ``debian/rules``
283 2. post-install tests defined in ``debian/tests/control``
285 For Debian rust packages, in (1) we run the crate's test suite with default
286 features but only if there are no dev-dependencies, and in (2) we run the whole
287 test suite with each feature enabled separately plus ``--no-default-features``
288 and ``--all-features``.
290 Sometimes, tests require extra tweaks and settings to work. In this case, you
291 can tweak ``debian/rules`` for (1), and for (2) you will simply have to mark
292 the relevant tests as broken using ``test_is_broken = true``. See the existing
293 crate configs for examples.
295 Other times, the tests are simply broken or can't be run in Debian. In this
296 case you should disable the test in (1) by running ``dh_auto_test -- build``
297 instead of the default ``dh_auto_test -- test --all``, and for (2) again you
298 should mark the relevant tests as broken.
299 These tests are going to be marked as flaky in autopkgtest, still executed but
300 won't fail the autopkgtest run.
302 Currently, using debcargo, it is not possible to add new dependencies as part
303 of an autopkgtest run. See https://salsa.debian.org/rust-team/debcargo/-/merge_requests/24
304 Instead, just override ``debian/tests/control``. See ``src/cbindgen/`` as
307 Please note that ``[packages.lib]\ntest_is_broken = true`` will transitively
308 disable tests for all combinations of features. Sometimes this is correct e.g.
309 if the test actually breaks for all features. Sometimes this is *not* correct,
310 e.g. if the test only breaks for ``--no-default-features``. In the latter case
311 you should instead patch the crate to ignore those tests when the relevant
312 features are absent - e.g. ``src/regex-automata/debian/patches/ignore-std-tests.patch``.
314 Binary-crate has "required-features"
315 ------------------------------------
317 See ``src/dotenv`` for an example on dealing with this.
319 Binary-crate has conflicting name
320 ---------------------------------
322 See ``src/fd-find`` for an example on dealing with this.
324 Updating the dependencies
325 -------------------------
327 In some cases, libraries/programs are forcing an old version of a library as
328 dependencies. In order to limit the number of duplicated libraries in the
329 archive, please try to evaluate if a newer version of the dependencies could be
332 To achieve that, after ``./update.sh``, try::
334 $ cd build/<package>/
335 $ rm -rf .pc # sometimes this is necessary due to minor debcargo bug
337 $ quilt new relax-dep.diff
338 $ quilt edit Cargo.toml
339 $ quilt header -e --dep3
341 $ cargo build # check that it works. if it does, then
342 $ cp -R patches ../../src/<package>/debian
344 Suppose you want to change the dependency from 0.3 to 0.5. If the crate builds
345 with no further source changes, then we would change the required version in
346 ``Cargo.toml`` from ``0.3`` to ``>= 0.3, < 0.6`` or something like that. Then
347 the convention is to put all these changes into a single patch called
348 ``relax-dep-versions.patch``.
350 OTOH, if the cargo build fails, and you can fix it up by editing the source
351 code in a minor way to use the new crate API, then: for each crate that needs
352 to be updated, you should instead name the patch ``update-dep-<crate>.patch``
353 and add both the ``Cargo.toml`` and the source code changes to it. The change
354 to ``Cargo.toml`` would then simply say (e.g.) ``0.5`` since the older versions
355 actually don't work, and not the version range from the previous paragraph.
357 If you want to make a crate work with an older dependency version than listed
358 in ``Cargo.toml`` (for example 0.3 instead of 0.5), you cannot use a flexible
359 version requirement like ``>= 0.3, < 0.6``. Instead you have to specify only
360 the older version, in this example ``0.3`` (`explanation`_).
362 .. _explanation: https://salsa.debian.org/rust-team/debcargo-conf/merge_requests/86#note_135456
364 Information on patch headers is available in `dep3`_.
365 Use (some of) the headers to explain **why** the patch exists.
367 .. _dep3: https://dep-team.pages.debian.net/deps/dep3/
369 Help, something went wrong!
370 ---------------------------
372 Sometimes, the error messages are not the most informative. In this case you
373 can try re-running the command with ``RUST_BACKTRACE=1``. If you are using the
374 ``debcargo`` from Debian's own repositories, you should also install the
375 ``debcargo-dbgsym`` package, otherwise the stack trace will be next to useless.
376 Make sure you have the `debug repository <https://wiki.debian.org/HowToGetABacktrace#Installing_the_debugging_symbols>`_
377 enabled in your APT sources.
383 In ``#debian-rust`` came these two blog posts along with the remark of _good read_
384 * https://blog.hackeriet.no/packaging-a-rust-project-for-debian/
385 * https://blog.hackeriet.no/packaging-rust-part-II/
387 Now are they, those two blog posts, parked here. Waiting for better integration.
390 Developing Rust code using Debian-packaged crates
391 =================================================
393 While perhaps not the stated intention, the Rust ecosystem in Debian
394 is actually quite usable for developing Rust code in general. Thanks
395 to `source replacement
396 <https://doc.rust-lang.org/cargo/reference/source-replacement.html>`_,
397 Cargo can be configured to use only local, Debian-provided packages by
398 placing something like the following in ``~/.cargo/config.toml`` (for
399 user-wide effect) or in a given project's ``.cargo/config.toml``::
407 replace-with = "debian"
410 directory = "/usr/share/cargo/registry"
412 In this state, Cargo will only look for crates installed as Debian
413 packages on the local system.