diff options
Diffstat (limited to 'csharp/BuildInstructions.md')
| -rw-r--r-- | csharp/BuildInstructions.md | 94 |
1 files changed, 71 insertions, 23 deletions
diff --git a/csharp/BuildInstructions.md b/csharp/BuildInstructions.md index 5b24f99142f..4a29e3448ba 100644 --- a/csharp/BuildInstructions.md +++ b/csharp/BuildInstructions.md @@ -1,95 +1,143 @@ # Building Ice for .NET -This page describes how to build and install Ice for .NET from source code using Visual Studio. If you prefer, you can also download [binary distributions](https://zeroc.com/download.html) for the supported platforms. +This page describes how to build and install Ice for .NET from source code using +Visual Studio. If you prefer, you can also download [binary distributions][1] for +the supported platforms. ## Build Requirements ### Operating Systems and Compilers -Ice for .NET was extensively tested using the operating systems and compiler versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html). +Ice for .NET was extensively tested using the operating systems and compiler versions +listed for our [supported platforms][2]. ### Slice to C# Translator -You will need the Slice to C# translator. ZeroC provides translator binaries for our supported platforms, or you can build Ice for C++ (which contains the Slice to C# translator) from source. +You will need the Slice to C# translator. ZeroC provides translator binaries for our +supported platforms, or you can build Ice for C++ (which contains the Slice to C# +translator) from source. ## Compiling Ice for .NET with Visual Studio ### Preparing to Build -The build system requires the Slice translator from Ice for C++. If you have not built Ice for C++ in this source distribution, you must set the ```ICE_HOME``` environment variable with the path name of your Ice installation: +The build system requires the Slice translator from Ice for C++. If you have not +built Ice for C++ in this source distribution, you must set the `ICE_HOME` +environment variable with the path name of your Ice installation: > set ICE_HOME=C:\Program Files (x86)\ZeroC\Ice-3.6.0 ### Building Ice for .NET -Open a Visual Studio command window and change to the ```csharp``` subdirectory: +Open a Visual Studio command window and change to the `csharp` subdirectory: > cd csharp -Review the settings in the file ```config\Make.rules.mak.cs``` and edit as necessary. For example, you may wish to enable optimization. +Review the settings in the file `config\Make.rules.mak.cs` and edit as necessary. +For example, you may wish to enable optimization. To build the Ice assemblies, services and tests, run > nmake /f Makefile.mak -Upon completion, the Ice assemblies are placed in the ```Assemblies``` subdirectory. +Upon completion, the Ice assemblies are placed in the `Assemblies` subdirectory. ## Running the .NET Tests -Some of the Ice for .NET tests employ applications that are part of the Ice for C++ distribution. If you have not built Ice for C++ in this source distribution then you must set the ```ICE_HOME``` environment variable with the path name of your Ice installation: +Some of the Ice for .NET tests employ applications that are part of the Ice for +C++ distribution. If you have not built Ice for C++ in this source distribution +then you must set the `ICE_HOME` environment variable with the path name of your +Ice installation: > set ICE_HOME=C:\Program Files (x86)\ZeroC\Ice-3.6.0 -Python is required to run the test suite. To run the tests, open a command window and change to the top-level directory. At the command prompt, execute: +Python is required to run the test suite. To run the tests, open a command window +and change to the top-level directory. At the command prompt, execute: > python allTests.py -You can also run tests individually by changing to the test directory and running this command: +You can also run tests individually by changing to the test directory and running +this command: > python run.py -If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```. +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. ## Protocol Compression with .NET -Ice for .NET attempts to dynamically load ```bzip2.dll``` to support protocol compression, therefore this DLL must be present in your PATH. Ice automatically disables protocol compression if the DLL cannot be found. +Ice for .NET attempts to dynamically load `bzip2.dll` to support protocol compression, +therefore this DLL must be present in your PATH. Ice automatically disables protocol +compression if the DLL cannot be found. -On 64-bit Windows, you must ensure that Ice finds the 64-bit version of ```bzip2.dll``` before the 32-bit version. The 64-bit and 32-bit bzip2 libraries are installed in ```<prefix>\bin\x64``` and ```<prefix>\bin```, respectively. For 64-bit Windows, the ```<prefix>\bin\x64``` directory must appear before ```<prefix>\bin``` in your application's PATH. (The Ice run time prints a warning to the console if it detects a ```bzip2.dll``` format mismatch during start-up.) +On 64-bit Windows, you must ensure that Ice finds the 64-bit version of `bzip2.dll` +before the 32-bit version. The 64-bit and 32-bit bzip2 libraries are installed in +`<prefix>\bin\x64` and `<prefix>\bin`, respectively. For 64-bit Windows, the +`<prefix>\bin\x64` directory must appear before `<prefix>\bin` in your application's +PATH. (The Ice run time prints a warning to the console if it detects a `bzip2.dll` +format mismatch during start-up.) ## Installing Ice for .NET -Run ```nmake /f Makefile.mak install``` to install Ice for .NET in the directory specified by the ```prefix``` variable in ```config\Make.rules.mak.cs```. After installation, the ```<prefix>\bin``` directory contains executables (such as ```iceboxnet.exe```), and the ```<prefix>\Assemblies``` directory contains the .NET assemblies. +Run `nmake /f Makefile.mak install` to install Ice for .NET in the directory specified +by the `prefix` variable in `config\Make.rules.mak.cs`. After installation, the +`<prefix>\bin` directory contains executables (such as `iceboxnet.exe`), and the +`<prefix>\Assemblies` directory contains the .NET assemblies. -> *This command must be executed in a command prompt that has administrative privileges because it requires write access to the registry to register the assemblies.* +> *This command must be executed in a command prompt that has administrative +privileges because it requires write access to the registry to register the +assemblies.* ## GAC Installation -You can add the assemblies to the Global Assembly Cache (GAC). To do this, open Windows Explorer and navigate to the directory ```C:\WINDOWS\assembly```. Next, drag and drop (or copy and paste) the assemblies from the ```Assemblies``` subdirectory of your Ice source build into the right-hand pane to install them in the cache. +You can add the assemblies to the Global Assembly Cache (GAC). To do this, open +Windows Explorer and navigate to the directory `C:\WINDOWS\assembly`. Next, drag +and drop (or copy and paste) the assemblies from the `Assemblies` subdirectory +of your Ice source build into the right-hand pane to install them in the cache. -You can also use ```gacutil``` from the command line to achieve the same result: +You can also use `gacutil` from the command line to achieve the same result: > gacutil /i library.dll -The ```gacutil``` tool should already be in your PATH if you open a Visual Studio command prompt. +The `gacutil` tool should already be in your PATH if you open a Visual Studio +command prompt. -Once installed in the cache, the assemblies will always be located correctly without having to set environment variables or copy them into the same directory as an executable. +Once installed in the cache, the assemblies will always be located correctly +without having to set environment variables or copy them into the same directory +as an executable. -If you want line numbers for stack traces, you must also install the PDB (```.pdb```) files in the GAC. Unfortunately, you cannot do this using Explorer, so you have to do it from the command line. Open a command shell window and navigate to ```C:\WINDOWS\assembly\Microsoft.NET\GAC_MSIL\Ice``` (assuming ```C:\WINDOWS``` is your system root). Doing a directory listing there, you will find a directory named ```v4.0_3.5.0.0__<UUID>```, for example: +If you want line numbers for stack traces, you must also install the PDB (`.pdb`) +files in the GAC. Unfortunately, you cannot do this using Explorer, so you have +to do it from the command line. Open a command shell window and navigate to +`C:\WINDOWS\assembly\Microsoft.NET\GAC_MSIL\Ice` (assuming `C:\WINDOWS` is your +system root). Doing a directory listing there, you will find a directory named +`v4.0_3.5.0.0__<UUID>`, for example: v4.0_3.5.0.0__cdd571ade22f2f16 -Change to that directory (making sure that you use the correct version number for this release of Ice). In this directory, you will see the file ```Ice.dll``` that you installed into the GAC in the preceding step. Now copy the ```Ice.pdb``` file into this directory: +Change to that directory (making sure that you use the correct version number +for this release of Ice). In this directory, you will see the file `Ice.dll` +that you installed into the GAC in the preceding step. Now copy the `Ice.pdb` +file into this directory: > copy path_to_ice.pdb . ## Targeting Managed Code -By default, Ice for .NET uses unmanaged code for performing protocol compression and for handling signals in the ```Ice.Application``` class. You can build a managed version of Ice for .NET that lacks the aforementioned features by editing ```config/Make.rules.mak.cs``` and uncommenting the ```MANAGED=yes``` line before you build. Run nmake to start the build: +By default, Ice for .NET uses unmanaged code for performing protocol compression +and for handling signals in the `Ice.Application` class. You can build a managed +version of Ice for .NET that lacks the aforementioned features by editing +`config/Make.rules.mak.cs` and uncommenting the `MANAGED=yes` line before you +build. Run nmake to start the build: > nmake /f Makefile.mak ## Targeting Unity -Ice for .NET can also be compiled to target the Unity API. To build Ice for the Unity API, open ```config\Make.rules.mak.cs``` and set ```UNITY=yes```. Run nmake as before: +Ice for .NET can also be compiled to target the Unity API. To build Ice for the +Unity API, open `config\Make.rules.mak.cs` and set `UNITY=yes`. Run nmake as before: > nmake /f Makefile.mak + +[1]: https://zeroc.com/download.html +[2]: https://zeroc.com/platforms_3_6_0.html |