Overview

What is Swig? Swig is an application that generates wrapper code for a native DLL to interface with other languages allowing you to use a C/C++ library in one of the supported languages. Currently Swig configuration for RakNet is set up to generate a managed interface that can be used in managed C# in Windows, as well as in Linux with Mono. Swig generates a CXX and .h file, which exposes interfaces that can be used by the target language. The CXX file is included when building the C++ dll that the target language uses. Swig also generates files in the target language for inclusion in the project of the target language to interface with the dll. These are added to the project of the target language. What is Mono? Mono is a cross platform implementation of the .Net framework. This allows you to compile C# and other .Net code and run them on platforms that originally are not .Net compatable like Linux. Choices to Make. You may choose to use the tools with RakNet or start from scratch. On Windows batch tools are provided make the process easier. These tools are located under the Swig Directory under DependentExtensions. For Linux the tools will use Wget to pull down Swig and install verision 1.3.40 if Swig is not installed. You may also download Swig yourself and compile them by specifying the options manually. In the manual portion the options used will be explained. Step Summery Manually: Download Swig, see "Downloading Swig" Generate the Swig files, see "Generating the Swig Files Manually" Create the DLL, see "Creating the Swig Wrapped DLL Project" Create the C# project. see "Creating the C# project" Using tools: *Windows -Using DLL_Swig project Download Swig, see section "Downloading Swig" If you do not plan on using SQLiteClientLoggerPlugin, DependentExtensions\Swig\DLL_Swig\DLL_Swig.sln already contains a DLL project that makes the Swig files, builds the DLL, and copies it to the C# sample. Perform a rebuild on this. Create the C# project see "Creating the C# project" -Not using DLL_Swig project Download Swig, See section "Downloading Swig" Generate the Swig files, see "Generating the Swig Files Using Included Tools" Create the DLL, see "Creating the Swig Wrapped DLL Project" Create the C# project see "Creating the C# project" *Linux Download Swig, See section "Downloading Swig". Generate the Swig files, see "Generating the Swig Files Using Included tools" Create the C# project see "Creating the C# project"

Downloading Swig

Windows Download Swig and Unzip. Go to http://www.swig.org/ On the left hand side click Download. Either fill out the survey or click the Download area link. It will say Windows users should download <link> click on the link. Unzip to C:\Swig or where you prefer C:\Swig will be used for this tutorial. If you wish to use the DLL_Swig project you will need to add to the path variable as shown below. Adding Swig to the Path Variable. Right click My Computer and click Properties. Click on the Advanced tab. Under Advanced, there is an Environment Variables button click it. Click the on the Path variable Click the Edit button Add the path C:\Swig or wherever you unzipped Swig to.
The path variable screen
Linux Download Swig,Unzip,Make, and Install. Note: You may be able to install Swig using your favorite package manager, if you can go that route do so. The instructions vary depending on your package manager and distribution. The batch file will attempt to install 1.6, but it is recommended to use the package manager if you are able to. Go to http://www.swig.org/ On the left hand side click Download. Either fill out the survey or click the Download area link. It will say latest development release is <link> click on the link. Open a terminal Change to the directory you download swig into type tar xzf swig-VERSIONNUMBER.tar.gz and hit enter type cd VERSIONNUMBER and hit enter type ./configure and hit enter type make and hit enter switch to your root user, or if user is a sudo user skip to next step if root type make install and hit enter, other wise type sudo make install and hit enter if user is a sudo user.

Generating the Swig Files Using Included Tools

