debian/README.Debian

   1 Test failures
   2 =============
   3
   4 Starting from version 1.20.0+dfsg1-1 the Debian packages of rustc no longer
   5 fail the overall build if > 0 tests fail. Instead, we allow up to around 5
   6 tests to fail. In other words, if you're reading this in a binary package,
   7 between 0 and 5 tests might have failed when building this.
   8
   9 This is due to lack of maintainer time to investigate all failures. Many
  10 previous test failures were reported to upstream and did not receive a timely
  11 response, suggesting the failures were not important. I was then forced to
  12 patch out the test to make the build proceed, so several tests were being
  13 ignored in practise anyway.
  14
  15 This brings the Debian package in line with the Fedora package which also
  16 ignores all test failures. (Many other distributions don't run tests at all.)
  17
  18 If you think that the Debian rustc package is miscompiling your program in a
  19 way that the upstream distributed compiler doesn't, you may check the test
  20 failures here:
  21
  22 https://buildd.debian.org/status/package.php?p=rustc
  23
  24 If you can identify a relevant test failure, as well as the patches needed to
  25 fix it (either to rustc or LLVM), this will speed up the processing of any bug
  26 reports on the Debian side.
  27
  28 We will also examine these failures ourselves on a best-effort basis and
  29 attempt to fix the more serious-looking ones.
  30
  31 Uncommon architectures
  32 ----------------------
  33
  34 Debian release architectures armel and s390x currently have more test failures,
  35 being tracked by upstream here:
  36
  37 - https://github.com/rust-lang/rust/issues/52493 armel
  38 - https://github.com/rust-lang/rust/issues/52491 s390x
  39
  40 Ports architectures
  41 -------------------
  42
  43 The number of allowed test failures on certain Debian ports architectures
  44 (currently powerpc, powerpcspe, sparc64, x32) is raised greatly to help unblock
  45 progress for porters. Of course, as a user this means you may run into more
  46 bugs than usual; as mentioned above bugs reports and patches are welcome.
  47
  48
  49 Shared libraries
  50 ================
  51
  52 For now, the shared libraries of Rust are private.
  53 The rational is the following:
  54  * Upstream prefers static linking for now
  55    - https://github.com/rust-lang/rust/issues/10209
  56  * rust is still under heavy development. As far as we know, there is
  57    no commitement from upstream to provide a stable ABI for now.
  58    Until we know more, we cannot take the chance to have Rust-built packages
  59    failing at each release of the compiler.
  60  * Static builds are working out of the box just fine
  61  * However, LD_LIBRARY_PATH has to be updated when -C prefer-dynamic is used
  62
  63  -- Sylvestre Ledru <sylvestre@debian.org>, Fri, 13 Feb 2015 15:08:43 +0100
  64
  65
  66 Architecture-specific notes
  67 ===========================
  68
  69 armhf
  70 -----
  71
  72 We only ship debuginfo for libstd and not the compiler itself, otherwise builds
  73 run out of memory on the Debian buildds, with non-obvious and random errors.
  74
  75 See https://github.com/rust-lang/rust/issues/45854 for details.
  76
  77 If all your armhf build machines have ~8GB memory or more, you can experiment
  78 with disabling this work-around (i.e. revert to normal) in d/rules.
  79
  80
  81 Cross-compiling
  82 ===============
  83
  84 Rust uses LLVM, so cross-compiling works a bit differently from the GNU
  85 toolchain. The most important difference is that there are no "cross"
  86 compilers, every compiler is already a cross compiler. All you need to do is
  87 install the standard libraries for each target architecture you want to compile
  88 to. For rustc, this is libstd-rust-dev, so your debian/control would look
  89 something like this:
  90
  91     Build-Depends:
  92      [..]
  93      rustc:native    (>= $version),
  94      libstd-rust-dev (>= $version),
  95      [..]
  96
  97 You need both, this is important. When Debian build toolchains satisfy the
  98 build-depends of a cross-build, (1) a "rustc:native" Build-Depends selects
  99 rustc for the native architecture, which is possible because it's "Multi-Arch:
 100 allowed", and this will implicitly pull in libstd-rust-dev also for the native
 101 architecture; and (2) a "libstd-rust-dev" Build-Depends implies libstd-rust-dev
 102 for the foreign architecture, since it's "Multi-Arch: same".
 103
 104 You'll probably also want to add
 105
 106     include /usr/share/rustc/architecture.mk
 107
 108 to your debian/rules. This sets some useful variables like DEB_HOST_RUST_TYPE.
 109
 110 See the cargo package for an example.
 111
 112 Terminology
 113 -----------
 114
 115 The rust ecosystem generally uses the term "host" for the native architecture
 116 running the compiler, equivalent to DEB_BUILD_RUST_TYPE or "build" in GNU
 117 terminology, and "target" for the foreign architecture that the build products
 118 run on, equivalent to DEB_HOST_RUST_TYPE or "host" in GNU terminology. For
 119 example, rustc --version --verbose will output something like:
 120
 121     rustc 1.16.0
 122     [..]
 123     host: x86_64-unknown-linux-gnu
 124
 125 And both rustc and cargo have --target flags:
 126
 127     $ rustc --help | grep '\-\-target'
 128         --target TARGET     Target triple for which the code is compiled
 129     $ cargo build --help | grep '\-\-target'
 130         --target TRIPLE              Build for the target triple
 131
 132 One major exception to this naming scheme is in CERTAIN PARTS OF the build
 133 scripts of cargo and rustc themselves, such as the `./configure` scripts and
 134 SOME PARTS of the `config.toml` files. Here, "build", "host" and "target" mean
 135 the same things they do in GNU toolchain terminology. However, IN OTHER PARTS
 136 OF the build scripts of cargo and rustc, as well as cargo and rustc's own
 137 output and logging messages, the term "host" and "target" mean as they do in
 138 the previous paragraph. Yes, it's a total mind fuck. :( Table for clarity:
 139
 140 ======================================= =============== ========================
 141                                         Rust ecosystem, Some parts of the rustc
 142 GNU term / Debian envvar                rustc and cargo and cargo build scripts
 143 ======================================= =============== ========================
 144 build   DEB_BUILD_{ARCH,RUST_TYPE}      host            build
 145   the machine running the build
 146 --------------------------------------- --------------- ------------------------
 147 host    DEB_HOST_{ARCH,RUST_TYPE}       target          host(s)
 148   the machine the build products run on
 149 --------------------------------------- --------------- ------------------------
 150 only relevant when building a compiler
 151 target  DEB_TARGET_{ARCH,RUST_TYPE}     N/A             target(s)
 152   the one architecture that the built                     extra architectures
 153   cross-compiler itself builds for                        to build "std" for
 154 --------------------------------------- --------------- ------------------------
 155
 156
 157 Porting to new architectures (on the same distro)
 158 =================================================
 159
 160 As mentioned above, to cross-compile rust packages you need to install the rust
 161 standard library for each relevant foreign architecture. However, this is not
 162 needed when cross-compiling rustc itself; its build system will build any
 163 relevant foreign-architecture standard libraries automatically.
 164
 165 Cross-build, in a schroot using sbuild
 166 --------------------------------------
 167
 168 0. Set up an schroot for your native architecture, for sbuild:
 169
 170     sudo apt-get install sbuild
 171     sudo sbuild-adduser $LOGNAME
 172     newgrp sbuild # or log out and log back in
 173     sudo sbuild-createchroot --include=eatmydata,ccache,gnupg unstable \
 174       /srv/chroot/unstable-$(dpkg-architecture -qDEB_BUILD_ARCH)-sbuild \
 175       http://deb.debian.org/debian
 176
 177    See https://wiki.debian.org/sbuild for more details.
 178
 179 1. Build it:
 180
 181     sudo apt-get source --download-only rustc
 182     sbuild --host=$new_arch rustc_*.dsc
 183
 184 Cross-build, directly on your own system
 185 ----------------------------------------
 186
 187 0. Install the build-dependencies of rustc (including cargo and itself):
 188
 189     sudo dpkg --add-architecture $new_arch
 190     sudo apt-get --no-install-recommends build-dep --host-architecture=$new_arch rustc
 191
 192 1. Build it:
 193
 194     apt-get source --compile --host-architecture=$new_arch rustc
 195
 196 Native-build using bundled upstream binary blobs
 197 ------------------------------------------------
 198
 199 Use the same instructions as given in "Bootstrapping" in debian/README.source
 200 in the source package, making sure to set the relevant architectures.
 201
 202 Responsible distribution of cross-built binaries
 203 ------------------------------------------------
 204
 205 By nature, cross-builds do not run tests. These are important for rustc and
 206 many tests often fail on newly-supported architectures even if builds and
 207 cross-builds work fine. You should find some appropriate way to test your
 208 cross-built packages rather than blindly shipping them to users.
 209
 210 For example, Debian experimental is an appropriate place to upload them, so
 211 that they can be installed and tested on Debian porter boxes, before being
 212 uploaded to unstable and distributed to users.
 213