From 9fc6e6ff867d861ef2c257355d92486e7dd46997 Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Wed, 10 May 2023 12:54:40 -0700 Subject: [PATCH] Update linux build instructions (#86062) To reflect recent series of changes to our official build. This updates the mentioned images to use floating tags, and clarifies that the new official build containers all are designed for cross-building. --- .../building/coreclr/cross-building.md | 16 +++++++-- .../building/coreclr/linux-instructions.md | 36 ++++++++++++------- 2 files changed, 36 insertions(+), 16 deletions(-) diff --git a/docs/workflow/building/coreclr/cross-building.md b/docs/workflow/building/coreclr/cross-building.md index 993ce2c76cbd90..4fbbdebdd404e0 100644 --- a/docs/workflow/building/coreclr/cross-building.md +++ b/docs/workflow/building/coreclr/cross-building.md @@ -146,12 +146,17 @@ When it comes to building, Docker offers the most flexibility when it comes to t ### Cross-Compiling for ARM32 and ARM64 with Docker -As mentioned in the [Linux Cross-Building section](#linux-cross-building), the _ROOTFS\_DIR_ environment variable has to be set to the _crossrootfs_ location. The prereqs Docker images already have _crossrootfs_ built, so you only need to specify it when creating the Docker container by means of the `-e` flag. These locations are specified in the [Docker Images table](/docs/workflow/building/coreclr/linux-instructions.md#docker-images). +As mentioned in the [Linux Cross-Building section](#linux-cross-building), the `ROOTFS_DIR` environment variable has to be set to the _crossrootfs_ location. The prereqs Docker images already have _crossrootfs_ built, so you only need to specify it when creating the Docker container by means of the `-e` flag. These locations are specified in the [Docker Images table](/docs/workflow/building/coreclr/linux-instructions.md#docker-images). In addition, you also have to specify the `--cross` flag with the target architecture. For example, the following command would create a container to build CoreCLR for Linux ARM64: ```bash -docker run --rm -v :/runtime -w /runtime -e ROOTFS_DIR=/crossrootfs/arm64 mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-18.04-cross-arm64-20220427171722-6e40d49 ./build.sh --subset clr --cross --arch arm64 --clang9 +docker run --rm \ + -v :/runtime \ + -w /runtime \ + -e ROOTFS_DIR=/crossrootfs/arm64 \ + mcr.microsoft.com/dotnet-buildtools/prereqs:cbl-mariner-2.0-cross-arm64 \ + ./build.sh --subset clr --cross --arch arm64 ``` ### Cross-Compiling for FreeBSD with Docker @@ -159,5 +164,10 @@ docker run --rm -v :/runtime -w /runtime -e ROOTFS_DIR=/cross Using Docker to cross-build for FreeBSD is very similar to any other Docker Linux build. You only need to use the appropriate image and pass `--os` as well to specify this is not an architecture(-only) build. For example, to make a FreeBSD x64 build: ```bash -docker run --rm -v :/runtime -w /runtime -e ROOTFS_DIR=/crossrootfs/x64 mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-18.04-cross-freebsd-12-20220831130538-f13d79e ./build.sh --subset clr --cross --os freebsd +docker run --rm \ + -v :/runtime \ + -w /runtime \ + -e ROOTFS_DIR=/crossrootfs/x64 \ + mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-18.04-cross-freebsd-12 \ + ./build.sh --subset clr --cross --os freebsd ``` diff --git a/docs/workflow/building/coreclr/linux-instructions.md b/docs/workflow/building/coreclr/linux-instructions.md index de38b5514d1c5c..f5dd0693b83b2d 100644 --- a/docs/workflow/building/coreclr/linux-instructions.md +++ b/docs/workflow/building/coreclr/linux-instructions.md @@ -30,7 +30,11 @@ Please note that choosing the same image as the host OS you are running on will Once you have chosen an image, the build is one command run from the root of the runtime repository: ```bash -docker run --rm -v :/runtime -w /runtime mcr.microsoft.com/dotnet-buildtools/prereqs:centos-7-20210714125435-9b5bbc2 ./build.sh --subset clr +docker run --rm \ + -v :/runtime \ + -w /runtime \ + mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-22.04 \ + ./build.sh --subset clr ``` Dissecting the command: @@ -42,21 +46,27 @@ Dissecting the command: * `./build.sh`: Command to be run in the container: run the root build command. * `-subset clr`: Build the clr subset (excluding libraries and installers). -To do cross-building for ARM32 or ARM64 using Docker, you need to use either specific images designated for this purpose, or configure your own. Detailed information on this can be found in the [cross-building doc](/docs/workflow/building/coreclr/cross-building.md#cross-building-using-docker). +To do cross-building using Docker, you need to use either specific images designated for this purpose, or configure your own. Detailed information on this can be found in the [cross-building doc](/docs/workflow/building/coreclr/cross-building.md#cross-building-using-docker). Note that the official build images are all cross-build images, even when targeting the same architecture as the host image. This is because they target versions of glibc or musl libc that are included in the cross-build rootfs, and not the host OS. ### Docker Images -This table of images might often become stale as we change our images as our requirements change. The images used for our official builds can be found in [the pipeline resources](/eng/pipelines/common/templates/pipeline-with-resources.yml) of our Azure DevOps builds under the `container` key of the platform you plan to build. - -| OS | Target Arch | Image location | crossrootfs location | Clang Version | -| --------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------- | -------------------- | ------------- | -| Alpine | x64 | `mcr.microsoft.com/dotnet-buildtools/prereqs:alpine-3.13-WithNode-20210910135845-c401c85` | - | -clang5.0 | -| CentOS 7 (build for RHEL 7) | x64 | `mcr.microsoft.com/dotnet-buildtools/prereqs:centos-7-20210714125435-9b5bbc2` | - | -clang9 | -| Ubuntu 18.04 (x64, arm ROOTFS) | arm32 (armhf) | `mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-18.04-cross-20220426130400-6e40d49` | `/crossrootfs/arm` | -clang9 | -| Ubuntu 18.04 (x64, arm64 ROOTFS) | arm64 (arm64v8) | `mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-18.04-cross-arm64-20220427171722-6e40d49` | `/crossrootfs/arm64` | -clang9 | -| Alpine (x64, arm ROOTFS) | arm | `mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-16.04-cross-arm-alpine-20210923140502-78f7860` | `/crossrootfs/arm64` | -clang9 | -| Alpine (x64, arm64 ROOTFS) | arm64 (arm64v8) | `mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-16.04-cross-arm64-alpine-20210923140502-78f7860` | `/crossrootfs/arm64` | -clang9 | -| FreeBSD (x64 ROOTFS) | x64 | `mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-18.04-cross-freebsd-12-20210917001307-f13d79e` | `/crossrootfs/x64` | (default) | +This table of images might often become stale as we change our images as our requirements change. The images used for our official builds can be found in [the pipeline resources](/eng/pipelines/common/templates/pipeline-with-resources.yml) of our Azure DevOps builds under the `container` key of the platform you plan to build. These image tags don't include version numbers, and our build infrastructure will automatically use the latest version of the image. You can ensure you are using the latest version by using `docker pull`, for example: + +``` +docker pull mcr.microsoft.com/dotnet-buildtools/prereqs:cbl-mariner-2.0-cross-arm64 +``` + +All official builds are cross-builds with a rootfs for the target OS, and will use the clang version available on the container. + +| Host OS | Target OS | Target Arch | Image location | crossrootfs location | +| --------------------- | ------------ | --------------- | -------------------------------------------------------------------------------- | -------------------- | +| CBL-mariner 2.0 (x64) | Alpine 3.13 | x64 | `mcr.microsoft.com/dotnet-buildtools/prereqs:cbl-mariner-2.0-cross-amd64-alpine` | `/crossrootfs/x64` | +| CBL-mariner 2.0 (x64) | Ubuntu 16.04 | x64 | `mcr.microsoft.com/dotnet-buildtools/prereqs:cbl-mariner-2.0-cross-amd64` | `/crossrootfs/x64` | +| CBL-mariner 2.0 (x64) | Alpine | arm32 (armhf) | `mcr.microsoft.com/dotnet-buildtools/prereqs:cbl-mariner-2.0-cross-arm-alpine` | `/crossrootfs/arm` | +| CBL-mariner 2.0 (x64) | Ubuntu 16.04 | arm32 (armhf) | `mcr.microsoft.com/dotnet-buildtools/prereqs:cbl-mariner-2.0-cross-arm` | `/crossrootfs/arm` | +| CBL-mariner 2.0 (x64) | Alpine | arm64 (arm64v8) | `mcr.microsoft.com/dotnet-buildtools/prereqs:cbl-mariner-2.0-cross-arm64-alpine` | `/crossrootfs/arm64` | +| CBL-mariner 2.0 (x64) | Ubuntu 16.04 | arm64 (arm64v8) | `mcr.microsoft.com/dotnet-buildtools/prereqs:cbl-mariner-2.0-cross-arm64` | `/crossrootfs/arm64` | +| Ubuntu 18.04 (x64) | FreeBSD | x64 | `mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-18.04-cross-freebsd-12` | `/crossrootfs/x64` | These Docker images are built using the Dockerfiles maintained in the [dotnet-buildtools-prereqs-docker repo](https://github.com/dotnet/dotnet-buildtools-prereqs-docker).