diff --git a/docs/BuildingLLVM.md b/docs/BuildingLLVM.md index 3a918a41..79249df5 100644 --- a/docs/BuildingLLVM.md +++ b/docs/BuildingLLVM.md @@ -3,88 +3,67 @@ This document explains how to build LLVM and Clang from source code. It's a process only recommended for developers that need to make changes to LLVM or Clang, or -build the binary packages needed for the CI system. +build the binary packages needed for the CI system. If you just want to build CppSharp, then +check out the getting started guide section on how to download our pre-compiled LLVM packages. -Git repository URLs found here: [http://llvm.org/docs/GettingStarted.html#git-mirror] -(http://llvm.org/docs/GettingStarted.html#git-mirror) +## Compiling using the build script -1. Clone LLVM to `\deps\llvm` -2. Clone Clang to `\deps\llvm\tools\clang` +This is the preferred way to compile LLVM for usage by CppSharp. -Required LLVM/Clang commits: +1. Before building, ensure Git, CMake and Ninja are installed and acessible from the command line. -[LLVM: see /build/LLVM-commit.](https://github.com/mono/CppSharp/tree/master/build/LLVM-commit) - -[Clang: see /build/Clang-commit.](https://github.com/mono/CppSharp/tree/master/build/Clang-commit) +Check the official download pages for each project for further instructions: -## Compiling on Windows/Visual Studio +- [Git](https://git-scm.com/downloads) +- [Ninja](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages) +- [CMake](https://cmake.org/download/) -```shell -cd \deps\llvm\build - -cmake -G "Visual Studio 12" -DCLANG_BUILD_EXAMPLES=false -DCLANG_INCLUDE_DOCS=false -DCLANG_INCLUDE_TESTS=false -DCLANG_INCLUDE_DOCS=false -DCLANG_BUILD_EXAMPLES=false -DLLVM_TARGETS_TO_BUILD="X86" -DLLVM_INCLUDE_EXAMPLES=false -DLLVM_INCLUDE_DOCS=false -DLLVM_INCLUDE_TESTS=false .. - -msbuild LLVM.sln /p:Configuration=RelWithDebInfo;Platform=Win32 /m +2. Navigate to the `/build` directory +3. Clone, build and package LLVM with ``` - -Or, if you need 64-bit binaries: - -```shell -cd \deps\llvm\build - -cmake -G "Visual Studio 12 Win64" -DCLANG_BUILD_EXAMPLES=false -DCLANG_INCLUDE_DOCS=false -DCLANG_INCLUDE_TESTS=false -DCLANG_INCLUDE_DOCS=false -DCLANG_BUILD_EXAMPLES=false -DLLVM_TARGETS_TO_BUILD="X86" -DLLVM_INCLUDE_EXAMPLES=false -DLLVM_INCLUDE_DOCS=false -DLLVM_INCLUDE_TESTS=false .. - -msbuild LLVM.sln /p:Configuration=RelWithDebInfo;Platform=x64 /m +$PREMAKE --file=scripts/LLVM.lua clone_llvm +$PREMAKE --file=scripts/LLVM.lua build_llvm +$PREMAKE --file=scripts/LLVM.lua package_llvm ``` -## Compiling on Mac OS X +`$PREMAKE` should be replaced with `premake5.exe`, `premake5-osx` or `premake5-linux-64` depending on environment. -### Compiling manually +You can specify an `--arch=x86` or `--arch=x64` flag to the invocations above to specify an explicit build architecture. -1. Compile LLVM solution in *RelWithDebInfo* mode - The following CMake variables should be enabled: - - LLVM_ENABLE_LIBCXX (enables libc++ standard library support) - - LLVM_BUILD_32_BITS for 32-bit builds (defaults to 64-bit) +If the `clone_llvm` step fails, you can try to manually clone LLVM and Clang as explained below. +You should still run clone_llvm to ensure that you are on the correct revision. -```shell -mkdir -p deps/llvm/build && cd deps/llvm/build +## Cloning from Git -cmake -G "Unix Makefiles" -DLLVM_ENABLE_LIBCXX=true -DLLVM_BUILD_32_BITS=true -DCMAKE_BUILD_TYPE=RelWithDebInfo .. +1. Clone LLVM to `\deps\llvm` -make +``` +git clone http://llvm.org/git/llvm.git ``` -### Compiling using the build script - -Before building, ensure cmake is installed under Applications/Cmake.app and Ninja is installed in your PATH. +2. Clone Clang to `\deps\llvm\tools\clang` -1. Navigate to `build/scripts` -2. Clone, build and package LLVM with ``` -../premake5-osx --file=LLVM.lua clone_llvm -../premake5-osx --file=LLVM.lua build_llvm -../premake5-osx --file=LLVM.lua package_llvm +cd llvm/tools +git clone http://llvm.org/git/clang.git ``` -You can specify an `--arch=x86` or `--arch=x64` flag to the invocations above to specify an explicit build architecture. +Official LLVM instructions can be found here: [http://llvm.org/docs/GettingStarted.html#git-mirror] +(http://llvm.org/docs/GettingStarted.html#git-mirror) -If the clone_llvm step fails, you can try to manually clone LLVM and Clang as explained above. You should still run clone_llvm to ensure that you are on the correct revision. +Make sure to use the revisions specified below, or you will most likely get compilation errors. +Required LLVM/Clang commits: -## Compiling on Linux +[LLVM: see /build/LLVM-commit.](https://github.com/mono/CppSharp/tree/master/build/LLVM-commit) +[Clang: see /build/Clang-commit.](https://github.com/mono/CppSharp/tree/master/build/Clang-commit) -If you do not have native build tools you can install them first with: +To change to the revisions specified above you can run the following commands: -```shell -sudo apt-get install cmake ninja-build build-essential +``` +git -C deps/llvm reset --hard +git -C deps/llvm/tools/clang reset --hard ``` -And then build LLVM with: - -```shell -cd deps/llvm/build -cmake -G Ninja -DCLANG_BUILD_EXAMPLES=false -DCLANG_INCLUDE_DOCS=false -DCLANG_INCLUDE_TESTS=false -DCLANG_INCLUDE_DOCS=false -DCLANG_BUILD_EXAMPLES=false -DLLVM_TARGETS_TO_BUILD="X86" -DLLVM_INCLUDE_EXAMPLES=false -DLLVM_INCLUDE_DOCS=false -DLLVM_INCLUDE_TESTS=false .. -ninja -``` diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index 5daa953e..8d012a6f 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -36,7 +36,8 @@ premake5-osx --file=scripts/LLVM.lua download_llvm # on OSX premake5-linux-64 --file=scripts/LLVM.lua download_llvm # on Linux ``` -Alternatively, if on Windows, just double click on `/build/DownloadDeps.bat`. +Alternatively, if on Windows, just run `/build/DownloadDeps.bat` from a Visual Studio command prompt +corresponding to the VS version you want to use. After this, you should end up with one or multiple `/build/scripts/llvm---` folders containing the headers and libraries for LLVM. @@ -50,64 +51,66 @@ Please check the guide in [Compiling LLVM and Clang from source](BuildingLLVM.md ## Compiling on Windows/Visual Studio +1. Generate the VS solution and project files + ```shell cd \build - GenerateProjects.bat -msbuild vs2013\CppSharp.sln /p:Configuration=Release;Platform=x86 ``` -Building in *Release* is recommended because else the Clang parser will be -excruciatingly slow. +2. Compile the project -It has been reported that running the solution upgrade process under VS 2013 breaks the build due -to an incompatibility of .NET versions between projects (4.5 and 4.0). If you experience this -problem you can change the targetted .NET version of the projects to be the same or just do not -run the upgrade process after generation. +You can open `CppSharp.sln` and hit F5 or compile via the command line: -## Compiling on Mac OS X +``` +msbuild vs2017\CppSharp.sln /p:Configuration=Release;Platform=x86 +``` -1. Run `./premake5-osx gmake` in `\build` -2. Build the generated makefiles: - - 32-bit builds: `config=release_x86 make -C gmake` - - 64-bit builds: `config=release_x64 make -C gmake` +Building in *Release* is recommended because else we will use the Clang parser +debug configuration, which will be too slow for practical use beyond debugging. -The version you compile needs to match the version of the Mono VM installed on your -system which you can find by running `mono --version`. The reason for this is because -a 32-bit VM will only be able to load 32-bit shared libraries and vice-versa for 64-bits. +## Compiling on macOS or Linux -## Compiling on Linux +1. Change directory to `\build` +2. Run `./Compile.sh` to generate the project files and compile the code. -Only 64-bits builds are supported at the moment. +If the above script fails, you can try these equivalent manual steps: -We depend on a somewhat recent version of Mono (.NET 4.5). -Ubuntu 14.04 contains recent enough Mono by default, which you can install with: +1. Generate the Makefiles -```shell -sudo apt-get install mono-devel +``` +./premake5-osx gmake # if on OSX +./premake5-linux-64 gmake # if on Linux ``` -If you are using another distribution then please look into the [download page](http://www.mono-project.com/download/#download-lin) on the Mono website. - -Generate the makefiles, and build CppSharp: +2. Build the generated makefiles: + - 32-bit builds: `make -C gmake config=release_x86` + - 64-bit builds: `make -C gmake config=release_x64` -```shell -cd /build -./premake5-linux-64 gmake -make -C gmake config=release_x64 -``` +The version you compile needs to match the version of the Mono VM installed on your +system which you can find by running `mono --version`. The reason for this is because +a 32-bit VM will only be able to load 32-bit shared libraries and vice-versa for 64-bits. If you need more verbosity from the builds invoke `make` as: ```shell -verbose=true make -C gmake config=release_x64 +make -C gmake config=release_x64 verbose=true ``` -If you get the following error, please see [issue #625](https://github.com/mono/CppSharp/issues/625#issuecomment-189283549): +## Running the testsuite -``` -/usr/include/wchar.h(39,11): fatal: 'stdarg.h' file not found CppSharp has encountered an error while parsing code. -``` +1. Change directory to `\build` +2. Run `./InstallNugets.sh` to install the NUnit test runner from Nuget. +3. Run `./RunTests.sh` to run the tests. + +## Linux notes + +Only 64-bits builds are supported. + +We depend on a recent version of Mono. + +Please look into the [download page](http://www.mono-project.com/download/#download-lin) on the +Mono website for official install instructions. # Generating bindings