Skip to content

Update the Coreclr docs #83

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jashook merged 2 commits into from
Nov 18, 2019
Merged

Update the Coreclr docs #83

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8ab9a5c
coreclr docs overhaul
Nov 18, 2019
1c80c92
Address feedback
Nov 18, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/coreclr/building/android.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ To compile for arm64, run:
CONFIG_DIR=`realpath cross/android/arm64` ROOTFS_DIR=`realpath cross/android-rootfs/toolchain/arm64/sysroot` ./build.sh cross arm64 skipgenerateversion skipmscorlib cmakeargs -DENABLE_LLDBPLUGIN=0
```

The resulting binaries will be found in `artifacts/Product/Linux.BuildArch.BuildType/`
The resulting binaries will be found in `artifacts/bin/coreclr/Linux.BuildArch.BuildType/`

Running the PAL tests on Android
--------------------------------
Expand All @@ -42,7 +42,7 @@ You can run the PAL tests on an Android device. To run the tests, you first copy

To copy the PAL tests over to an Android phone:
```
adb push artifacts/obj/Linux.arm64.Debug/src/pal/tests/palsuite/ /data/local/tmp/coreclr/src/pal/tests/palsuite
adb push artifacts/obj/coreclr/Linux.arm64.Debug/src/pal/tests/palsuite/ /data/local/tmp/coreclr/src/pal/tests/palsuite
adb push cross/android/toolchain/arm64/sysroot/usr/lib/libintl.so /data/local/tmp/coreclr/lib
adb push cross/android/toolchain/arm64/sysroot/usr/lib/libandroid-support.so /data/local/tmp/coreclr/lib/
adb push cross/android/toolchain/arm64/sysroot/usr/lib/libandroid-glob.so /data/local/tmp/coreclr/lib/
Expand Down
97 changes: 15 additions & 82 deletions docs/coreclr/building/cross-building.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,28 +13,28 @@ Cross compiling CoreCLR

Build using "-arm" as the architecture. For example:

C:\coreclr> build.cmd -arm -debug
C:\runtime> build.cmd -arm -debug


Cross Compilation for ARM, ARM64 or x86 on Linux
================================================

Through cross compilation, on Linux it is possible to build CoreCLR for arm or arm64.
Through cross compilation, on Linux it is possible to build CoreCLR for arm or arm64. Note that this documentation exists to explain using `runtime/eng/common/build-rootfs.sh`. This will build a rootfs and then use it to cross build. Newer documentation [linux-instructions.md](linux-instructions.md) exists which leverages docker to use a prebuilt environment to cross build.

Requirements for targetting Debian based distros
------------------------------------------------

You need a Debian based host and the following packages need to be installed:

ben@ubuntu ~/git/coreclr/ $ sudo apt-get install qemu qemu-user-static binfmt-support debootstrap
~/runtime/ $ sudo apt-get install qemu qemu-user-static binfmt-support debootstrap

In addition, to cross compile CoreCLR the binutils for the target are required. So for arm you need:

ben@ubuntu ~/git/coreclr/ $ sudo apt-get install binutils-arm-linux-gnueabihf
~/runtime/ $ sudo apt-get install binutils-arm-linux-gnueabihf

and conversely for arm64:

ben@ubuntu ~/git/coreclr/ $ sudo apt-get install binutils-aarch64-linux-gnu
~/runtime/ $ sudo apt-get install binutils-aarch64-linux-gnu


Requirements for targetting ARM or ARM64 Alpine Linux
Expand Down Expand Up @@ -66,62 +66,36 @@ The `build-rootfs.sh` script must be run as root as it has to make some symlinks

For example, to generate an arm rootfs:

ben@ubuntu ~/git/coreclr/ $ sudo ./eng/common/cross/build-rootfs.sh arm
~/runtime/ $ sudo ./eng/common/cross/build-rootfs.sh arm

You can choose Linux code name to match your target, give `vivid` for `Ubuntu 15.04`, `wily` for `Ubuntu 15.10`. The default is `trusty`, version `Ubuntu 14.04`.

ben@ubuntu ~/git/coreclr/ $ sudo ./eng/common/cross/build-rootfs.sh arm wily
~/runtime/ $ sudo ./eng/common/cross/build-rootfs.sh arm wily

and if you wanted to generate the rootfs elsewhere:

ben@ubuntu ~/git/coreclr/ $ sudo ROOTFS_DIR=/home/ben/coreclr-cross/arm ./eng/common/cross/build-rootfs.sh arm
~/runtime/ $ sudo ROOTFS_DIR=/home/cross/arm ./eng/common/cross/build-rootfs.sh arm

