Jenkins Software


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.
Downloading Swig
Windows

Download Swig and Unzip.

  1. Go to http://www.swig.org/
  2. On the left hand side click Download.
  3. Either fill out the survey or click the Download area link.
  4. It will say Windows users should download <link> click on the link.
  5. Unzip to C:\Swig or where you prefer C:\Swig will be used for this tutorial.
  6. 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.

  1. Right click My Computer and click Properties.
  2. Click on the Advanced tab.
  3. Under Advanced, there is an Environment Variables button click it.
  4. Click the on the Path variable
  5. Click the Edit button
  6. 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.
  1. Go to http://www.swig.org/
  2. On the left hand side click Download.
  3. Either fill out the survey or click the Download area link.
  4. It will say latest development release is <link> click on the link.
  5. Open a terminal
  6. Change to the directory you download swig into
  7. type tar xzf swig-VERSIONNUMBER.tar.gz and  hit enter
  8. type cd VERSIONNUMBER and  hit enter
  9. type ./configure and  hit enter
  10. type make and  hit enter
  11. switch to your root user, or if user is a sudo user skip to next step
  12. 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.
  1. Click the start menu and click on run. In Vista click start->search type "run" hit enter.
  2. Type cmd and hit enter.
  3. In the next command PATH_TO_RAKNET_SWIG_FILES is the path to the swig directory. For example C:\RakNet\DependentExtensions\Swig
  4. Type cd PATH_TO_RAKNET_SWIG_FILES hit enter
  5. 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.
  6. Type MakeSwig.bat PATH_TO_RAKNETSOURCE PATH_TO_SWIG hit enter
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.
  1. Open a terminal if you are not already at one.
  2. In the next command PATH_TO_RAKNET_SWIG_FILES is the path to the swig directory. For example /home/usr/RakNet/DependentExtensions/Swig
  3. Type cd PATH_TO_RAKNET_SWIG_FILES hit enter
  4. Type chmod u+x MakeSwig.sh
  5. In the next command PATH_TO_RAKNETSOURCE is the path to the swig source directory. For example: /home/usr/RakNet/Source
  6. Type ./MakeSwig.sh PATH_TO_RAKNETSOURCE hit enter
 Generating the Swig Files Manually
Windows

Generate the Swig Files
  1. Click the start menu and click on run. In Vista click start->search type "run" hit enter.
  2. Type cmd and hit enter.
  3. In the next command PATH_TO_RAKNET_SWIG_FILES is the path to the swig directory. For example C:\RakNet\DependentExtensions\Swig
  4. Type cd PATH_TO_RAKNET_SWIG_FILES hit enter
  5. In the next command PATH_TO_RAKNETSOURCE is the path to the swig source directory. For example: C:\RakNet\Source
  6. Type C:\Swig\swig -c++ -csharp  -I"%1" -I"SwigInterfaceFiles" -outdir SwigOutput\SwigCSharpOutput -o SwigOutput\CplusDLLIncludes\RakNet_wrap.cxx SwigInterfaceFiles\RakNet.i hit enter
Linux

Generate the Swig Files
  1. Open a terminal
  2. In the next command PATH_TO_RAKNET_SWIG_FILES is the path to the swig directory. For example /home/usr/RakNet/DependentExtensions/Swig
  3. Type cd PATH_TO_RAKNET_SWIG_FILES hit enter
  4. In the next command PATH_TO_RAKNETSOURCE is the path to the swig source directory. For example: /home/usr/RakNet/Source
  5. 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
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.

Creating the Swig Wrapped DLL Project

Windows


Note: There is a directory called DLL_Swig that contains a project that makes the Swig files, builds the DLL, and copies it to the C# sample. The next steps are for making your own project.

Creating the Swig  DLL

  1. 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.
  2. Add the source files under the /Source directory to the project.
  3. Add RakNet.cxx from Swigtools/CplusDLLIncludes
  4. Add to "Additional Include Directories" your directory with the source files.
  5. 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.
  6. 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).
  7. Add _RAKNET_DLL to the Preprocessor Definitions. In VS Project Properties -> Configuration Properties -> C/C++ -> PreProcessor -> Preprocessor Definitions
  8. Set the character set to "not set".In VS Project Properties -> Configuration Properties -> General-> Character Set
  9. Optionally set your preprocessor directives.
  10. 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.

  1. In the next command PATH_TO_RAKNET_SWIG_FILES is the path to the swig directory.  EX:: ../DependentExtensions/Swig
  2. g++ *.cpp PATH_TO_RAKNET_SWIG_FILES/SwigOutput/CplusDLLIncludes/RakNet_wrap.cxx -l pthread -I./ -shared -o RakNet
  3. Note: In the previous command -l pthread is lower case L while -I./ is uppercase i.
  4. A file called RakNet should be created that will be copied in the next section

Creating the C# project
Windows

C# Project Setup
  1. Create a new C# project. In the included sample a console project is used.
  2. If you wish to keep the project cleaner create a new folder called Swig. Right click the project and go to Add -> New folder
  3. 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.
  4. Go to Add -> Existing Item. 
  5. Browse to the SwigOutput\SwigCSharpOutput directory.
  6.  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.
  7. Copy the DLL created in the previous step to the same folder as the binary. Example: bin\Debug
C# Sample
 
A C# sample project is included under Samples/Swig. 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.

Linux

Installing Mono, if it is not Installed

Note: 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.

  1. Go to http://www.go-mono.com/mono-downloads/download.html
  2. Download the linux version
  3. open a terminal
  4. change to the directory you downloaded mono to..
  5. type tar xzvf mono-VERSION.tar.gz hit enter
  6. type cd mono-VERSION hit enter
  7. type ./configure --prefix=/usr/local and  hit enter
  8. type make and  hit enter
  9. switch to your root user, or if user is a sudo user skip to next step
  10. 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
  1. Copy the dynamic link library to /usr/lib and rename it to RakNet with no extension if it is not already.
  2. Copy the files in Swigtools/SwigCSharpOutput into your project directory.
  3. Create your main C# .cs file in that folder.
  4. Type gmcs *.cs -out:ExecutableName.exe where ExecutableName is the name you want and hit enter.
  5. The file can be ran with mono ExecutableName.exe

C# Sample
 
A C# sample is included under Samples/Swig/SwigLinux. The DLL file is not included and needs to be copied to /usr/lib as per the earlier instructions.
Limitations
Limitations
  1. BitStream may have problems if larger than 9 megabytes.


See Also

Index