Building

Windows

Building on Windows is tested with the Visual Studio 2022 MSVC compiler (choose the C++ workflow when installing). You will need to install git. The easiest is to use VSCode with the CMake Tools extension to build.

• Open in vscode. Configure for Release or Debug.
• Add -DPACKAGE_DEV=ON to cmake configure args in cmaketools.
• Build the Install target.
• Press F5 to debug and run. The PACKAGE_DEV means keep the files as loose rather than bundling them. The directory structure matches portable in that everything is relative to the executable. This stops development from interfering with and installations.

Optionally, to build from the Visual Studio x64 Command Prompt:

mkdir build
cd build
cmake .. -G"Visual Studio 17 2022" -Ax64
cmake --build . --config Release --target install

To create a portable zip package see https://github.com/bluescan/tacentview/wiki/Distributing

Windows with WSL 2

The Windows Subsystem for Linux version 2 supports GUI applications right out of the box. This allows you to easily build and debug both Windows and Linux builds straight from VSCode with the CMake extension. The only wrinkle is that by default you will be logged-in as root from VSCode/CMakeTools, which doesn't support GUI apps. We will fix that. Also note there is no need to partition your drive -- you can use the same location you cloned the repo to since WSL2 has access to your Windows drives.

Prerequisites:

• Install WSL2 in Windows. If already installed you may need to update to latest. In a PowerShell windows (run as Administrator) type wsl --install. If you are updating type wsl --update. Next restart WSL2 by typing wsl --shutdown.
• Create a non-root user. Open bash (Search for Ubuntu in the Windows start menu). Type sudo adduser yourusername. Make the password something memorable. I used yourusername. Close bash after success.
• Set default WSL2 user. Since the WSL extension in vscode just launches WSL, we need it to use our non-root user so GUI apps will work. In the PowerShell window type wsl --status. You should see the default version as 2 and the distribution name something like Ubuntu-22.04. Next type ubuntu2204 config --default-user yourusername. I'm not quite sure how the mapping from Ubuntu-22.04 gets to ubuntu2204 but just try removing the non-alphanumeric characters and lower-casing it. You can always start typing 'ubun' and hit TAB for command completion.
• It can be handy to give your new user sudo powers. Launch WSL as root from a windows command prompt: wsl --user root. Then type sudo usermod -a -G sudo yourusername. Finally type groups yourusername to confirm the user is in the sudo group.
• You may need to update the CMAKE version. The easiest is to use kitware's APT repositories as detailed here: https://askubuntu.com/questions/355565/how-do-i-install-the-latest-version-of-cmake-from-the-command-line. The commands are essentially these:

cmake --version
sudo apt remove --purge --auto-remove cmake
sudo apt update
sudo apt install -y software-properties-common lsb-release
sudo apt clean all
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /etc/apt/trusted.gpg.d/kitware.gpg >/dev/null
sudo apt-add-repository "deb https://apt.kitware.com/ubuntu/ $(lsb_release -cs) main"
sudo apt update
sudo apt install cmake
cmake --version

You may need to 'sudo apt install wget' and to update the snap VM's CMAKE you would need run snapcraft --debug to bring up a shell.

Setting up vscode for WSL:

• Install vscode, Visual Studio Community, cmake, and your favourite Git client (I like SmartGit). Clone Tacent View to a local folder.
• Open vscode and install the following extensions: C/C++ from Microsoft, CMake Tools from Microsoft, WSL from Microsoft. I also have optional extensions: Better C++ Syntax from Jeff Hykin, Bookmarks from Alessandro Fragnani, C/C++ Extension Pack from Microsoft, C/C++ Themes from Microsoft, and Hex Editor from Microsoft.
• At the bottom-left of vscode there is a little Open Remote Window button. Click it and choose Connect to WSL.
• Open the Tacent View folder you cloned. It will be in /mnt/d/ClonedDir/ or wherever you cloned it (here d means D: drive). It will configure for Linux because the WSL extension is connecting vscode to WSL.
• Hit F7 to build and F5 to run. An X11 window will pop up with Tacent View running. All inside of Windows!

You can skip the Open Remote Window in the future since vscode remembers it in your recent folders list. Of course don't use it if you just want to build for Windows. Opening a Windows folder in vscode will show up in the recent folders list as a separate entry to the WSL folder even though they are the same physical location. This is great as it makes switching platforms super-easy.

Ubuntu

Building for Ubuntu is tested with Clang 13 and GCC 11.2 (and is known to work with more recent releases). CMake and Git are required. Ninja is suggested but optional. The 'Software and Updates' app allows you to manage (add and remove) repositories or use the command line:

sudo apt-get install gdebi               # Installs gdebi to allow command-line deb file installation. Optional.
sudo apt-get install git                 # Install git or download the source as a zip.
sudo gdebi Downloads/smartgit-19_1_7.deb # Install smartgit or some other git frontend. Optional.
sudo apt-get install llvm                # The compiler. Optional if not using GCC.
sudo apt-get install clang               # The compiler. Optional if not using GCC.
sudo apt-get install lldb                # The debugger. Optional if not using GCC.
sudo apt-get install cmake               # CMake.
sudo apt-get install ninja-build         # Ninja build system.
sudo apt-get install libx11-dev          # At least Mint needs this.
sudo update-alternatives --config c++    # Choose clang. Optional if not using GCC.
sudo update-alternatives --config cc     # Choose clang. Optional if not using GCC.

I usually use VSCode with the CMake Tools to build. Alternatively from the command line:

mkdir ninjabuild
cd ninjabuild
cmake .. -GNinja
ninja install

You can pass -DCMAKE_BUILD_TYPE=Debug (or Release) to cmake if so desired. The install target places the viewer into a ViewerInstall directory along with any data resources it needs. Install is also leveraged to build packages. If you configure and build with:

cmake .. -GNinja -DPACKAGE_DEB=True
ninja install

Then a deb file with all required content will be generated.

CMake Tools Extension Notes

By default switching configurations uses the same default build folder which slows things down if you need to switch from Debug to Release or from Windows to Linux since it needs to reconfigure each time. To avoid this and have a different build folder for each one, go to the CMake Tools extension settings in vscode and find Cmake: Build Directory and set it to something like ${workspaceFolder}/build_${buildKitTargetOs}_${buildKitTargetArch}_${variant:buildType}. This will make CMake generate folders with names like build_linux_x64_debug, build_linux_x64_release, build_win32_x64_debug, and build_win32_x64_release. Switching will become fast. This is a local setting and not in source control.

To make hitting F5 work without having to edit launch.json every time (this file is in source control), the program to launch line has been changed to "program": "${command:cmake.buildDirectory}/ViewerInstall/tacentview" for each configuration (tacentview.exe for the Windows cppvsdbg configuration). You can now launch using the correct debugger for whatever platform/configuration you built. There is no need to do anything here as the json is in Github.