]>
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 | |
8960a81d XL |
22 | To package an 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 | ||
90 | ||
c6709bfe XL |
91 | Build environment |
92 | ================= | |
93 | ||
94 | To set up a suitable build environment for ``./build.sh``:: | |
95 | ||
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 | |
100 | ||
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:: | |
106 | ||
107 | $ export IGNORE_MISSING_BUILD_DEPS=1 | |
108 | $ ./release.sh A | |
109 | $ ( cd build && ./build.sh A ) | |
110 | # push pending and checkout master | |
111 | $ ./release.sh B | |
112 | $ ( cd build && ./build.sh B librust-A*.deb ) | |
113 | ||
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. | |
117 | ||
118 | After everything is built successfully, you can ``dput`` all of them and then | |
119 | push all the ``pending-*`` branches as normal. | |
120 | ||
121 | ||
7f68b728 XL |
122 | General packaging tips |
123 | ====================== | |
124 | ||
125 | Dependencies on clippy | |
126 | ---------------------- | |
127 | ||
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. | |
131 | ||
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. | |
134 | ||
738135f9 XL |
135 | OS-specific crates |
136 | ------------------ | |
137 | ||
138 | See redox-syscall for examples on how to deal with these. | |
139 | ||
140 | If this is unclear, ask on IRC. | |
141 | ||
7f68b728 XL |
142 | Architecture-specific crates |
143 | ---------------------------- | |
01f68998 | 144 | |
738135f9 | 145 | This is a bit harder. Usually there are two options: |
95399141 | 146 | |
738135f9 XL |
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 | |
151 | ||
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. | |
156 | ||
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. | |
161 | ||
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 | |
164 | ||
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 | |
167 | correctly already.) | |
95399141 | 168 | |
a0c73b1a XL |
169 | Changed orig tarballs |
170 | --------------------- | |
171 | ||
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``. | |
178 | ||
7f68b728 XL |
179 | ITPs |
180 | ---- | |
95399141 | 181 | |
7f68b728 | 182 | Don't file ITPs for library crates, but do file them for binary crates. |
01f68998 | 183 | |
7f68b728 XL |
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. | |
01f68998 | 188 | |
0d1e2247 SL |
189 | Testing |
190 | ------- | |
191 | ||
dc94b1d5 XL |
192 | Debian has two types of tests: |
193 | ||
194 | 1. pre-install tests run in debian/rules | |
195 | 2. post-install tests defined in debian/tests/control | |
196 | ||
197 | For Debian rust packages, in (1) we run the crate's test suite with default | |
198 | features but only if there are no dev-dependencies, and in (2) we run the whole | |
199 | test suite with each feature enabled separately plus --no-default-features and | |
200 | --all-features. | |
201 | ||
202 | Sometimes, tests require extra tweaks and settings to work. In this case, you | |
203 | can tweak ``debian/rules`` for (1), and for (2) you will simply have to mark | |
204 | the relevant tests as broken using ``test_is_broken = true``. See the existing | |
205 | crate configs for examples. | |
206 | ||
207 | Other times, the tests are simply broken or can't be run in Debian. In this | |
208 | case you should disable the test in (1) by running ``dh_auto_test -- build`` | |
209 | instead of the default ``dh_auto_test -- test --all``, and for (2) again you | |
210 | should mark the relevant tests as broken. | |
211 | ||
212 | Please note that ``[packages.lib]\ntest_is_broken = true`` will transitively | |
213 | disable tests for all combinations of features. Sometimes this is correct e.g. | |
214 | if the test actually breaks for all features. Sometimes this is *not* correct, | |
215 | e.g. if the test only breaks for ``--no-default-features``. In the latter case | |
216 | you should instead patch the crate to ignore those tests when the relevant | |
217 | features are absent - see commit 457f5d76 for an example. | |
01f68998 | 218 | |
a1872536 XL |
219 | Binary-crate has "required-features" |
220 | ------------------------------------ | |
221 | ||
222 | See ``src/dotenv`` for an example on dealing with this. | |
223 | ||
224 | Binary-crate has conflicting name | |
225 | --------------------------------- | |
226 | ||
227 | See ``src/fd-find`` for an example on dealing with this. | |
228 | ||
053e604c SL |
229 | Updating the dependencies |
230 | ------------------------- | |
231 | ||
ed1eaac5 XL |
232 | In some cases, libraries/programs are forcing an old version of a library as |
233 | dependencies. In order to limit the number of duplicated libraries in the | |
234 | archive, please try to evaluate if a newer version of the dependencies could be | |
235 | used. | |
236 | ||
237 | To achieve that, after ./update.sh, try:: | |
238 | ||
239 | $ cd build/<package>/ | |
240 | $ rm -rf .pc # sometimes this is necessary due to minor debcargo bug | |
241 | $ quilt push -a | |
242 | $ quilt new relax-dep.diff | |
243 | $ quilt edit Cargo.toml | |
244 | $ quilt refresh | |
245 | $ cargo build # check that it works. if it does, then | |
246 | $ cp -R patches ../../src/<package>/debian | |
247 | ||
248 | Suppose you want to change the dependency from 0.3 to 0.5. If the crate builds | |
249 | with no further source changes, then we would change the required version in | |
250 | ``Cargo.toml`` from ``0.3`` to ``>= 0.3, < 0.6`` or something like that. Then | |
251 | the convention is to put all these changes into a single patch called | |
252 | ``relax-dep-versions.patch``. | |
253 | ||
254 | OTOH, if the cargo build fails, and you can fix it up by editing the source | |
255 | code in a minor way to use the new crate API, then: for each crate that needs | |
256 | to be updated, you should instead name the patch ``update-dep-<crate>.patch`` | |
257 | and add both the ``Cargo.toml`` and the source code changes to it. Use | |
258 | ``quilt rename`` if that helps you. |