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