-For now, the shared libraries of Rust are private.
-The rational is the following:
- * Upstream prefers static linking for now
- - https://github.com/rust-lang/rust/issues/10209
- * rust is still under heavy development. As far as we know, there is
- no commitement from upstream to provide a stable ABI for now.
- Until we know more, we cannot take the chance to have Rust-built packages
- failing at each release of the compiler.
- * Static builds are working out of the box just fine
- * However, LD_LIBRARY_PATH has to be updated when -C prefer-dynamic is used
+Architecture-specific notes
+===========================
- -- Sylvestre Ledru <sylvestre@debian.org>, Fri, 13 Feb 2015 15:08:43 +0100
+armhf armel mips mipsel powerpc powerpcspe
+------------------------------------------
+
+We only ship debuginfo for libstd and not the compiler itself, otherwise builds
+run out of memory on the Debian buildds, with non-obvious and random errors.
+
+See https://github.com/rust-lang/rust/issues/45854 for details.
+
+If all your armhf build machines have ~8GB memory or more, you can experiment
+with disabling this work-around (i.e. revert to normal) in d/rules.
+
+wasm32
+------
+
+We ship two different wasm32 targets - wasm32-unknown-unknown and wasm32-wasi -
+in the libstd-rust-dev-wasm32-cross package.
+
+wasm32-unknown-unknown is suitable for web stuff, where you typically will need
+to depending on the rust-wasm-bindgen, js-sys, and web-sys crates. Here, calls
+to libstd stuff (such as println!()) will silently do nothing, as defined in
+``src/libstd/sys/wasm/fs.rs`` and explained in upstream #48564.
+
+wasm32-wasi is suitable for non-web stuff, and is closer to a "normal" target
+where you expect libstd to be available, and for println!() to actually print
+to stdout. If you just want to cross-compile a regular non-wasm library or
+program to wasm for whatever reason, and only want to run it natively and not
+inside a web browser, use this target.
+
+To run the generated wasm, you will need a runtime:
+
+- https://github.com/bytecodealliance/wasmtime
+- https://github.com/bytecodealliance/lucet
+- https://github.com/wasmerio/wasmer
+- https://nodejs.org/api/wasi.html (sadly Debian's is too old, ATTOW)
+
+The first 3 are actually also all written in Rust, so one day some of them may
+even be packaged for Debian.
+
+
+Cross-compiling
+===============
+
+Rust uses LLVM, so cross-compiling works a bit differently from the GNU
+toolchain. The most important difference is that there are no "cross"
+compilers, every compiler is already a cross compiler. All you need to do is
+install the standard libraries for each target architecture you want to compile
+to. For rustc, this is libstd-rust-dev, so your debian/control would look
+something like this:
+
+ Build-Depends:
+ [..]
+ rustc:native (>= $version),
+ libstd-rust-dev (>= $version),
+ [..]
+
+You need both, this is important. When Debian build toolchains satisfy the
+build-depends of a cross-build, (1) a "rustc:native" Build-Depends selects
+rustc for the native architecture, which is possible because it's "Multi-Arch:
+allowed", and this will implicitly pull in libstd-rust-dev also for the native
+architecture; and (2) a "libstd-rust-dev" Build-Depends implies libstd-rust-dev
+for the foreign architecture, since it's "Multi-Arch: same".
+
+You'll probably also want to add
+
+ include /usr/share/rustc/architecture.mk
+
+to your debian/rules. This sets some useful variables like DEB_HOST_RUST_TYPE.
+
+See the cargo package for an example.
+
+Terminology
+-----------
+
+The rust ecosystem generally uses the term "host" for the native architecture
+running the compiler, equivalent to DEB_BUILD_RUST_TYPE or "build" in GNU
+terminology, and "target" for the foreign architecture that the build products
+run on, equivalent to DEB_HOST_RUST_TYPE or "host" in GNU terminology. For
+example, rustc --version --verbose will output something like:
+
+ rustc 1.16.0
+ [..]
+ host: x86_64-unknown-linux-gnu
+
+And both rustc and cargo have --target flags:
+
+ $ rustc --help | grep '\-\-target'
+ --target TARGET Target triple for which the code is compiled
+ $ cargo build --help | grep '\-\-target'
+ --target TRIPLE Build for the target triple
+
+One major exception to this naming scheme is in CERTAIN PARTS OF the build
+scripts of cargo and rustc themselves, such as the `./configure` scripts and
+SOME PARTS of the `config.toml` files. Here, "build", "host" and "target" mean
+the same things they do in GNU toolchain terminology. However, IN OTHER PARTS
+OF the build scripts of cargo and rustc, as well as cargo and rustc's own
+output and logging messages, the term "host" and "target" mean as they do in
+the previous paragraph. Yes, it's a total mind fuck. :( Table for clarity:
+
+======================================= =============== ========================
+ Rust ecosystem, Some parts of the rustc
+GNU term / Debian envvar rustc and cargo and cargo build scripts
+======================================= =============== ========================
+build DEB_BUILD_{ARCH,RUST_TYPE} host build
+ the machine running the build
+--------------------------------------- --------------- ------------------------
+host DEB_HOST_{ARCH,RUST_TYPE} target host(s)
+ the machine the build products run on
+--------------------------------------- --------------- ------------------------
+only relevant when building a compiler
+target DEB_TARGET_{ARCH,RUST_TYPE} N/A target(s)
+ the one architecture that the built extra architectures
+ cross-compiler itself builds for to build "std" for
+--------------------------------------- --------------- ------------------------
-Bootstrapping from nothing
---------------------------
-WARNING: This does not work for now as rust cannot bootstrap itself
+Porting to new architectures (on the same distro)
+=================================================
+As mentioned above, to cross-compile rust packages you need to install the rust
+standard library for each relevant foreign architecture. However, this is not
+needed when cross-compiling rustc itself; its build system will build any
+relevant foreign-architecture standard libraries automatically.
-You need a "stage0" rust compiler from somewhere. You can download a
-pre-built minimal stage0 from http://www.rust-lang.org/ at build time,
-or use a rustc that was already in /usr/bin via whatever black magic
-(or some other path if you modify debian/rules).
+Cross-build, in a schroot using sbuild
+--------------------------------------
- apt-get source --compile --build-profiles=dlstage0,nodoc rustc
+0. Set up an schroot for your native architecture, for sbuild:
-"dlstage0" downloads a stage0 from rust-lang.org during the build.
-"nodoc" disables building rust-doc package and skips the long list of
-build-deps usually required.
+ sudo apt-get install sbuild
+ sudo sbuild-adduser $LOGNAME
+ newgrp sbuild # or log out and log back in
+ sudo sbuild-createchroot --include=eatmydata,ccache,gnupg unstable \
+ /srv/chroot/unstable-$(dpkg-architecture -qDEB_BUILD_ARCH)-sbuild \
+ http://deb.debian.org/debian
- dpkg -i rustc*.deb
- apt-get source --compile rustc
+ See https://wiki.debian.org/sbuild for more details.
-This produces the full rust compiler built using your now obsolete
-"dlstage0" rustc compiler.
+1. Build it:
-Bootstrapping a new architecture
---------------------------------
+ sudo apt-get source --download-only rustc
+ sbuild --host=$new_arch rustc_*.dsc
-0. Start with rust installed on an existing platform
+Cross-build, directly on your own system
+----------------------------------------
-1. Build a rust cross-compiler targeting new architecture
+0. Install the build-dependencies of rustc (including cargo and itself):
- sudo apt-get build-dep --build-profile=nodoc rustc
- dpkg-buildpackage -t $new_arch
+ sudo dpkg --add-architecture $new_arch
+ sudo apt-get --no-install-recommends build-dep --host-architecture=$new_arch rustc
-2. Use cross-compiler to build a compiler that runs on new architecture
+1. Build it:
- dpkg --add-architecture $new_arch
- sudo apt-get build-dep --host-architecture=$new_arch rustc
- dpkg-buildpackage -a $new_arch
+ apt-get source --compile --host-architecture=$new_arch rustc
- # Perhaps this is sufficient ??
- #apt-get source --compile --host-architecture=$new_arch rustc
+Native-build using bundled upstream binary blobs
+------------------------------------------------
- -- Angus Lees <gus@debian.org>, Sun, 1 Feb 2015 16:16:44 +1100
+Use the same instructions as given in "Bootstrapping" in debian/README.source
+in the source package, making sure to set the relevant architectures.
+
+Responsible distribution of cross-built binaries
+------------------------------------------------
+
+By nature, cross-builds do not run tests. These are important for rustc and
+many tests often fail on newly-supported architectures even if builds and
+cross-builds work fine. You should find some appropriate way to test your
+cross-built packages rather than blindly shipping them to users.
+
+For example, Debian experimental is an appropriate place to upload them, so
+that they can be installed and tested on Debian porter boxes, before being
+uploaded to unstable and distributed to users.
+
+
+Test failures
+=============
+
+Starting from version 1.20.0+dfsg1-1 the Debian packages of rustc no longer
+fail the overall build if > 0 tests fail. Instead, we allow up to around 5
+tests to fail. In other words, if you're reading this in a binary package,
+between 0 and 5 tests might have failed when building this.
+
+This is due to lack of maintainer time to investigate all failures. Many
+previous test failures were reported to upstream and did not receive a timely
+response, suggesting the failures were not important. I was then forced to
+patch out the test to make the build proceed, so several tests were being
+ignored in practise anyway.
+
+This brings the Debian package in line with the Fedora package which also
+ignores all test failures. (Many other distributions don't run tests at all.)
+
+If you think that the Debian rustc package is miscompiling your program in a
+way that the upstream distributed compiler doesn't, you may check the test
+failures here:
+
+https://buildd.debian.org/status/package.php?p=rustc
+
+If you can identify a relevant test failure, as well as the patches needed to
+fix it (either to rustc or LLVM), this will speed up the processing of any bug
+reports on the Debian side.
+
+We will also examine these failures ourselves on a best-effort basis and
+attempt to fix the more serious-looking ones.
+
+Uncommon architectures
+----------------------
+
+Debian release architectures armel and s390x currently have more test failures,
+being tracked by upstream here:
+
+- https://github.com/rust-lang/rust/issues/52493 armel
+- https://github.com/rust-lang/rust/issues/52491 s390x
+
+Ports architectures
+-------------------
+
+The number of allowed test failures on certain Debian ports architectures
+(currently powerpc, powerpcspe, sparc64, x32) is raised greatly to help unblock
+progress for porters. Of course, as a user this means you may run into more
+bugs than usual; as mentioned above bugs reports and patches are welcome.
+
+
+Shared libraries
+================
+
+For now, the shared libraries of Rust are private.
+The rational is the following:
+ * Upstream prefers static linking for now
+ - https://github.com/rust-lang/rust/issues/10209
+ * rust is still under heavy development. As far as we know, there is
+ no commitement from upstream to provide a stable ABI for now.
+ Until we know more, we cannot take the chance to have Rust-built packages
+ failing at each release of the compiler.
+ * Static builds are working out of the box just fine
+ * However, LD_LIBRARY_PATH has to be updated when -C prefer-dynamic is used
+
+ -- Sylvestre Ledru <sylvestre@debian.org>, Fri, 13 Feb 2015 15:08:43 +0100
projects / rustc.git / blobdiff