Building CTSim (CMake)
======================

Requirements: CMake >= 3.22, a C++20 compiler, zlib, libpng, FFTW3 (double),
HDF5.  Optional: Qt 6.4 or later for the graphical application (on by
default), DCMTK for DICOM, OpenMP, libedit or GNU readline.

The wxWidgets interface was removed in 7.0.0; the graphical application is
now built with Qt 6.

Debian/Ubuntu (built and tested on Ubuntu 24.04 and 26.04; Debian 13 or later
should also work, nothing here is release-specific):
  apt install cmake ninja-build g++ pkg-config \
              libfftw3-dev libpng-dev zlib1g-dev libhdf5-dev libedit-dev \
              libgl-dev libdcmtk-dev \
              qt6-base-dev qt6-base-dev-tools qt6-svg-dev

macOS:   xcode-select --install                  # Apple clang
         brew install cmake pkg-config qt fftw hdf5 libpng dcmtk libedit libomp

         libomp is not optional in practice: Apple's clang supports OpenMP
         but ships neither the runtime nor the headers, so without it the
         reconstruction and projection loops run on one core.  CMake finds
         it through "brew --prefix libomp" automatically.

         Build with Apple's clang, not a Homebrew GCC: Homebrew's Qt and
         DCMTK are built with clang and mixing compilers fails in their
         headers.

         The application is built as build/ctsim.app, a bundle -- there is
         no plain "build/ctsim" file to look for.  Run it from the build
         directory with "open build/ctsim.app".  See "Installing on macOS"
         below for installing it and for making a disk image.

Windows: MSYS2 UCRT64 is the straightforward route --
         pacman -S mingw-w64-ucrt-x86_64-{toolchain,cmake,ninja,qt6-base,\
                   qt6-svg,fftw,hdf5,libpng,zlib,dcmtk}
         Visual Studio works too, with the same libraries from vcpkg.

Homebrew and vcpkg keep their headers outside the compiler's default search
path; CMake finds them through the packages' own configuration, so no
include directories need to be given by hand.

The scripts in scripts/ do all of the below with one command:

  scripts/build.sh --init          install the dependencies (apt or brew)
  scripts/build.sh --clean --man --test
  scripts/build.sh --deb           the Debian packages
  scripts/build.sh --dmg           a macOS disk image
  scripts/build.sh --help          every option

  scripts\build.bat --help         the same on Windows

The commands it runs are these:

Build, test and install:

  cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
  cmake --build build -j
  ctest --test-dir build
  cmake --install build

One test, the DICOM physics validation, needs python3 with numpy and skips
itself otherwise (pip3 install numpy, or brew install numpy on macOS).  The
Qt tests run on Qt's offscreen platform and need no display; they detach
themselves from DISPLAY, so they run the same over ssh as at a console.

The graphical application can be driven by a script, which is how the
sequence test works and how Help - Run Demonstration shows what CTSim does:
  ctsim --script scripts/demos/intro.ctsim
The manual's Scripts section lists the commands.

Options:
  -DCTSIM_GUI=qt|none         graphical application (default qt)
  -DCTSIM_BUILD_TESTS=ON|OFF  unit tests and the regression suite (default ON)
  -DCTSIM_WERROR=ON           warnings are errors (for development)

The manual:

  cmake --build build --target manual       # HTML
  cmake --build build --target manual-pdf   # PDF

These targets exist only when pandoc was found at configure time; without it
"cmake --build ... --target manual" reports "unknown target".  The configure
output says which of the three tools were found and what each missing one
would cost:

  Debian/Ubuntu: apt install pandoc texlive-latex-recommended lmodern \
                             librsvg2-bin
  macOS:         brew install pandoc librsvg
                 brew install --cask basictex     # or mactex, much larger
                 eval "$(/usr/libexec/path_helper)"   # puts pdflatex on PATH
                 # or: export PATH="/Library/TeX/texbin:$PATH"
                 # then reconfigure, so CMake finds pdflatex

basictex is a few hundred MB against MacTeX's several GB, and has the
packages the manual needs.  After installing it, open a new terminal or run
path_helper: pdflatex is in /Library/TeX/texbin, which is not on the PATH of
a shell that was already running.  CMake also looks there directly.

doc/manual/README.md explains why each package is needed.  The installed
manual is what the application's Help menu opens.

Packages:

  cpack --config build/CPackConfig.cmake    # .tar.gz and, on Linux, .deb
  dpkg-buildpackage -us -uc -b              # the Debian packaging in debian/

Installing is by component: Runtime (the application), Tools (ctsimtext,
its manual pages and the examples) and Documentation (the manual).  On
Linux a plain "cmake --install build" installs all three under /usr/local.


Installing on macOS
===================

A Mac application belongs in /Applications, and the bundle is not a file
that can sit in /usr/local/bin, so the two halves are installed separately:

  cmake --build build --target manual manual-pdf   # the Help menu's manual
  cmake --install build --component Runtime --prefix /Applications
  sudo cmake --install build --component Tools

The first command needs no sudo if /Applications is writable by you, which
it is on a personal Mac.  Installing Runtime also runs Qt's deployment step,
which copies the Qt frameworks and plugins into the bundle, so the result
runs on a Mac with no Homebrew and no Qt.

Build the manual first, or the Help menu will find nothing: the manual is
installed into the bundle, and the rule is optional, so a missing manual is
not an error.

The Runtime component puts everything inside ctsim.app:

  Contents/MacOS/ctsim               the application
  Contents/MacOS/ctsimtext           every command-line tool
  Contents/Resources/manual/         ctsim.pdf, ctsim.html, figures
  Contents/Resources/man/man1/       the tools' manual pages
  Contents/Frameworks/               Qt, added by the deployment step

The Tools component additionally installs ctsimtext and its manual pages in
/usr/local in the usual way, for working from a terminal.  If you would
rather use the copy inside the bundle:

  sudo ln -s /Applications/ctsim.app/Contents/MacOS/ctsimtext /usr/local/bin/
  export MANPATH="/Applications/ctsim.app/Contents/Resources/man:$MANPATH"


Making a macOS disk image
=========================

cpack, not cmake --install.  cpack stages its own install, so there is no
need to have installed anything first -- but the manual still has to have
been built:

  cmake --build build --target manual manual-pdf
  cpack --config build/CPackConfig.cmake -G DragNDrop

The image and cpack's staging directory are written into the build
directory, not the one cpack is run from.

This writes build/ctsim-7.0.0-Darwin.dmg holding one self-contained
ctsim.app to drag to /Applications, and a note saying how to reach the
command-line tools inside it.

To check what a disk image will contain before building it:

  cmake --install build --component Runtime --prefix /tmp/stage
  find /tmp/stage

On Windows, "cpack --config build/CPackConfig.cmake -G NSIS" makes an
installer the same way; "-G ZIP" makes a plain folder, which is the simpler
thing to try first.

Full instructions, including the platform notes above in more detail, are in
the manual's Installation chapter (doc/manual/install.md).
