debian/README.Debian

   1 Shared libraries
   2 ================
   3
   4 For now, the shared libraries of Rust are private.
   5 The rational is the following:
   6  * Upstream prefers static linking for now
   7    - https://github.com/rust-lang/rust/issues/10209
   8  * rust is still under heavy development. As far as we know, there is
   9    no commitement from upstream to provide a stable ABI for now.
  10    Until we know more, we cannot take the chance to have Rust-built packages
  11    failing at each release of the compiler.
  12  * Static builds are working out of the box just fine
  13  * However, LD_LIBRARY_PATH has to be updated when -C prefer-dynamic is used
  14
  15  -- Sylvestre Ledru <sylvestre@debian.org>, Fri, 13 Feb 2015 15:08:43 +0100
  16
  17 Building from source
  18 ====================
  19
  20 By default, the Debian rustc package will use the system rustc to bootstrap
  21 itself from. The system rustc has to be either the previous or the same version
  22 as the rustc being built; the build will fail if this is not the case.
  23
  24   apt-get source --compile rustc
  25
  26 Alternatively, you may give the "pkg.rustc.dlstage0" DEB_BUILD_PROFILE to
  27 instead use the process defined by Rust upstream. This downloads the "official"
  28 stage0 compiler for the version being built from rust-lang.org. At the time of
  29 writing "official" means "the previous stable version".
  30
  31   apt-get source --compile --build-profiles=pkg.rustc.dlstage0 rustc
  32
  33 If neither of these options are acceptable to you, (e.g. because your build
  34 process cannot access the network), see the below sections on "Bootstrapping"
  35 for more options.
  36
  37 Bootstrapping a new distro
  38 ==========================
  39
  40 If you want to bootstrap a new distro that does not already have rustc, you
  41 may run `debian/rules source_orig-dl` to create a .dsc that does not
  42 Build-Depend on rustc. Instead, it includes an extra orig-dl source tarball
  43 that contains the official stage0 compiler, pre-downloaded from rust-lang.org
  44 so that your build daemons don't need to access the network during the build.
  45
  46   debian/rules source_orig-dl
  47   sbuild ../rustc_*.dsc
  48
  49 To only bootstrap specific architectures, run this instead:
  50
  51   upstream_bootstrap_arch="arm64 armel armhf" debian/rules source_orig-dl
  52
  53 This way, other architectures will be omitted from the orig-dl tarball. You
  54 might want to do this e.g. if these other architectures are already present in
  55 your distro, but the $upstream_bootstrap_arch ones are not yet present.
  56
  57 Notes
  58 -----
  59
  60 The approach here is based on doing a *source-only upload*, where the building
  61 of the binary packages are done by automatic build daemons. We achieve this, by
  62 bundling the upstream bootstrapping binaries inside the Debian source package.
  63 This is a nasty hack that stretches the definition of "source package", but is
  64 unavoidable if we want to securely bootstrap self-hosted compilers.
  65
  66 This differs from the traditional Debian way of bootstrapping compilers, which
  67 involves locally building a "stage0" Debian package using upstream binaries
  68 (instead of Debian build dependencies that don't yet exist), then using this
  69 stage0 Debian package to do a "standard" build that then forms part of a binary
  70 upload. This allows the source package to remain binary-free. However, both the
  71 original stage0 package and upstream binaries are lost, and Debian currently
  72 does not have any policy nor infrastructure that can try to reproduce what the
  73 uploader supposedly did.
  74
  75 The advantage of our (non-traditional) approach is that anyone can download
  76 this source package if they want to build the binaries themselves - they can
  77 just follow the same automatic build processes that apply to every other Debian
  78 package. If the build process is reproducible [1] then they can be sure that
  79 *you* (as the Debian Developer that prepared the source-only upload) didn't
  80 backdoor the binaries, nor did the automatic build daemons even if they were
  81 compromised during the build.
  82
  83 (The upstream binaries contained in the orig-dl tarball may still have been
  84 backdoored. However, this is true in both scenarios - our arrangement is still
  85 a strict improvement in security, because it reduces the set of "things that
  86 may have been backdoored". Furthermore, more people use the upstream binaries,
  87 so presumably any backdoors would be noticed more quickly.)
  88
  89 In the future, both approaches are unifiable into a single secure process, as
  90 long as:
  91
  92 1. We can trace the binaries that were *actually used* in the original
  93    bootstrapping event.
  94 2. We can optionally *choose* to use a different bootstrapping binary, such as
  95    an independently-written rustc.
  96 3. We have a unified well-defined process for both (1) or (2), that applies to
  97    all bootstrapped packages (not just rustc). "Well-defined" means that it can
  98    be automated by a program, and it can verify that both options result in the
  99    same binary outputs (after the stage2 compilation step).
 100
 101 This is otherwise known as Diverse Double-Compilation.
 102
 103 [1] https://github.com/rust-lang/rust/issues/34902
 104 [2] http://www.dwheeler.com/trusting-trust/
 105
 106 Bootstrapping a new architecture
 107 ================================
 108
 109 Compiling from upstream releases
 110 --------------------------------
 111
 112 See the previous section, "Bootstrapping a new distro", specifically the part
 113 about how to "only bootstrap specific architectures".
 114
 115 For Debian, we should be able to support armhf soon:
 116
 117 Complete: armhf https://github.com/rust-lang/rust/issues/35590
 118 In-progress: ppc64, ppc64el, s390x: https://github.com/rust-lang/rust/issues/36006
 119 In-progress: mips, mipsel, mips64el: https://github.com/rust-lang/rust/issues/36015
 120
 121 Cross-compiling from Debian packages
 122 ------------------------------------
 123
 124 WARNING: This does not work yet
 125
 126 0. Start with rust installed on an existing platform
 127
 128 1. Build a rust cross-compiler targeting new architecture
 129
 130     sudo apt-get build-dep --build-profile=nodoc rustc
 131     dpkg-buildpackage -t $new_arch
 132
 133 2. Use cross-compiler to build a compiler that runs on new architecture
 134
 135     dpkg --add-architecture $new_arch
 136     sudo apt-get build-dep --host-architecture=$new_arch rustc
 137     dpkg-buildpackage -a $new_arch
 138
 139     # Perhaps this is sufficient ??
 140     #apt-get source --compile --host-architecture=$new_arch rustc
 141
 142  -- Angus Lees <gus@debian.org>, Sun,  1 Feb 2015 16:16:44 +1100