libc-rs/ci
Francis Gagné 18341fd23a Rename the dox configuration option to cross_platform_docs
The libc crate is used as a dependency of the Rust compiler. Its build
system passes `--cfg dox` to all crates when generating their
documentation. libc's documentation is generated when the build system
is asked to generate the compiler documentation because `cargo doc`
automatically documents all dependencies.

When the dox configuration option is enabled, libc disables its
dependency on the core crate and provides the necessary definitions
itself. The dox configuration option is meant for generating
documentation for a multitude of targets even if the core crate for that
target is not installed. However, when documenting the compiler, it's
not necessary to do that; we can just use core or std as usual.

This change is motivated by the changes made to the compiler in
rust-lang/rust#48171. With these changes, it's necessary to provide
implementations of the Clone and Copy traits for some primitive types in
the library that defines these traits (previously, these implementations
were provided by the compiler). Normally, these traits (and thus the
implementations) are provided by core, so any crate that uses
`#![no_core]` must now provide its own copy of the implementations.

Because libc doesn't provide its own copy of the implementations yet,
and because the compiler's build system passes `--cfg dox` to libc,
generating the documentation for the compiler fails when generating
documentation for libc. By renaming the configuration option, libc will
use core or std and will thus have the necessary definitions for the
documentation to be generated successfully.
2018-03-18 16:39:40 -04:00
..
docker Update FreeBSD docker CI to use FreeBSD 11.1 image 2018-03-16 08:23:01 +11:00
ios Touch up the iOS deploy script 2017-01-18 10:20:13 -08:00
android-install-ndk.sh Update to NDK r15b (with unified headers) and add missing symbols needed by nix crate 2017-07-03 13:26:35 +02:00
android-install-sdk.sh Fix android ci 2017-10-27 16:46:32 -02:00
android-sysimage.sh Add x86_64-linux-android test 2017-05-03 20:12:49 -03:00
dox.sh Rename the dox configuration option to cross_platform_docs 2018-03-18 16:39:40 -04:00
emscripten-entry.sh Use more convenient and UNIX-agnostic shebang 2017-11-13 13:42:00 +00:00
emscripten.sh Update emscripten to latest 2017-08-27 08:37:15 -07:00
landing-page-footer.html Swap header/footer... dunno how they got that way? 2016-03-28 13:58:13 -07:00
landing-page-head.html Swap header/footer... dunno how they got that way? 2016-03-28 13:58:13 -07:00
linux-s390x.sh Run s390x test in qemu system instead of qemu user 2017-10-31 09:44:54 -02:00
linux-sparc64.sh Run sparc64-unknown-linux-gnu tests on qemu system 2017-10-31 10:10:35 -02:00
README.md Update the instructions for building a FreeBSD CI image 2018-03-15 21:22:00 +11:00
run-docker.sh Update Android images/runners 2017-08-21 22:52:06 -07:00
run-qemu.sh use new openbsd-6.0 qcow2 image 2016-09-09 06:24:40 +02:00
run.sh Update FreeBSD docker CI to use FreeBSD 11.1 image 2018-03-16 08:23:01 +11:00
runtest-android.rs Update Android images/runners 2017-08-21 22:52:06 -07:00
style.rs Add a style checking script to CI 2016-03-01 22:03:34 -08:00
test-runner-linux Use more convenient and UNIX-agnostic shebang 2017-11-13 13:42:00 +00:00

The goal of the libc crate is to have CI running everywhere to have the strongest guarantees about the definitions that this library contains, and as a result the CI is pretty complicated and also pretty large! Hopefully this can serve as a guide through the sea of scripts in this directory and elsewhere in this project.

Files

First up, let's talk about the files in this directory:

  • run-travis.sh - a shell script run by all Travis builders, this is responsible for setting up the rest of the environment such as installing new packages, downloading Rust target libraries, etc.

  • run.sh - the actual script which runs tests for a particular architecture. Called from the run-travis.sh script this will run all tests for the target specified.

  • cargo-config - Cargo configuration of linkers to use copied into place by the run-travis.sh script before builds are run.

  • dox.sh - script called from run-travis.sh on only the linux 64-bit nightly Travis bots to build documentation for this crate.

  • landing-page-*.html - used by dox.sh to generate a landing page for all architectures' documentation.

  • run-qemu.sh - see discussion about QEMU below

  • mips, rumprun - instructions to build the docker image for each respective CI target