For example, to generate an armel rootfs:

hqu@ubuntu ~/git/coreclr/ $ sudo ./eng/common/cross/build-rootfs.sh armel
~/runtime/ $ sudo ./eng/common/cross/build-rootfs.sh armel

You can choose code name to match your target, give `jessie` for `Debian`, `tizen` for `Tizen`. The default is `jessie`.

hque@ubuntu ~/git/coreclr/ $ sudo ./eng/common/cross/build-rootfs.sh armel tizen
~/runtime/ $ sudo ./eng/common/cross/build-rootfs.sh armel tizen

and if you wanted to generate the rootfs elsewhere:

hque@ubuntu ~/git/coreclr/ $ sudo ROOTFS_DIR=/home/ben/coreclr-cross/armel ./eng/common/cross/build-rootfs.sh armel tizen
~/runtime/ $ sudo ROOTFS_DIR=/home/armel ./eng/common/cross/build-rootfs.sh armel tizen


Cross compiling CoreCLR
-----------------------
Once the rootfs has been generated, it will be possible to cross compile CoreCLR. If `ROOTFS_DIR` was set when generating the rootfs, then it must also be set when running `build.sh`.
`ROOTFS_DIR` must be set when running `build.sh`.

So, without `ROOTFS_DIR`:
~/runtime/ $ ROOTFS_DIR=/home/arm ./build.sh arm debug verbose cross

ben@ubuntu ~/git/coreclr/ $ ./build.sh arm debug verbose cross

And with:

ben@ubuntu ~/git/coreclr/ $ ROOTFS_DIR=/home/ben/coreclr-cross/arm ./build.sh arm debug verbose cross

As usual, the resulting binaries will be found in `artifacts/Product/BuildOS.BuildArch.BuildType/`


Compiling System.Private.CoreLib for ARM Linux
==============================================

It is also possible to use a Windows and a Linux machine to build the managed components of CoreCLR for ARM Linux. This can be useful when the build on the target platform fails, for example due to Mono issues.

