diff options
Diffstat (limited to 'debian/README.Debian')
| -rw-r--r-- | debian/README.Debian | 345 |
1 files changed, 345 insertions, 0 deletions
diff --git a/debian/README.Debian b/debian/README.Debian new file mode 100644 index 000000000..960cfa574 --- /dev/null +++ b/debian/README.Debian @@ -0,0 +1,345 @@ +Architecture-specific notes +=========================== + +This section talks about the rustc compiler on your host architecture. For +cross-compiling to a foreign target architecture, see the next section. + +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. + + +Cross-compiling +=============== + +Rust supports cross-compiling to many different architectures, and we expose +this feature as fully as feasible in Debian, including to wasm and windows. + +Introduction and terminology +---------------------------- + +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. For cross-compiling, all +you need to do (on the rustc / LLVM side) is to install the standard libraries +for each target architecture you want to compile to, i.e. libstd-rust-dev. + +Before we go further, we must clarify some 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 +--------------------------------------- --------------- ------------------------ + +General case for other Debian platforms +--------------------------------------- + +To manually use the Debian rustc binary for cross-compiling: + +0. If you haven't done so previously, run: + + dpkg --add-architecture ${DEB_TARGET_ARCH} + apt-get update + + (This is something that you need to do for all Debian crossbuilding or + multi-architecture installing.) + +1. Install crossbuild-essential-${DEB_TARGET_ARCH} e.g. arm64. + + (This is something that you need to do for all Debian crossbuilding.) + + For certain (HOST, TARGET) pairs you can instead install gcc-multilib, e.g. + when compiling from amd64 to i386. + +2. Install libstd-rust-dev:${DEB_TARGET_ARCH}. + +3. Add the following flags to your rustc invocation: + + -C linker=${DEB_TARGET_GNU_TYPE}-gcc # e.g. aarch64-linux-gnu + --target ${DEB_TARGET_RUST_TYPE} # e.g. aarch64-unknown-linux-gnu + + For certain (HOST, TARGET) pairs, namely the same ones as above that are + supported by gcc-multilib, you can omit the linker flag since the default + ``gcc`` linker (with multilib support) will work. + +You can find the right TARGET vars to use in dpkg-architecture(1) and/or +/usr/share/rustc/architecture.mk and/or possibly on the Debian wiki. + +These steps are different when cross-building a Debian package, or preparing +one for cross-compiling. (1) is performed automatically by cross-building tools +such as sbuild, and (3) is performed automatically by our cargo wrapper script. +The details of how to do (2) correctly are explained in the section below +called "Using rustc in a Debian package". + +Foreign non-Debian platforms +---------------------------- + +Targetting a non-Debian platform is not a common Debian crossbuilding pattern, +so we do something ad-hoc for our Debian rust packages. + +Instead of libstd-rust-dev:$arch (for an $arch that is not in Debian), we +provide a libstd-rust-dev-$platform:$arch package. For example, +libstd-rust-dev-windows:i386. For VM platforms such as WASM, $arch is omitted. + +Instead of implicitly relying on crossbuild-essential-$arch (for an $arch that +is not in Debian), we have the libstd-rust-dev-$platform:$arch package +Recommend the appropriate linker. For example, Clang or MinGW. + +To use these for manual crossbuilding: + +1. Install the appropriate library package, as well as the corresponding linker + package from its Recommends if it isn't pulled in automatically. + +2. Pass in the appropriate ``-C linker`` and ``--target`` flags to ``rustc``. + +WASM +~~~~ + +We ship two different wasm32 targets - wasm32-unknown-unknown and wasm32-wasi - +in the libstd-rust-dev-wasm32 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 +``library/std/src/sys/wasm/mod.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 can either: + +1. Use /usr/share/rustc/bin/wasi-node, which depends on nodejs. + + Pending #986616, this will be added to the nodejs package directly. + +2. Compile and use one of the following runtimes: + + - https://github.com/bytecodealliance/wasmtime + - https://github.com/bytecodealliance/lucet + - https://github.com/wasmerio/wasmer + +Windows +~~~~~~~ + +We ship the following targets: + +- x86_64-pc-windows-gnu in the libstd-rust-dev-windows:amd64 package +- i686-pc-windows-gnu in the libstd-rust-dev-windows:i386 package + +To run the compiled binaries, you can use wine. You will need to set one of: + +- WINEPATH="/usr/lib/gcc/x86_64-w64-mingw32/10-posix;/usr/lib/rustlib/x86_64-pc-windows-gnu/lib" +- WINEPATH="/usr/lib/gcc/i686-w64-mingw32/10-posix;/usr/lib/rustlib/i686-pc-windows-gnu/lib" + +If you get "import_dll ... not found" errors, check that these paths are mapped +to some windows drive path - run "winecfg $path" for each path in the component +of WINEPATH; if any begin with "\\?\unix\" then you'll need to map them to a +drive in "winecfg" -> Drives. If all begin with some windows drive letter, then +your error is something unrelated and we sadly can't help you here. + + +Using rustc in a Debian package +=============================== + +You are encouraged to support cross-compiling. See the above section for more +details; in summary you need to install rustc for the host architecture and +libstd-rust-dev for the target architecture, 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. + +If your build uses cargo, you'll want to add: + + Build-Depends: + [..] + cargo:native, + [..] + +and use our cargo wrapper script instead of /usr/bin/cargo directly. See +/usr/share/cargo/bin/cargo for details on how to use it. + + +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. + +Cross-build, in a schroot using sbuild +-------------------------------------- + +0. Set up an schroot for your native architecture, for sbuild: + + 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 + + See https://wiki.debian.org/sbuild for more details. + +1. Build it: + + sudo apt-get source --download-only rustc + sbuild --host=$new_arch rustc_*.dsc + +Cross-build, directly on your own system +---------------------------------------- + +0. Install the build-dependencies of rustc (including cargo and itself): + + sudo dpkg --add-architecture $new_arch + sudo apt-get --no-install-recommends build-dep --host-architecture=$new_arch rustc + +1. Build it: + + apt-get source --compile --host-architecture=$new_arch rustc + +Native-build using bundled upstream binary blobs +------------------------------------------------ + +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 |