Generating the Swig Files Using Included Tools on Windows. Note: This step on Windows can be skipped if you are using the included DLL_Swig project as it runs the tools on rebuild. Click the start menu and click on run. In Vista click start->search type "run" hit enter. Type cmd and hit enter. In the next command PATH_TO_RAKNET_SWIG_FILES is the path to the swig directory. For example C:\RakNet\DependentExtensions\Swig Type cd PATH_TO_RAKNET_SWIG_FILES hit enter In the next command PATH_TO_RAKNETSOURCE is the path to the swig source directory. For example: C:\RakNet\Source. PATH_TO_SWIG is an unquoted path with a trailing slash to the Swig directory Example: C:\Swig\. If you added swig to your path variable then PATH_TO_SWIG is not needed and can be ignored. Type MakeSwig.bat PATH_TO_RAKNETSOURCE PATH_TO_SWIG hit enter Click to toggle extra instructions for SQLiteClientLoggerPlugin If you want to use SQLiteClientLoggerPlugin skip #6, the next steps will be used instead. If you have added swig to your path variable, just use "" for PATH_TO_SWIG PATH_TO_SQLITEPLUGIN is the path to the SQLite plugin directory. EX: C:\RakNet\DependentExtensions\SQLite3Plugin Type MakeSwig.bat PATH_TO_RAKNETSOURCE PATH_TO_SWIG PATH_TO_SQLITEPLUGIN hit enter Goto "Creating the Swig Wrapped DLL Project" Generating the Swig Files Using Included Tools on Linux. Note: The Linux batch requires Wget,Tar,Make and GCC to be installed, unless swig is already installed. Most of the time Wget,Tar,Make and GCC are already installed. Open a terminal if you are not already at one. In the next command PATH_TO_RAKNET_SWIG_FILES is the path to the swig directory. For example /home/usr/RakNet/DependentExtensions/Swig Type cd PATH_TO_RAKNET_SWIG_FILES hit enter Type chmod u+x MakeSwig.sh In the next command PATH_TO_RAKNETSOURCE is the path to the swig source directory. For example: /home/usr/RakNet/Source Type ./MakeSwig.sh PATH_TO_RAKNETSOURCE hit enter Click to toggle extra instructions for SQLiteClientLoggerPlugin If you want to use SQLiteClientLoggerPlugin skip #6, the next steps will be used instead. PATH_TO_SQLITEPLUGIN is the path to the SQLite plugin directory. EX: /home/usr/RakNet/DependentExtensions/SQLite3Plugin Type MakeSwig.sh PATH_TO_RAKNETSOURCE PATH_TO_SQLITEPLUGIN hit enter Skip to "Creating the C# project".

Generating the Swig Files Manually

Windows Generate the Swig Files Click the start menu and click on run. In Vista click start->search type "run" hit enter. Type cmd and hit enter. In the next command PATH_TO_RAKNET_SWIG_FILES is the path to the swig directory. For example C:\RakNet\DependentExtensions\Swig Type cd PATH_TO_RAKNET_SWIG_FILES hit enter In the next command PATH_TO_RAKNETSOURCE is the path to the swig source directory. For example: C:\RakNet\Source Type C:\Swig\swig -c++ -csharp -I" PATH_TO_RAKNETSOURCE" -I"SwigInterfaceFiles" -outdir SwigOutput\SwigCSharpOutput -o SwigOutput\CplusDLLIncludes\RakNet_wrap.cxx SwigInterfaceFiles\RakNet.i hit enter Click to toggle extra instructions for SQLiteClientLoggerPlugin If you want to use SQLiteClientLoggerPlugin skip #6 PATH_TO_SQLITEPLUGIN is the path to the SQLite plugin directory. EX: C:\RakNet\DependentExtensions\SQLite3Plugin Type C:\Swig\swig -c++ -csharp -I" PATH_TO_RAKNETSOURCE" -I"SwigInterfaceFiles" -I"PATH_TO_SQLITEPLUGIN" -DSWIG_ADDITIONAL_SQL_LITE -outdir SwigOutput\SwigCSharpOutput -o SwigOutput\CplusDLLIncludes\RakNet_wrap.cxx SwigInterfaceFiles\RakNet.i hit enter Linux Generate the Swig Files Open a terminal In the next command PATH_TO_RAKNET_SWIG_FILES is the path to the swig directory. For example /home/usr/RakNet/DependentExtensions/Swig Type cd PATH_TO_RAKNET_SWIG_FILES hit enter In the next command PATH_TO_RAKNETSOURCE is the path to the swig source directory. For example: /home/usr/RakNet/Source Type swig -c++ -csharp -I"PATH_TO_RAKNETSOURCE" -I"SwigInterfaceFiles" -outdir SwigOutput/SwigCSharpOutput -o SwigOutput/CplusDLLIncludes/RakNet_wrap.cxx SwigInterfaceFiles/RakNet.i and hit enter Click to toggle extra instructions for SQLiteClientLoggerPlugin f you want to use SQLiteClientLoggerPlugin skip #6 PATH_TO_SQLITEPLUGIN is the path to the SQLite plugin directory. EX: /home/usr/RakNet/DependentExtensions/SQLite3Plugin Type swig -c++ -csharp -I"PATH_TO_RAKNETSOURCE" -I"SwigInterfaceFiles" -I"PATH_TO_SQLITEPLUGIN" -DSWIG_ADDITIONAL_SQL_LITE -outdir SwigOutput/SwigCSharpOutput -o SwigOutput/CplusDLLIncludes/RakNet_wrap.cxx SwigInterfaceFiles/RakNet.i and hit enter Swig Options Explained -c++ This must come first. This means that the source files are C++ not C. -csharp This is the target language. Currently the files are made for C# and may not work with the other options. -I"PATH_TO_RAKNETSOURCE" This option includes the directory for any source and includes if different from the interface file location. -I"SwigInterfaceFiles" This option includes the directory for the interface files. -outdir SwigOutput/SwigCSharpOutput This is where the output files to be included in the target language are placed. -o SwigOutput/CplusDLLIncludes/RakNet_wrap.cxx This is where the file that is included in the DLL project is placed. *The below two are used if SQLiteClientLoggerPlugin is used: -I"PATH_TO_SQLITEPLUGIN" Another include directory, the base directory where the SQLite plugin is. -DSWIG_ADDITIONAL_SQL_LITE A conditional compilation symbol, defined to include SQLiteClientLoggerPlugin.

