diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/building/freebsd-instructions.md | 93 |
1 files changed, 54 insertions, 39 deletions
diff --git a/Documentation/building/freebsd-instructions.md b/Documentation/building/freebsd-instructions.md index 045e7c829a..ae36d3c9ff 100644 --- a/Documentation/building/freebsd-instructions.md +++ b/Documentation/building/freebsd-instructions.md @@ -19,43 +19,36 @@ Install the following packages for the toolchain: - bash - cmake -- llvm35 (should be installed automatically as dependency of clang35) -- clang35 +- llvm37 (includes LLVM 3.7, Clang 3.7 and LLDB 3.7) - libunwind - gettext -Note: LLDB is not yet available in the pkg repository on FreeBSD. The LLDB plugin is currently not being build on FreeBSD. Instructions for this will be added later. - To install the packages you need: -`janhenke@freebsd-frankfurt:~ % sudo pkg install bash cmake clang35 libunwind gettext` +```sh +janhenke@freebsd-frankfurt:~ % sudo pkg install bash cmake libunwind gettext llvm37 +``` -You now have all the required components. +The command above will install Clang and LLVM 3.7. For information on building CoreCLR with other versions, see section on [Clang/LLVM versions](#note-on-clangllvm-versions). Debugging CoreCLR (Optional) ---------------------------- -Note: This step is *optional* and is not required to build CoreCLR itself. If you intend on hacking or debugging the CoreCLR source code, you need to follow these steps. You must follow these steps *before* starting the build itself. - -In order to debug CoreCLR you will also need to install LLDB, the LLVM debugger. LLDB is still in the process of being ported to FreeBSD, so no official packages exist (see the FreeBSD LLDB Wiki page for more information on what has been ported so far: https://wiki.freebsd.org/lldb). However, it is possible to manually download and install LLDB from the LLVM source tree by following the instructions below: - -Firstly, install the following packages: python ninja swig13 git (in addition to the packages above), i.e. - -```janhenke@freebsd-frankfurt:~ % sudo pkg install python ninja swig13 git``` +Note: This step is not required to build CoreCLR itself. If you intend on hacking or debugging the CoreCLR source code, you need to follow these steps. You must follow these steps *before* starting the build itself. -Then, run the install script in ~/coreclr/src/pal/tools: +In order to debug CoreCLR you will also need to install [LLDB](http://lldb.llvm.org/), the LLVM debugger. -```janhenke@freebsd-frankfurt:~ % ~/coreclr/src/pal/tools/freebsd-install-lldb.sh``` - -Note: LLDB will run su in order to install the LLDB build to /usr/local/include. - -(Optional) If you wish to run sudo instead of su, you can change line 29-31 to: - -```sudo $NINJA lldb install``` +To build with clang 3.7 from coreclr project root: +```sh +LLDB_LIB_DIR=/usr/local/llvm37/lib LLDB_INCLUDE_DIR=/usr/local/llvm37/include ./build.sh clang3.7 debug +``` -You now have all the required components to debug CoreCLR installed. +Run tests: +```sh +./src/pal/tests/palsuite/runpaltests.sh $PWD/bin/obj/FreeBSD.x64.Debug $PWD/bin/paltestout +``` Git Setup --------- @@ -67,11 +60,11 @@ Build the Runtime To build the runtime on FreeBSD, run build.sh from the root of the coreclr repository: -``` +```sh janhenke@freebsd-frankfurt:~/git/coreclr % ./build.sh ``` -Note: FreeBSD 10.1-RELEASE system's Clang/LLVM is 3.4, the minimum version to compile CoreCLR runtime is 3.5. You may need to specify `./build.sh clang3.5` to find Clang 3.5. +Note: FreeBSD 10.1-RELEASE system's Clang/LLVM is 3.4, the minimum version to compile CoreCLR runtime is 3.5. See [Note on Clang/LLVM versions](#note-on-clangllvm-versions). After the build is completed, there should some files placed in `bin/Product/FreeBSD.x64.Debug`. The ones we are interested in are: @@ -81,7 +74,7 @@ After the build is completed, there should some files placed in `bin/Product/Fre In order to keep everything tidy, let's create a new directory for the runtime and copy the runtime and corerun into it. -``` +```sh janhenke@freebsd-frankfurt:~/git/coreclr % mkdir -p ~/coreclr-demo/runtime janhenke@freebsd-frankfurt:~/git/coreclr % cp bin/Product/FreeBSD.x64.Debug/corerun ~/coreclr-demo/runtime janhenke@freebsd-frankfurt:~/git/coreclr % cp bin/Product/FreeBSD.x64.Debug/libcoreclr*.so ~/coreclr-demo/runtime @@ -90,13 +83,14 @@ janhenke@freebsd-frankfurt:~/git/coreclr % cp bin/Product/FreeBSD.x64.Debug/libc Build the Framework Native Components ====================================== -``` +```sh janhenke@freebsd-frankfurt:~/git/corefx$ src/Native/build.sh janhenke@freebsd-frankfurt:~/git/corefx$ cp bin/FreeBSD.x64.Debug/Native/*.so ~/coreclr-demo/runtime ``` Build the Framework Managed Components ====================================== + We don't _yet_ have support for building managed code on FreeBSD, so you'll need a Windows machine with clones of both the CoreCLR and CoreFX projects. You will build `mscorlib.dll` out of the coreclr repository and the rest of the framework that out of the corefx repository. For mscorlib (from a regular command prompt window) run: @@ -133,7 +127,7 @@ The rest of the assemblies you need to run are presently just facades that point Create a folder for the packages: -``` +```sh janhenke@freebsd-frankfurt:~/git/coreclr % mkdir ~/coreclr-demo/packages janhenke@freebsd-frankfurt:~/git/coreclr % cd ~/coreclr-demo/packages ``` @@ -143,7 +137,7 @@ Install Mono If you don't already have Mono installed on your system, use the pkg tool again: -``` +```sh janhenke@freebsd-frankfurt:~/coreclr-demo/packages % sudo pkg install mono ``` @@ -152,7 +146,7 @@ Download the NuGet Client Grab NuGet (if you don't have it already) -``` +```sh janhenke@freebsd-frankfurt:~/coreclr-demo/packages % curl -L -O https://nuget.org/nuget.exe ``` Download NuGet Packages @@ -162,7 +156,7 @@ With Mono and NuGet in hand, you can use NuGet to get the required dependencies. Make a `packages.config` file with the following text. These are the required dependencies of this particular app. Different apps will have different dependencies and require a different `packages.config` - see [Issue #480](https://github.com/dotnet/coreclr/issues/480). -``` +```xml <?xml version="1.0" encoding="utf-8"?> <packages> <package id="System.Console" version="4.0.0-beta-22703" /> @@ -188,19 +182,19 @@ Make a `packages.config` file with the following text. These are the required de And restore your packages.config file: -``` +```sh janhenke@freebsd-frankfurt:~/coreclr-demo/packages % mono nuget.exe restore -Source https://www.myget.org/F/dotnet-corefx/ -PackagesDirectory . ``` NOTE: This assumes you already installed the default CA certs. If you have problems downloading the packages please see [Issue #602](https://github.com/dotnet/coreclr/issues/602#issuecomment-88203778). The command for FreeBSD is: -``` +```sh janhenke@freebsd-frankfurt:~/coreclr-demo/packages % mozroots --import --sync ``` Finally, you need to copy over the assemblies to the runtime folder. You don't want to copy over System.Console.dll or System.Diagnostics.Debug however, since the version from NuGet is the Windows version. The easiest way to do this is with a little find magic: -``` +```sh janhenke@freebsd-frankfurt:~/coreclr-demo/packages % find . -wholename '*/aspnetcore50/*.dll' -exec cp -n {} ~/coreclr-demo/runtime \; ``` @@ -209,14 +203,14 @@ Compile an App Now you need a Hello World application to run. You can write your own, if you'd like. Personally, I'm partial to the one on corefxlab which will draw Tux for us. -``` +```sh janhenke@freebsd-frankfurt:~/coreclr-demo/packages % cd ~/coreclr-demo/runtime janhenke@freebsd-frankfurt:~/coreclr-demo/runtime % curl -O https://raw.githubusercontent.com/dotnet/corefxlab/master/demos/CoreClrConsoleApplications/HelloWorld/HelloWorld.cs ``` Then you just need to build it, with `mcs`, the Mono C# compiler. FYI: The Roslyn C# compiler will soon be available on FreeBSD. Because you need to compile the app against the .NET Core surface area, you need to pass references to the contract assemblies you restored using NuGet: -``` +```sh janhenke@freebsd-frankfurt:~/coreclr-demo/runtime % mcs /nostdlib /noconfig /r:../packages/System.Console.4.0.0-beta-22703/lib/contract/System.Console.dll /r:../packages/System.Runtime.4.0.20-beta-22703/lib/contract/System.Runtime.dll HelloWorld.cs ``` @@ -225,7 +219,7 @@ Run your App You're ready to run Hello World! To do that, run corerun, passing the path to the managed exe, plus any arguments. The HelloWorld from corefxlab will print a daemon if you pass "freebsd" as an argument, so: -``` +```sh janhenke@freebsd-frankfurt:~/coreclr-demo/runtime % ./corerun HelloWorld.exe freebsd ``` @@ -242,10 +236,31 @@ Run the test suite If you've made changes to the CoreCLR PAL code, you might want to run the PAL tests directly to validate your changes. This can be done after a clean build, without any other dependencies. -```bash -janhenke@freebsd-frankfurt:~/coreclr % ./build.sh && src/pal/tests/palsuite/runpaltests.sh ~/coreclr/bin/obj/FreeBSD.x64.Debug ~/coreclr/bin/paltestout +From the coreclr project directory: + +```sh +janhenke@freebsd-frankfurt:~/coreclr % ./src/pal/tests/palsuite/runpaltests.sh ~/coreclr/bin/obj/FreeBSD.x64.Debug ~/coreclr/bin/paltestout ``` This should run all the tests associated with the PAL. -**Note:** For FreeBSD all PAL tests may not pass at this point. +Note on Clang/LLVM versions +=========================== + +The minimum version to build CoreCLR is Clang 3.5 or above. + +FreeBSD 10.X releases ship with Clang 3.4. + +If you intend on building CoreCLR with LLDB debug support, pick llvm37 or llvm-devel. + +To install clang 3.5: `sudo pkg install clang35` + +To install clang 3.6: `sudo pkg install clang36` + +To install clang 3.7: `sudo pkg install llvm37` + +To install clang development snapshot: `sudo pkg install llvm-devel` + +clang35 and clang36 download llvm35 and llvm36 packages as a dependency. + +llvm37 and llvm-devel include clang and lldb. Since clang is included with llvm 3.7 and onward, there is no clang37 package. |