# Install Guide

## Windows

### Build Crystal Tracker from source

You will need [Microsoft Visual Studio](https://visualstudio.microsoft.com/vs/); the Community edition is free.

#### Clone this repository

0. Clone [crystal-tracker](https://github.com/dannye/crystal-tracker). This will create the **crystal-tracker** folder.

#### Setting up FLTK

1. Clone [fltk release-1.4.5](https://github.com/fltk/fltk/tree/release-1.4.5) into lib\\**fltk** (ie, `git clone -b release-1.4.5 https://github.com/fltk/fltk.git lib/fltk`) and apply fltk.patch by running `git apply ../patches/fltk.patch` from the lib\fltk directory.
2. Open Visual Studio, select **Open a local folder**, and open the lib\fltk folder. This will automatically generate the CMake project with a configuration named **x64-Debug**.
3. Create the following additional configurations with the appropriate **Configuration Type** of either Debug or Release: x64-Release, x86-Debug, and x86-Release. For x64 configurations, make sure the **Toolset** is set to **msvc_x64_x64**. For x86 configurations, make sure the Toolset is set to **msvc_x86_x64**. For all 4 configurations, uncheck the **FLTK_GRAPHICS_GDIPLUS** option and set the **FLTK_ABI_VERSION** option to **10405**.
4. Set the configuration to **x86-Release**.
5. In the **Solution Explorer**, switch to the **CMake Targets View**, right-click on **fltk_images**, and select **Build fltk_images**. This will also build the other required libraries: fltk, fltk_png, and fltk_z.
6. Move all the .lib files from lib\fltk\out\build\x86-Release\lib\\\*.lib up to lib\\\*.lib. (You may also choose the x86-Debug config in the previous step and move the .lib files from lib\fltk\out\build\x86-Debug\lib\\\*.lib to lib\Debug\\\*.lib instead.)
7. Copy the lib\fltk\\**FL** folder to a new include\\**FL** folder. Also copy lib\fltk\out\build\x86-Release\FL\fl_config.h into include\FL. All configurations will generate their own fl_config.h, but they should all be identical.

#### Setting up PortAudio

8. Clone [portaudio v19.7.0](https://github.com/PortAudio/portaudio/tree/v19.7.0) into lib\\**portaudio**. (ie, `git clone -b v19.7.0 https://github.com/PortAudio/portaudio.git lib/portaudio`)
9. Apply the PortAudio patch that is provided with Crystal Tracker by running the following command from the root of the PortAudio directory (ie, lib\\**portaudio**): `git apply ../patches/portaudio.patch`  
  This fixes a Windows-only glitch that will be fixed in the next major release of PortAudio but is being fixed manually here for now. See https://github.com/PortAudio/portaudio/commit/ba486a3a8c9e7b2a7b217ab6e31a4c46c6ca38db for more details.
10. Open lib\portaudio\build\msvc\\**portaudio.sln** in Visual Studio 2022.
11. A "One-way upgrade" dialog will open, since portaudio.sln was made for Visual Studio 2005. Click OK to upgrade.
12. In the **Solution Explorer**, remove the 4 ASIO-related cpp files under **Source Files → hostapi → ASIO** from the project. (Right-click each of the 4 cpp files and click "Remove".)
13. In the **Project Properties** window, go to **Configuration Properties → General** and change the value of **Configuration Type** from "Dynamic Library (.dll)" to "Static Library (.lib)". Do this for the Release configuration, and also the Debug configuration if desired.
14. In the **Project Properties** window, go to **Configuration Properties → C/C++ → Preprocessor** and add `PA_USE_ASIO=0;` to the beginning of the **Processor Definitions** property. Do this for the Release configuration, and also the Debug configuration if desired.
15. Open lib\portaudio\build\msvc\\**portaudio.def** in a text editor and comment out the 4 lines beginning with "PaAsio_" by putting a semicolon (`;`) at the start of the line.
16. Set the Solution Configuration to Release and set the Solution Platform to Win32 then press **Build → Build Solution**. You may also build Debug|Win32 if desired.
17. Move lib\portaudio\build\msvc\Win32\Release\portaudio.lib to lib\portaudio.lib (or move lib\portaudio\build\msvc\Win32\Debug\portaudio.lib to lib\Debug\portaudio.lib if Debug build).
18. Open lib\portaudio\bindings\cpp\build\vc7_1\\**static_library.sln** in Visual Studio 2022.
19. A "One-way upgrade" dialog will open. Click OK to upgrade.
20. In the **Project Properties** window, go to **Configuration Properties → C/C++ → Code Generation** and change **Runtime Library** from "Multi-threaded DLL (/MD)" to "Multi-threaded (/MT)". For the Debug configuration, change it from "Multi-threaded Debug DLL (/MDd)" to "Multi-threaded Debug (/MTd)".
21. Set the Solution Configuration to Release then press **Build → Build Solution**. You may also build Debug|x86 if desired.
22. Move lib\portaudio\bindings\cpp\lib\portaudiocpp-vc7_1-r.lib to lib\portaudiocpp-vc7_1-r.lib (or move lib\portaudio\bindings\cpp\lib\portaudiocpp-vc7_1-d.lib to lib\Debug\portaudiocpp-vc7_1-d.lib if Debug build).
23. Copy the lib\portaudio\bindings\cpp\include\\**portaudiocpp** folder to a new include\\**portaudiocpp** folder.
24. Copy the header files from lib\portaudio\include into the include\\**portaudiocpp** folder as well.

#### Setting up libopenmpt

25. Clone [libopenmpt-0.8.4](https://github.com/OpenMPT/openmpt/tree/libopenmpt-0.8.4) into lib\\**openmpt**. (ie, `git clone -b libopenmpt-0.8.4 https://github.com/OpenMPT/openmpt.git lib/openmpt`)
26. Open lib\openmpt\build\vs2022win10\\**libopenmpt-small.sln** in Visual Studio 2022.
27. Retarget the 4 projects to your installed version of the Windows 10 SDK if necessary.
28. For each of the 4 projects, go to **Configuration Properties → C/C++ → Code Generation** and change **Spectre Mitigation** to "Disabled". Do this for the Release configuration, and also the Debug configuration if desired.
29. Set the Solution Configuration to Release and set the Solution Platform to Win32 then press **Build → Build Solution**. You may also build Debug|Win32 if desired.
30. Move the 4 .lib files from lib\openmpt\build\lib\vs2022win10\x86\Release to lib (or from lib\openmpt\build\lib\vs2022win10\x86\Debug to lib\Debug if Debug build).
31. Copy the public interface header files from lib\openmpt\libopenmpt into a new include\\**libopenmpt** folder. (Only libopenmpt.hpp, libopenmpt_ext.hpp, libopenmpt_config.h, and libopenmpt_version.h are required.)

#### Building Crystal Tracker

32. Open ide\\**crystal-tracker.sln** in Visual Studio 2022.
33. If the Solution Configuration dropdown on the toolbar says Debug, set it to **Release**.
34. Go to **Build → Build Solution** to build the project. This will create bin\Release\\**crystaltracker.exe**. (A Debug build will create bin\Debug\\**crystaltrackerd.exe**.)

**Note:** To build a 64-bit executable, you will need to create the x64 Solution Platform for portaudiocpp (static_library.sln). To do this, go to **Build → Configuration Manager…** and in the **Active solution platform:** dropdown select **<New…>**. Set the new platform to "x64" and copy settings from the 32-bit platform (either Win32 or x86). Make sure the "Create new project platforms" checkbox is checked and then click OK. Make sure the project configuration changes described above are also applied to this platform. portaudio.sln and libopenmpt-small.sln already have an x64 target.  
After building the x64 libs for fltk, portaudio, portaudiocpp, and openmpt, copy the .lib files to lib\\**x64** and lib\Debug\\**x64**.


## Linux

### Install dependencies

You need at least g++ 7 for C++17 support.

CMake (version 3.15 or later) is required for building FLTK 1.4.

#### Ubuntu/Debian

Run the following commands:

```bash
sudo apt install make g++ git autoconf cmake
sudo apt install zlib1g-dev libpng-dev libxpm-dev libx11-dev libxft-dev libxinerama-dev libfontconfig1-dev x11proto-xext-dev libxrender-dev libxfixes-dev libcairo2-dev libpango1.0-dev libasound2-dev libpulse-dev
```

### Install and build Crystal Tracker

Run the following commands:

```bash
# Clone Crystal Tracker
git clone https://github.com/dannye/crystal-tracker.git
cd crystal-tracker

# Build FLTK 1.4.5
git clone -b release-1.4.5 https://github.com/fltk/fltk.git lib/fltk
pushd lib/fltk
git apply ../patches/fltk.patch
cmake -B build \
	-D CMAKE_INSTALL_PREFIX="$(realpath "$PWD/../..")" \
	-D CMAKE_BUILD_TYPE=Release \
	-D FLTK_ABI_VERSION=10405 \
	-D FLTK_BUILD_GL=0 \
	-D FLTK_BUILD_TEST=0 \
	-D FLTK_GRAPHICS_CAIRO=1 \
	-D FLTK_BACKEND_WAYLAND=0
cmake --build build
cmake --install build
popd

# Build PortAudio v19.7.0
git clone -b v19.7.0 https://github.com/PortAudio/portaudio.git lib/portaudio
pushd lib/portaudio
./configure --prefix="$(realpath "$PWD/../..")" --includedir="$(realpath "$PWD/../../include/portaudiocpp")" CXXFLAGS="-O2" CFLAGS="-O2" --without-jack
make
make install
cd bindings/cpp
./configure --prefix="$(realpath "$PWD/../../../..")" CXXFLAGS="-O2" CFLAGS="-O2"
make
make install
popd

# Build libopenmpt-0.8.4
pushd lib
wget https://lib.openmpt.org/files/libopenmpt/src/libopenmpt-0.8.4+release.autotools.tar.gz
mkdir libopenmpt && tar xf libopenmpt-0.8.4+release.autotools.tar.gz -C libopenmpt --strip-components=1
cd libopenmpt
./configure --prefix="$(realpath "$PWD/../..")" CXXFLAGS="-O2" CFLAGS="-O2" \
	PKG_CONFIG_PATH="$(realpath "$PWD/../../lib/pkgconfig")" \
	--without-flac \
	--without-mpg123 \
	--without-ogg \
	--without-sndfile \
	--without-vorbis \
	--without-vorbisfile
make
make install
popd

# Build Crystal Tracker
make

# Install Crystal Tracker
# (tested on Ubuntu and Ubuntu derivatives only; it just copies bin/crystaltracker
#  and res/app.xpm to system directories and creates the .desktop entry)
sudo make install
```


## Mac

Follow the ["Install and build"](#install-and-build-crystal-tracker) instructions for Linux, but with the following changes:

### FLTK

When building FLTK with CMake, use the following `cmake` command instead of the one shown above:

```bash
cmake -B build \
	-D CMAKE_INSTALL_PREFIX="$(realpath "$PWD/../..")" \
	-D CMAKE_BUILD_TYPE=Release \
	-D FLTK_ABI_VERSION=10405 \
	-D FLTK_BUILD_GL=0 \
	-D FLTK_BUILD_TEST=0 \
	-D FLTK_USE_SYSTEM_LIBPNG=ON \
	-D PNG_PNG_INCLUDE_DIR="$(pkg-config --cflags-only-I libpng | cut -c 3-)" \
	-D PNG_LIBRARY_RELEASE="$(pkg-config --static --libs-only-L libpng | cut -c 3-)/libpng.a" \
	-D LIB_png="$(pkg-config --static --libs-only-L libpng | cut -c 3-)/libpng.a" \
	-D FLTK_USE_SYSTEM_ZLIB=ON \
	-D ZLIB_INCLUDE_DIR="$(PKG_CONFIG_PATH=/opt/homebrew/opt/zlib/lib/pkgconfig pkg-config --cflags-only-I zlib | cut -c 3-)" \
	-D ZLIB_LIBRARY_RELEASE="$(PKG_CONFIG_PATH=/opt/homebrew/opt/zlib/lib/pkgconfig pkg-config --static --libs-only-L zlib | cut -c 3-)/libz.a" \
	-D LIB_zlib="$(PKG_CONFIG_PATH=/opt/homebrew/opt/zlib/lib/pkgconfig pkg-config --static --libs-only-L zlib | cut -c 3-)/libz.a"
```

zlib may be installed in a different directory, such as `/usr/local/opt/zlib` instead of `/opt/homebrew/opt/zlib`.

### PortAudio

If errors about unused variables are encountered when building PortAudio, apply [this fix](https://github.com/PortAudio/portaudio/commit/bc3ad0214a358be3cc01f6b2cc2eaaf284c6de34) and try again.