Creating the Swig Wrapped DLL Project

Windows Note: If you do not plan on using SQLiteClientLoggerPlugin, DependentExtensions\Swig\DLL_Swig\DLL_Swig.sln already contains a DLL project that makes the Swig files, builds the DLL, and copies it to the C# sample. You do not need to run these steps if you use that project. In that case, run the solution, rebuild the project, and goto "Creating the C# project" Creating the Swig DLL Create a DLL project. I'll assume you know how to do this. In MSVC 7 you would create an empty project, then under Application Settings you check DLL and empty project. Add the source files under the /Source directory to the project. Add RakNet.cxx from Swigtools/CplusDLLIncludes Click to toggle extra instructions for SQLiteClientLoggerPlugin Add to the project these files under DependentExtensions: SQLite3Plugin\SQLite3ClientPlugin.h, SQLite3Plugin\SQLite3PLuginCommon.h, SQLite3Plugin\Logger\ClientOnly\SQLiteClientLoggerPlugin.h, SQLite3Plugin\Logger\SQLliteLoggerCommon.h, SQLite3Plugin\SQLite3ClientPlugin.cpp, SQLite3Plugin\SQLite3PLuginCommon.cpp, SQLite3Plugin\Logger\ClientOnly\SQLiteClientLoggerPlugin.cpp, SQLite3Plugin\Logger\SQLliteLoggerCommon.cpp Add to "Additional Include Directories" the path to these folders in the DependentExtensions directory: SQLite3Plugin\Logger\ClientOnly, SQLite3Plugin\Logger, SQLite3Plugin Add to "Additional Include Directories" your directory with the source files. Import ws2_32.lib, or wsock32.lib if you don't have Winsock 2 installed. In MSVC 7 you can right click on the project, select configuration properties / linker / input / additional dependencies and type "ws2_32.lib" in there. Set your project to use multi-threaded runtime libraries. In MSVC 7 you can right click on the project, select configuration properties / C/C++ / Code Generation / Runtime Library and change it to Multi-threaded (/MT). Add _RAKNET_DLL to the Preprocessor Definitions. In VS Project Properties -> Configuration Properties -> C/C++ -> PreProcessor -> Preprocessor Definitions Set the character set to "not set".In VS Project Properties -> Configuration Properties -> General-> Character Set Optionally set your preprocessor directives. Then hit F7 or the equivalent to build your DLL and Lib.
Creating an empty DLL project in .net 2003
Setting Multithreaded debug in .net 2003
Including ws2_32.lib in .net 2003
Linux Creating the Swig Dynamic Link Note: If you ran the linux batch tool it will have made the dynamic link and attempted to install it, so you may skip these steps if it ran successfully. In the next command PATH_TO_RAKNET_SWIG_FILES is the path to the swig directory. EX:: ../DependentExtensions/Swig g++ *.cpp PATH_TO_RAKNET_SWIG_FILES/SwigOutput/CplusDLLIncludes/RakNet_wrap.cxx -l pthread -I./ -shared -o RakNet Note: In the previous command -l pthread is lower case L while -I./ is uppercase i. Click to toggle extra instructions for SQLiteClientLoggerPlugin If you wish to use SQLiteClientLoggerPlugin in the place of #2 use the below instructions PATH_TO_SQLITEPLUGIN is the path to the SQLite plugin directory. EX: /home/usr/RakNet/DependentExtensions/SQLite3Plugin g++ *.cpp PATH_TO_RAKNET_SWIG_FILES/SwigOutput/CplusDLLIncludes/RakNet_wrap.cxx PATH_TO_SQLITEPLUGIN\SQLite3ClientPlugin.cpp PATH_TO_SQLITEPLUGIN \SQLite3PLuginCommon.cpp PATH_TO_SQLITEPLUGIN \Logger\ClientOnly\SQLiteClientLoggerPlugin.cpp PATH_TO_SQLITEPLUGIN \Logger\SQLliteLoggerCommon.cpp -l pthread -I./ -IPATH_TO_SQLITEPLUGIN\Logger\ClientOnly -IPATH_TO_SQLITEPLUGIN\Logger -IPATH_TO_SQLITEPLUGIN -shared -o RakNet A file called RakNet should be created that will be copied in the next section