CI Systems

Currently this repository leverages a combination of Travis CI and AppVeyor for running tests. The triples tested are:

  • AppVeyor
    • {i686,x86_64}-pc-windows-{msvc,gnu}
  • Travis
    • {i686,x86_64,mips,aarch64}-unknown-linux-gnu
    • {x86_64,aarch64}-unknown-linux-musl
    • arm-unknown-linux-gnueabihf
    • arm-linux-androideabi
    • {i686,x86_64}-apple-{darwin,ios}
    • x86_64-rumprun-netbsd
    • x86_64-unknown-freebsd
    • x86_64-unknown-openbsd

The Windows triples are all pretty standard, they just set up their environment then run tests, no need for downloading any extra target libs (we just download the right installer). The Intel Linux/OSX builds are similar in that we just download the right target libs and run tests. Note that the Intel Linux/OSX builds are run on stable/beta/nightly, but are the only ones that do so.

The remaining architectures look like:

  • Android runs in a docker image with an emulator, the NDK, and the SDK already set up. The entire build happens within the docker image.
  • The MIPS, ARM, and AArch64 builds all use the QEMU userspace emulator to run the generated binary to actually verify the tests pass.
  • The MUSL build just has to download a MUSL compiler and target libraries and then otherwise runs tests normally.
  • iOS builds need an extra linker flag currently, but beyond that they're built as standard as everything else.
  • The rumprun target builds an entire kernel from the test suite and then runs it inside QEMU using the serial console to test whether it succeeded or failed.
  • The BSD builds, currently OpenBSD and FreeBSD, use QEMU to boot up a system and compile/run tests. More information on that below.

QEMU

Lots of the architectures tested here use QEMU in the tests, so it's worth going over all the crazy capabilities QEMU has and the various flavors in which we use it!

First up, QEMU has userspace emulation where it doesn't boot a full kernel, it just runs a binary from another architecture (using the qemu-<arch> wrappers). We provide it the runtime path for the dynamically loaded system libraries, however. This strategy is used for all Linux architectures that aren't intel. Note that one downside of this QEMU system is that threads are barely implemented, so we're careful to not spawn many threads.

For the rumprun target the only output is a kernel image, so we just use that plus the rumpbake command to create a full kernel image which is then run from within QEMU.

Finally, the fun part, the BSDs. Quite a few hoops are jumped through to get CI working for these platforms, but the gist of it looks like:

  • Cross compiling from Linux to any of the BSDs seems to be quite non-standard. We may be able to get it working but it might be difficult at that point to ensure that the libc definitions align with what you'd get on the BSD itself. As a result, we try to do compiles within the BSD distro.
  • On Travis we can't run a VM-in-a-VM, so we resort to userspace emulation (QEMU).
  • Unfortunately on Travis we also can't use KVM, so the emulation is super slow.

With all that in mind, the way BSD is tested looks like:

  1. Download a pre-prepared image for the OS being tested.
  2. Generate the tests for the OS being tested. This involves running the ctest library over libc to generate a Rust file and a C file which will then be compiled into the final test.
  3. Generate a disk image which will later be mounted by the OS being tested. This image is mostly just the libc directory, but some modifications are made to compile the generated files from step 2.
  4. The kernel is booted in QEMU, and it is configured to detect the libc-test image being available, run the test script, and then shut down afterwards.
  5. Look for whether the tests passed in the serial console output of the kernel.

There's some pretty specific instructions for setting up each image (detailed below), but the main gist of this is that we must avoid a vanilla cargo run inside of the libc-test directory (which is what it's intended for) because that would compile syntex_syntax, a large library, with userspace emulation. This invariably times out on Travis, so we can't do that.

Once all those hoops are jumped through, however, we can be happy that we're testing almost everything!

