Greetings esteemed viewer,
Following is my complete guide to compiling UnrealIRCd on the Windows platform! (The end result of a 6hr writing blitz and two overhauls! )
This guide has been written entirely from scratch, with reference to existing Windows compilation instructional material, particularly the 'compiling_win32.txt' file included with current UnrealIRCd releases, to ensure that no pre-existing information is left unaddressed. The guide aims to be 'The Complete Reference' to compiling UnrealIRCd on Windows, from a basic standard compile of UnrealIRCd, through to compiling modules and UnrealIRCd with SSL/ZLIB/Remote Includes support. I have tried to ensure this guide is as comprehensive as possible, answering all common questions concerning compiling UnrealIRCd on Windows, catering to both newbies and more advanced Windows UnrealIRCd users alike.
This guide was originally written as a short update to the instructions in the compiling_win32.txt file concerning building the 'support applications' on Windows required to build UnrealIRCd with SSL/ZLIB/Remote Includes support, that were out-of-date for newer versions of the support apps, and a bit of a mess. The guide evolved into a highly comprehensive guide to compiling the support apps, and from there, a total overhaul of the compiling_win32.txt document. I hope this guide is of use to the UnrealIRCd community, and if the UnrealIRCd developers approve of the guide, I would be happy to convert it to a simple txt document format for inclusion in the UnrealIRCd official releases as a replacement to the current 'compiling_win32.txt' document.
Any suggestions on how this guide can be improved, spelling/grammar corrections, comments and constructive criticism would be greatly appreciated, as I finalize the guide.
Finally, if the community has issues with the guide, thinks it's got serious problems, or is just 'plain rubbish', I won't take any offense.
Enjoy the guide !
Compiling UnrealIRCd on Windows
Introduction
UnrealIRCd is a highly advanced, feature-rich IRC Daemon that supports a range of operating systems, including all 32bit versions of Microsoft Windows.
UnrealIRCd can be installed onto a Windows system in two different ways:
a) By downloading and installing the UnrealIRCd binary, a complete version of UnrealIRCd 'pre-built' from the source code with all the optional features, that can simply be installed onto a Windows system through an installer just like any other standard Windows application. This is by far the easiest method of setting up UnrealIRCd on a Windows system.
b) By downloading and compiling the UnrealIRCd source code, allowing you to customise UnrealIRCd to your liking to a much greater extent, as well as compile additional modules. This is a much more time consuming method, and potentially more difficult, however, it can offer benefits that are not possible with the 'pre-built' binary.
If your download of UnrealIRCd is an executable, you have chosen option A, and can simply run the file to install the IRC Daemon. This document is not relevant to you and you can safely ignore it (and save yourself from a good deal of reading).
If your download of UnrealIRCd is a compressed archive, you have chose option B, in which case, you should read this document comprehensively, as it is your complete guide to compiling UnrealIRCd on the Windows platform.
This document is a comprehensive guide to compiling UnrealIRCd on the Windows platform. This guide covers all the basic topics of compiling UnrealIRCd on Windows, as well as some more advanced ones. Current topics that are covered in this guide include:
---How to complete a 'basic' compile of UnrealIRCd
---How to compile additional modules for UnrealIRCd
---What are 'support applications'?
---Which UnrealIRCd features require which support applications?
---How to compile the support applications for UnrealIRCd
---What files are required from the compile of each support application?
---How to complete an 'advanced' compile of UnrealIRCd
---Guide Info and Credits
Without further ado, on with the guide!
UnrealIRCd 'Basic' Compile
Completing a 'basic', that is, a standard, unmodified compile of UnrealIRCd is a relatively straightforward process. Such a compile will result in a fully-working version of UnrealIRCd, minus three features:
a) SSL Support
SSL Support allows the IRC Daemon to support SSL encrypted client connections, as well as SSL encrypted server links, allowing for a more secure IRC network.
b) Compression Support
Compression Support allows the IRC Daemon to compress traffic between server links, allowing for a reduction in server bandwidth usage.
c) Remote Includes Support
Remote Includes Support allows the IRC Daemon to retrieve configuration information from a remote server, allowing for centralised IRC configuration.
It is important to note that merely compiling the IRC Daemon with support for these technologies will not instantly mean you have their respective benefits. All three of these features must be configured when you create the IRC Daemon's configuration file(s). By their nature, these features can be a lot of work to implement, and hence, are recommended to be implemented only be experienced IRC users.
If you require any of these features in the IRC Daemon, than the basic compile is not for you. You should skip this section and move on to the section explaining what are 'support applications'.
Compiling UnrealIRCd (Basic Compile)
The following are detailed instructions on how to complete a basic compile of UnrealIRCd:
Before we begin the basic compile of UnrealIRCd, you must ensure you have Microsoft Visual C++ installed, as a pre-requisite for compiling UnrealIRCd. Microsoft Visual C++ 7.0 (Visual Studio .NET 2002) or newer is highly recommended. Compiling under VC++ 6 may work, but is strongly discouraged. You may run into difficulties, and compiling under VC++ 6 or earlier is not tested. As such, it is assumed in this guide that you are compiling under VC++ 7.0 or newer, if you're not, you're pretty much on your own.
1. Start the Visual Studio .NET Command Prompt.
2. Browse to the directory where you extracted UnrealIRCd.
3. Start the compile with: 'nmake -f makefile.win32'
On completion, assuming there were no errors, your copy of UnrealIRCd is compiled! You will now have the following files:
wircd.exe --- The UnrealIRCd executable
unreal.exe --- UnrealIRCd Services Handler (for installing and running UnrealIRCd as a Windows NT Service)
src\win32\tre.dll --- The TRE Regex Library DLL (required by UnrealIRCd)
Simply copy these three files to a new directory, where you can run UnrealIRCd from. You now need to create your UnrealIRCd configuration file. Please refer to the 'unreal32docs.html' file in the docs folder for more information.
UnrealIRCd 'Module' Compile
UnrealIRCd supports 'modules', which are blocks of code that typically add additional features, that can be dynamically inserted and removed from the IRC Daemon. Modules are typically programmed by a third-party programmer, but there are some modules coded by the UnrealIRCd development team, that have not been included with the official distribution. Modules are added to your IRC Daemon through a DLL (Dynamic Link Library) file. If you have downloaded the source code of a Windows compatible UnrealIRCd module, it needs to be compiled, before it can be used by UnrealIRCd.
Compiling UnrealIRCd Modules
The following are detailed instructions on how to compile UnrealIRCd modules:
Before we begin compiling the UnrealIRCd module, you must first uncompress the module archive (if it came in a compressed archive), and copy the module source code (the .c file) to the src\modules directory.
1. Start the Visual Studio .NET Command Prompt.
2. Browse to the directory where you extracted UnrealIRCd.
3. Start the compile with: 'nmake -f makefile.win32 custommodule MODULEFILE=modulename'
Where 'modulename' is the name of the module. For example, if the module's file name is 'm_soper.c', you would substitute 'modulename' for 'm_soper'.
On completion, assuming there were no errors, your UnrealIRCd module is compiled! You will now have a new DLL file located in src\modules\modulename.dll.
To use the module with UnrealIRCd, copy the module's DLL file to your compiled UnrealIRCd directory, and consult the 'unreal32docs.html' file located in the docs directory for more information on installing modules.
What are 'support applications'?
UnrealIRCd has a myriad of features, however, some of these features require some additional 'support applications' to be compiled and referenced before an UnrealIRCd compile, in order for the IRC Daemon to support them. These support applications are generally a breeze to compile on a UNIX based platform, as they are designed for UNIX as their primary target platform. However, compiling the support applications on Windows can be a bit challenging, particularly for those without programming and development knowledge.
This leaves those who wish to compile UnrealIRCd on Windows with features which require additional support applications with two options:
a) Compile the additional support applications themselves. This is a time-consuming process, and can also be very complex. Some of the support applications require numerous tweaks and modifications in order to successfully compile on Windows. This guide provides indepth instructions on how to complete these procedures, however, it's not for the 'faint of heart'.
b) Download the latest available 'pre-built' versions of the support applications for use with UnrealIRCd. These are the latest versions available that have been compiled by the UnrealIRCd developers. They are guaranteed to work with UnrealIRCd, and will shorten what might take over an hour of compiling down to a five minute download. However, they may not be the latest versions that are described in this guide. This should only be of concern to those who like to compile their IRCd with the 'bleeding edge' support applications.
If you choose Option A, continue on reading, and proceed through the detailed instructions on compiling the support applications under Windows.
If you choose Option B, you should download the latest available 'pre-built' versions of the support applications for use with UnrealIRCd. The UnrealIRCd developers generally release a new 'pack' of the latest pre-built versions of the support applications for use with UnrealIRCd with each new official UnrealIRCd release. These packs are available at: http://vulnscan.org/unrealwin32dev/. Alternatively, r3mbr4ndt, a member of the UnrealIRCd community and contributor to this guide, provides pre-built binaries of the latest versions of the support applications for use with UnrealIRCd, and other useful resources, at his website located at: http://unreal.hates.tv.
Continue on reading, as there is a lot of important information ahead you should know, but you can skip the section on compiling the support applications on Windows.
Which UnrealIRCd features require which support applications?
SSL Support <-> Requires OpenSSL
Compression Support <-> Requires zlib
Remote Includes Support <-> Requires cURL with c-ares support
UnrealIRCd 'Support Applications' Compile
The following are detailed instructions on how to compile each support application on the Windows platform:
IMPORTANT INFORMATION
1. The following instructions are for use with Microsoft Visual Studio .NET and the Microsoft Visual Studio .NET C++ Compiler. These instructions were tested with Microsoft Visual Studio .NET 2003, however, they should be applicable to Microsoft Visual Studio .NET 2002 and 2005 with little or no modification. While it is undoubtedly possible to compile the support applications with other IDE's and compilers, support for this will not be given here, and is also not recommended.
2. If you are intending to compile cURL for use with UnrealIRCd, you must also compile c-ares. cURL requires a compiled version of c-ares in order to successfully compile.
c-ares - http://daniel.haxx.se/projects/c-ares/ - Instructions tested on c-ares v1.3.0
c-ares is complex to compile on the Windows platform for use with UnrealIRCd, requiring numerous tweaks.
1. Download the source code from the above URL and uncompress to a location of your choice.
2. Open the c-ares-x.x.x\vc\vc.dsw file in Microsoft Visual Studio .NET. When prompted to convert the project to the current Visual C++ project format, choose 'Yes To All'.
3. Right-click on the 'areslib' project and choose 'Properties', and perform the following tweaks:
-Browse to 'Configuration Properties -> C/C++ -> Code Generation'
-Under 'Runtime Libary' choose 'Multi-threaded DLL (/MD)'
-Click 'OK'
4. Expand the 'areslib' project, right-click on 'Source Files', choose 'Add -> Add Existing Item...', and add the following files:
-c-ares-x.x.x\ares_parse_aaaa_reply.c
-c-ares-x.x.x\bitncmp.c
-c-ares-x.x.x\inet_net_pton.c
5. Expand the 'areslib' project, right-click on 'Header Files', choose 'Add -> Add Existing Item...', and add the following files:
-c-ares-x.x.x\setup.h
6. Expand the 'areslib' project, expand the 'Header Files' folder, open the 'setup.h' file for editing, and perform the following tweaks:
-The following three lines should be added to the bottom of the 'setup.h' file, but before the final '#endif':
-#define HAVE_IOCTLSOCKET
-#define HAVE_STRUCT_IN6_ADDR
-#include <IPExport.h>
-Save and close
7. Right-click on the 'areslib' project, and select 'Build'.
8. Close Microsoft Visual Studio .NET, choosing to save all changes.
You should now have successfully compiled c-ares for use with UnrealIRCd.
These instructions should be applicable to the tested version of c-ares. These instructions may or may not work with future versions, and it is not recommended that you try.
cURL - http://curl.haxx.se/ - Instructions tested on cURL v7.15.0
cURL is complex to compile on the Windows platform for use with UnrealIRCd, requiring numerous tweaks.
1. Download the source code from the above URL and uncompress to a location of your choice.
2. Open the curl-x.x.x\lib\curllib.dsw file in Microsoft Visual Studio .NET. When prompted to convert the project to the current Visual C++ project format, choose 'Yes To All'.
3. Right-click on the 'curllib' project and choose 'Properties', and perform the following tweaks:
-Browse to 'Configuration Properties -> C/C++ -> General'
-Under 'Additional Include Directories' add the path to your c-ares directory. (e.g. c:\c-ares-x.x.x)
-Browse to 'Configuration Properties -> C/C++ -> Code Generation'
-Under 'Runtime Libary' choose 'Multi-threaded DLL (/MD)'
-Browse to 'Configuration Properties -> Linker -> General'
-Under 'Additional Library Directories' add the path to your c-ares Debug directory. (e.g. c:\c-ares-x.x.x\vc\areslib\Debug)
-Browse to 'Configuration Properties -> Linker -> Input'
-Under 'Additional Dependencies' add 'areslib.lib'
-Click 'OK'
4. Expand the 'curllib' project, right-click on 'Header Files', choose 'Add -> Add Existing Item...', and add the following files:
-curl-x.x.x\include\curl\multi.h
5. Expand the 'curllib' project, expand the 'Header Files' folder, open the 'config-win32.h' file for editing, and perform the following tweaks:
-The following line should be added to the bottom of the 'config-win32.h' file, but before the 'This section is for compiler specific defines.' segment:
-#define USE_ARES 1
-Save and close
6. Expand the 'curllib' project, expand the 'Header Files' folder, open the 'multi.h' file for editing, and perform the following tweaks:
-Modify the '#include <winsock2.h>' line to read '#include <winsock.h>'
-Save and close
7. Right-click on the 'curllib' project, and select 'Build'.
8. Close Microsoft Visual Studio .NET, choosing to save all changes.
You should now have successfully compiled cURL for use with UnrealIRCd.
These instructions should be applicable to the tested version of cURL. These instructions may or may not work with future versions, and it is not recommended that you try.
OpenSSL - http://www.openssl.org/ - Instructions tested on OpenSSL v0.9.8a
OpenSSL is without a doubt the easiest support application to compile on the Windows platform, requiring no modification of the standard compile procedure to successfully compile and use with UnrealIRCd. Considering that no special modification of the program is required for successful compilation, and OpenSSL includes excellent documentation, detailed instructions will not be provided for compiling this support application.
1. Simply download the source code from the above URL, uncompress it, and follow the instructions provided in the 'INSTALL.W32' file for 'Visual C++'.
You should now have successfully compiled OpenSSL for use with UnrealIRCd.
These instructions should be applicable to the tested version of OpenSSL, and all future versions of OpenSSL, at the current time.
zlib - http://www.zlib.net/ - Instructions tested on zlib v1.2.3
zlib is relatively simple to compile on the Windows platform for use with UnrealIRCd, requiring only some minor tweaks.
1. Download the source code from the above URL and uncompress to a location of your choice.
2. Open the zlib-x.x.x\win32\Makefile.msc file for editing (Notepad is recommended), and perform the following tweaks:
-Change the 'SHAREDLIB' line to equal 'zlibwapi.dll'
-Change the 'IMPLIB' line to equal 'zlibwapi.lib'
-Add '-D ZLIB_WINAPI' to the end of the 'CFLAGS' line
-Save and close
3. Open the Visual Studio .NET Command Prompt, browse to the zlib directory, and run the following command:
-nmake -f win32\Makefile.msc
You should now have successfully compiled zlib for use with UnrealIRCd.
These instructions should be applicable to the tested version of zlib, and may be compatible with future versions of zlib.
What files are required from the compile of each support application?
The following is detailed information on which files output from the compile of the support applications are:
a) Required by UnrealIRCd during the compile of the IRC Daemon.
AND
b) Required by UnrealIRCd during the operation of the IRC Daemon.
IMPORTANT INFORMATION
1. Where a directory that contains files required by UnrealIRCd is specified below, do not include files from sub-directories.
e.g. If all Header files (*.h) are required from zlib-x.x.x, do not include Header files from zlib-x.x.x\examples.
c-ares - http://daniel.haxx.se/projects/c-ares/
UnrealIRCd does not require any files from the c-ares compile either during compile or operation of the IRC Daemon.
The c-ares files are required only by cURL during a compile.
cURL - http://curl.haxx.se/
The following files are required by UnrealIRCd during compilation of the IRC Daemon:
-All Header file(s) (*.h) located in curl-x.x.x\include\curl
-All Dynamic Link Library file(s) (*.dll) located in curl-x.x.x\lib\Debug
-All Library file(s) (*.lib) located in curl-x.x.x\lib\Debug
The following files are required by UnrealIRCd during operation of the IRC Daemon:
-All Dynamic Link Library file(s) (*.dll) located in curl-x.x.x\lib\Debug
OpenSSL - http://www.openssl.org/
The following files are required by UnrealIRCd during compilation of the IRC Daemon:
-All Header file(s) (*.h) located in openssl-x.x.x\inc32\openssl
-All Dynamic Link Library file(s) (*.dll) located in openssl-x.x.x\out32dll
-All Library file(s) (*.lib) located in openssl-x.x.x\out32dll
The following files are required by UnrealIRCd during operation of the IRC Daemon:
-All Dynamic Link Library file(s) (*.dll) located in openssl-x.x.x\out32dll
zlib - http://www.zlib.net/
The following files are required by UnrealIRCd during compilation of the IRC Daemon:
-All Header file(s) (*.h) located in zlib-x.x.x
-All Dynamic Link Library file(s) (*.dll) located in zlib-x.x.x
-The 'zlibwapi.lib' Library file located in zlib-x.x.x
The following files are required by UnrealIRCd during operation of the IRC Daemon:
-All Dynamic Link Library file(s) (*.dll) located in openssl-x.x.x\out32dll
UnrealIRCd 'Advanced' Compile
The following is detailed information on how-to configure UnrealIRCd to compile with additional features selected, and reference the compiled support applications to UnrealIRCd for use during the compile:
Selecting which additional feature(s) you wish UnrealIRCd to support
By default, UnrealIRCd is set to compile on the Windows platform without SSL/Compression/Remote Includes support. As such, we must modify the UnrealIRCd 'MakeFile' (the file which instructs the Visual Studio compiler how to compile UnrealIRCd) to instruct UnrealIRCd to compile the select additional features which we require. This is an easy task.
1. Download the UnrealIRCd source code (I'm hoping you already know the URL ) and uncompress to a location of your choice.
2. Open the Unrealx.x.x\makefile.win32 file for editing (Notepad is recommended).
3. Simply uncomment (remove the preceding hash symbol) the line(s) pertaining to the feature(s) you wish to enable in the IRC Daemon.
e.g. To enable SSL Support, you would change the line from '#USE_SSL=1' to 'USE_SSL=1'
Once you have uncommented the lines pertaining to the additional features you wish to enable support for in the IRC Daemon, procede to the next step.
Specifying the locations(s) of the relevant support application(s)
Once you have enabled the feature(s) you wish to enable support for in the IRC Daemon, you must specify the location of the relevant support application(s), so that UnrealIRCd can successfully locate the required support application files to compile in your required feature. This is not a difficult task. Detailed information on how each of the six possible 'location' lines should be set follows:
LIBCURL_INC_DIR
Must point to a folder on your hard-drive, that contains a folder labelled 'curl' that contains the relevant cURL header files.
LIBCURL_LIB_DIR
Must point to a folder on your hard-drive, that contains the relevant cURL library and dynamic link library files.
ZLIB_INC_DIR
Must point to a folder on your hard-drive, that contains the relevant zlib header files.
ZLIB_LIB_DIR
Must point to a folder on your hard-drive, that contains the relevant zlib library and dynamic link library files.
OPENSSL_INC_DIR
Must point to a folder on your hard-drive, that contains a folder labelled 'openssl' that contains the relevant OpenSSL header files.
OPENSSL_LIB_DIR
Must point to a folder on your hard-drive, that contains the relevant OpenSSL library and dynamic link library files.
Once you have completed setting the location(s) of the compiled support application(s) in the MakeFile, you have successfully finished preparing UnrealIRCd to compile in your selected additional features. You should now complete the compile procedure documented in the UnrealIRCd 'Basic' Compile section, to compile your IRC Daemon with additional features.
Guide Info and Credits
This guide to compiling UnrealIRCd on Windows I have put together, hopefully as a definitive guide to compiling UnrealIRCd on Windows, that caters to both newbie's and veteran's. I hope you liked the guide, and found it useful and informative. If you have any suggestions/feedback/flames, please let me know!
I intend to keep this guide as up-to-date as possible as time permits. So please check back as required, for updated information on compiling UnrealIRCd on the Windows platform (particularly new versions of the support applications).
Thanks to syzop, for some helpful tips for compiling the support applications, and the correspondence concerning updating the somewhat dated 'compiling_win32.txt' document.
Thanks to r3mbr4ndt, for numerous contributions to the compiling the support applications segment of the guide.
Thanks to the c-ares mailing list, for some helpful tips for getting c-ares to compile on the windows platform.
This guide was created by Ralish as a small contribution to the UnrealIRCd community and the hardworking development team.