BuildingWindowsDependencies - 0ad

0ad/0ad

Table of Contents

boost
enet
FCollada
gloox
libcurl
libiconv
libicu
libpng
libsodium
libxml2
NVTT
OpenAL Soft
SpiderMonkey
vorbis
zlib

This page will document how to build the game's Windows dependencies, useful for updating them to newer versions.

Important

Windows dependencies are prebuilt and served over Subversion at svn.wildfiregames.com/public/windows-libs/trunk. The libraries\get-windows-libs.bat is used to retrieve them. Whenever a library is upgraded, it is necessary to update the revision number in the download script. The correct step order for a library upgrade is as follows:

Update the library, commit it to SVN, and write down the new revision number.

Create a PR in which the revision number in libraries\get-windows-libs.bat is updated. CI will pick that up and test it.

Merge the PR to the main repository.

Carefully following these steps allows the git commits to remain atomic and buildable at all times. Checking out an older commit will make the script download older and compatible library versions.

This is a work in progress and incomplete. It can also include libraries that are not (yet) dependencies.

boost

Note: bcp will be used to generate a subset of Boost libs from the game's source code.

Note: This works as well with VS 2015 and 2017, just start the correct Tools Command Prompt and replace the toolset version by 14.0_xp or 14.1_xp.

Command line MSVC build:
- Download Boost Windows source archive and extract somewhere (X:\path\to\boost_x_xx_x)
- Run VS2013 x86 Native Tools Command Prompt from the start menu (under Visual Studio 2013 > Visual Studio Tools)
- Change directory to Boost source location
```
cd X:\path\to\boost_x_xx_x
md minimal
```
- Run bootstrapper to build Boost.Build
```
bootstrap.bat
```
- Build bcp tool
```
b2.exe tools/bcp
```
- Run bcp on game's source code (from X:\path\to\source) to generate subset of Boost libs in minimal\:
```
SET 0ad_source=X:\path\to\source
FOR /f "tokens=*" %i IN ('dir /s /b %0ad_source%\*.cpp %0ad_source%\*.h %0ad_source%\*.hpp') DO dist\bin\bcp.exe --scan --boost=X:\path\to\boost_x_xx_x %i minimal >> bcp.log 2>&1
```
- Copy these files to minimal\ (bcp can be used to do this, if desired):
  - b2.exe
  - bjam.exe
  - boostcpp.jam
  - boost-build.jam
  - project-config.jam }}}
- Copy tools to minimal\tools
- Copy libs\config to minimal\libs\config
- Build filesystem and system libs into minimal\stage directory with the XP support toolset
```
cd minimal
b2.exe --with-filesystem --with-system --toolset=msvc-12.0_xp variant=debug,release link=static runtime-link=shared threading=multi stage
```
- stage\lib contains debug and release multithreaded static libs to copy into libraries\win32\boost\lib:
  - libboost_system-vc120-mt-x_xx.lib
  - libboost_system-vc120-mt-gd-x_xx.lib
  - libboost_filesystem-vc120-mt-x_xx.lib
  - libboost_filesystem-vc120-mt-gd-x_xx.lib
- minimal\boost contains headers to copy into libraries\win32\boost\include

enet

Download the latest source code from http://enet.bespin.org/Downloads.html.
Follow the instructions at http://enet.bespin.org/Installation.html:
- Open enet.dsp and upgrade the project.
- In the project properties:
  - For all configurations, add ws2_32.lib and winmm.lib to the list of linked libraries.
  - For the Debug configuration, add the d suffix to the Target name so it becomes $(ProjectName)d.
- Build the Debug and Release versions.
- In the project properties, for all configurations, change the target type to a DLL. Add ENET_DLL to the list of preprocessor definitions.
- Build the Debug and Release versions once more.
Copy Debug/enetd.lib and Release/enet.lib to libraries/win32/enet/lib/
Copy Debug/enetd.dll and Release/enet.dll to binaries/system/
Copy include/enet to libraries/win32/enet/include/

FCollada

Open libraries/source/fcollada/src/FCollada/FCollada.sln in VS. Let it upgrade the project.
Switch to v120_xp toolset for compatibility with WinXP:
- Open the properties for the FCollada project
- Change the Configuration to All Configurations
- Change Platform Toolset to Visual Studio 2013 - Windows XP (v120_xp)
- Disable the treat warning as error flag.
Build Debug DLL Win32 and Release DLL Win32. Ignore the Unicode and Retail configurations.
In both configurations, FColladaTest will fail to link. This is not an issue. You can delete the FColladaTest project if you want to feel better about the build output.
Next to FCollada.sln, there is now an Output directory.
- Copy Output/FColladaD.lib and Output/FCollada.lib to libraries/source/fcollada/lib/.
- Copy Output/Debug DLL Win32/FColladaD.dll and Output/Release DLL Win32/FCollada.dll.
- If you need the debug symbols, they are in Output/Debug DLL Win32/FCollada/FCollada.pdb.

