Submitting new build documentation for building CppSharp / QtSharp

Docs/1. Building - QtSharp.md

@@ -0,0 +1,26 @@
+# Building QtSharp
+
+## Overview
+
+I've put some details here on how to build the QtSharp libraries.<br />
+QtSharp offers the possibility of using Qt from within a .Net managed language for a cross platform GUI
+(something other than GTK / WinForms)
+
+So far most of the documentation here surrounds the use of QtSharp with Visual Studio 2013.<br />
+For these examples I'm using Qt 5.4.1 / Mingw 32bit version of Qt for Windows with the default install options
+
+## General Order of things
+
+* Building QtSharp
+* Running QtSharp.CLI (Generate Bindings Code)
+
+Optionally:
+
+* Running NUnit Tests
+* Building CppSharp
+
+## Links
+
+* [Qt Libraries](https://qt-project.org/)
+* [QtSharp Github](https://github.com/ddobrev/QtSharp)
+* [CppSharp (depend of QtSharp)](https://github.com/mono/CppSharp)

Docs/2. Running - QtSharp.CLI.md

@@ -0,0 +1,68 @@
+# QtSharp Building / Running
+
+## Setting up the Sources
+
+First we need to clone QtSharp to our local machine
+
+    mkdir C:\GITHUB
+    cd C:\GITHUB\
+    git clone https://github.com/ddobrev/QtSharp.git QtSharp
+    cd C:\GITHUB\QtSharp
+    git checkout master
+
+Next we need to tell NuGet to download any missing depends into a packages sub directory <br \>
+To do this at the command line
+
+    nuget.exe restore QtSharp.sln
+
+The other alternative is just to
+
+* Open the solution in Visual Studio
+* Right click solution
+* Select "Manage NuGet Packages for Solution"
+* Select the "Restore" button at the top right
+
+This should create a packages subdirectory and download any needed external libraries
+
+## Building QtSharp / QtSharp.CLI
+
+### Visual Studio 2013
+
+To build the sources under Visual Studio 2013
+
+  * Open up the QtSharp.sln File within Visual Studio
+  * Right Click Build on the QtSharp / QtSharp.CLI / QtSharp.Tests Projects
+
+### Windows Command Line
+
+TODO
+
+### Mono Command Line
+
+TODO
+
+## Running the Build
+
+QtSharp.CLI is the app to run to generate the bindings
+
+To run from the command line
+
+    cd C:\GITHUB\QtSharp\QtSharp.CLI\bin\Debug
+    QtSharp.CLI.exe C:\Qt\Qt5.4.1\5.4\mingw491_32\bin\qmake.exe C:\Qt\Qt5.4.1\Tools\mingw491_32\bin\mingw32-make.exe
+
+Or you could just add the above cmd line options to QtSharp.CLI under Project Properties and run it from within Visual Studio
+
+This will do the following
+
+  * The file Wrappers\QtCore\QtCore.cs will be overwritten with a new generated copy
+  * Using the project file within Wrappers\QtCore\ the dll's QtCoreSharp.dll, QtCore-inlines.dll will be generated
+
+  * The above will be repeated for any additional Qt Modules included in the build process
+
+The 2 files needed for QtCore will be
+
+  * CppSharp.Runtime.dll
+  * QtCoreSharp.dll
+
+Note currently there may be some issues when running QtSharp.CLI for the QtGUI Module <br \>
+I found that rebuilding CppSharp seemed to fix this problem

Docs/3. Running - NUnit Tests.md

@@ -0,0 +1,24 @@
+# NUnit Tests
+
+## Running NUnit Tests - Visual Studio
+
+The tests use NUnit to run instead of the inbuilt Visual Studio test system (more cross platform) <br \>
+In order to run the tests within Visual Studio:
+
+First make sure the NUnit Test Adapter is installed for Visual Studio under the Extensions
+
+* Within Visual Studio 2013 Tools -> Extensions and Updates -> Install NUnit Test Adapter
+
+Next we need to Build QtSharp.Tests (don't try to run it as a project, just build)
+
+* Right click the QtSharp.Tests project and select Build
+
+Next make sure the test / platform setting is set to x32 to match the architecture setting of the QtSharp library
+
+* Test Menu -> Test Settings -> Default Processor Architecture -> X86
+
+Next Run the Tests
+
+* Test Menu -> Windows -> Test Explorer
+* wait a while for it to analyse the available tests
+* Click Run All

Docs/4. Building - CppSharp.md

@@ -0,0 +1,199 @@
+# Building CppSharp
+
+## Overview
+
+In order to use QtSharp, we need CppSharp and LLVM (which CppSharp depends on).<br />
+Since this project is still under developement, it's usefull to know how to build CppSharp <br />
+CppSharp is where most of the work is done for generating the bindings
+
+For QTSharp, we can ether use the pre-built dll's generated within the repository within the References directory
+or we can try to generate our own from a more recent version of CppSharp / LLVM
+
+## Building under Windows / Visual Studio 2013 / 32bit
+
+This documentation is based on the below link with perhaps a couple of additional notes
+
+  * [CppSharp - Getting Started](https://github.com/mono/CppSharp/blob/master/docs/GettingStarted.md)
+
+A couple of notes:
+
+* It's probably a good idea to make sure to build it within directories that don't have spaces in the path name (at least for a windows box anyway)
+* The version I'm using here is built to .Net 4.0
+* Check the patches subdirectory in CppSharp for patches to experiment with
+
+### Installed Pre-requisite Software
+
+As part of the build, I'm currently using the following versions of software, although the latest stable versions should be fine
+
+* Git 1.9.5 - Windows
+* cmake-3.2.1 - WIndows
+* Python-3.4.3 - Windows
+
+## Downloading / Prepping Sources
+
+### Cloning CppSharp
+
+First we need to clone CppSharp <br />
+For this example I'm using version ae4fab7db53d55a37defdc61fad4abd486f52f1d
+but the latest release is probably the best for experimenting <br />
+
+To clone the repo at the command prompt:
+
+    mkdir C:\GITHUB
+    cd C:\GITHUB\
+    git clone https://github.com/mono/CppSharp CppSharp
+    cd C:\GITHUB\cppsharp
+    git checkout master
+
+If you already have done a clone before, to update run
+
+    cd C:\GITHUB\cppsharp
+    git pull
+    git checkout master
+
+To see which version your on
+
+    git rev-parse HEAD
+
+If you want a specific version
+
+    git checkout ae4fab7db53d55a37defdc61fad4abd486f52f1d
+
+Theres a few different forks available
+
+* [CppSharp - Original Upstream Tree](https://github.com/mono/CppSharp)
+* [CppSharp - GoldRanks fork](https://github.com/golddranks/CppSharp.git)
+* [CppSharp - ddobrev's tree](https://github.com/ddobrev/CppSharp.git)
+
+### Cloning LLVM
+
+Next we need to clone the LLVM Sources <br />
+For the recommended commit number to use with the latest version of CppSharp<br />
+see [CppSharp - Getting Started](https://github.com/mono/CppSharp/blob/master/docs/GettingStarted.md)
+
+    cd C:\GITHUB\CppSharp\deps\
+    git clone http://llvm.org/git/llvm.git llvm
+    cd C:\GITHUB\CppSharp\deps\llvm
+    git checkout 0e8abfa6ed986c892ec723236e32e78fd9c47b88
+
+### Cloning Clang
+
+Next we need to clone Clang <br />
+Again check the above link for the latest commit number to use with the latest CppSharp
+
+    cd C:\GITHUB\CppSharp\deps\llvm\tools\
+    git clone http://llvm.org/git/clang.git clang
+    cd C:\GITHUB\CppSharp\deps\llvm\tools\clang
+    git checkout 3457cd5516ac741fa106623d9578f5ac88593f4d
+
+## Building LLVM
+
+Next we're going to build LLVM which is a depend of CppSharp, Clang will be built as part of this process automatically <br />
+To get things to match up we're going to use a 64 bit build <br />
+Note that while QtSharp and QtSharp.CLI run as x64 by default, it is possible just to change the arch to x32 in the project settings <br />
+Also the project / source for the wrapper for QT will actually be x32 by default
+
+This next part is taken from the CppSharp readme <br />
+we first need to run cmake on llvm to generate the project files <br />
+Followed by msbuild to compile LLVM <br />
+Make sure to run this within a **Visual Studio Command prompt** so that it can find the msbuild command <br />
+This selects **RelWithDebInfo** as the build configuration <br />
+
+For 64bit:
+
+    cd C:\GITHUB\CppSharp\deps\llvm
+    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
+
+For 32bit:
+
+    cd C:\GITHUB\CppSharp\deps\llvm
+    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
+
+## Building CppSharp
+
+### Generating the Project Files
+
+Next we need to build CppSharp <br />
+First generate the Project / Solution files
+
+    cd C:\GITHUB\CppSharp\build
+    GenerateProjects.bat
+    Choose option 2 / Visual Studio 2013
+
+Next you may want to have a look at the Build/patches directory <br />
+For any patches to explore
+
+### Fixes to Project Files
+
+In order to get CppSharp to build on my system I had to make a couple of tweaks <br />
+
+* Open CppSharp.sln with Visual Studio 2013
+* Ignore the warning about upgrading project files, click OK
+* Select Release from the top menu of Visual Studio
+* If building x64 make sure x64 is also selected to match llvm
+
+The first change:
+
+* Next this appears to be needed to find the lib files during the build
+* Right click the **CppSharp.CppParser** (C++) Project
+* Select Properties
+* Configuration Properties -> Linker -> General -> Additional Library Directories
+* Add the following directory
+
+    C:\GITHUB\CppSharp\deps\llvm\RelWithDebInfo\lib
+
+The second change:
+
+* Right click the **CppSharp.Parser.CLI** (C++) Project
+* Select Properties
+* Under Configuration Properties -> General
+* make sure the Platform Toolset is set to **Visual Studio 2013 - Windows XP (v120_xp)**
+
+Finally to do the build:
+
+* Right Click Build the Solution within Visual Studio
+* Wait lots
+* Some of the tests may fail to build, but as long as the main library's build this is what counts
+
+### Building CppSharp - Command Line
+
+I've just put this here for reference, to build CppSharp from the command line <br />
+(from a visual studio command prompt)
+
+For 64bit:
+
+    msbuild vs2013\CppSharp.sln /p:Configuration=Release;Platform=x64
+
+For 32bit:
+
+    msbuild vs2013\CppSharp.sln /p:Configuration=Release;Platform=x86
+
+The .Net level should default to 4.0 <br />
+Which is fine since it matches the .Net level of QtSharp <br />
+If you decide to change it to 4.5 / 4.5.1 you'll also need to change it for the QtSharp projects as well
+
+
+### Copying the Built files
+
+The dll output build should now be within
+
+    C:\GITHUB\CppSharp\build\vs2013\lib\Release_x64\
+
+Or Release_x32 for 32bit <br />
+The important files that we need are:
+
+    CppSharp.AST.dll
+    CppSharp.CppParser.dll
+    CppSharp.dll
+    CppSharp.Generator.dll
+    CppSharp.Parser.CLI.dll
+    CppSharp.Parser.CSharp.dll
+    CppSharp.Runtime.dll
+
+Note that the **CppSharp.CppParser.dll** is a bit special in that it's a native C++ dll not a managed .Net dll so you won't be able to add a reference to it <br />
+You ether need to add it into the project as a Link, or alter your system path to point to it <br />
+
+The QtSharp project already has a link to it in the project file for copying across (although this isn't visible under references) <br />
+Backup the files within the References directory within QtSharp, and then replace them with these built ones

QtSharp.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio 2013
-VisualStudioVersion = 12.0.21005.1
+VisualStudioVersion = 12.0.31101.0
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "QtSharp", "QtSharp\QtSharp.csproj", "{861046E1-DA11-4229-B9B6-45426E7A723E}"
 EndProject
@@ -15,6 +15,14 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "QtCore", "Wrappers\QtCore\Q
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "QtGui", "Wrappers\QtGui\QtGui.csproj", "{CAFDBAA8-3BF5-434D-97ED-5D0234005EC5}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Docs", "Docs", "{345349CF-F2FF-407A-A38E-A3816616208A}"
+	ProjectSection(SolutionItems) = preProject
+		Docs\1. Building - QtSharp.md = Docs\1. Building - QtSharp.md
+		Docs\2. Running - QtSharp.CLI.md = Docs\2. Running - QtSharp.CLI.md
+		Docs\3. Running - NUnit Tests.md = Docs\3. Running - NUnit Tests.md
+		Docs\4. Building - CppSharp.md = Docs\4. Building - CppSharp.md
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU