build.txt

BUILD NOTES
static site checker
https://dylanharris.org/ssc/
(c) 2020-2026 Dylan Harris


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

Older versions ssc build with some older compilers on some older
systems, although, unsurprisingly, not all features are available.

Be warned, I wrote ssc 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 that the gcc build time can be very poor.


Libraries
=========

Common dependencies
-------------------
ssc needs boost version 1.75 or better (https://boost.org), Microsoft's
GSL (https://github.com/Microsoft/GSL) (or define NO_GSL), and, except
under Windows, a recent copy of ICU4C (https://icu-project.org/) (or
define NOICU). If you want to experiment with the still-in-development
GUI version, you'll need to define WX, amd a recent version of WX
Widgets (https://wxwidgets.org/). If you want its output signed, or to
verify such a signature, download LibreSSL (https://www.libressl.org/,
built into OpenBSD and recent versions of Windows). Often, an Operating
System's package manager will have an appropriate version 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, or want to build the GUI, set BOOST to your boost 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 (not used under
  Windows);
- WX_ROOT: if you're building the gui version of ssc, you'll need to
  install wxWidgets and set WX_ROOT to its installation directory.
- SSL: for signed output, install libreSSL or equivalent. Note that
  libreSSL is built into OpenBSD and Windows 11. You may need to
  #define SIGNED.

hunspell
--------
Building SSC under unii, including MacOS, requires a development
installation of hunspell (https://hunspell.github.io/).

winspell
--------
The Windows build, by default, uses the native Windows spellchecker,
although, preceding Windows 11, that doesn't seem to work so well in
contexts unimpaired by monolingualism.


Notes on the GUI
================

wxWidgets
---------
Why use this ancient behemoth given the good number of somewhat less
archaic C++ GUI libraries? The requirements were: (i) Open Source;
(ii) supports Windows/MacOS/Linux/OpenBSD. Of those libraries I found,
only wxWidgets is documented to support OpenBSD. 

Polylingualism
--------------
ssc is written for coders. HTML/etc. code is based on various flavours
of English, so ssc's GUI text is similarly monolingual. It uses
standard English, with dishonourable exceptions.


Building
========

Windows
-------
To build from Visual Studio, navigate to recipe/tea, open the
appropriate .sln file, then build. Only Visual Studios 2022 and 2026
have been used to build & test for amd64 (x64) and arm64 (a64) under
Windows 11. Older versions for amd64 and i386 were tested on older
versions of Windows.

On low memory 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 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, but I expect brew is good too.
From the home ssc 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

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

SSC has, at various times, been successfully built under OpenBSD,
FreeBSD, (mostly Ubuntu) Linux, & MacOS, on AMD64 and ARM64
architectures. 

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.

Linux
-----
I tend to build under Ubuntu, but some other flavours should 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. The bugs are probably in ssc code, but I've not
found them.


Testing
=======

Windows
-------
Under Visual Studio, run ssc??-test using these arguments:
  -v -x $(ProjectDir)..\..\ssc.exe
    -f $(ProjectDir)..\toast\ssc-test\win.lst
(on one line)

Add '-d' if you want the test utility to retain temporary files.

CMake
-----
Under CMake, run ctest:
  ctest -V
(which runs 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
(https://github.com/Microsoft/GSL), then unpack, build and install it.
In Windows, remember to add its root directory to your local path.

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

Most package managers support it, or you can download and build your
own version using the source found at https://boost.org/. SSC requires
boost version 1.89 or better.

ICU4C
-----
ICU4C is used to process unicode in most operating systems.

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

LibreSSL
--------
This is only required if you wish to sign andor verify SSC's output. It
is native to OpenBSD and Windows 11. It is found in some package
managers, or can be downloaded from https://www.libressl.org/.
Alternatives are available, although I've not tested them.

wxWidgets
---------
This is only required if you make a GUI build. It can be found at
https://wxwidgets.org/. Note that ssc has not been tested on many of the
systems supported by wxWidgets.


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 linguistically weak 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: and/or sans ancienne; land of Gift (aber nicht das Gift)

Regarding documentation, much professional experience maintaining other
people's code over decades has taught me:

- Specifications are essential (for some of the specifications used by
  ssc, see https://dylanharris.org/ssc/spex/index.shtml);
- Comments in code are rarely useful, often counterproductive, and
  sometimes even dangerous (for my reasoning, see
  https://dylanharris.org//prose/opinion/comments.shtml).