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 Normally, ``./build.sh`` will fail early if not all the build dependencies are
90 available in your local apt cache. If you are packaging a large dependency tree
91 however, to avoid many round-trips through NEW it is possible to bypass this
92 check and build all the packages together. Suppose package B depends on package
93 A, then you can run something like::
95 $ export IGNORE_MISSING_BUILD_DEPS=1
97 $ ( cd build && ./build.sh A )
98 # push pending and checkout master
100 $ ( cd build && ./build.sh B librust-A*.deb )
102 The extra arguments after ``./build.sh B <args>`` is extra deb files to pass to
103 sbuild to use as dependencies. In this case, ``librust-A*.deb`` should have
104 been built by the previous step.
106 After everything is built successfully, you can ``dput`` all of them and then
107 push all the ``pending-*`` branches as normal.
113 ``pending-*`` branches are managed by ``./release.sh``, so please don't manage
114 them yourself as you will interfere with the working of that script. The
115 intention is that they should only differ from the master branch by 1 commit,
116 i.e. the ``dch -r`` commit created by ``./release.sh``.
118 If you want to create separate non-master branches, that is fine - just don't
119 call them ``pending-*`` and don't run ``./release.sh`` on those branches. If you
120 want to test your crate, instead run::
122 cd build && [SOURCEONLY=1] ./build.sh <rust-crate-name> [<old-version>]
124 omitting or not omitting the stuff in [] as needed.
126 Like many other Debian git repositories, we don't follow "feature branch"
127 practises here. We generally don't package just 1 or 2 rust crates at a time,
128 but all of its dependencies and sometimes some reverse-dependencies too. So
129 normally we'll be touching a few dozen packages at once. In this context, it's
130 good to merge often, to avoid conflicts with someone else that might also need
131 to touch those too in the next few days.
133 To match a release (i.e. a ``.deb`` or a ``.dsc`` file) to a commit, find the
134 commit message that actually says "Release package X". This will usually be a
138 Expert mode & packaging multiple packages
139 =========================================
141 You should get used to the single-packaging workflow a bit first, including
142 doing a few `test builds <#build-environment>`_ of your package. Otherwise the
143 instructions below may seem a bit opaque.
145 1. ``rm -rf build/* && sbuild-update -udr debcargo-unstable-amd64-sbuild`` -
146 clears out your build directory, making the subsequent steps a bit faster.
147 2. ``./update.sh <CRATE>`` for all your relevant packages
148 3. Do any manual updates.
149 4. ``cd build`` then ``IGNORE_MISSING_BUILD_DEPS=1 ./build.sh <CRATE> *.deb``
150 for all your relevant packages, in dependency order.
151 5. Deal with any issues that come up.
152 6. Push your updates to our git.
153 7. Run ``dev/list-rdeps <CRATE> [<CRATE> ...]`` on all the crates you updated.
154 Any reverse-dependencies that are affected, also need to be updated and you
155 should repeat steps 1-7 (including this step) for them as well, until this
156 step lists no new packages that are affected.
157 8. ``./release.sh <CRATE>`` for all the packages you updated, running the build
158 again if necessary. It may be possible to do this out of dependency order,
159 assuming you didn't have to make significant changes in step (5). If you
160 did, then this step also has to be done in dependency order.
161 9. Push your ``pending-*`` branches to our git.
163 I like to have 4 shell windows open for this:
165 1. To do the manual updates.
166 2. To explore git, to remember what step you're on and to lookup previous
168 3. To explore the build directory, e.g. logs and crate source code.
169 4. To run a build. Try to have one running here at all times, for the next
170 package you didn't look at yet, to save time waiting.
172 There are also various scripts in ``dev/*`` that might help you. They should
173 have a couple lines at the top of the source code describing their
174 functionality and some brief usage instructions.
176 Whew, thanks for all your work!
179 General packaging tips
180 ======================
182 Dependencies on clippy
183 ----------------------
185 Patch away dependencies on "clippy" unless it is a "real" dependency. Usually
186 crates only use clippy to lint themselves and it is not a "real" dependency
187 in the sense that they actually import clippy's code for what they do.
189 If you want to be sure, ``rg clippy`` and check that all the usages of it are
190 inside ``cfg_attr`` declarations. If so, then just get rid of it.
195 See redox-syscall for examples on how to deal with these.
197 If this is unclear, ask on IRC.
199 Architecture-specific crates
200 ----------------------------
202 This is a bit harder. Usually there are two options:
204 1. The crate should build a dummy/no-op version of itself "out-of-the-box"
205 on the architectures it doesn't work on.
206 2. Dependent crates should depend on it with a platform-specific dependency,
207 see https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies
209 (1) involves less burden for others, both for dependent crates and for us
210 packagers, since we don't have to override d/rules to ignore test failures on
211 non-working architectures. You should communicate to upstream that this is
212 the preferred approach.
214 In the case of (2), the crate should document exactly what conditional should
215 be used, and keep this documentation up-to-date. This allows us to easily
216 determine if dependent crates are using the correct conditional. You will then
217 have to override d/rules for this crate, see src/simd for an example.
219 You should file a bug upstream if the crate does neither (1) nor document the
220 conditions for (2), e.g. https://github.com/hsivonen/simd/issues/25
222 (Actually the above applies even for "OS-specific crates" but then (2) is
223 obvious so documentation is less necessary, and dependent crates all do it
226 Changed orig tarballs
227 ---------------------
229 Sometimes the orig.tar generated by debcargo might change e.g. if you are using
230 a newer version of debcargo and one of the dependencies relating to generating
231 the tarball was updated and its behaviour changed - compression settings,
232 tarball archive ordering, etc. This will cause your upload to get REJECTED by
233 the Debian FTP archive for having a different orig.tar. In this case, set
234 ``REUSE_EXISTING_ORIG_TARBALL=1`` when running ``./release.sh``.
239 Don't file ITPs for library crates, but do file them for binary crates.
241 Generally we'll be uploading a dozen crates or so at once. Submitting ITPs for
242 these is unnecessary since we're the only ones uploading and there is no chance
243 of conflict. It would only be spam for the bug tracker. Please instead
244 co-ordinate uploads on the ``#debian-rust`` IRC channel.
249 Debian has two types of tests:
251 1. pre-install tests run in ``debian/rules``
252 2. post-install tests defined in ``debian/tests/control``
254 For Debian rust packages, in (1) we run the crate's test suite with default
255 features but only if there are no dev-dependencies, and in (2) we run the whole
256 test suite with each feature enabled separately plus ``--no-default-features``
257 and ``--all-features``.
259 Sometimes, tests require extra tweaks and settings to work. In this case, you
260 can tweak ``debian/rules`` for (1), and for (2) you will simply have to mark
261 the relevant tests as broken using ``test_is_broken = true``. See the existing
262 crate configs for examples.
264 Other times, the tests are simply broken or can't be run in Debian. In this
265 case you should disable the test in (1) by running ``dh_auto_test -- build``
266 instead of the default ``dh_auto_test -- test --all``, and for (2) again you
267 should mark the relevant tests as broken.
268 These tests are going to be marked as flaky in autopkgtest, still executed but
269 won't fail the autopkgtest run.
271 Currently, using debcargo, it is not possible to add new dependencies as part
272 of an autopkgtest run. See https://salsa.debian.org/rust-team/debcargo/-/merge_requests/24
273 Instead, just override ``debian/tests/control``. See ``src/cbindgen/`` as
276 Please note that ``[packages.lib]\ntest_is_broken = true`` will transitively
277 disable tests for all combinations of features. Sometimes this is correct e.g.
278 if the test actually breaks for all features. Sometimes this is *not* correct,
279 e.g. if the test only breaks for ``--no-default-features``. In the latter case
280 you should instead patch the crate to ignore those tests when the relevant
281 features are absent - e.g. ``src/regex-automata/debian/patches/ignore-std-tests.patch``.
283 Binary-crate has "required-features"
284 ------------------------------------
286 See ``src/dotenv`` for an example on dealing with this.
288 Binary-crate has conflicting name
289 ---------------------------------
291 See ``src/fd-find`` for an example on dealing with this.
293 Updating the dependencies
294 -------------------------
296 In some cases, libraries/programs are forcing an old version of a library as
297 dependencies. In order to limit the number of duplicated libraries in the
298 archive, please try to evaluate if a newer version of the dependencies could be
301 To achieve that, after ``./update.sh``, try::
303 $ cd build/<package>/
304 $ rm -rf .pc # sometimes this is necessary due to minor debcargo bug
306 $ quilt new relax-dep.diff
307 $ quilt edit Cargo.toml
308 $ quilt header -e --dep3
310 $ cargo build # check that it works. if it does, then
311 $ cp -R patches ../../src/<package>/debian
313 Suppose you want to change the dependency from 0.3 to 0.5. If the crate builds
314 with no further source changes, then we would change the required version in
315 ``Cargo.toml`` from ``0.3`` to ``>= 0.3, < 0.6`` or something like that. Then
316 the convention is to put all these changes into a single patch called
317 ``relax-dep-versions.patch``.
319 OTOH, if the cargo build fails, and you can fix it up by editing the source
320 code in a minor way to use the new crate API, then: for each crate that needs
321 to be updated, you should instead name the patch ``update-dep-<crate>.patch``
322 and add both the ``Cargo.toml`` and the source code changes to it. The change
323 to ``Cargo.toml`` would then simply say (e.g.) ``0.5`` since the older versions
324 actually don't work, and not the version range from the previous paragraph.
326 If you want to make a crate work with an older dependency version than listed
327 in ``Cargo.toml`` (for example 0.3 instead of 0.5), you cannot use a flexible
328 version requirement like ``>= 0.3, < 0.6``. Instead you have to specify only
329 the older version, in this example ``0.3`` (`explanation`_).
331 .. _explanation: https://salsa.debian.org/rust-team/debcargo-conf/merge_requests/86#note_135456
333 Information on patch headers is available in `dep3`_.
334 Use (some of) the headers to explain **why** the patch exists.
336 .. _dep3: https://dep-team.pages.debian.net/deps/dep3/
338 Help, something went wrong!
339 ---------------------------
341 Sometimes, the error messages are not the most informative. In this case you
342 can try re-running the command with ``RUST_BACKTRACE=1``. If you are using the
343 ``debcargo`` from Debian's own repositories, you should also install the
344 ``debcargo-dbgsym`` package, otherwise the stack trace will be next to useless.
345 Make sure you have the `debug repository <https://wiki.debian.org/HowToGetABacktrace#Installing_the_debugging_symbols>`_
346 enabled in your APT sources.
352 In ``#debian-rust`` came these two blog posts along with the remark of _good read_
353 * https://blog.hackeriet.no/packaging-a-rust-project-for-debian/
354 * https://blog.hackeriet.no/packaging-rust-part-II/
356 Now are they, those two blog posts, parked here. Waiting for better integration.
359 Developing Rust code using Debian-packaged crates
360 =================================================
362 While perhaps not the stated intention, the Rust ecosystem in Debian
363 is actually quite usable for developing Rust code in general. Thanks
364 to `source replacement
365 <https://doc.rust-lang.org/cargo/reference/source-replacement.html>`_,
366 Cargo can be configured to use only local, Debian-provided packages by
367 placing something like the following in ``~/.cargo/config.toml`` (for
368 user-wide effect) or in a given project's ``.cargo/config.toml``::
376 replace-with = "debian"
379 directory = "/usr/share/cargo/registry"
381 In this state, Cargo will only look for crates installed as Debian
382 packages on the local system.