README.rst

   1 Instructions
   2 ============
   3
   4 To get set up, run::
   5
   6   apt update && apt install debcargo
   7
   8 Then for each new package:
   9
  10 To package a new crate, or to update an existing crate
  11 ------------------------------------------------------
  12
  13 ::
  14
  15   ./new-package.sh <rust-crate-name>  # or
  16   ./update.sh      <rust-crate-name>
  17
  18 and follow its instructions.
  19
  20 Note that ``new-package.sh`` is just a symlink to ``update.sh``, to help newcomers.
  21
  22 To package an older version of a crate
  23 --------------------------------------
  24
  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::
  27
  28   ./new-package.sh <rust-crate-name> <old-version>  # or
  29   ./update.sh      <rust-crate-name> <old-version>
  30
  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.
  34
  35 To prepare a release
  36 --------------------
  37
  38 ::
  39
  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
  43
  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.
  48
  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
  59
  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
  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
  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
  97 Architecture-specific crates
  98 ----------------------------
  99
 100 This is a bit harder. Usually there are two options:
 101
 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.)
 123
 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
 134 ITPs
 135 ----
 136
 137 Don't file ITPs for library crates, but do file them for binary crates.
 138
 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.
 143
 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.
 150
 151 Binary-crate has "required-features"
 152 ------------------------------------
 153
 154 See ``src/dotenv`` for an example on dealing with this.
 155
 156 Binary-crate has conflicting name
 157 ---------------------------------
 158
 159 See ``src/fd-find`` for an example on dealing with this.
 160
 161 Updating the dependencies
 162 -------------------------
 163
 164 In some cases, libraries/programs are forcing an old version of a library as
 165 dependencies. In order to limit the number of duplicated libraries in the
 166 archive, please try to evaluate if a newer version of the dependencies could be
 167 used.
 168
 169 To achieve that, after ./update.sh, try::
 170
 171   $ cd build/<package>/
 172   $ rm -rf .pc # sometimes this is necessary due to minor debcargo bug
 173   $ quilt push -a
 174   $ quilt new relax-dep.diff
 175   $ quilt edit Cargo.toml
 176   $ quilt refresh
 177   $ cargo build # check that it works. if it does, then
 178   $ cp -R patches ../../src/<package>/debian
 179
 180 Suppose you want to change the dependency from 0.3 to 0.5. If the crate builds
 181 with no further source changes, then we would change the required version in
 182 ``Cargo.toml`` from ``0.3`` to ``>= 0.3, < 0.6`` or something like that. Then
 183 the convention is to put all these changes into a single patch called
 184 ``relax-dep-versions.patch``.
 185
 186 OTOH, if the cargo build fails, and you can fix it up by editing the source
 187 code in a minor way to use the new crate API, then: for each crate that needs
 188 to be updated, you should instead name the patch ``update-dep-<crate>.patch``
 189 and add both the ``Cargo.toml`` and the source code changes to it. Use
 190 ``quilt rename`` if that helps you.
 191
 192
 193 DD instructions
 194 ===============
 195
 196 To set up a suitable build environment for ``./build.sh``::
 197
 198   $ sudo apt-get install devscripts reprepro debootstrap sbuild dh-cargo
 199   $ sudo sbuild-createchroot --include=eatmydata,ccache,gnupg,dh-cargo,cargo,lintian,perl-openssl-defaults \
 200       --chroot-prefix debcargo-unstable unstable \
 201       /srv/chroot/debcargo-unstable-amd64-sbuild http://deb.debian.org/debian
 202
 203 Normally, ``./build.sh`` will fail early if not all the build dependencies are
 204 available in your local apt cache. If you are packaging a large dependency tree
 205 however, to avoid many round-trips through NEW it is possible to bypass this
 206 check and build all the packages together. Suppose package B depends on package
 207 A, then you can run something like::
 208
 209   $ export IGNORE_MISSING_BUILD_DEPS=1
 210   $ ./release.sh A
 211   $ ( cd build && ./build.sh A )
 212   # push pending and checkout master
 213   $ ./release.sh B
 214   $ ( cd build && ./build.sh B librust-A*.deb )
 215
 216 The extra arguments after ``./build.sh B <args>`` is extra deb files to pass to
 217 sbuild to use as dependencies. In this case, ``librust-A*.deb`` should have
 218 been built by the previous step.
 219
 220 After everything is built successfully, you can ``dput`` all of them and then
 221 push all the ``pending-*`` branches as normal.
 222
 223 Packaging the existing revision
 224 ===============================
 225
 226 In order to build a package A already in ``debcargo-conf/src``
 227 in the exact version which is present here, do the following::
 228
 229   $ ./repackage.sh A
 230   $ cd build
 231   $ ./build.sh A
 232
 233 If this package is already in the archive and you want to recreate that, you
 234 will need to use the exact same version of debcargo that was used previously.