]>
Commit | Line | Data |
---|---|---|
d580884e XL |
1 | Instructions |
2 | ============ | |
3 | ||
1057693c XL |
4 | To get set up, run:: |
5 | ||
cc2d233e DKG |
6 | apt update && apt install cargo debcargo |
7 | ||
8 | As your regular user, update the crates.io index: | |
9 | ||
10 | cargo search | |
1057693c XL |
11 | |
12 | Then for each new package: | |
23db3623 | 13 | |
8960a81d XL |
14 | To package a new crate, or to update an existing crate |
15 | ------------------------------------------------------ | |
931eabc0 | 16 | |
8960a81d XL |
17 | :: |
18 | ||
19 | ./new-package.sh <rust-crate-name> # or | |
20 | ./update.sh <rust-crate-name> | |
86e10bdd | 21 | |
6c1b3182 XL |
22 | and follow its instructions. |
23 | ||
8960a81d | 24 | Note that ``new-package.sh`` is just a symlink to ``update.sh``, to help newcomers. |
7b976234 | 25 | |
8960a81d XL |
26 | To package an older version of a crate |
27 | -------------------------------------- | |
7b976234 | 28 | |
6c1b3182 | 29 | To maintain an old version of a crate alongside the latest one, first make sure |
8960a81d | 30 | the latest version is packaged by doing all of the above, then run:: |
6c1b3182 | 31 | |
8960a81d XL |
32 | ./new-package.sh <rust-crate-name> <old-version> # or |
33 | ./update.sh <rust-crate-name> <old-version> | |
86e10bdd | 34 | |
fed17d69 XL |
35 | and follow its instructions. To save time, you can first copy anything relevant |
36 | from ``src/<rust-crate-name>`` to ``src/<rust-crate-name>-<old-version>``, then | |
37 | adapt it as needed. | |
999f9269 | 38 | |
8960a81d XL |
39 | To prepare a release |
40 | -------------------- | |
41 | ||
42 | :: | |
5cbe2f60 | 43 | |
8960a81d XL |
44 | ./release.sh <rust-crate-name> # or |
45 | ./release.sh <rust-crate-name> <old-version> # as appropriate | |
86e10bdd | 46 | |
fed17d69 XL |
47 | This prepares the necessary Debian files in ``build/``, and creates a git |
48 | branch to manage the packaging until it is accepted in Debian itself. You need | |
49 | to run additional commands after this - more specific instructions are given to | |
50 | you about this, by the script after you run it. | |
6c1b3182 | 51 | |
8960a81d XL |
52 | Holding packages at old versions |
53 | -------------------------------- | |
54 | ||
55 | If you need to keep the latest version in Debian at an older version than is | |
56 | released on crates.io, e.g. to upload an important bugfix without being blocked | |
57 | on having to package all the dependencies of the newest version, you can:: | |
58 | ||
59 | REALVER=<old-version> ./update.sh <rust-crate-name> # then | |
60 | REALVER=<old-version> ./release.sh <rust-crate-name> | |
61 | ||
d580884e | 62 | |
7f68b728 XL |
63 | General packaging tips |
64 | ====================== | |
65 | ||
66 | Dependencies on clippy | |
67 | ---------------------- | |
68 | ||
69 | Patch away dependencies on "clippy" unless it is a "real" dependency. Usually | |
70 | crates only use clippy to lint themselves and it is not a "real" dependency | |
71 | in the sense that they actually import clippy's code for what they do. | |
72 | ||
73 | If you want to be sure, `rg clippy` and check that all the usages of it are | |
74 | inside `cfg_attr` declarations. If so, then just get rid of it. | |
75 | ||
738135f9 XL |
76 | OS-specific crates |
77 | ------------------ | |
78 | ||
79 | See redox-syscall for examples on how to deal with these. | |
80 | ||
81 | If this is unclear, ask on IRC. | |
82 | ||
7f68b728 XL |
83 | Architecture-specific crates |
84 | ---------------------------- | |
01f68998 | 85 | |
738135f9 | 86 | This is a bit harder. Usually there are two options: |
95399141 | 87 | |
738135f9 XL |
88 | 1. The crate should build a dummy/no-op version of itself "out-of-the-box" |
89 | on the architectures it doesn't work on. | |
90 | 2. Dependent crates should depend on it with a platform-specific dependency, | |
91 | see https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies | |
92 | ||
93 | (1) involves less burden for others, both for dependent crates and for us | |
94 | packagers, since we don't have to override d/rules to ignore test failures on | |
95 | non-working architectures. You should communicate to upstream that this is | |
96 | the preferred approach. | |
97 | ||
98 | In the case of (2), the crate should document exactly what conditional should | |
99 | be used, and keep this documentation up-to-date. This allows us to easily | |
100 | determine if dependent crates are using the correct conditional. You will then | |
101 | have to override d/rules for this crate, see src/simd for an example. | |
102 | ||
103 | You should file a bug upstream if the crate does neither (1) nor document the | |
104 | conditions for (2), e.g. https://github.com/hsivonen/simd/issues/25 | |
105 | ||
106 | (Actually the above applies even for "OS-specific crates" but then (2) is | |
107 | obvious so documentation is less necessary, and dependent crates all do it | |
108 | correctly already.) | |
95399141 | 109 | |
7f68b728 XL |
110 | ITPs |
111 | ---- | |
95399141 | 112 | |
7f68b728 | 113 | Don't file ITPs for library crates, but do file them for binary crates. |
01f68998 | 114 | |
7f68b728 XL |
115 | For now (updated 2018-09) we have several hundred crates to upload. Submitting |
116 | ITPs for these is unnecessary since we're the only ones uploading and there is | |
117 | no chance of conflict. It would only be spam for the bug tracker. Please | |
118 | instead co-ordinate uploads on the #debian-rust IRC channel. | |
01f68998 | 119 | |
0d1e2247 SL |
120 | Testing |
121 | ------- | |
122 | ||
123 | For now, testsuites aren't executed for library. | |
124 | However, for binary, it is strongly recommended to run the testsuites. | |
125 | See ripgrep as example. | |
01f68998 | 126 | |
053e604c SL |
127 | Updating the dependencies |
128 | ------------------------- | |
129 | ||
ed1eaac5 XL |
130 | In some cases, libraries/programs are forcing an old version of a library as |
131 | dependencies. In order to limit the number of duplicated libraries in the | |
132 | archive, please try to evaluate if a newer version of the dependencies could be | |
133 | used. | |
134 | ||
135 | To achieve that, after ./update.sh, try:: | |
136 | ||
137 | $ cd build/<package>/ | |
138 | $ rm -rf .pc # sometimes this is necessary due to minor debcargo bug | |
139 | $ quilt push -a | |
140 | $ quilt new relax-dep.diff | |
141 | $ quilt edit Cargo.toml | |
142 | $ quilt refresh | |
143 | $ cargo build # check that it works. if it does, then | |
144 | $ cp -R patches ../../src/<package>/debian | |
145 | ||
146 | Suppose you want to change the dependency from 0.3 to 0.5. If the crate builds | |
147 | with no further source changes, then we would change the required version in | |
148 | ``Cargo.toml`` from ``0.3`` to ``>= 0.3, < 0.6`` or something like that. Then | |
149 | the convention is to put all these changes into a single patch called | |
150 | ``relax-dep-versions.patch``. | |
151 | ||
152 | OTOH, if the cargo build fails, and you can fix it up by editing the source | |
153 | code in a minor way to use the new crate API, then: for each crate that needs | |
154 | to be updated, you should instead name the patch ``update-dep-<crate>.patch`` | |
155 | and add both the ``Cargo.toml`` and the source code changes to it. Use | |
156 | ``quilt rename`` if that helps you. | |
053e604c SL |
157 | |
158 | ||
cf33b9a8 XL |
159 | DD instructions |
160 | =============== | |
161 | ||
162 | To set up a suitable build environment for ``./build.sh``:: | |
163 | ||
164 | $ sudo apt-get install devscripts reprepro debootstrap sbuild | |
165 | $ sudo sbuild-createchroot --include=eatmydata,ccache,gnupg,dh-cargo,cargo,lintian,perl-openssl-defaults \ | |
166 | --chroot-prefix debcargo-unstable unstable \ | |
167 | /srv/chroot/debcargo-unstable-amd64-sbuild http://deb.debian.org/debian | |
d580884e | 168 | |
cf33b9a8 XL |
169 | Normally, ``./build.sh`` will fail early if not all the build dependencies are |
170 | available in your local apt cache. If you are packaging a large dependency tree | |
171 | however, to avoid many round-trips through NEW it is possible to bypass this | |
172 | check and build all the packages together. Suppose package B depends on package | |
173 | A, then you can run something like:: | |
174 | ||
175 | $ export IGNORE_MISSING_BUILD_DEPS=1 | |
176 | $ ./release.sh A | |
177 | $ ( cd build && ./build.sh A ) | |
178 | # push pending and checkout master | |
179 | $ ./release.sh B | |
180 | $ ( cd build && ./build.sh B librust-A*.deb ) | |
181 | ||
182 | The extra arguments after ``./build.sh B <args>`` is extra deb files to pass to | |
183 | sbuild to use as dependencies. In this case, ``librust-A*.deb`` should have | |
184 | been built by the previous step. | |
185 | ||
186 | After everything is built successfully, you can ``dput`` all of them and then | |
187 | push all the ``pending-*`` branches as normal. |