build notes

Introduction

ssc can be built on various unii with CMake and clang or gcc for C++ 17 or better, or Visual Studios 2017 / 2019 / 2022 under Windows. I have built & tested it under various OSs on some amd64 & arm64 architectures, including various flavours of Linux, MacOS, OpenBSD, and Windows.

Although ssc builds with some older compilers on some older systems, not all features are available.

Libraries

Common dependencies

ssc needs boost version 1.75 or better, a recent copy of the ICU libraries (or #define NOICU), Microsoft’s GSL library (or #define NO_GSL), and a recent version of libcurl (note that libcurl requires an underlying thread–safe SSL library, or #define NOCURL). If you want to experiment with the still–in–development GUI version, #define WX, and you’ll need a recent version of wxWidgets. Usually, an Operating System’s package manager has appropriate versions ready to install.

You may need to set these environment variables:

• BOOST: if you’re not using your operating system’s packaged flavour of boost, then set BOOST to your boost source root directory;
• CURL: if you’re not using your operating system’s packaged flavour of curl, then set CURL to your curl source root directory;
• GSL: set it to your GSL root directory.
• ICU_ROOT: if you’re not using your operating system’s packaged ICU, set ICU_ROOT to your ICU source root directory (alternative, #define NOICU);
• WX_ROOT: if you’re building the gui front end to ssc, you’ll need to install wxWidgets and set WX_ROOT to its installation directory.

hunspell

Building ssc with spelling checks under unii, including macos, requires a development installation of hunspell, or equivalent. You should be able to install it using the appropriate package manager. Alternatively, #define NOSPELL.

winspell

The Windows build, by default, uses the native Windows spellchecker, although, in Windows 10, that doesn’t seem to work so well in contexts unimpaired by monolingualism. Alternatively, #define NOSPELL.

Building

Windows

To build from Visual Studio, navigate to recipe/tea, open the appropriate .sln file, then build. Only Visual Studios 2017, 2019 and 2022 have been built & tested for amd64 (x64), and only 2022 has been tested for arm64 under Windows 10 & 11. Older versions for amd64 and i386 were tested on older versions of Windows.

On low memory machines, disable the /MP switch.

Some versions of the Visual Studio solutions use vcpkg, which sometimes resolves dependencies. For all such versions, except recent editions of Visual Studio 2022, you may need to first download and install vcpkg yourself.

Unii & mock Unii

You will need CMake 3.24 or better. On Linux, you will also need lsb-release. These can be found in most distributions’ standard packages. For macos, I used macports, but brew should be good too. From the home directory, compile a normal build thus:

For a debug build:

If everything works correctly, then everything will be built, a series of tests run, with a final result at the very end saying no failures. Having said that, given ssc is alpha, don’t be too surprised to see some warnings or some final test errors.

In particular, complaints about being unable to find or copy files during testing are not of concern. These come from scripts that set up or tear down individual tests. The standard commands used sometimes complain if they can’t find files they’re supposed to delete, which is a bit silly given that means things are already in the required state.

Versions of ssc have been successfully built in OpenBSD, FreeBSD, Linux, & MacOS on AMD64, and in recent versions of Linux & MacOS under ARM64.

The current version of ssc requires the current version of an operating system. Older operating systems require older versions of ssc. Not all features work on all systems.

I’ve sometimes found it necessary to use cmake’s -DCMAKE_CXX_COMPILER=… switch.

Centos 9

The appropriate CMake command for Centos Stream 9 is:

(note the standard English spelling of flavour.)

OpenBSD

You may need to increase significantly the available memory setting for your build account in login.conf.

macOS

Certain versions of macos clang produce buggy code, whether or not optimisations are applied. Use an alternative compiler if you want a stable executable. I suspect this is really due to a bug in ssc, but I’ve not been able to find it.

compression

Note that, at the end of building, there may be an attempt to create a compressed file using either 7z or tar zip, depending on the environment. It doesn’t matter if this fails, it’s only produced to aid distribution.

Testing

Windows

Under Visual Studio, run ssc-test using these arguments:

Add ‘-d’ if you want the test utility to retain its intermediate output files.

CMake

Under CMake, run ctest:

(which runs an ssc-test for you, using nix.lst).

Dimitude

The testing utility is rather dim; it will test unbuilt features, causing failures.

Spelling test results depend on the dictionaries installed.

Supporting libraries

GSL

If you can’t find a copy of Microsoft’s GSL in your system’s standard package suite, then grab a current copy from its github repository, then unpack, build and install it.

Boost

Boost is to C++ as breakfast to the working day.

Most package managers support it, including vcpkg. Alternatively, build your own version using the source found at boost.org.

curl

curl is used for link checking and, where necessary, obtaining remote resources. Most package managers support it.

ICU4C

The ICU4C C++ library is used to process unicode.

Most package managers support it. Alternatively, build your own version using the source found at icu.unicode.org.

wxWidgets

This is only required if you make a GUI build, which is not recommended (yet). It can be found at wxwidgets.org. Note that I have not tested it under many supported (by wxWidgets) systems.

Editions

Currently, there is a new, work–in–progress, gui edition in the Visual Studio solution. This does not work and should not be used. Stick to the standard edition.

Dylan Harris
November 2024