Skip to content

Commit

Permalink
[docs] Update the getting started guide and LLVM compilation guide.
Browse files Browse the repository at this point in the history
  • Loading branch information
@tritao
tritao committed Aug 27, 2017
1 parent 6fa9778 commit bbd9ab8
Show file tree
Hide file tree
Showing 2 changed files with 74 additions and 92 deletions.
91 changes: 35 additions & 56 deletions docs/BuildingLLVM.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<CppSharp>\deps\llvm`
2. Clone Clang to `<CppSharp>\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 <CppSharp>\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 `<CppSharp>/build` directory
3. Clone, build and package LLVM with
```

Or, if you need 64-bit binaries:

```shell
cd <CppSharp>\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 `<CppSharp>\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 `<CppSharp>\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 <llvm-rev>
git -C deps/llvm/tools/clang reset --hard <clang-rev>
```

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
```
75 changes: 39 additions & 36 deletions docs/GettingStarted.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<CppSharp>/build/DownloadDeps.bat`.
Alternatively, if on Windows, just run `<CppSharp>/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 `<CppSharp>/build/scripts/llvm-<revision>-<os>-<configuration>` folders
containing the headers and libraries for LLVM.
Expand All @@ -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 <CppSharp>\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 `<CppSharp>\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 `<CppSharp>\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 <CppSharp>/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 `<CppSharp>\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

Expand Down

0 comments on commit bbd9ab8

Please sign in to comment.