README.rst 7.21 KB
Newer Older
1 2 3
Instructions
============

4 5
To get set up, run::

6
  apt update && apt install debcargo
7 8

Then for each new package:
Ximin Luo's avatar
Ximin Luo committed
9

10 11
To package a new crate, or to update an existing crate
------------------------------------------------------
Ximin Luo's avatar
Ximin Luo committed
12

13 14 15 16
::

  ./new-package.sh <rust-crate-name>  # or
  ./update.sh      <rust-crate-name>
Ximin Luo's avatar
Ximin Luo committed
17

Ximin Luo's avatar
Ximin Luo committed
18 19
and follow its instructions.

20
Note that ``new-package.sh`` is just a symlink to ``update.sh``, to help newcomers.
Sylvestre Ledru's avatar
Sylvestre Ledru committed
21

22 23
To package an older version of a crate
--------------------------------------
Sylvestre Ledru's avatar
Sylvestre Ledru committed
24

Ximin Luo's avatar
Ximin Luo committed
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::
Ximin Luo's avatar
Ximin Luo committed
27

28 29
  ./new-package.sh <rust-crate-name> <old-version>  # or
  ./update.sh      <rust-crate-name> <old-version>
Ximin Luo's avatar
Ximin Luo committed
30

Ximin Luo's avatar
Ximin Luo committed
31 32 33
and follow its instructions. To save time, you can first copy anything relevant
from ``src/<rust-crate-name>`` to ``src/<rust-crate-name>-<old-version>``, then
adapt it as needed.
34

35 36 37 38
To prepare a release
--------------------

::
39

40 41 42
  ./release.sh <rust-crate-name>                     # or
  ./release.sh <rust-crate-name> <old-version>       # as appropriate
  DISTRO=experimental ./release.sh <rust-crate-name> # to target another distro
Ximin Luo's avatar
Ximin Luo committed
43

Ximin Luo's avatar
Ximin Luo committed
44 45 46 47
This prepares the necessary Debian files in ``build/``, and creates a git
branch to manage the packaging until it is accepted in Debian itself. You need
to run additional commands after this - more specific instructions are given to
you about this, by the script after you run it.
Ximin Luo's avatar
Ximin Luo committed
48

49 50 51 52 53 54 55 56 57 58
Holding packages at old versions
--------------------------------

If you need to keep the latest version in Debian at an older version than is
released on crates.io, e.g. to upload an important bugfix without being blocked
on having to package all the dependencies of the newest version, you can::

  REALVER=<old-version> ./update.sh  <rust-crate-name>  # then
  REALVER=<old-version> ./release.sh <rust-crate-name>

59

60 61 62 63 64 65 66 67 68 69 70 71 72
General packaging tips
======================

Dependencies on clippy
----------------------

Patch away dependencies on "clippy" unless it is a "real" dependency. Usually
crates only use clippy to lint themselves and it is not a "real" dependency
in the sense that they actually import clippy's code for what they do.

If you want to be sure, `rg clippy` and check that all the usages of it are
inside `cfg_attr` declarations. If so, then just get rid of it.

73 74 75 76 77 78 79
OS-specific crates
------------------

See redox-syscall for examples on how to deal with these.

If this is unclear, ask on IRC.

80 81
Architecture-specific crates
----------------------------
Ximin Luo's avatar
Ximin Luo committed
82

83
This is a bit harder. Usually there are two options:
84

85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105
1. The crate should build a dummy/no-op version of itself "out-of-the-box"
   on the architectures it doesn't work on.
2. Dependent crates should depend on it with a platform-specific dependency,
   see https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies

(1) involves less burden for others, both for dependent crates and for us
packagers, since we don't have to override d/rules to ignore test failures on
non-working architectures. You should communicate to upstream that this is
the preferred approach.

In the case of (2), the crate should document exactly what conditional should
be used, and keep this documentation up-to-date. This allows us to easily
determine if dependent crates are using the correct conditional. You will then
have to override d/rules for this crate, see src/simd for an example.