Build System.Private.CoreLib on Windows
---------------------------------------
The following instructions assume you are on a Windows machine with a clone of the CoreCLR repo that has a correctly configured [environment](https://github.com/dotnet/coreclr/wiki/Windows-instructions#environment).

To build System.Private.CoreLib for Linux, run the following command:

```
D:\git\coreclr> build.cmd linuxmscorlib arm
```

The arguments `freebsdmscorlib` and `osxmscorlib` can be used instead to build System.Private.CoreLib for FreeBSD or OS X.

The output is at bin\Product\<BuildOS>.arm.Debug\System.Private.CoreLib.dll.
As usual, the resulting binaries will be found in `artifacts/bin/coreclr/BuildOS.BuildArch.BuildType/`


Build System.Private.CoreLib on Ubuntu
Expand All @@ -140,45 +114,4 @@ The output is at artifacts/Product/<BuildOS>.arm.Debug/System.Private.CoreLib.dl
lgs@ubuntu ~/git/coreclr/ $ file ./artifacts/Product/Linux.arm.Debug/System.Private.CoreLib.dll
./artifacts/Product/Linux.arm.Debug/System.Private.CoreLib.dll: PE32 executable (DLL)
(console) ARMv7 Thumb Mono/.NET assembly, for MS Windows
```

Building coreclr for Linux ARM Emulator
=======================================

It is possible to build coreclr binaries (native and System.Private.CoreLib.dll) and run coreclr unit tests on the Linux ARM Emulator (latest version provided here: [#3805](https://github.com/dotnet/coreclr/issues/3805)).
The `tests/scripts/arm32_ci_script.sh` script does this.

The following instructions assume that:
* You have set up the extracted emulator at `/opt/linux-arm-emulator` (such that `/opt/linux-arm-emulator/platform/rootfs-t30.ext4` exists)
The emulator rootfs is of 4GB size by default. But to enable testing of coreclr binaries on the emulator, you need to resize the rootfs (to atleast 7GB) using the instructions given in the `doc/RESIZE-IMAGE.txt` file of the extracted emulator.
* The mount path for the emulator rootfs is `/opt/linux-arm-emulator-root` (change this path if you have a working directory at this path).

All the following instructions are for the Release mode. Change the commands and files accordingly for the Debug mode.

To just build libcoreclr and System.Private.CoreLib for the Linux ARM Emulator, run the following command:
```
prajwal@ubuntu ~/coreclr $ ./tests/scripts/arm32_ci_script.sh \
--emulatorPath=/opt/linux-arm-emulator \
--mountPath=/opt/linux-arm-emulator-root \
--buildConfig=Release \
--skipTests
```

The Linux ARM Emulator is based on soft floating point and thus the native binaries in coreclr are built for the armel architecture. The coreclr binaries generated by the above command (native and System.Private.CoreLib) can be found at `~/coreclr/artifacts/Product/Linux.armel.Release`.

To build libcoreclr and System.Private.CoreLib, and run selected coreclr unit tests on the emulator, do the following:
* Download the latest Coreclr unit test binaries (or build on Windows) from here: [Debug](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_windows_nt_bld/lastSuccessfulBuild/artifact/artifacts/tests/tests.zip) and [Release](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_windows_nt_bld/lastSuccessfulBuild/artifact/artifacts/tests/tests.zip).
Setup the binaries at `~/coreclr/artifacts/tests/Windows_NT.x64.Release`.
* Build corefx binaries for the Emulator as given [here](https://github.com/dotnet/corefx/blob/master/Documentation/building/cross-building.md#building-corefx-for-linux-arm-emulator).
Setup these binaries at `~/corefx/artifacts/Linux.arm-softfp.Release`, `~/corefx/artifacts/Linux.AnyCPU.Release`, `~/corefx/artifacts/Unix.AnyCPU.Release`, and `~/corefx/artifacts/AnyOS.AnyCPU.Release`.
* Run the following command (change value of `--testDirFile` argument to the file containing your selection of tests):
```
prajwal@ubuntu ~/coreclr $ ./tests/scripts/arm32_ci_script.sh \
--emulatorPath=/opt/linux-arm-emulator \
--mountPath=/opt/linux-arm-emulator-root \
--buildConfig=Release \
--testRootDir=~/coreclr/artifacts/tests/Windows_NT.x64.Release \
--coreFxNativeBinDir=~/corefx/artifacts/Linux.arm-softfp.Release \
--coreFxBinDir="~/corefx/artifacts/Linux.AnyCPU.Release;~/corefx/artifacts/Unix.AnyCPU.Release;~/corefx/artifacts/AnyOS.AnyCPU.Release" \
--testDirFile=~/coreclr/tests/testsRunningInsideARM.txt
```
```
20 changes: 10 additions & 10 deletions docs/coreclr/building/linux-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Please note that when choosing an image choosing the same image as the host os y
Once you have chosen an image the build is one command run from the root of the coreclr repository:

```sh
docker run --rm -v /home/dotnet-bot/coreclr:/coreclr -w /coreclr mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-16.04-c103199-20180628134544 ./build.sh
docker run --rm -v ~/runtime:/runtime -w /runtime mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-16.04-c103199-20180628134544 ./src/coreclr/build.sh
```

Dissecting the command:
Expand All @@ -32,15 +32,15 @@ Dissecting the command:

`mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-16.04-c103199-20180628134544: image name`

`./build.sh: command to be run in the container`
`./src/coreclr/build.sh: command to be run in the container`

If you are attempting to cross build for arm/arm64 then use the crossrootfs location to set the ROOTFS_DIR. The command would add `-e ROOTFS_DIR=<crossrootfs location>`. See [Docker Images](#Docker-Images) for the crossrootfs location. In addition you will need to specify `cross`.

```sh
docker run --rm -v /home/dotnet-bot/coreclr:/coreclr -w /coreclr -e ROOTFS_DIR=/crossrootfs/arm64 mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-16.04-cross-arm64-a3ae44b-20180315221921 ./build.sh arm64 cross
docker run --rm -v ~/runtime:/runtime -w /runtime -e ROOTFS_DIR=/crossrootfs/arm64 mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-16.04-cross-arm64-a3ae44b-20180315221921 ./src/coreclr/build.sh arm64 cross
```

Note that instructions on building the crossrootfs location can be found at https://github.com/dotnet/coreclr/blob/master/Documentation/building/cross-building.md. These instructions are suggested only if there are plans to change the rootfs, or the Docker images for arm/arm64 are insufficient for you build.
Note that instructions on building the crossrootfs location can be found at [cross-building.md](cross-building.md). These instructions are suggested only if there are plans to change the rootfs, or the Docker images for arm/arm64 are insufficient for you build.

Docker Images
=============
Expand Down Expand Up @@ -131,10 +131,10 @@ Build the Runtime and Microsoft Core Library
To build the runtime on Linux, run build.sh from the root of the coreclr repository:

```
./build.sh
./src/coreclr/build.sh
```

After the build is completed, there should some files placed in `artifacts/Product/Linux.x64.Debug`. The ones we are interested in are:
After the build is completed, there should some files placed in `runtime/artifacts/bin/coreclr/Linux.x64.Debug`. The ones we are interested in are:

* `corerun`: The command line host. This program loads and starts the CoreCLR runtime and passes the managed program you want to run to it.
* `libcoreclr.so`: The CoreCLR runtime itself.
Expand All @@ -146,17 +146,17 @@ Create the Core_Root
The Core_Root folder will have the built binaries, from `build.sh` and it will also include the CoreFX packages required to run tests.

```
./build-test.sh generatelayoutonly
./src/coreclr/build-test.sh generatelayoutonly
```

After the build is complete you will be able to find the output in the `artifacts/tests/Linux.x64.Debug/Tests/Core_Root` folder.
After the build is complete you will be able to find the output in the `artifacts/tests/coreclr/Linux.x64.Debug/Tests/Core_Root` folder.

Running a single test
===================

After `build-test.sh` is run, corerun from the Core_Root folder is ready to be run. This can be done by using the full absolute path to corerun, or by setting an environment variable to the Core_Root folder.
After `src/coreclr/build-test.sh` is run, corerun from the Core_Root folder is ready to be run. This can be done by using the full absolute path to corerun, or by setting an environment variable to the Core_Root folder.

```sh
export CORE_ROOT=/home/dotnet-bot/coreclr/artifacts/tests/Linux.x64.Debug/Tests/Core_Root
export CORE_ROOT=~/runtime/artifacts/tests/coreclr/Linux.x64.Debug/Tests/Core_Root
$CORE_ROOT/corerun hello_world.dll
```
20 changes: 9 additions & 11 deletions docs/coreclr/building/osx-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,10 @@ Git Setup
Clone the CoreCLR and CoreFX repositories (either upstream or a fork).

```sh
git clone https://github.com/dotnet/coreclr
# Cloning into 'coreclr'...
git clone https://github.com/dotnet/runtime
# Cloning into 'runtime'...
```

This guide assumes that you've cloned the coreclr and corefx repositories into `~/git/coreclr` and `~/git/corefx` on your OS X machine. If your setup is different, you'll need to pay careful attention to the commands you run. In this guide, I'll always show what directory I'm in.

CMake
-----

Expand All @@ -48,10 +46,10 @@ Build the Runtime and Microsoft Core Library
To Build CoreCLR, run build.sh from the root of the coreclr repo.

```sh
./build.sh
./src/coreclr/build.sh
```

After the build has completed, there should some files placed in `artifacts/Product/OSX.x64.Debug`. The ones we are interested in are:
After the build has completed, there should some files placed in `artifacts/bin/coreclr/OSX.x64.Debug`. The ones we are interested in are:

- `corerun`: The command line host. This program loads and starts the CoreCLR runtime and passes the managed program you want to run to it.
- `libcoreclr.dylib`: The CoreCLR runtime itself.
Expand All @@ -60,21 +58,21 @@ After the build has completed, there should some files placed in `artifacts/Prod
Create the Core_Root
===================

The Core_Root folder will have the built binaries, from `build.sh` and it will also include the CoreFX packages required to run tests.
The Core_Root folder will have the built binaries, from `src/coreclr/build.sh` and it will also include the CoreFX packages required to run tests.

```
./build-test.sh generatelayoutonly
./src/coreclr/build-test.sh generatelayoutonly
```

After the build is complete you will be able to find the output in the `artifacts/tests/OSX.x64.Debug/Tests/Core_Root` folder.
After the build is complete you will be able to find the output in the `artifacts/tests/coreclr/OSX.x64.Debug/Tests/Core_Root` folder.

Running a single test
===================

After `build-test.sh` is run, corerun from the Core_Root folder is ready to be run. This can be done by using the full absolute path to corerun, or by setting
After `src/coreclr/build-test.sh` is run, corerun from the Core_Root folder is ready to be run. This can be done by using the full absolute path to corerun, or by setting
an environment variable to the Core_Root folder.

```sh
export CORE_ROOT=/path/to/coreclr/artifacts/tests/OSX.x64.Debug/Tests/Core_Root
export CORE_ROOT=/path/to/runtime/artifacts/tests/coreclr/OSX.x64.Debug/Tests/Core_Root
$CORE_ROOT/corerun hello_world.dll
```
Loading