Creating the C# project

Windows C# Project Setup Create a new C# project. In the included sample a console project is used. If you wish to keep the project cleaner create a new folder called Swig. Right click the project and go to Add -> New folder Add the source files that were generated under the SwigOutput\SwigCSharpOutput directory to the project.The first step to doing this is right clicking the project, or if you added a folder right click the folder. Go to Add -> Existing Item. Browse to the SwigOutput\SwigCSharpOutput directory. If you want to link to the files rather than create a copy click on the arrow next to add and add a link. Otherwise click add. Copy the DLL created in the previous step to the same folder as the binary. Example: bin\Debug If you wish the project to be compatible with 64 bit vista you need to use the following steps. When the project is opnen there should be a menu item called Build. Click it. Go to Configuration manager and click it. On the top right there is a drop down menu called Active Solution platform. If X86 is in the project menu click it and go to step 16. If not click New. Under "Type or select the new platform" pick x86. Copy settings should be set to "Any CPU" Make sure "Create new project platforms" is checked and click ok. Click on "Active Solutions configuration" in the top left. Pick the next item after the one currently selected if that item is not <New> or <Edit>. Repeat 11-17 for that item. There should be a list under "Project Contexts". Under the "Platform" column it should say x86 under each item, if not change it to x86. Thre should be an column called "Configuration", cycle through all the items except for <New> and <Edit> and make sure that #20 is true. Do #20-21 for each item in the list.
Example of steps 9-21 to run on 64-bit systems.
C# Sample A C# sample project is included under DependentExtensions\Swig\SwigWindowsCSharpSample. The DLL file is not included and needs to be copied to the bin/Debug or the bin/Release folder depending on whether or not you are doing a release or debug build. If the DLL_Swig project is used the dll is copied automatically. Linux Installing Mono, if it is not Installed Note: Mono greater than version 2.0 is needed for full compatability, earlier versions work with most of RakNet but cause crashes in some of it. You may be able to install Mono using your favorite package manager, if you can go that route do so. The instructions vary depending on your package manager and distribution. Some package manager have different options for the C# compiler. This tutorial assumes gmcs is installed. Go to http://www.go-mono.com/mono-downloads/download.html Download the linux version open a terminal change to the directory you downloaded mono to.. type tar xzvf mono-VERSION.tar.gz hit enter type cd mono-VERSION hit enter type ./configure --prefix=/usr/local and hit enter type make and hit enter switch to your root user, or if user is a sudo user skip to next step if root type make install and hit enter, other wise type sudo make install and hit enter if user is a sudo user. C# Project Setup Note: If you used the included tools and just want to run the sample you may skip this section. Copy the dynamic link library to /usr/lib and rename it to RakNet with no extension if it is not already. Copy the files in Swigtools/SwigCSharpOutput into your project directory. Create your main C# .cs file in that folder. Building the Project Type gmcs *.cs -out:ExecutableName.exe where ExecutableName is the name you want and hit enter. The file can be ran with mono ExecutableName.exe C# Sample A C# sample is included under DependentExtensions/Swig/SwigLinuxCSharpSample. The DLL file is not included and needs to be copied to /usr/lib as per the earlier instructions. If the tools are used the cs files are automatically copied to the sample directory and there is an attempt by tools to copy the dll to /usr/lib.

Limitations

Limitations BitStream may have problems if larger than 9 megabytes.

Important Information

Important Information RakPeer,RakString,FullyConnectedMesh2,NetworkIDObject,UDPForwarder, and UDPProxyCoordinator need to be released before the program ends.Any item that go out of scope before program end just needs to be garbage collected, so items not in main or global generally do not have issues. For these just call the GC before program end.For globals and items in main the items can be released with the Dispose method if new was used, if a RakNetworkFactory method was used to create use RakNetworkFactory to destroy the object.

See Also

Index