6 apt update && apt install debcargo
8 Then for each new package:
10 To package a new crate, or to update an existing crate
11 ------------------------------------------------------
15 ./new-package.sh <rust-crate-name> # or
16 ./update.sh <rust-crate-name>
18 and follow its instructions.
20 Note that ``new-package.sh`` is just a symlink to ``update.sh``, to help newcomers.
22 To package an older version of a crate
23 --------------------------------------
25 To maintain an old version of a crate alongside the latest one, first make sure
26 the latest version is packaged by doing all of the above, then run::
28 ./new-package.sh <rust-crate-name> <old-version> # or
29 ./update.sh <rust-crate-name> <old-version>
31 and follow its instructions. To save time, you can first copy anything relevant
32 from ``src/<rust-crate-name>`` to ``src/<rust-crate-name>-<old-version>``, then
40 ./release.sh <rust-crate-name> # or
41 ./release.sh <rust-crate-name> <old-version> # as appropriate
42 DISTRO=experimental ./release.sh <rust-crate-name> # to target another distro
44 This prepares the necessary Debian files in ``build/``, and creates a git
45 branch to manage the packaging until it is accepted in Debian itself. You need
46 to run additional commands after this - more specific instructions are given to
47 you about this, by the script after you run it.
49 Holding packages at old versions
50 --------------------------------
52 If you need to keep the latest version in Debian at an older version than is
53 released on crates.io, e.g. to upload an important bugfix without being blocked
54 on having to package all the dependencies of the newest version, you can::
56 REALVER=<old-version> ./update.sh <rust-crate-name> # then
57 REALVER=<old-version> ./release.sh <rust-crate-name>
59 Repackaging the existing revision
60 ---------------------------------
62 In order to build a package A already in ``debcargo-conf/src``
63 in the exact version which is present here, do the following::
69 If this package is already in the archive and you want to recreate that
70 exactly, you will need to use the exact same version of debcargo that was
71 used previously. This version is mentioned in ``debian/changelog``.
77 `pending-*` branches are managed by `./release.sh`, so please don't manage them
78 yourself as you will interfere with the working of that script. The intention
79 is that they should only differ from the master branch by 1 commit, i.e. the
80 `dch -r` commit created by `./release.sh`.
82 If you want to create separate non-master branches, that is fine - just don't
83 call them `pending-*` and don't run `./release.sh` on those branches. If you
84 want to test your crate, instead run::
86 cd build && [SOURCEONLY=1] ./build.sh <rust-crate-name> [<old-version>]
88 omitting or not omitting the stuff in [] as needed.
94 To set up a suitable build environment for ``./build.sh``::
96 $ sudo apt-get install devscripts reprepro debootstrap sbuild dh-cargo
97 $ sudo sbuild-createchroot --include=eatmydata,ccache,gnupg,dh-cargo,cargo,lintian,perl-openssl-defaults \
98 --chroot-prefix debcargo-unstable unstable \
99 /srv/chroot/debcargo-unstable-amd64-sbuild http://deb.debian.org/debian
101 Normally, ``./build.sh`` will fail early if not all the build dependencies are
102 available in your local apt cache. If you are packaging a large dependency tree
103 however, to avoid many round-trips through NEW it is possible to bypass this
104 check and build all the packages together. Suppose package B depends on package
105 A, then you can run something like::
107 $ export IGNORE_MISSING_BUILD_DEPS=1
109 $ ( cd build && ./build.sh A )
110 # push pending and checkout master
112 $ ( cd build && ./build.sh B librust-A*.deb )
114 The extra arguments after ``./build.sh B <args>`` is extra deb files to pass to
115 sbuild to use as dependencies. In this case, ``librust-A*.deb`` should have
116 been built by the previous step.
118 After everything is built successfully, you can ``dput`` all of them and then
119 push all the ``pending-*`` branches as normal.
122 General packaging tips
123 ======================
125 Dependencies on clippy
126 ----------------------
128 Patch away dependencies on "clippy" unless it is a "real" dependency. Usually
129 crates only use clippy to lint themselves and it is not a "real" dependency
130 in the sense that they actually import clippy's code for what they do.
132 If you want to be sure, `rg clippy` and check that all the usages of it are
133 inside `cfg_attr` declarations. If so, then just get rid of it.
138 See redox-syscall for examples on how to deal with these.
140 If this is unclear, ask on IRC.
142 Architecture-specific crates
143 ----------------------------
145 This is a bit harder. Usually there are two options:
147 1. The crate should build a dummy/no-op version of itself "out-of-the-box"
148 on the architectures it doesn't work on.
149 2. Dependent crates should depend on it with a platform-specific dependency,
150 see https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies
152 (1) involves less burden for others, both for dependent crates and for us
153 packagers, since we don't have to override d/rules to ignore test failures on
154 non-working architectures. You should communicate to upstream that this is
155 the preferred approach.
157 In the case of (2), the crate should document exactly what conditional should
158 be used, and keep this documentation up-to-date. This allows us to easily
159 determine if dependent crates are using the correct conditional. You will then
160 have to override d/rules for this crate, see src/simd for an example.
162 You should file a bug upstream if the crate does neither (1) nor document the
163 conditions for (2), e.g. https://github.com/hsivonen/simd/issues/25
165 (Actually the above applies even for "OS-specific crates" but then (2) is
166 obvious so documentation is less necessary, and dependent crates all do it
169 Changed orig tarballs
170 ---------------------
172 Sometimes the orig.tar generated by debcargo might change e.g. if you are using
173 a newer version of debcargo and one of the dependencies relating to generating
174 the tarball was updated and its behaviour changed - compression settings,
175 tarball archive ordering, etc. This will cause your upload to get REJECTED by
176 the Debian FTP archive for having a different orig.tar. In this case, set
177 REUSE_EXISTING_ORIG_TARBALL=1 when running ``./release.sh``.
182 Don't file ITPs for library crates, but do file them for binary crates.
184 For now (updated 2018-09) we have several hundred crates to upload. Submitting
185 ITPs for these is unnecessary since we're the only ones uploading and there is
186 no chance of conflict. It would only be spam for the bug tracker. Please
187 instead co-ordinate uploads on the #debian-rust IRC channel.
192 For now, testsuites aren't executed for library.
193 However, for binary, it is strongly recommended to run the testsuites.
194 See ripgrep as example.
196 Binary-crate has "required-features"
197 ------------------------------------
199 See ``src/dotenv`` for an example on dealing with this.
201 Binary-crate has conflicting name
202 ---------------------------------
204 See ``src/fd-find`` for an example on dealing with this.
206 Updating the dependencies
207 -------------------------
209 In some cases, libraries/programs are forcing an old version of a library as
210 dependencies. In order to limit the number of duplicated libraries in the
211 archive, please try to evaluate if a newer version of the dependencies could be
214 To achieve that, after ./update.sh, try::
216 $ cd build/<package>/
217 $ rm -rf .pc # sometimes this is necessary due to minor debcargo bug
219 $ quilt new relax-dep.diff
220 $ quilt edit Cargo.toml
222 $ cargo build # check that it works. if it does, then
223 $ cp -R patches ../../src/<package>/debian
225 Suppose you want to change the dependency from 0.3 to 0.5. If the crate builds
226 with no further source changes, then we would change the required version in
227 ``Cargo.toml`` from ``0.3`` to ``>= 0.3, < 0.6`` or something like that. Then
228 the convention is to put all these changes into a single patch called
229 ``relax-dep-versions.patch``.
231 OTOH, if the cargo build fails, and you can fix it up by editing the source
232 code in a minor way to use the new crate API, then: for each crate that needs
233 to be updated, you should instead name the patch ``update-dep-<crate>.patch``
234 and add both the ``Cargo.toml`` and the source code changes to it. Use
235 ``quilt rename`` if that helps you.