1# Building Ice for .NET 2 3This page describes how to build Ice for .NET from source and package the 4resulting binaries. As an alternative, you can download and install the 5[zeroc.ice.net][1] NuGet package. 6 7* [Building on Windows](#building-on-windows) 8 * [Windows Build Requirements](#windows-build-requirements) 9 * [Compiling Ice for \.NET on Windows](#compiling-ice-for-net-on-windows) 10 * [Strong Name Signatures for \.NET Framework 4\.5 Assemblies](#strong-name-signatures-for-net-framework-45-assemblies) 11 * [Authenticode Signatures](#authenticode-signatures) 12 * [Building only the Test Suite](#building-only-the-test-suite) 13* [Building on Linux or macOS](#building-on-linux-or-macos) 14 * [Linux and macOS Build Requirements](#linux-and-macos-build-requirements) 15 * [Compiling Ice for \.NET on Linux or macOS](#compiling-ice-for-net-on-linux-or-macos) 16* [Running the Tests](#running-the-tests) 17* [NuGet Package](#nuget-package) 18* [Building Ice for Xamarin Test Suite](#building-ice-for-xamarin-test-suite) 19 20## Building on Windows 21 22A source build of Ice for .NET on Windows produces two sets of assemblies: 23 - assemblies for the .NET Framework 4.5 24 - assemblies for [.NET Standard 2.0][2] 25 26### Windows Build Requirements 27 28In order to build Ice for .NET from source, you need all of the following: 29 - a [supported version][3] of Visual Studio 30 - the [.NET Core 2.1 SDK][4], if you use Visual Studio 2017 31 32> Note: Visual Studio 2017 version 15.3.0 or higher is required for .NET Core 33> builds. 34 35### Compiling Ice for .NET on Windows 36 37Open a Visual Studio command prompt and change to the `csharp` subdirectory: 38``` 39cd csharp 40``` 41 42To build all Ice assemblies and the associated test suite, run: 43``` 44msbuild msbuild\ice.proj 45``` 46 47Upon completion, the Ice assemblies for the .NET Framework 4.5 and .NET Standard 2.0 48are placed in the `lib\net45` and `lib\netstandard2.0` folders respectively. 49 50> Note: the assemblies for .NET Standard 2.0 are created only when you build with 51> Visual Studio 2017 or greater. 52 53You can skip the build of the test suite with the `BuildDist` target: 54``` 55msbuild msbuild\ice.proj /t:BuildDist 56``` 57 58The `BuildNet45`, `BuildNet45Dist`, `BuildNetStandard` and `BuildNetStandardDist` targets 59allow you to build assemblies only for the .NET Framework 4.5 or .NET Standard 2.0, 60with or without the test suite. 61 62The iceboxnet and test applications target `netcoreapp2.1`. You can change the target framework 63by setting the `AppTargetFrameworks` property to a different Target Framework Monikers (TFMs) 64value, for example: 65``` 66msbuild msbuild\ice.proj /p:"AppTargetFrameworks=net462" 67``` 68 69This builds the test programs for `net462`. The target frameworks you specify must 70implement .NET Standard 2.0. 71 72#### Strong Name Signatures 73 74You can add Strong Naming signatures to the Ice assemblies by setting the following 75environment variables before building these assemblies: 76 77 - PUBLIC_KEYFILE Identity public key used to delay sign the assembly 78 - KEYFILE Identity full key pair used to sign the assembly 79 80If only PUBLIC_KEYFILE is set, the assemblies are delay-signed during the build 81and you must re-sign the assemblies later with the full identity key pair. 82 83If only KEYFILE is set, the assemblies are fully signed during the build using 84KEYFILE. 85 86If both PUBLIC_KEYFILE and KEYFILE are set, assemblies are delay-signed during 87the build using PUBLIC_KEYFILE and re-signed after the build using KEYFILE. 88This can be used for generating [Enhanced Strong Naming][5] signatures. 89 90*Strong Name Signatures can be generated only from Windows builds.* 91 92#### Authenticode Signatures 93 94You can sign the Ice binaries with Authenticode by setting the following 95environment variables before building these assemblies: 96 - SIGN_CERTIFICATE to your Authenticode certificate 97 - SIGN_PASSWORD to the certificate password 98 99*Authenticode can be generated only from Windows builds.* 100 101#### Building only the Test Suite 102 103You can build only the test suite with this command: 104``` 105msbuild msbuild\ice.proj /p:ICE_BIN_DIST=all 106``` 107 108This build retrieves and installs the `zeroc.ice.net` NuGet package if necessary. 109 110## Building on Linux or macOS 111 112### Linux and macOS Build Requirements 113 114You need the [.NET Core 2.1 SDK][4] to build Ice for .NET from source. 115 116### Compiling Ice for .NET on Linux or macOS 117 118Open a command prompt and change to the `csharp` subdirectory: 119``` 120cd csharp 121``` 122 123Then run: 124``` 125dotnet msbuild msbuild/ice.proj 126``` 127 128Upon completion, the Ice assemblies for .NET Standard 2.0 are placed in the 129`lib/netstandard2.0` directory. 130 131You can skip the build of the test suite with the `BuildDist` target: 132``` 133dotnet msbuild msbuild/ice.proj /t:BuildDist 134``` 135 136## Running the Tests 137 138Python is required to run the test suite. Additionally, the Glacier2 tests 139require the Python module `passlib`, which you can install with the command: 140``` 141pip install passlib 142``` 143 144To run the tests, open a command window and change to the top-level directory. 145At the command prompt, execute: 146``` 147python allTests.py 148``` 149 150If everything worked out, you should see lots of `ok` messages. In case of a 151failure, the tests abort with `failed`. 152 153On Windows, `allTests.py` executes by default the tests for .NET Framework 4.5. 154In order to execute the tests with .NET Core framework add the `--dotnetcore` option. 155For example: 156``` 157python allTests.py --dotnetcore 158``` 159 160If you build the test against a different target framework you must use `--framework` option 161with the corresponding target framework. 162 163For example to run test build against .NET Framework 4.6.2: 164``` 165python allTests.py --framework=net462 166``` 167 168And to run test build against .NET Core 3.0: 169``` 170python allTests.py --dotnetcore --framework=netcoreapp3.0 171``` 172 173## NuGet Package 174 175To create a NuGet package, open a Visual Studio command prompt and run the 176following command: 177``` 178msbuild msbuild\ice.proj /t:NuGetPack 179``` 180 181This creates `zeroc.ice.net\zeroc.ice.net.nupkg`. 182 183> Note: The new NuGet package always includes assemblies for the .NET Framework 4.5. 184> If you build with Visual Studio 2017, the NuGet package also includes assemblies 185> for .NET Standard 2.0. 186 187*Temporary limitation: you currently cannot create NuGet packages on Linux and macOS.* 188 189## Building Ice for Xamarin Test Suite 190 191The `msbuild\ice.xamarin.test.sln` Visual Studio solution allows building 192the Ice test suite as a Xamarin application that can be deployed on iOS, Android 193or UWP platforms. 194 195The Xamarin test suite uses the Ice assemblies for .NET Standard 2.0. either 196from the source distribution or using the zeroc.ice.net NuGet package. If using 197the assembles from the source distribution, they must be built before this 198application. 199 200### Building on Windows 201 202#### Windows Build Requirements 203 204* Visual Studio 2017 with following workloads: 205 * Universal Windows Platform development 206 * Mobile development with .NET 207 * .NET Core cross-platform development 208 209#### Building the Android test controller 210 211Open a Visual Studio 2017 command prompt: 212 213``` 214MSBuild msbuild\ice.proj /t:AndroidXamarinBuild 215``` 216 217#### Building the UWP test controller 218 219Open a Visual Studio 2017 command prompt: 220 221``` 222MSBuild msbuild\ice.proj /t:UWPXamarinBuild 223``` 224 225#### Running the Android test suite 226 227``` 228set PATH=%LOCALAPPDATA%\Android\sdk\tools\bin;%PATH% 229set PATH=%LOCALAPPDATA%\Android\sdk\platform-tools;%PATH% 230set PATH=%LOCALAPPDATA%\Android\sdk\emulator;%PATH% 231 232python allTests.py --android --controller-app --config Release --platform x64 233``` 234 235#### Running the UWP test suite 236 237``` 238python allTests.py --uwp --controller-app --config Release --platform x64 239``` 240 241### Building on macOS 242 243#### macOS Build Requirements 244 245* Visual Studio for Mac 246 247#### Building the Android test controller 248 249``` 250msbuild msbuild/ice.proj /t:AndroidXamarinBuild 251``` 252 253#### Building the iOS test controller 254 255``` 256msbuild msbuild/ice.proj /t:iOSXamarinBuild 257``` 258 259#### Running the Android test suite 260 261``` 262export PATH=~/Library/Android/sdk/tools/bin:$PATH 263export PATH=~/Library/Android/sdk/platform-tools:$PATH 264export PATH=~/Library/Android/sdk/emulator:$PATH 265 266python allTests.py --android --controller-app --config Release --platform x64 267``` 268 269#### Running the iOS test suite 270 271``` 272python allTests.py --controller-app --config Release --platform iphonesimulator 273``` 274 275[1]: https://zeroc.com/distributions/ice 276[2]: https://blogs.msdn.microsoft.com/dotnet/2017/08/14/announcing-net-standard-2-0 277[3]: https://doc.zeroc.com/display/Rel/Supported+Platforms+for+Ice+3.7.2 278[4]: https://dotnet.microsoft.com/download/dotnet-core/2.1 279[5]: https://docs.microsoft.com/en-us/dotnet/framework/app-domains/enhanced-strong-naming 280