README.rst

   1 Instructions
   2 ============
   3
   4 To get set up, run::
   5
   6   apt update && apt build-dep cargo && apt install cargo dh-cargo
   7   cargo install debcargo # eventually will be replaced by "apt install debcargo"
   8
   9 Then for each new package:
  10
  11 To package a new crate, or to update an existing crate
  12 ------------------------------------------------------
  13
  14 ::
  15
  16   ./new-package.sh <rust-crate-name>  # or
  17   ./update.sh      <rust-crate-name>
  18
  19 and follow its instructions.
  20
  21 Note that ``new-package.sh`` is just a symlink to ``update.sh``, to help newcomers.
  22
  23 To package an older version of a crate
  24 --------------------------------------
  25
  26 To maintain an old version of a crate alongside the latest one, first make sure
  27 the latest version is packaged by doing all of the above, then run::
  28
  29   ./new-package.sh <rust-crate-name> <old-version>  # or
  30   ./update.sh      <rust-crate-name> <old-version>
  31
  32 and follow its instructions. To save time, you can first copy anything relevant
  33 from ``src/<rust-crate-name>`` to ``src/<rust-crate-name>-<old-version>``, then
  34 adapt it as needed.
  35
  36 To prepare a release
  37 --------------------
  38
  39 ::
  40
  41   ./release.sh <rust-crate-name>                # or
  42   ./release.sh <rust-crate-name> <old-version>  # as appropriate
  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 DD instructions
  61 ===============
  62
  63 To set up a suitable build environment for ``./build.sh``::
  64
  65   $ sudo apt-get install devscripts reprepro debootstrap sbuild
  66   $ sudo sbuild-createchroot --include=eatmydata,ccache,gnupg,dh-cargo,cargo,lintian \
  67       --chroot-prefix debcargo-unstable unstable \
  68       /srv/chroot/debcargo-unstable-amd64-sbuild http://deb.debian.org/debian
  69
  70
  71 General packaging tips
  72 ======================
  73
  74 Dependencies on clippy
  75 ----------------------
  76
  77 Patch away dependencies on "clippy" unless it is a "real" dependency. Usually
  78 crates only use clippy to lint themselves and it is not a "real" dependency
  79 in the sense that they actually import clippy's code for what they do.
  80
  81 If you want to be sure, `rg clippy` and check that all the usages of it are
  82 inside `cfg_attr` declarations. If so, then just get rid of it.
  83
  84 OS-specific crates
  85 ------------------
  86
  87 See redox-syscall for examples on how to deal with these.
  88
  89 If this is unclear, ask on IRC.
  90
  91 Architecture-specific crates
  92 ----------------------------
  93
  94 This is a bit harder. Usually there are two options:
  95
  96 1. The crate should build a dummy/no-op version of itself "out-of-the-box"
  97    on the architectures it doesn't work on.
  98 2. Dependent crates should depend on it with a platform-specific dependency,
  99    see https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies
 100
 101 (1) involves less burden for others, both for dependent crates and for us
 102 packagers, since we don't have to override d/rules to ignore test failures on
 103 non-working architectures. You should communicate to upstream that this is
 104 the preferred approach.
 105
 106 In the case of (2), the crate should document exactly what conditional should
 107 be used, and keep this documentation up-to-date. This allows us to easily
 108 determine if dependent crates are using the correct conditional. You will then
 109 have to override d/rules for this crate, see src/simd for an example.
 110
 111 You should file a bug upstream if the crate does neither (1) nor document the
 112 conditions for (2), e.g. https://github.com/hsivonen/simd/issues/25
 113
 114 (Actually the above applies even for "OS-specific crates" but then (2) is
 115 obvious so documentation is less necessary, and dependent crates all do it
 116 correctly already.)
 117
 118 ITPs
 119 ----
 120
 121 Don't file ITPs for library crates, but do file them for binary crates.
 122
 123 For now (updated 2018-09) we have several hundred crates to upload. Submitting
 124 ITPs for these is unnecessary since we're the only ones uploading and there is
 125 no chance of conflict. It would only be spam for the bug tracker. Please
 126 instead co-ordinate uploads on the #debian-rust IRC channel.
 127
 128 Testing
 129 -------
 130
 131 For now, testsuites aren't executed for library.
 132 However, for binary, it is strongly recommended to run the testsuites.
 133 See ripgrep as example.
 134
 135 TODO
 136 ====
 137
 138 Maybe use ``--copyright-guess-harder``.