build notes
requirements
To build ssc on current versions of various unii, you’ll need CMake and clang or gcc for C++ 17 or better. For current versions of Windows, you’ll need Visual Studios 2017 / 2019 / 2022 / 2026. I have built and tested it under amd64 & arm64 only.
If you’re stuck with an older OS, you’ll probably have to build a corresponding older version of ssc. Some versions were also tested on other operating systems, such as FreeBSD, but I’ve not targetted those systems for rather a long time.
building
source
You can download the current source here, or from github.
windows
To build from Visual Studio, navigate to recipe/tea, open the appropriate .sln file, then build. Only Visual Studios 2017, 2019, 2022, & 2026 have been built & tested for x64, and only 2022 & 2026 have been build & tested for arm64 under Windows 11. Older versions for amd64 and i386 were tested on older versions of Windows.
On low resource machines, disable the /MP switch.
unii & mock unii
I wrote ssc using visual C++ and clang. It turns out that, regretfully, some of the choices I made left gcc ridiculously slow. I suggest, if you have the choice, that you avoid it.
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, although brew should be good too.
From the home directory, compile a normal build thus:
cmake .
make
make install
For a debug build:
cmake -DCMAKE_BUILD_TYPE=Debug .
make
make install
If everything works correctly, then everything will be built 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.
You can run the test suite thus:
ctest -V
Note that complaints about being unable to find or copy files during testing are of no concern. These come from scripts that set up or tear down individual tests. The standard commands used sometimes complain that they can’t find files they’re supposed to delete, which is a bit silly given that means things are already in the desired state.
Unfortunately, the spelling tests depend on the local system spell checker, and they’re inconsistent across systems, so they’re excluded from the unix tests.
linux
I’ve sometimes found it necessary to use cmake’s -DCMAKE_CXX_COMPILER=… switch.
I tend to build under ubuntu LTS, but many other flavours work too.
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 realise this is probably due to a bug in ssc, but I’ve never found it.
speed
Be warned: ssc is written to run fast, not build fast. I could probably make some changes to improve build speed, but, to be honest, I find it quite acceptable on my primary build machine (which runs msvc). I regret to say the gcc build time can be rather poor.
libraries
boost
Boost is to C++ as breakfast to the working day.
This is the only required external library. ssc requires boost version 1.75 or better.
Most package managers support it. Alternatively, build your own version using the source found at boost.org.
If you’re not using your operating system’s packaged flavour of boost, then set the environment variable BOOST to point to your boost source root directory.
GSL
ssc uses Microsoft’s GSL for internal consistency enforcement. If you don’t want to use it, #define NO_GSL, otherwise set the environment variable GSL to point to the GSL root directory.
If you can’t find a copy of Microsoft’s GSL in your system’s standard package suite, then grab a copy from github, unpack, build, and install it.
icu4c
The ICU4C C++ library is required for unii, not Windows. It is used to process unicode. If you prefer not to use it, #define NOICU, otherwise, if you’re not using your operating system’s packaged ICU, set ICU_ROOT to point to your ICU source root directory.
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. It can be found at wxwidgets.org. Note that ssc has not been tested on many of the systems supported by wxWidgets.
Set the environment variable WX_ROOT to point to your WX installation directory, and define WX when building.
libreSSL
LibreSSL is only required if you wish to sign andor verify ssc’s output. Alternatives are available, although I’ve not tested them. It is native to OpenBSD and recent versions of Windows.
If you use it, you may need to set the environment variable SSL to point to your installation of libreSSL (or equivalent). You may also need to #define SIGNED.
hunspell
Under unii, if you want spelling to be checked, install a development version of hunspell or equivalent, with dictionaries. Otherwise, #define NOSPELL.
winspell
The Windows build, by default, uses the native Windows spellchecker. Be warned that, in some older versions of Windows, that doesn’t seem to work so well in contexts unimpaired by monolingualism. Alternatively, #define NOSPELL.
note
In many cases, an Operating System’s package manager will have appropriate versions of libraries ready to install.
testing
windows
Under Visual Studio, run ssc-test using these arguments:
-v -x $(ProjectDir)..\..\ssc.exe -f $(ProjectDir)..\toast\ssc-test\win.lst
Add ‘-d’ if you want the test utility to retain intermediate output files.
cmake
Under CMake, run ctest:
ctest -V
(which runs ssc-test, 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.
bugs
This is an alpha version of ssc. It is incomplete. What is complete needs refining. The developer needs coffee.
It may contain unexpected features. If you encounter one, please help improve ssc by collecting the following information (where relevant) and forwarding it to the developer:
- version of ssc (for example, 0.2.23);
- precise version of the operating system;
- hardware architecture and system information;
- detailed description of the problem;
- detailed description of the steps to recreate it;
- copy of output file/s and relevant logs;
- copy of pages/website being analysed;
- precise command used;
- configuration file/s used, if any;
- any ndx file or other pre–existing file used during the run;
- any known workarounds, fixes or solutions;
- a video of a dance interpretation of the issue (might just be optional, that).
Please email everything to devongarde@me.com (if the collected files are more than small, kindly use a public fileserver and email the link). Do NOT send anything confidential. Furthermore, unless you explicitly state otherwise, we reserve the right to publish some or all of the information sent in future versions of ssc, probably in the test suite. If you have a fix, you are invited to submit a pull request on github, at https://github.com/devongarde/ssc. Thank you kindly.
ssc can be run in a CGI environment. This is intended for use with OpenBSD’s native httpd web server. You are reminded that ssc is not production software. Do NOT expose it to untrusted data sources, such as those found on the open web.
browsing the source
If you browse the source code, you may come across the following names:
- recipe: a nod to Vernor Vinge’s “A Fire Upon the Deep”;
- tea: without tea, nothing works; then there’s builders’ tea;
- sauce: makes the dull tasty; identifies punless pedants;
- toast: toasts code; i liked burnt toast;
- heater: i’m not stopping now;
- unii: my preferred plural of unix: to my ears, both unixes and unices sound like they sing castrato;
- andor: andor sans ancienne; land of Gift (aber nicht das Gift).