]>
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 | ||
d580884e | 59 | |
ed79d202 XL |
60 | Repository structure |
61 | ==================== | |
62 | ||
63 | `pending-*` branches are managed by `./release.sh`, so please don't manage them | |
64 | yourself as you will interfere with the working of that script. The intention | |
65 | is that they should only differ from the master branch by 1 commit, i.e. the | |
66 | `dch -r` commit created by `./release.sh`. | |
67 | ||
68 | If you want to create separate non-master branches, that is fine - just don't | |
69 | call them `pending-*` and don't run `./release.sh` on those branches. If you | |
70 | want to test your crate, instead run:: | |
71 | ||
72 | cd build && [SOURCEONLY=1] ./build.sh <rust-crate-name> [<old-version>] | |
73 | ||
74 | omitting or not omitting the stuff in [] as needed. | |
75 | ||
76 | ||
7f68b728 XL |
77 | General packaging tips |
78 | ====================== | |
79 | ||
80 | Dependencies on clippy | |
81 | ---------------------- | |
82 | ||
83 | Patch away dependencies on "clippy" unless it is a "real" dependency. Usually | |
84 | crates only use clippy to lint themselves and it is not a "real" dependency | |
85 | in the sense that they actually import clippy's code for what they do. | |
86 | ||
87 | If you want to be sure, `rg clippy` and check that all the usages of it are | |
88 | inside `cfg_attr` declarations. If so, then just get rid of it. | |
89 | ||
738135f9 XL |
90 | OS-specific crates |
91 | ------------------ | |
92 | ||
93 | See redox-syscall for examples on how to deal with these. | |
94 | ||
95 | If this is unclear, ask on IRC. | |
96 | ||
7f68b728 XL |
97 | Architecture-specific crates |
98 | ---------------------------- | |
01f68998 | 99 | |
738135f9 | 100 | This is a bit harder. Usually there are two options: |
95399141 | 101 | |
738135f9 XL |
102 | 1. The crate should build a dummy/no-op version of itself "out-of-the-box" |
103 | on the architectures it doesn't work on. | |
104 | 2. Dependent crates should depend on it with a platform-specific dependency, | |
105 | see https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies | |
106 | ||
107 | (1) involves less burden for others, both for dependent crates and for us | |
108 | packagers, since we don't have to override d/rules to ignore test failures on | |
109 | non-working architectures. You should communicate to upstream that this is | |
110 | the preferred approach. | |
111 | ||
112 | In the case of (2), the crate should document exactly what conditional should | |
113 | be used, and keep this documentation up-to-date. This allows us to easily | |
114 | determine if dependent crates are using the correct conditional. You will then | |
115 | have to override d/rules for this crate, see src/simd for an example. | |
116 | ||
117 | You should file a bug upstream if the crate does neither (1) nor document the | |
118 | conditions for (2), e.g. https://github.com/hsivonen/simd/issues/25 | |
119 | ||
120 | (Actually the above applies even for "OS-specific crates" but then (2) is | |
121 | obvious so documentation is less necessary, and dependent crates all do it | |
122 | correctly already.) | |
95399141 | 123 | |
a0c73b1a XL |
124 | Changed orig tarballs |
125 | --------------------- | |
126 | ||
127 | Sometimes the orig.tar generated by debcargo might change e.g. if you are using | |
128 | a newer version of debcargo and one of the dependencies relating to generating | |
129 | the tarball was updated and its behaviour changed - compression settings, | |
130 | tarball archive ordering, etc. This will cause your upload to get REJECTED by | |
131 | the Debian FTP archive for having a different orig.tar. In this case, set | |
132 | REUSE_EXISTING_ORIG_TARBALL=1 when running ``./release.sh``. | |
133 | ||
7f68b728 XL |
134 | ITPs |
135 | ---- | |
95399141 | 136 | |
7f68b728 | 137 | Don't file ITPs for library crates, but do file them for binary crates. |
01f68998 | 138 | |
7f68b728 XL |
139 | For now (updated 2018-09) we have several hundred crates to upload. Submitting |
140 | ITPs for these is unnecessary since we're the only ones uploading and there is | |
141 | no chance of conflict. It would only be spam for the bug tracker. Please | |
142 | instead co-ordinate uploads on the #debian-rust IRC channel. | |
01f68998 | 143 | |
0d1e2247 SL |
144 | Testing |
145 | ------- | |
146 | ||
147 | For now, testsuites aren't executed for library. | |
148 | However, for binary, it is strongly recommended to run the testsuites. | |
149 | See ripgrep as example. | |
01f68998 | 150 | |
053e604c SL |
151 | Updating the dependencies |
152 | ------------------------- | |
153 | ||
ed1eaac5 XL |
154 | In some cases, libraries/programs are forcing an old version of a library as |
155 | dependencies. In order to limit the number of duplicated libraries in the | |
156 | archive, please try to evaluate if a newer version of the dependencies could be | |
157 | used. | |
158 | ||
159 | To achieve that, after ./update.sh, try:: | |
160 | ||
161 | $ cd build/<package>/ | |
162 | $ rm -rf .pc # sometimes this is necessary due to minor debcargo bug | |
163 | $ quilt push -a | |
164 | $ quilt new relax-dep.diff | |
165 | $ quilt edit Cargo.toml | |
166 | $ quilt refresh | |
167 | $ cargo build # check that it works. if it does, then | |
168 | $ cp -R patches ../../src/<package>/debian | |
169 | ||
170 | Suppose you want to change the dependency from 0.3 to 0.5. If the crate builds | |
171 | with no further source changes, then we would change the required version in | |
172 | ``Cargo.toml`` from ``0.3`` to ``>= 0.3, < 0.6`` or something like that. Then | |
173 | the convention is to put all these changes into a single patch called | |
174 | ``relax-dep-versions.patch``. | |
175 | ||
176 | OTOH, if the cargo build fails, and you can fix it up by editing the source | |
177 | code in a minor way to use the new crate API, then: for each crate that needs | |
178 | to be updated, you should instead name the patch ``update-dep-<crate>.patch`` | |
179 | and add both the ``Cargo.toml`` and the source code changes to it. Use | |
180 | ``quilt rename`` if that helps you. | |
053e604c SL |
181 | |
182 | ||
cf33b9a8 XL |
183 | DD instructions |
184 | =============== | |
185 | ||
186 | To set up a suitable build environment for ``./build.sh``:: | |
187 | ||
b1c00851 | 188 | $ sudo apt-get install devscripts reprepro debootstrap sbuild dh-cargo |
cf33b9a8 XL |
189 | $ sudo sbuild-createchroot --include=eatmydata,ccache,gnupg,dh-cargo,cargo,lintian,perl-openssl-defaults \ |
190 | --chroot-prefix debcargo-unstable unstable \ | |
191 | /srv/chroot/debcargo-unstable-amd64-sbuild http://deb.debian.org/debian | |
d580884e | 192 | |
cf33b9a8 XL |
193 | Normally, ``./build.sh`` will fail early if not all the build dependencies are |
194 | available in your local apt cache. If you are packaging a large dependency tree | |
195 | however, to avoid many round-trips through NEW it is possible to bypass this | |
196 | check and build all the packages together. Suppose package B depends on package | |
197 | A, then you can run something like:: | |
198 | ||
199 | $ export IGNORE_MISSING_BUILD_DEPS=1 | |
200 | $ ./release.sh A | |
201 | $ ( cd build && ./build.sh A ) | |
202 | # push pending and checkout master | |
203 | $ ./release.sh B | |
204 | $ ( cd build && ./build.sh B librust-A*.deb ) | |
205 | ||
206 | The extra arguments after ``./build.sh B <args>`` is extra deb files to pass to | |
207 | sbuild to use as dependencies. In this case, ``librust-A*.deb`` should have | |
208 | been built by the previous step. | |
209 | ||
210 | After everything is built successfully, you can ``dput`` all of them and then | |
211 | push all the ``pending-*`` branches as normal. | |
a6de9fda DC |
212 | |
213 | Packaging the existing revision | |
214 | =============================== | |
215 | ||
216 | In order to build a package A already in ``debcargo-conf/src`` | |
217 | in the exact version which is present here, do the following:: | |
218 | ||
219 | $ ./repackage.sh A | |
220 | $ cd build | |
ed79d202 XL |
221 | $ ./build.sh A |
222 | ||
223 | If this package is already in the archive and you want to recreate that, you | |
224 | will need to use the exact same version of debcargo that was used previously. |