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 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
  73
  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
  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
 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
 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
 142 Architecture-specific crates
 143 ----------------------------
 144
 145 This is a bit harder. Usually there are two options:
 146
 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.)
 168
 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
 179 ITPs
 180 ----
 181
 182 Don't file ITPs for library crates, but do file them for binary crates.
 183
 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.
 188
 189 Testing
 190 -------
 191
 192 For now, testsuites aren't executed for library.
 193 However, for binary, it is strongly recommended to run the testsuites.
 194 See ripgrep as example.
 195
 196 Binary-crate has "required-features"
 197 ------------------------------------
 198
 199 See ``src/dotenv`` for an example on dealing with this.
 200
 201 Binary-crate has conflicting name
 202 ---------------------------------
 203
 204 See ``src/fd-find`` for an example on dealing with this.
 205
 206 Updating the dependencies
 207 -------------------------
 208
 209 In some cases, libraries/programs are forcing an old version of a library as
 210 dependencies. In order to limit the number of duplicated libraries in the
 211 archive, please try to evaluate if a newer version of the dependencies could be
 212 used.
 213
 214 To achieve that, after ./update.sh, try::
 215
 216   $ cd build/<package>/
 217   $ rm -rf .pc # sometimes this is necessary due to minor debcargo bug
 218   $ quilt push -a
 219   $ quilt new relax-dep.diff
 220   $ quilt edit Cargo.toml
 221   $ quilt refresh
 222   $ cargo build # check that it works. if it does, then
 223   $ cp -R patches ../../src/<package>/debian
 224
 225 Suppose you want to change the dependency from 0.3 to 0.5. If the crate builds
 226 with no further source changes, then we would change the required version in
 227 ``Cargo.toml`` from ``0.3`` to ``>= 0.3, < 0.6`` or something like that. Then
 228 the convention is to put all these changes into a single patch called
 229 ``relax-dep-versions.patch``.
 230
 231 OTOH, if the cargo build fails, and you can fix it up by editing the source
 232 code in a minor way to use the new crate API, then: for each crate that needs
 233 to be updated, you should instead name the patch ``update-dep-<crate>.patch``
 234 and add both the ``Cargo.toml`` and the source code changes to it. Use
 235 ``quilt rename`` if that helps you.