]>
Commit | Line | Data |
---|---|---|
d580884e XL |
1 | Instructions |
2 | ============ | |
3 | ||
1057693c XL |
4 | To get set up, run:: |
5 | ||
4333698e | 6 | apt update && apt install debcargo |
1057693c XL |
7 | |
8 | Then for each new package: | |
23db3623 | 9 | |
8960a81d XL |
10 | To package a new crate, or to update an existing crate |
11 | ------------------------------------------------------ | |
931eabc0 | 12 | |
8960a81d XL |
13 | :: |
14 | ||
15 | ./new-package.sh <rust-crate-name> # or | |
16 | ./update.sh <rust-crate-name> | |
86e10bdd | 17 | |
6c1b3182 XL |
18 | and follow its instructions. |
19 | ||
8960a81d | 20 | Note that ``new-package.sh`` is just a symlink to ``update.sh``, to help newcomers. |
7b976234 | 21 | |
1ff2ded3 XL |
22 | To package a co-installable older version of a crate |
23 | ---------------------------------------------------- | |
7b976234 | 24 | |
6c1b3182 | 25 | To maintain an old version of a crate alongside the latest one, first make sure |
8960a81d | 26 | the latest version is packaged by doing all of the above, then run:: |
6c1b3182 | 27 | |
8960a81d XL |
28 | ./new-package.sh <rust-crate-name> <old-version> # or |
29 | ./update.sh <rust-crate-name> <old-version> | |
86e10bdd | 30 | |
fed17d69 XL |
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 | |
33 | adapt it as needed. | |
999f9269 | 34 | |
8960a81d XL |
35 | To prepare a release |
36 | -------------------- | |
37 | ||
38 | :: | |
5cbe2f60 | 39 | |
699de4ac SL |
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 | |
86e10bdd | 43 | |
fed17d69 XL |
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. | |
6c1b3182 | 48 | |
8960a81d XL |
49 | Holding packages at old versions |
50 | -------------------------------- | |
51 | ||
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:: | |
55 | ||
56 | REALVER=<old-version> ./update.sh <rust-crate-name> # then | |
57 | REALVER=<old-version> ./release.sh <rust-crate-name> | |
58 | ||
c6709bfe XL |
59 | Repackaging the existing revision |
60 | --------------------------------- | |
61 | ||
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:: | |
64 | ||
65 | $ ./repackage.sh A | |
66 | $ cd build | |
67 | $ ./build.sh A | |
68 | ||
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``. | |
72 | ||
d580884e | 73 | |
ed79d202 XL |
74 | Repository structure |
75 | ==================== | |
76 | ||
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`. | |
81 | ||
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:: | |
85 | ||
86 | cd build && [SOURCEONLY=1] ./build.sh <rust-crate-name> [<old-version>] | |
87 | ||
88 | omitting or not omitting the stuff in [] as needed. | |
89 | ||
1ff2ded3 XL |
90 | Like many other Debian git repositories, we don't follow "feature branch" |
91 | practises here. We generally don't package just 1 or 2 rust crates at a time, | |
92 | but all of its dependencies and sometimes some reverse-dependencies too. So | |
93 | normally we'll be touching a few dozen packages at once. In this context, it's | |
94 | good to merge often, to avoid conflicts with someone else that might also need | |
95 | to touch those too in the next few days. | |
96 | ||
97 | To match a release (i.e. a ``.deb`` or a ``.dsc`` file) to a commit, find the | |
98 | commit message that actually says "Release package X". This will usually be a | |
99 | merge commit. | |
100 | ||
ed79d202 | 101 | |
c6709bfe XL |
102 | Build environment |
103 | ================= | |
104 | ||
105 | To set up a suitable build environment for ``./build.sh``:: | |
106 | ||
107 | $ sudo apt-get install devscripts reprepro debootstrap sbuild dh-cargo | |
108 | $ sudo sbuild-createchroot --include=eatmydata,ccache,gnupg,dh-cargo,cargo,lintian,perl-openssl-defaults \ | |
109 | --chroot-prefix debcargo-unstable unstable \ | |
110 | /srv/chroot/debcargo-unstable-amd64-sbuild http://deb.debian.org/debian | |
111 | ||
1ff2ded3 XL |
112 | An explanation of this, plus more recipes, can be found on the `sbuild wiki |
113 | page <https://wiki.debian.org/sbuild>`_. | |
114 | ||
c6709bfe XL |
115 | Normally, ``./build.sh`` will fail early if not all the build dependencies are |
116 | available in your local apt cache. If you are packaging a large dependency tree | |
117 | however, to avoid many round-trips through NEW it is possible to bypass this | |
118 | check and build all the packages together. Suppose package B depends on package | |
119 | A, then you can run something like:: | |
120 | ||
121 | $ export IGNORE_MISSING_BUILD_DEPS=1 | |
122 | $ ./release.sh A | |
123 | $ ( cd build && ./build.sh A ) | |
124 | # push pending and checkout master | |
125 | $ ./release.sh B | |
126 | $ ( cd build && ./build.sh B librust-A*.deb ) | |
127 | ||
128 | The extra arguments after ``./build.sh B <args>`` is extra deb files to pass to | |
129 | sbuild to use as dependencies. In this case, ``librust-A*.deb`` should have | |
130 | been built by the previous step. | |
131 | ||
132 | After everything is built successfully, you can ``dput`` all of them and then | |
133 | push all the ``pending-*`` branches as normal. | |
134 | ||
135 | ||
7f68b728 XL |
136 | General packaging tips |
137 | ====================== | |
138 | ||
139 | Dependencies on clippy | |
140 | ---------------------- | |
141 | ||
142 | Patch away dependencies on "clippy" unless it is a "real" dependency. Usually | |
143 | crates only use clippy to lint themselves and it is not a "real" dependency | |
144 | in the sense that they actually import clippy's code for what they do. | |
145 | ||
146 | If you want to be sure, `rg clippy` and check that all the usages of it are | |
147 | inside `cfg_attr` declarations. If so, then just get rid of it. | |
148 | ||
738135f9 XL |
149 | OS-specific crates |
150 | ------------------ | |
151 | ||
152 | See redox-syscall for examples on how to deal with these. | |
153 | ||
154 | If this is unclear, ask on IRC. | |
155 | ||
7f68b728 XL |
156 | Architecture-specific crates |
157 | ---------------------------- | |
01f68998 | 158 | |
738135f9 | 159 | This is a bit harder. Usually there are two options: |
95399141 | 160 | |
738135f9 XL |
161 | 1. The crate should build a dummy/no-op version of itself "out-of-the-box" |
162 | on the architectures it doesn't work on. | |
163 | 2. Dependent crates should depend on it with a platform-specific dependency, | |
164 | see https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies | |
165 | ||
166 | (1) involves less burden for others, both for dependent crates and for us | |
167 | packagers, since we don't have to override d/rules to ignore test failures on | |
168 | non-working architectures. You should communicate to upstream that this is | |
169 | the preferred approach. | |
170 | ||
171 | In the case of (2), the crate should document exactly what conditional should | |
172 | be used, and keep this documentation up-to-date. This allows us to easily | |
173 | determine if dependent crates are using the correct conditional. You will then | |
174 | have to override d/rules for this crate, see src/simd for an example. | |
175 | ||
176 | You should file a bug upstream if the crate does neither (1) nor document the | |
177 | conditions for (2), e.g. https://github.com/hsivonen/simd/issues/25 | |
178 | ||
179 | (Actually the above applies even for "OS-specific crates" but then (2) is | |
180 | obvious so documentation is less necessary, and dependent crates all do it | |
181 | correctly already.) | |
95399141 | 182 | |
a0c73b1a XL |
183 | Changed orig tarballs |
184 | --------------------- | |
185 | ||
186 | Sometimes the orig.tar generated by debcargo might change e.g. if you are using | |
187 | a newer version of debcargo and one of the dependencies relating to generating | |
188 | the tarball was updated and its behaviour changed - compression settings, | |
189 | tarball archive ordering, etc. This will cause your upload to get REJECTED by | |
190 | the Debian FTP archive for having a different orig.tar. In this case, set | |
1ff2ded3 | 191 | ``REUSE_EXISTING_ORIG_TARBALL=1`` when running ``./release.sh``. |
a0c73b1a | 192 | |
7f68b728 XL |
193 | ITPs |
194 | ---- | |
95399141 | 195 | |
7f68b728 | 196 | Don't file ITPs for library crates, but do file them for binary crates. |
01f68998 | 197 | |
1ff2ded3 XL |
198 | Generally we'll be uploading a dozen crates or so at once. Submitting ITPs for |
199 | these is unnecessary since we're the only ones uploading and there is no chance | |
200 | of conflict. It would only be spam for the bug tracker. Please instead | |
201 | co-ordinate uploads on the ``#debian-rust`` IRC channel. | |
01f68998 | 202 | |
0d1e2247 SL |
203 | Testing |
204 | ------- | |
205 | ||
dc94b1d5 XL |
206 | Debian has two types of tests: |
207 | ||
1ff2ded3 XL |
208 | 1. pre-install tests run in ``debian/rules`` |
209 | 2. post-install tests defined in ``debian/tests/control`` | |
dc94b1d5 XL |
210 | |
211 | For Debian rust packages, in (1) we run the crate's test suite with default | |
212 | features but only if there are no dev-dependencies, and in (2) we run the whole | |
1ff2ded3 XL |
213 | test suite with each feature enabled separately plus ``--no-default-features`` |
214 | and ``--all-features``. | |
dc94b1d5 XL |
215 | |
216 | Sometimes, tests require extra tweaks and settings to work. In this case, you | |
217 | can tweak ``debian/rules`` for (1), and for (2) you will simply have to mark | |
218 | the relevant tests as broken using ``test_is_broken = true``. See the existing | |
219 | crate configs for examples. | |
220 | ||
221 | Other times, the tests are simply broken or can't be run in Debian. In this | |
222 | case you should disable the test in (1) by running ``dh_auto_test -- build`` | |
223 | instead of the default ``dh_auto_test -- test --all``, and for (2) again you | |
224 | should mark the relevant tests as broken. | |
225 | ||
226 | Please note that ``[packages.lib]\ntest_is_broken = true`` will transitively | |
227 | disable tests for all combinations of features. Sometimes this is correct e.g. | |
228 | if the test actually breaks for all features. Sometimes this is *not* correct, | |
229 | e.g. if the test only breaks for ``--no-default-features``. In the latter case | |
230 | you should instead patch the crate to ignore those tests when the relevant | |
1ff2ded3 | 231 | features are absent - e.g. ``src/regex-automata/debian/patches/ignore-std-tests.patch``. |
01f68998 | 232 | |
a1872536 XL |
233 | Binary-crate has "required-features" |
234 | ------------------------------------ | |
235 | ||
236 | See ``src/dotenv`` for an example on dealing with this. | |
237 | ||
238 | Binary-crate has conflicting name | |
239 | --------------------------------- | |
240 | ||
241 | See ``src/fd-find`` for an example on dealing with this. | |
242 | ||
053e604c SL |
243 | Updating the dependencies |
244 | ------------------------- | |
245 | ||
ed1eaac5 XL |
246 | In some cases, libraries/programs are forcing an old version of a library as |
247 | dependencies. In order to limit the number of duplicated libraries in the | |
248 | archive, please try to evaluate if a newer version of the dependencies could be | |
249 | used. | |
250 | ||
1ff2ded3 | 251 | To achieve that, after ``./update.sh``, try:: |
ed1eaac5 XL |
252 | |
253 | $ cd build/<package>/ | |
254 | $ rm -rf .pc # sometimes this is necessary due to minor debcargo bug | |
255 | $ quilt push -a | |
256 | $ quilt new relax-dep.diff | |
257 | $ quilt edit Cargo.toml | |
258 | $ quilt refresh | |
259 | $ cargo build # check that it works. if it does, then | |
260 | $ cp -R patches ../../src/<package>/debian | |
261 | ||
262 | Suppose you want to change the dependency from 0.3 to 0.5. If the crate builds | |
263 | with no further source changes, then we would change the required version in | |
264 | ``Cargo.toml`` from ``0.3`` to ``>= 0.3, < 0.6`` or something like that. Then | |
265 | the convention is to put all these changes into a single patch called | |
266 | ``relax-dep-versions.patch``. | |
267 | ||
268 | OTOH, if the cargo build fails, and you can fix it up by editing the source | |
269 | code in a minor way to use the new crate API, then: for each crate that needs | |
270 | to be updated, you should instead name the patch ``update-dep-<crate>.patch`` | |
1ff2ded3 XL |
271 | and add both the ``Cargo.toml`` and the source code changes to it. The change |
272 | to ``Cargo.toml`` would then simply say (e.g.) ``0.5`` since the older versions | |
273 | actually don't work, and not the version range from the previous paragraph. | |
e4d0e3d6 XL |
274 | |
275 | Help, something went wrong! | |
276 | --------------------------- | |
277 | ||
278 | Sometimes, the error messages are not the most informative. In this case you | |
279 | can try re-running the command with ``RUST_BACKTRACE=1``. If you are using the | |
280 | ``debcargo`` from Debian's own repositories, you should also install the | |
281 | ``debcargo-dbgsym`` package, otherwise the stack trace will be next to useless. | |
282 | Make sure you have the `debug repository <https://wiki.debian.org/HowToGetABacktrace#Installing_the_debugging_symbols>`_ | |
283 | enabled in your APT sources. |