You should file a bug upstream if the crate does neither (1) nor document the
conditions for (2), e.g. https://github.com/hsivonen/simd/issues/25

(Actually the above applies even for "OS-specific crates" but then (2) is
obvious so documentation is less necessary, and dependent crates all do it
correctly already.)
106

107 108 109 110 111 112 113 114 115 116
Changed orig tarballs
---------------------

Sometimes the orig.tar generated by debcargo might change e.g. if you are using
a newer version of debcargo and one of the dependencies relating to generating
the tarball was updated and its behaviour changed - compression settings,
tarball archive ordering, etc. This will cause your upload to get REJECTED by
the Debian FTP archive for having a different orig.tar. In this case, set
REUSE_EXISTING_ORIG_TARBALL=1 when running ``./release.sh``.

117 118
ITPs
----
119

120
Don't file ITPs for library crates, but do file them for binary crates.
Ximin Luo's avatar
Ximin Luo committed
121

122 123 124 125
For now (updated 2018-09) we have several hundred crates to upload. Submitting
ITPs for these is unnecessary since we're the only ones uploading and there is
no chance of conflict. It would only be spam for the bug tracker. Please
instead co-ordinate uploads on the #debian-rust IRC channel.
Ximin Luo's avatar
Ximin Luo committed
126

127 128 129 130 131 132
Testing
-------

For now, testsuites aren't executed for library.
However, for binary, it is strongly recommended to run the testsuites.
See ripgrep as example.
Ximin Luo's avatar
Ximin Luo committed
133

134 135 136
Updating the dependencies
-------------------------

137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
In some cases, libraries/programs are forcing an old version of a library as
dependencies. In order to limit the number of duplicated libraries in the
archive, please try to evaluate if a newer version of the dependencies could be
used.

To achieve that, after ./update.sh, try::

  $ cd build/<package>/
  $ rm -rf .pc # sometimes this is necessary due to minor debcargo bug
  $ quilt push -a
  $ quilt new relax-dep.diff
  $ quilt edit Cargo.toml
  $ quilt refresh
  $ cargo build # check that it works. if it does, then
  $ cp -R patches ../../src/<package>/debian

Suppose you want to change the dependency from 0.3 to 0.5. If the crate builds
with no further source changes, then we would change the required version in
``Cargo.toml`` from ``0.3`` to ``>= 0.3, < 0.6`` or something like that. Then
the convention is to put all these changes into a single patch called
``relax-dep-versions.patch``.

OTOH, if the cargo build fails, and you can fix it up by editing the source
code in a minor way to use the new crate API, then: for each crate that needs
to be updated, you should instead name the patch ``update-dep-<crate>.patch``
and add both the ``Cargo.toml`` and the source code changes to it. Use
``quilt rename`` if that helps you.
164 165


166 167 168 169 170
DD instructions
===============

To set up a suitable build environment for ``./build.sh``::

171
  $ sudo apt-get install devscripts reprepro debootstrap sbuild dh-cargo
172 173 174
  $ sudo sbuild-createchroot --include=eatmydata,ccache,gnupg,dh-cargo,cargo,lintian,perl-openssl-defaults \
      --chroot-prefix debcargo-unstable unstable \
      /srv/chroot/debcargo-unstable-amd64-sbuild http://deb.debian.org/debian
175

176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194
Normally, ``./build.sh`` will fail early if not all the build dependencies are
available in your local apt cache. If you are packaging a large dependency tree
however, to avoid many round-trips through NEW it is possible to bypass this
check and build all the packages together. Suppose package B depends on package
A, then you can run something like::

  $ export IGNORE_MISSING_BUILD_DEPS=1
  $ ./release.sh A
  $ ( cd build && ./build.sh A )
  # push pending and checkout master
  $ ./release.sh B
  $ ( cd build && ./build.sh B librust-A*.deb )

The extra arguments after ``./build.sh B <args>`` is extra deb files to pass to
sbuild to use as dependencies. In this case, ``librust-A*.deb`` should have
been built by the previous step.

After everything is built successfully, you can ``dput`` all of them and then
push all the ``pending-*`` branches as normal.