WindowsBuild

Windows Build

Prerequisites

Mercurial

Install TortoiseHg (5.6 or greater) 64bit from http://www.mercurial-scm.org

Visual Studio

Install MSVC Community from https://visualstudio.microsoft.com/downloads/
When installing, choose Desktop Development with C++

Help

Goto to http://microsoft.com and search for html help workshop download. Download htmlhelp.exe and run it. This will install the HTML Help tools.

GetText

Download gettext from http://gnuwin32.sourceforge.net/packages/gettext.htm and install using the setup program.

NSIS

NSIS is used to create the installer for Windows. Download from https://nsis.sourceforge.io/

FreeImage

FreeImage: http://freeimage.sourceforge.net/ is used for loading and rendering the backgrounds.

Libzip/ZLib

Libzip: https://libzip.org/ and zlib: https://github.com/madler/zlib brings the functionality to read and write the extended file format. See [HowtoBuildLibzip] for instructions on building libzip and zlib in Visual Studio.

MiniXML

Attention At the time of writing, MiniXML 4.x.y is available. This cannot be used for XTrackCAD. Get version 3.3.1 instead.
The following instructions are valid for that version.

Creating SVG exports depends on the MiniXML library: https://www.msweet.org/mxml/. If this library cannot be found in the build system XTrackCAD is built anyway but won't include SVG export.
Note The library and the main program share objects from the C Runtime Library. Therefore it is necessary to select the same runtime when building the mxml library and XTrackCAD. Using the the vcnet/mxml.sln provided with the source package of MiniXML build the solution mxmlstat. After complete copy mxmlstat.lib and mxml.h to the external tree into the ((architecture))/mxml directory eg x64/mxml.

Optional development tools

The following tools can be used to make development easier but are not required.

• CMocka: https://cmocka.org/ is a unit testing framework that can be used for testing some features.
• Doxygen: http://www.doxygen.nl/ documentation can be created to ease navigation through the source code.
• For some document generation pandoc: https://pandoc.org/ is used.

Build

Third Party Tools

Not all of these libs have a standard installation method for Windows. For XTrackCAD the following setup is recommended:
1) create a directory for all external dependencies, eg. C:\Users\<yourid>\Documents\XTrackCAD/XTCEXTERN
1) set the environment variable XTCEXTERNALROOT to that complete path.
1) in the root directory create a directory x86 for the 32 bit dependencies and x64 for the 64-bit dependencies.
1) Inside that directory create additional directories per dependency.</yourid>

The complete structure is

Root	Architecture	Folder	Contents
XTCEXTERN	x64	FreeImage	FreeImage.dll, FreeImage.h, FreeImage.lib
		libzip	bin
			include
			lib
			share
		mxml	mxml.h, mxmlstat.lib
		zlib	bin
			include
			lib
			share
	x86	FreeImage	FreeImage.dll, FreeImage.h, FreeImage.lib
		libzip	as above for x64
		mxml	as above for x64
		zlib	as above for x64

Note: the contents of the zlib and libzip directories isn't shown in detail. This will be filled correctly by using the approach described in HowtoBuildLibzip.

Using this setup the CMake modules included will automatically find and resolve all dependencies for building under Windows. Use CMake-GUI to create the project files needed by Visual Studio. You can have both 32-bit and 64-bit builds by using separate directories for each destination. I set up my source and build folders within my main XTrackCAD folder like this:

Root	Folder	Contents
XTrackCAD	xtrkcad	Source files from SourceForge
	buildx64	Folder for 64-bit binaries
	buildx86	Folder for 32-bit binaries

Fetch

Launch TortoiseHg Workbench

• Configure TortoiseHg to use SSH. Copy your private key into the .ssh folder shown below. Edit the Settings and add the following in the [ui] section:
  [ui]
  ssh = "C:\Program Files\TortoiseHg\lib\tortoiseplink.exe" -ssh -i "C:\Users\WINDOWSUSER.ssh\sfprivate.ppk"
• Create a new repository. This will be the folder containing your source code.

• Set the URL alias for the new read-only repository to >ssh://hg.code.sf.net/p/xtrkcad-fork/xtrkcad

• If you are going to be pushing changes you will need to use your sourceforge USERNAME

  ssh://USERNAME@hg.code.sf.net/p/xtrkcad-fork/xtrkcad

@@{{image url="images/WindowsBuild/thg-1.png" title="TortioseHg Setup" alt="TortoiseHg Setup"}}@@

• pull incoming changes
• update to the desired branch
  This might complain about differences in .hgignore. If so, check 'Discard local changes, no backup' on the Update dialog and try again.

CMake

Install cmake (3.18.4 or greater) win64 from https://cmake.org/download

• Launch CMake-gui
• Select the build folder (from above) corresponding to the project you want to build (x64 or x86)
• Run cmake-gui: generator = Visual Studio 16 2019, platform = <blank> for x64, win32 for x86, optional toolset = <blank>, use default native compilers. </blank></blank>
• Configure, Generate, then Open Solution

32-bit Build

@@{{image url="images/WindowsBuild/CMake-2.png" title="CMake Setup 32-bit" alt="CMake Setup 32-bit"}}@@

64-bit Build

@@{{image url="images/WindowsBuild/CMake-4.png" title="CMake Setup 64-bit" alt="CMake Setup 64-bit"}}@@

• You will see a number of configuration values to set. We only need to deal with 2:
  ~~ CMAKE_CONFIGURATION_TYPE: Set to Debug or RelWithDebInfo (if building a release version)
  ~~ CMAKE_INSTALL_PREFIX: Should be set to the appropriate folder: C:\Program Files\XTrackCAD for x64, C:\Program Files (x86)\XTrackCAD for x86.

Build

• Compile XTrackCAD using the new project files. For example, start MSVC and open the XTrkCAD.sln solution file which is located in your build directory.
• Build the "BUILD_ALL" project to build the software.
• Build the "INSTALL" project to install the software.
• Run XTrackCAD by double-clicking its icon located in the install directory - for example: ##C:/Program Files/XTrkCAD/bin/xtrkcad.exe##.

Release Build

On Windows you have the possibility to create an installer using NSIS: [http://nsis.sf.net/] and a ZIP archive for the source code.

Installer

Make sure that NSIS is installad and running. In Visual C++ build the ##PACKAGE## project. If all goes well, the installable package ##xtrkcad-setup-//version//.exe## is created in your build directory.

Building the source archive takes a few more steps.

Open a command window and execute

(language-ref)
cd (build-directory)
cpack --config CPackSourceConfig.cmake
CPack: Create package using ZIP
CPack: Install projects
CPack: - Install directory: D:/XTrackCAD/xtc-version
CPack: Create package
CPack: - package: [builddir]xtrkcad-source-//version//.zip generated.

Code Signing

''Currently we don't have a code signing certificate. This step can be omitted.'' In case signing the executable is wanted open the Visual Studio shell:

cd (build-directory)/app/bin/Release
signtool sign /f certfile /p password xtrkcad.exe
cd (build-directory)
cpack
signtool sign /f certfile /p password xtrkcad-setup-4.2.4a.exe

CategoryDevel