Below are some details of how to set up the initial OS images which are downloaded. Each image must be enabled have input/output over the serial console, log in automatically at the serial console, detect if a second drive in QEMU is available, and if so mount it, run a script (it'll specifically be run-qemu.sh in this folder which is copied into the generated image talked about above), and then shut down.

QEMU Setup - FreeBSD

  1. Download the latest stable amd64-bootonly release ISO. E.g. FreeBSD-11.1-RELEASE-amd64-bootonly.iso
  2. Create the disk image: qemu-img create -f qcow2 FreeBSD-11.1-RELEASE-amd64.qcow2 2G
  3. Boot the machine: qemu-system-x86_64 -cdrom FreeBSD-11.1-RELEASE-amd64-bootonly.iso -drive if=virtio,file=FreeBSD-11.1-RELEASE-amd64.qcow2 -net nic,model=virtio -net user
  4. Run the installer, and install FreeBSD:
    1. Install

    2. Continue with default keymap

    3. Set Hostname: freebsd-ci

    4. Distribution Select:

      1. Uncheck lib32
      2. Uncheck ports
    5. Network Configuration: vtnet0

    6. Configure IPv4? Yes

    7. DHCP? Yes

    8. Configure IPv6? No

    9. Resolver Configuration: Ok

    10. Mirror Selection: Main Site

    11. Partitioning: Auto (UFS)

    12. Partition: Entire Disk

    13. Partition Scheme: MBR

    14. App Partition: Ok

    15. Partition Editor: Finish

    16. Confirmation: Commit

    17. Wait for sets to install

    18. Set the root password to nothing (press enter twice)

    19. Set time zone to UTC

    20. Set Date: Skip

    21. Set Time: Skip

    22. System Configuration:

      1. Disable sshd
      2. Disable dumpdev
    23. System Hardening

      1. Disable Sendmail service
    24. Add User Accounts: No

    25. Final Configuration: Exit

    26. Manual Configuration: Yes

    27. echo 'console="comconsole"' >> /boot/loader.conf

    28. echo 'autoboot_delay="0"' >> /boot/loader.conf

    29. echo 'ext2fs_load="YES"' >> /boot/loader.conf

    30. Look at /etc/ttys, see what getty argument is for ttyu0 (E.g. 3wire)

    31. Edit /etc/gettytab (with vi for example), look for ttyu0 argument, prepend :al=root to the line beneath to have the machine auto-login as root. E.g.

      3wire:\
               :np:nc:sp#0:
      

      becomes:

      3wire:\
               :al=root:np:nc:sp#0:
      
    32. Edit /root/.login and put this in it:

      [ -e /dev/vtbd1 ] || exit 0
      mount -t ext2fs /dev/vtbd1 /mnt
      sh /mnt/run.sh /mnt
      poweroff
      
    33. Exit the post install shell: exit

    34. Back in in the installer choose Reboot

    35. If all went well the machine should reboot and show a login prompt. If you switch to the serial console by choosing View > serial0 in the qemu menu, you should be logged in as root.

    36. Shutdown the machine: shutdown -p now

Helpful links

QEMU setup - OpenBSD

  1. Download CD installer
  2. qemu-img create -f qcow2 foo.qcow2 2G
  3. qemu -cdrom foo.iso -drive if=virtio,file=foo.qcow2 -net nic,model=virtio -net user
  4. run installer
  5. echo 'set tty com0' >> /etc/boot.conf
  6. echo 'boot' >> /etc/boot.conf
  7. Modify /etc/ttys, change the tty00 at the end from 'unknown off' to 'vt220 on secure'
  8. Modify same line in /etc/ttys to have "/root/foo.sh" as the shell
  9. Add this script to /root/foo.sh
#!/bin/sh
exec 1>/dev/tty00
exec 2>&1

if mount -t ext2fs /dev/sd1c /mnt; then
  sh /mnt/run.sh /mnt
  shutdown -ph now
fi

# limited shell...
exec /bin/sh < /dev/tty00
  1. chmod +x /root/foo.sh

Helpful links:

Questions?

Hopefully that's at least somewhat of an introduction to everything going on here, and feel free to ping @alexcrichton with questions!