Recent changes to WindowsBuild

WindowsBuild modified by Russell Shilling

Russell Shilling — Tue, 24 Jun 2025 02:38:51 -0000

--- v9
+++ v10
@@ -92,9 +92,9 @@
 #### Fetch

 Launch **TortoiseHg** Workbench
-* Configure TortoiseHg to use SSH.  Copy your private key into the .ssh folder as 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\USER\.ssh\sfprivate.ppk"
+* 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

WindowsBuild modified by Russell Shilling

Russell Shilling — Tue, 24 Jun 2025 02:28:49 -0000

--- v8
+++ v9
@@ -92,8 +92,11 @@
 #### Fetch

 Launch **TortoiseHg** Workbench
+* Configure TortoiseHg to use SSH.  Copy your private key into the .ssh folder as 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\USER\.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 >http://hg.code.sf.net/p/xtrkcad-fork/xtrkcad
+* 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

WindowsBuild modified by Martin Fischer

Martin Fischer — Wed, 12 Mar 2025 15:33:35 -0000

--- v7
+++ v8
@@ -32,9 +32,12 @@
 _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

WindowsBuild modified by Martin Fischer

Martin Fischer — Mon, 10 Mar 2025 19:10:31 -0000

--- v6
+++ v7
@@ -29,7 +29,7 @@

 #### 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 lipzip and zlib in Visual Studio.
+_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**

WindowsBuild modified by Martin Fischer

Martin Fischer — Mon, 10 Mar 2025 12:02:08 -0000

--- v5
+++ v6
@@ -17,11 +17,11 @@

 #### **GetText**

-Install gettext for windows. Download from http://gnuwin32.sourceforge.net/packages/gettext.htm
+Download _gettext_ from http://gnuwin32.sourceforge.net/packages/gettext.htm and install using the setup program. 

 #### NSIS

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

 #### **FreeImage**

@@ -29,12 +29,12 @@

 #### 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 lipzip and zlib in Visual Studio.
+_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 lipzip and zlib in Visual Studio.

 #### **MiniXML**

 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##.
+**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

WindowsBuild modified by Russell Shilling

Russell Shilling — Sun, 28 Apr 2024 18:47:16 -0000

--- v4
+++ v5
@@ -145,7 +145,7 @@
 Open a command window and execute 

 >(language-ref)
-> cd [builddir]
+> cd (build-directory)
 > cpack --config CPackSourceConfig.cmake
 CPack: Create package using ZIP
 CPack: Install projects
@@ -157,11 +157,11 @@

 ### Code Signing

-''Currently we don't have a code signing certicate. This step can be omitted.'' In case signing the executable is wanted open the Visual Studio shell:
+''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 [builddirectory]/app/bin/Release
+>cd (build-directory)/app/bin/Release
 >signtool sign /f certfile /p password xtrkcad.exe
->cd [builddirectory]
+>cd (build-directory)
 >cpack
 >signtool sign /f certfile /p password xtrkcad-setup-4.2.4a.exe

WindowsBuild modified by Russell Shilling

Russell Shilling — Sun, 28 Apr 2024 18:44:44 -0000

--- v3
+++ v4
@@ -25,23 +25,23 @@

 #### **FreeImage**

-_FreeImage:_ [http://freeimage.sourceforge.net/] is used for loading and rendering the backgrounds.
+_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 lipzip and zlib in Visual Studio.
+_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 lipzip and zlib in Visual Studio.

 #### **MiniXML**

-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.
+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.
+* _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

WindowsBuild modified by Russell Shilling

Russell Shilling — Sat, 27 Apr 2024 21:14:07 -0000

--- v2
+++ v3
@@ -77,12 +77,12 @@
 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: 
->
-XTrackCAD ------+-- xtrkcad - Source files from SourceForge
-       |
-       +-- buildx64 - Folder for 64-bit binaries
-       |
-       +-- buildx86 - Folder for 32-bit binaries
+
+| Root | Folder | Contents |
+| --- | --- | --- |
+| XTrackCAD | xtrkcad | Source files from SourceForge |
+|   | buildx64 | Folder for 64-bit binaries |
+|   | buildx86 | Folder for 32-bit binaries |

WindowsBuild modified by Russell Shilling

Russell Shilling — Sat, 27 Apr 2024 21:11:39 -0000

--- v1
+++ v2
@@ -55,29 +55,24 @@
    1) Inside that directory create additional directories per dependency.

 The complete structure is
->
-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="">>

+| 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.

</as></as></as>

WindowsBuild modified by Russell Shilling

Russell Shilling — Thu, 28 Mar 2024 01:27:19 -0000

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

Install gettext for windows. Download from http://gnuwin32.sourceforge.net/packages/gettext.htm

NSIS

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 lipzip and zlib in Visual Studio.

MiniXML

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

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="">></as></as></as>

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:

XTrackCAD ------+-- xtrkcad - Source files from SourceForge
|
+-- buildx64 - Folder for 64-bit binaries
|
+-- buildx86 - Folder for 32-bit binaries

Fetch

Launch TortoiseHg Workbench
* Create a new repository. This will be the folder containing your source code.
* Set the URL alias for the new read-only repository to >http://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.
* Configure, Generate, then Open Solution</blank></blank>

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 [builddir]
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 certicate. This step can be omitted.'' In case signing the executable is wanted open the Visual Studio shell:

cd [builddirectory]/app/bin/Release
signtool sign /f certfile /p password xtrkcad.exe
cd [builddirectory]
cpack
signtool sign /f certfile /p password xtrkcad-setup-4.2.4a.exe

CategoryDevel