Building Ironclad 3.4 on Windows

Ironclad 3.4 only builds as a 64-bit package. 32-bit builds are not supported.

Building on Windows

Option 1: Using a Docker container

In the root of the project there is a Dockerfile that contains Docker instructions to create a Docker image suitable to run a Docker container with all tools necessary for the build of the main branch of Ironclad. Before using it, make sure that Docker Desktop is set to use Windows containers: after starting Docker Desktop, right-click on the Docker whale icon in the status area of the Windows taskbar and make sure the popup menu entry reads Switch to Linux containers…​. Otherwise, if it is Switch to Windows containers…​, select that option.

To build the container image and then run the container, change the current directory to the project root directory and, using PowerShell:

docker build -t ironclad-build:v3.4 -m 2GB .
docker run -it -v ${pwd}:C:\ironclad --name ironclad-build-v3.4 ironclad-build:v3.4

Subsequent re-runs of the created container can be done with:

docker start -ai ironclad-build-v3.4

Option 2: Install build dependencies on Windows

For building outside of a Docker container, install the following prerequisites:

• .NET Framework 4.6.2 or higher

• Visual Studio 2022 (any edition), with:

  • Visual C tools and libraries (64-bit)

  • Windows 10 SDK

  • .NET 6.0 SDK or higher

  • Clang toolset

• MinGW64 with the NASM compiler (the tools have to be put on the search path $env:PATH)

• CPython 3.4 64-bit (no need to put it on the search path)

• Visual C 2010 Redistributable (latest version)

• CPython 3.9 or higher (executable as to be put it on $env:PATH), with the following packages installed:

  • scons

  • castxml

  • pygccxml

• IronPython 3.4, latest release

  • for .NET Framework

  • for .NET (Core)

The above setup is sufficient to build Ironclad with Clang (which is the default build). To build using MSVC v16.0, additionally install:

• Windows® SDK for Windows® 7 and .NET Framework 4

• Microsoft Visual C++ 2010 Service Pack 1 Compiler Update for the Windows SDK 7.1

Edit SCons script

Ironclad’s build process is configured by main.scons in the project root directory. Go to the section marked PLATFORM-SPECIFIC GLOBALS, and change anything that looks wrong for your system. The values provided in current main.scons are known to work with the Docker container and on Windows 11 x64 with the following assumptions:

• IronPython for .NET Framework installed using Chocolatey

• IronPython for .NET installed as a dotnet tool IronPython.Console

• MinGW64, CPython 3.9+ are on executable search path

• Other tools and components installed in default locations

Build

Having done the above, running scons in the project root directory (C:\ironclad in Docker container), in your favourite shell, should build everything required by Ironclad. By default, it will build a release configuration targeting the .NET Framework. To build for other frameworks or configurations, use SCons build parameters (variables) on the scons command line, like scons framework=all configuration=debug. The final build output is placed in directory 'out/«configuration»/«framework»'. Intermediate build artifacts are placed in 'build/«configuration»/«framework»'. Run scons -h for info about supported build parameters and options, their accepted values, and where the final build artifacts are placed. Note that build parameters on the command line are placed without leading dashes and with an equal sign.

Clean

Run scons --clean or scons -c. Again, by default it will only clean a release configuration targeting the .NET Framework. To clean other builds, run scons -c with the same build parameters as used to create those builds.

Sometimes, after some tests have been run, running scons -c may complains that it cannot remove some test files because they are "in use". In such case run scons -c the second time.

It is also possible to purge all artifacts created by any build run, by deleting the whole trees build and out in the project root directory.

Testing

Running complete test suite

Run scons test with the relevant build parameters on command line. This will execute the whole test suite for the selected configuration/framework. E.g. to run all tests for all builds:

scons test configuration=all framework=all

Running single test case

Out-of-source builds (default)

To run a specific test, first set IRONPYTHONPATH to the DLLs and site-packages directories of CPython 3.4. E.g. in PowerShell, assuming the standard installation of CPython (like the one in the Docker container):

$env:IRONPYTHONPATH = "C:\Python34\DLLs;C:\Python34\Lib\site-packages"

Then run the test with:

\path\to\ipy.exe .\runtests.py tests.«testtfile».«testcase» «configuration»/«framework»

If .«testcase» is omitted, all tests in module «testtfile» are run.

Use ipy.exe for the same .NET CLR as the one Ironclad under test is targeting. E.g.

~\.dotnet\tools\ipy.exe .\runtests.py tests.dllreadertest.DllReaderTest release/net6.0

It is possible to skip argument «configuration»/«framework» if environment variables IRONPYTHONPATH and TESTDATA_BUILDDIR are set appropriately (see section "In-source builds" below), but it may be less convenient.

In-source builds

To run a specific test, first set IRONPYTHONPATH to the directory containing the Ironclad package (for in source builds it is normally the build directory), and the DLLs and site-packages directories of CPython 3.4. E.g. to run a test for a debug build on .NET 6.0 in PowerShell on Windows:

$env:IRONPYTHONPATH = ".\build;C:\Python34\DLLs;C:\Python34\Lib\site-packages"

Then set environment variable TESTDATA_BUILDDIR to the location of the compiled test files in the source directory. Continuing the example above:

$env:TESTDATA_BUILDDIR = ".\tests\data"

Finally run the test with:

\path\to\ipy.exe .\runtests.py tests.«testtfile».«testcase»