@@ -5,31 +5,21 @@ PowerShell script.
55
66The nature of the .NET SDK projects and VCX projects drives the need for the script,instead of
77VS solution dependencies or even MSBuild project to project references. Unfortunately, due to
8- the way multi-targeting is done in the newer C# SDK projects project to project references
9- don't work. The VCXproj files don't have targets for all the .NET targets. Making that all work
10- seamlessly in VS is just plain hard work that has, thus far, not worked particularly well. Thus,
11- the design here uses a simpler PowerShell script that takes care of building the correct
12- platform+configuration+target framework combinations of each and finally builds the NuGet
8+ the way multi-targeting is done in the newer C# SDK projects the project to project references
9+ don't work with C++ . The VCXproj files don't have targets for all the .NET targets. Making that
10+ all work seamlessly in VS is just plain hard work that has, thus far, not worked particularly
11+ well. Thus, the design here uses a simpler PowerShell script that takes care of building the
12+ correct platform+configuration+target framework combinations of each and finally builds the NuGet
1313package from the resulting binaries.
1414
1515## Projects
16- ### LibLLVM
17- This is the native project that creates the extended LLVM-C API as an actual DLL. Currently
18- only Windows 64 bit is supported, though other configurations are plausible with additional
19- build steps in the PowerShell script to build for other platforms. The extensions are configured
20- to build with high C++ conformance mode, so they should readily build without much modification
21- for other platforms given the appropriate build infrastructure is set up.
22-
23- ### Ubiquity.NET.Llvm.Interop
24- This is the .NET P/Invoke layer that provides the raw API projection to .NET. The, majority
25- of the code is generated P/Invokes from the LlvmBindingsGenerator tool. There are a few
26- additional support classes that are consistent across variations in LLVM. While this library
27- has a runtime dependency on the native LibLLVM binary there is no compile time dependency.
28-
2916### LlvmBindingsGenerator
3017This is the P/Invoke generator for the generated interop code in Ubiquity.NET.Llvm.Interop. It uses
31- CppSharp to parse the C headers and generate the C# P/Invoke API declarations, enums and value
32- types required to interop with the native code.
18+ CppSharp to parse the C or C++ headers and generate the C# P/Invoke API declarations, enums and value
19+ types required to interop with the native code. The generator has a number of automatic marshaling
20+ rules, but there are ambiguous cases that it needs a configuration file to resolve. The configuration
21+ file provides resolution of the ambiguities and also helps in detection of missing or removed APIs when
22+ moving to a newer version of LLVM.
3323
3424#### Usage
3525` LlvmBindingsGenerator <llvmRoot> <extensionsRoot> [OutputPath] `
@@ -46,6 +36,19 @@ change, the PowerShell script takes care of running the generator to update the
4636code base on each run, even if nothing changes in the end. This is run on every automated build before building
4737the Ubiquity.NET.Llvm.Interop project so that the generator is tested on every full automated build.
4838
39+ ### LibLLVM
40+ This is the native project that creates the extended LLVM-C API as an actual DLL. Currently
41+ only Windows 64 bit is supported, though other configurations are plausible with additional
42+ build steps in the PowerShell script to build for other platforms. The extensions are configured
43+ to build with high C++ conformance mode, so they should readily build without much modification
44+ for other platforms given the appropriate build infrastructure is set up.
45+
46+ ### Ubiquity.NET.Llvm.Interop
47+ This is the .NET P/Invoke layer that provides the raw API projection to .NET. The, majority
48+ of the code is generated P/Invokes from the LlvmBindingsGenerator tool. There are a few
49+ additional support classes that are consistent across variations in LLVM. While this library
50+ has a runtime dependency on the native LibLLVM binary there is no compile time dependency.
51+
4952## Building the Interop libraries
5053### General requirements
5154There are some general steps that are required to successfully build the interop NuGet package and a couple
@@ -65,24 +68,13 @@ The interop libraries are built using the Build-Interop.ps1 PowerShell script. T
6568to correctly build the projects in an automated build as it isn't possible to accomplish all the required
6669steps in a standard project/solution. (OK, impossible is a bit strong as creating custom targets and tasks
6770could probably cover it but at the expense of greater complexity). The script is pretty simple though
68- understanding it is a more complex matter this document is aimed towards.
69-
70- ### Manually (developer inner loop)
71- While it is possible to use the PowerShell script as part of the development of the interop libraries themselves,
72- it is generally easier to use the solution file. The solution contains projects for the native libraries, the
73- bindings generator and the managed interop. _ ** Using the solution requires that you manually build/run the projects
74- in the correct order to get changes to propagate correctly.** _
71+ understanding why it is needed is a more complex matter this document is aimed towards.
7572
76- 1 . Build LlvmBindingsGenerator project
77- 2 . Run LlvmBindingsGenerator (via command line or debugger launch) with the location of the LLVM headers, the
78- LibLLVM headers, and the output location of generated code for the Ubiquity.NET.Llvm.Interop project.
79- 1. (See above for full command line options for LlvmBindingsGenerator)
80- 2. This, generates C# interop source files AND also generates the native C++ EXPORTS.DEF for the LibLLVM library
81- and therefore, must run before building either of the other libraries.
82- 3 . Build LibLLVM project for all architectures and configurations.
83- 1 . At present the only supported runtime and architecture is Windows 64bit so batch building, etc.. isn't required.
84- Other runtimes and architectures are possible in the future, however.
85- 4 . Build the Ubiquity.NET.Llvm.Interop project.
73+ > [ !NOTE]
74+ > Building the interop tests via the solution is required as building the CSproj doesn't 'publish' the test.
75+ > If you build via a solution file, then the publish automatically occurs. (You can run the publish target via
76+ > ` dotnet publish ` , but that's both an extra step AND ends up doing things differently then when you build the
77+ > solution! (There's a publish folder with binaries in it and things are generally in different places - Go Figure!)
8678
8779
8880
0 commit comments