Alternatively you can use this script after updating the sln with visual studio.

gloox

On Windows, we need to use the trunk version of gloox (future 1.1.x) to support TLS (#4705).

Checkout the latest SVN revision at svn://svn.camaya.net/gloox/trunk.
Open gloox.vcproj in VS. Let it upgrade the project.
Fix the Debug configuration:
- Right-click the gloox-1.0 project and click Properties
- Copy-paste the Output directory value from the Release project (it should be $(SolutionDir)$(Configuration)\ instead of some hardcoded thing)
- Add the d suffix to the Target name so it becomes $(ProjectName)d
Use the correct compiler v141_xp by changing it in "All Configurations"
Add all recent files to the solution by directly right-clicking the gloox-1.0 project and clicking "Add > Add Existing Element" then adding all source files directly under src/ (not examples nor tests).
In the 8.1 Windows Kit, SChannel does not support DTLS, so remove the cases related to it in the switches lines 324 and 327, and 742 and 747 of tlsschannel.cpp.
Build the Release and Debug configurations
Copy Debug/gloox-1.0d.lib and Release/gloox-1.0.lib to libraries/win32/gloox/lib/
Copy Debug/gloox-1.0d.dll and Release/gloox-1.0.dll to binaries/system/
Copy all the header files from src to libraries/win32/gloox/include/gloox

Now we need to rebuild the glooxwrapper project. Just run update-workspaces.bat with the argument --build-shared-glooxwrapper and build the Release and Debug configurations of the game.

libcurl

Note: the included CMake scripts are outdated, but there are also untested makefiles for a command line build

Bundled MSVC project:
- Download libcurl source and extract somewhere
- Open projects\Windows\VC12\curl-all.sln
- Switch to v120_xp toolset for compatibility with WinXP:
  - Open the properties for the libcurl project
  - Change the Configuration to All Configurations
  - Change Platform Toolset to Visual Studio 2013 - Windows XP (v120_xp)
- Build both DLL Debug - DLL Windows SSPI and DLL Release - DLL Windows SSPI configurations (in order to enable native SSL support).
- Binaries are located in build\Win32\VC12\DLL Debug\ and build\Win32\VC12\DLL Release\
  - Copy the *.dll files to binaries\system, *.lib files to libraries\win32\libcurl\lib
- Copy the *.h files from include\curl to libraries\win32\libcurl\include\curl

libiconv

Note: iconv doesn't support MSVC anymore, only mingw and cygwin

Create Visual Studio project: http://www.codeproject.com/Articles/302012/How-to-Build-libiconv-with-Microsoft-Visual-Studio

libicu

Download the latest release from here.
Make sure MSBuild is in your path.
Run MSBuild.exe source\allinone\allinone.sln /v:q /m:4 /p:Configuration=Release /p:Platform=Win32 /p:SkipUWP=true /p:PlatformToolset=v140_xp
Copy the dlls icu*.dll in bin/ to binaries/system
Copy the libs in lib/ to libraries/win32/icu/lib
Copy the contents of include/ libraries/win32/icu/include

libpng

Note: Depends on zlib, so if you're building it too, do that first. Note down the install path where CMake installed the zlib build output.

CMake GUI-based build:
- Download libpng source .zip and extract somewhere (X:\path\to\lpng1xxx)
- Open cmake-gui (v3.16 in this example)
- Set source location to the X:\path\to\lpng1xxx
- Set build location to X:\path\to\lpng1xxx\build (so the build files will be separate from the source)
- Press Configure
  - Choose Yes to create the build directory if it doesn't exist
- Choose Visual Studio 14 2015 default native compiler as generator. Set the value of Optional toolset to use to v140_xp (to use the XP compatible toolset), then Finish
- There should be an error because it can't find zlib yet
- Set ZLIB_ROOT to the install path of the zlib build output
- Change CMAKE_INSTALL_PREFIX to X:\path\to\lpng1xxx\installdir (install is not possible because of the existing INSTALL file)
- Press Configure until there are no errors or red entries
- Press Generate
- Press Open project
- Optional DLL version info: Right-click on the png project, click Add > Existing element and select lpng1xxx\scripts\pngwin.rc
- Build solution for Debug configuration, there should be no errors. Build the INSTALL project to copy files to the install folders set up earlier
- Repeat for Release configuration
- lpng1xxx\installdir should contain the newly built libs

libsodium

Download the latest source from https://download.libsodium.org/libsodium/releases/.

It contains a folder builds/msvc/ with all the solutions for recent and old versions of Visual Studio. Pick yours.

Open Project > Properties.

Select All configurations and change the toolset to support target XP.
Select all Debug configurations (either one by one or with the multiple selection tool) and change Target Name so that d is added to the filename base (for instance $(TargetName)d instead of $(TargetName)).
Build both Dynamic configurations.
Copy bin/Win32/{Debug,Release}/toolset/dynamic/libsodium{d,}.dll to binaries/system/.
Copy bin/Win32/{Debug,Release}/toolset/dynamic/libsodium{d,}.lib to libraries/win32/libsodium/lib/.
Copy headers to libraries/win32/libsodium/include/. It looks like the build doesn't create a minimal folder of headers, so my advice is downloading the zip with prebuilt libs for msvc from the download page and using the include folder from that.

libxml2

Note: Depends on iconv, so if you're building it too, do that first.

Command line MSVC build:

[Download libxml2]ftp://xmlsoft.org/libxml2/ source tarball and extract somewhere (X:\path\to\libxml2-x.x.x)
Open Windows command prompt in the libxml2-x.x.x\win32 subdirectory
Run configure script to install in X:\path\to\install and pull in iconv lib from X:\path\to\iconv (for SVN, this is libraries\win32\iconv)

cscript configure.js compiler=msvc prefix=X:\path\to\install include=X:\path\to\iconv\include lib=X:\path\to\iconv\lib

**Note:** spaces are NOT allowed in these paths!

There should be no errors if it completed successfully
Set MSVC build environment

"C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\vcvars32.bat"

Configure XP-compatible platform toolset (based on Windows XP Targeting with C++ in Visual Studio 2012)

SET INCLUDE=%ProgramFiles(x86)%\Microsoft SDKs\Windows\7.1A\Include;%INCLUDE%
SET PATH=%ProgramFiles(x86)%\Microsoft SDKs\Windows\7.1A\Bin;%PATH%
SET LIB=%ProgramFiles(x86)%\Microsoft SDKs\Windows\7.1A\Lib;%LIB%
SET CL=/D_USING_V110_SDK71_
SET LINK=/SUBSYSTEM:WINDOWS,5.01

Modify Makefile.msvc to search for correct libiconv lib:

!if "$(WITH_ICONV)" == "1"
LIBS = $(LIBS) libiconv.lib
!endif

Build and install

nmake /f Makefile.msvc
nmake /f Makefile.msvc install

NVTT

Note: We build the custom version included in SVN. Depends on libpng and zlib, so if you're building those too, do that first.

CMake GUI-based build:
- Download and install Microsoft DirectX SDK (June 2010)
- Open cmake-gui (v3.16 in this example)
- Set source location to X:\path\to\0ad\libraries\source\nvtt\src
- Set build location to X:\path\to\0ad\libraries\source\nvtt\src\build
- Press Configure
  - Choose Yes to create the build directory if it doesn't exist
- Choose Visual Studio 14 2015 default native compiler as generator. Set the value of Optional toolset to use to v140_xp (to use the XP compatible toolset), then Finish
- Use Add Entry to set the location of the built libpng and zlib:
  - Set ZLIB_INCLUDE_DIR (Type PATH) to X:\path\to\0ad\libraries\win32\zlib\include
  - Set ZLIB_LIBRARY to (Type FILEPATH) X:\path\to\0ad\libraries\win32\zlib\lib\zlib1.lib
  - Set PNG_PNG_INCLUDE_DIR (this is not a typo) (Type PATH) to X:\path\to\0ad\libraries\win32\libpng\include
  - Set PNG_LIBRARY (Type FILEPATH) to X:\path\to\0ad\libraries\win32\libpng\lib\libpng16.lib
- Add Entry for NVTT_SHARED (Type BOOL) and set it to True.
- Change CMAKE_INSTALL_PREFIX to X:\path\to\0ad\libraries\source\nvtt\src\install
- Press Configure until there are no errors or red entries (warnings are OK)
- Press Generate
- Press Open project
- Build solution for RelWithDebInfo configuration.
- Build the INSTALL project by right-clicking on it (to copy files to the install folders set up earlier).
- X:\path\to\0ad\libraries\source\nvtt\src\install should contain all the newly built libs. The only one missing is the PDB, located at nvtt\src\build\src\nvtt\RelWithDebInfo\nvtt.pdb.

OpenAL Soft

CMake GUI-based build:
- Download and install Microsoft DirectX SDK (June 2010)
- Download OpenAL-Soft source and extract somewhere (X:\path\to\openal-soft-x.xx.x)
- Open cmake-gui (v3.2 in this example)
- Set source location to the X:\path\to\openal-soft-x.xx.x folder
- Set build location to X:\path\to\openal-soft-x.xx.x\build (this way the build files will be separate from the source)
- Press Configure
  - Choose Yes to create the build directory if it doesn't exist
- Choose Visual Studio 12 2013 default native compiler as generator, then Finish
- Add Entry, CMAKE_GENERATOR_TOOLSET as a String, and set the value to v120_xp (to use the XP compatible toolset)
- Change CMAKE_INSTALL_PREFIX to X:\path\to\openal-soft-x.xx.x\install
- Uncheck/turn off ALSOFT_UTILS
- Press Configure until there are no errors or red entries (warnings are OK)
- Press Generate
- In X:\path\to\openal-soft-x.xx.x\build, there should be an OpenAL.sln solution you can open in Visual Studio 2013. Open it
- Build solution for Release configuration
  - Build the INSTALL project by right-clicking on it (to copy files to the install folders set up earlier)
- openal-soft-x.xx.x\install should contain all the newly built libs

SpiderMonkey

Follow the instructions at [libraries/source/spidermonkey/README.txt]source:ps/trunk/libraries/source/spidermonkey/README.txt.

vorbis

Download the latest source code for libogg and libvorbis from https://xiph.org/downloads.
Create a folder in which you extract libogg-1.x.x and libvorbis-1.x.x.
First compile libogg DLLs:
- Open win32/VS2015/libogg_dynamic.sln. Accept to upgrade the solution.
- In the project properties, for all configurations, change the toolset to v140_xp.
- In the project properties, for the Debug configuration, change TargetName so that it ends with d (typically $(ProjectName)d instead of $(ProjectName).
- Compile both configurations.
- Copy win32/VS2015/Win32/{Debug,Release}/libogg{d,}.dll to binaries/system/.
- Copy win32/VS2015/Win32/{Debug,Release}/libogg{d,}.lib to libraries/win32/vorbis/lib/.
Then compile libogg_static:
- Open win32/VS2015/libogg_static.sln. Accept to upgrade the solution.
- In the project properties, for all configurations, change the toolset to v140_xp.
- Compile both configurations and don't copy anything, we don't distribute those.
Finally compile vorbis:
- In win32/VS2010/libogg.props, check that LIBOGG_VERSION is the same as the one you compiled, and check that paths seem to match. Else, fix them.
- Open libvorbis_dynamic.sln, accept to upgrade the solution.
- For both the libvorbis and libvorbisfile projects:
  - for all configurations, change the toolset to v140_xp.
  - for the Debug configuration, change TargetName so that it ends with d.
  - for all configurations, reset Linker > General > OutputFile and Linker > Advanced > ImportLibrary to their default values (which should contain $(TargetName)).
- For libvorbisfile (and vorbisdec and vorbisenc if you care), for the Debug configuration, in Linker > Input > Additional Dependencies, change libvorbis.lib to libvorbisd.lib.
- Compile both configurations.
- Copy win32/VS2010/Win32/{Debug,Release}/libvorbis{,file}{d,}.dll to binaries/system/.
- Copy win32/VS2010/Win32/{Debug,Release}/libvorbis{,file}{d,}.lib to libraries/win32/vorbis/lib/.
Copy include files for ogg and vorbis.

zlib

CMake GUI-based build:
- Download zlib source .zip and extract somewhere (X:\path\to\zlib-x.x.x)
- We will start by fixing the target name for the built library. In X:\path\to\zlib-x.x.x\CMakeLists.txt, find the line that adds the 1 to the DLL name.
```
Replace:
set_target_properties(zlib PROPERTIES SUFFIX "1.dll")
by:
set_target_properties(zlib PROPERTIES OUTPUT_NAME "zlib1")
```
That way, the debug DLL will be called zlib1d.dll and not zlibd1.dll. See https://github.com/madler/zlib/issues/273.
- Open cmake-gui (v3.16 in this example)
- Set source location to the X:\path\to\zlib-x.x.x folder
- Set build location to X:\path\to\zlib-x.x.x\build (this way the build files will be separate from the source)
- Press Configure
  - Choose Yes to create the build directory if it doesn't exist
- Choose Visual Studio 14 2015 default native compiler as generator. Set the value of Optional toolset to use to v140_xp (to use the XP compatible toolset), then Finish
- Change CMAKE_INSTALL_PREFIX to X:\path\to\zlib-x.x.x\install
- Delete all the INSTALL_* group entries and press Configure again. They should now all follow the path you specified during the previous step
- Add a new BUILD_SHARED_LIBS entry and set its value to TRUE
- Press Configure until there are no errors or red entries
- Press Generate
- Press Open project
- Build solution for Debug configuration, there should be no errors
  - Build the INSTALL project by right-clicking on it (to copy files to the install folders set up earlier)
- Repeat for Release configuration
- zlib-x.x.x\install should contain all the newly built libs