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