Build Instructions

Contents

Getting the source

Clone the source code using git, and grab all the submodules:

git clone --recursive https://github.com/PrismLauncher/PrismLauncher.git
cd PrismLauncher

The rest of the documentation assumes you have already cloned the repository.

Linux

Getting the project to build and run on Linux is easy if you use any modern and up-to-date Linux distribution.

Build dependencies

  • A C++ compiler capable of building C++17 code.

  • Qt Development tools 6.0 or newer (qt6-base-dev qtchooser qt6-base-dev-tools libqt6core6 libqt6core5compat6-dev libqt6network6 on Debian (testing/unstable) based systems).

  • Alternatively, you can also use Qt 5.12 or newer (qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools libqt5core5a libqt5network5 libqt5gui5 on Debian-based systems), if you prefer it.

  • cmake 3.15 or newer (cmake on Debian-based system)

  • ninja (ninja-build on Debian-based systems)

  • extra-cmake-modules (extra-cmake-modules on Debian-based system)

  • zlib (zlib1g-dev on Debian-based system)

  • Java JDK (openjdk-17-jdk on Debian-based system)

  • GL headers (libgl1-mesa-dev on Debian-based system)

  • scdoc if you want to generate manpages (scdoc on Debian-based system)

You can use IDEs, like KDevelop, QtCreator or CLion to open the CMake project, if you want to work on the code.

Building a portable binary 

cmake -S . -B build -G Ninja \
   -DCMAKE_INSTALL_PREFIX=install
#  -DLauncher_QT_VERSION_MAJOR="5" # if you want to use Qt 5

cmake --build build
cmake --install build
cmake --install build --component portable

Building & installing to the system

This is the preferred method of installation, and is suitable for packages.

cmake -S . -B build -G Ninja \
   -DCMAKE_BUILD_TYPE=Release \
   -DCMAKE_INSTALL_PREFIX="/usr" \ # Use "/usr" when building Linux packages. If building not for package, use "/usr/local"
   -DENABLE_LTO=ON # if you want to enable LTO/IPO
#  -DLauncher_QT_VERSION_MAJOR="5" # if you want to use Qt 5

cmake --build build
cmake --install build # Optionally specify DESTDIR for packages (i.e. DESTDIR=${pkgdir} cmake --install ...)

Building a .deb

Requirements: makedeb installed on your system.

git clone https://mpr.makedeb.org/prismlauncher.git
cd prismlauncher
makedeb -s

The .deb will be located in the directory the repo was cloned in.

Building an .rpm for Fedora

Build dependencies are automatically installed using DNF, however, you will also need the rpmdevtools package (on Fedora),
in order to fetch sources and set up your tree.
You don't need to clone the repo for this; the spec file handles that.

cd ~
# setup your ~/rpmbuild directory, required for rpmbuild to work.
rpmdev-setuptree
# get the rpm spec file from the prismlauncher repo on pagure
git clone https://pagure.io/prismlauncher.git
cd prismlauncher-rpm
# install build dependencies
sudo dnf builddep prismlauncher.spec
sudo dnf builddep -D "_without_qt6 1" prismlauncher.spec # if you want to use Qt 5 instead of Qt 6
# download build sources
spectool -g -R prismlauncher.spec
# move patches to rpmbuild sources directory
cp *.patch ~/rpmbuild/SOURCES
# now build!
rpmbuild -bb prismlauncher.spec
rpmbuild -bb --without qt6 prismlauncher.spec # if you want to use Qt 5 instead of Qt 6

The path to the .rpm packages will be printed once the build is complete.

Building an .rpm for openSUSE

Unlike Fedora, the openSUSE packages depend on the Open Build Service, so you will need to install the command line tool osc by following this guide.
It also uses the obs_scm service, which is available in the obs-service-obs_scm package if it's not already installed.

osc checkout home:getchoo

# there will be 4 directories in home:getchoo, with some having a -qt5 and/or -nightly suffix
# -qt5 packages will build with Qt 5 instead of Qt 6, while -nightly packages will build with the latest commit (updated every 24h)
# for this example, we're just using the stable release package that builds with Qt 6
# NOTE: only -qt5 will build on Leap
cd home:getchoo/prismlauncher

# to build against the current version of Leap, replace `openSUSE_Tumbleweed` with 15.4
osc build --sccache openSUSE_Tumbleweed

The path to the .rpm packages will be printed once the build is complete.

Building a Flatpak

You don't need to clone the entire Prism Launcher repo for this; the Flatpak file handles that.
Both flatpak and flatpak-builder must be installed on your system to proceed.

git clone https://github.com/flathub/org.prismlauncher.PrismLauncher
cd org.prismlauncher.PrismLauncher
# remove --user --install if you want to build without installing
flatpak-builder --user --install flatbuild org.prismlauncher.PrismLauncher.yml

Installing Qt using the installer (optional)

  1. Run the Qt installer.

  2. Choose a place to install Qt.

  3. Choose the components that you wish install.

    • You need Qt 6.0.x 64-bit ticked. (or a newer version)
    • Alternatively you can choose Qt 5.12.0 or newer
    • You need Tools/Qt Creator ticked.
    • Other components are selected by default, you can un-tick them if you don't need them.

  4. Accept the license agreements.

  5. Double-check the install details and then click "Install".

    • Installation can take a very long time, go grab a cup of tea or something and let it work.

Loading the project in Qt Creator (optional)

  1. Open Qt Creator.

  2. Choose File->Open File or Project.

  3. Navigate to the Launcher source folder you cloned and choose CMakeLists.txt.

  4. Read the instructions that just popped up about a build location and choose one.

  5. You should see "Run CMake" in the window.

    • Make sure that Generator is set to "Unix Generator (Desktop Qt 6.x.x GCC 64bit)".
      • Alternatively this is probably "Unix Generator (Desktop Qt 5.12.x GCC 64bit)"
    • Hit the "Run CMake" button.
    • You'll see warnings, and it might not be clear that it succeeded until you scroll to the bottom of the window.
    • Hit "Finish" if CMake ran successfully.

  6. Cross your fingers, and press the "Run" button (bottom left of Qt Creator).

    • If the project builds successfully it will run and the Launcher window will pop up.

If this doesn't work for you, please let us know on our Discord sever, or Matrix Space.

Windows MSVC

Dependencies

  • Visual Studio - Software Distribution and Building Platform for Windows
    • If you don't want install the Visual Studio IDE, go to 'Tools For Visual Studio' and download 'Build Tools for Visual Studio' instead
    • Select 'Desktop development with C++', note that in the optional components (right side) CMake will be selected
  • Java Development Kit 8 or later
    • Make sure that "Set JAVA_HOME variable" is enabled in the Adoptium installer.
  • Qt
    • For Qt 6 (Qt 6.6.2 is the recommended one), 'Qt 5 Compatibility Module' & 'Qt Image Formats' are required
    • For Qt 5 (Qt 5.15.2 is the recommended one), OpenSSL Toolkit is required
    • If you don't want to use the Qt installer, than you can use aqt, see aqt-list for help with command arguments.

Compile from command line on Windows using msbuild

You will need to run commands from x64 Native Tools Command Prompt or x86 Native Tools Command Prompt depending on if you are building 64bit or 32bit.
These instructions assume you are using the x64 Native Tools Command Prompt to build for 64bit.
All commands are for a debug build, for release builds, replace Debug with Release in the cmake build and install commands.

  1. cd into the folder you cloned Prism Launcher to. Put quotation marks around the path.

  2. Now we can prepare the build itself: Run cmake -Bbuild -DCMAKE_INSTALL_PREFIX=install -DENABLE_LTO=ON -DCMAKE_PREFIX_PATH=C:\Qt\6.4.0\msvc2019_64\lib\cmake. These options will copy the final build to the install folder after the build.

    • If you have installed Qt in a non-default location, then change the CMAKE_PREFIX_PATH to -DCMAKE_PREFIX_PATH=<Path to Qt Install>\6.4.0\msvc2019_64\lib\cmake, replacing <Path to Qt Install> with the path to your Qt install.
    • If you are building for 32bit, change msvc2019_64 to msvc2019.
    • If you want to build using Qt 5, then add the -DLauncher_QT_VERSION_MAJOR=5 parameter and change CMAKE_PREFIX_PATH to point to Qt 5.

  3. Now you need to run the build itself: Run cmake --build build --config Debug -- /p:UseMultiToolTask=true /p:EnforceProcessCountAcrossBuilds=true.

    • If preferred, UseMultiToolTask & EnforceProcessCountAcrossBuilds can be set as environment variables instead of passing as arguments.

  4. Now, wait for it to compile. This could take some time, so hopefully it compiles properly.

  5. Run the command cmake --install build --config Debug, and it should install Prism Launcher to whatever the -DCMAKE_INSTALL_PREFIX was.

  6. If you don't want Prism Launcher to store its data in %APPDATA%, run cmake --install build --config Debug --component portable after the install process.

  7. When building on Qt 5, whenever compiling, the OpenSSL DLLs aren't put into the directory to where Prism Launcher installs which are necessary in that case, meaning that you cannot log in. The best way to fix this, is just to do robocopy D:/Qt/Tools/OpenSSL/Win_x64/bin/ install libcrypto-1_1-x64.dll libssl-1_1-x64.dll. This should copy the required OpenSSL DLLs to log in. When building on Qt 6 this is not necessary because it can use schannel, the Windows tls library.

    • Replace <Path to Qt Install> with the path to your Qt install.
    • If building for 32bit, replace Win_x64 with Win_x86 and remove -x64 from the dlls names.

Using ccache

CMake with the msbuild generator currently does not support CMAKE_CXX_COMPILER_LAUNCHER, so the process of setting up ccache differs from other build systems.
ccache 4.7.x or newer is required for MSVC support.

  1. Copy ccache.exe and rename that copy to cl.exe

  2. In the build command, add /p:TrackFileAccess=false /p:CLToolExe=cl.exe /p:CLToolPath=<path to ccache cl> to the end of the build arguments

    • Replace <path to ccache cl> with the path to the copy of ccache.exe you renamed to cl.exe

If this doesn't work for you, please let us know on our Discord sever, or Matrix Space.

Windows MinGW

Dependencies

Preparing MSYS2

  1. Open one of the shortcuts from the MSYS2 folder in the Start menu

    • We recommend building using the CLANG64 msystem of MSYS2, as it compiles considerably faster and with a few less bugs.

  2. Install helpers: Run pacman -Syu pactoys git mingw-w64-x86_64-binutils in the MSYS2 shell.

  3. Install all build dependencies using pacboy: Run pacboy -S toolchain:p cmake:p ninja:p qt6-base:p qt6-5compat:p qt6-svg:p qt6-imageformats:p quazip-qt6:p extra-cmake-modules:p ninja:p ccache:p.

    • Alternatively you can use Qt 5 (for older Windows versions), by running the following command instead: pacboy -S toolchain:p cmake:p ninja:p qt5-base:p qt5-svg:p qt5-imageformats:p quazip-qt5:p extra-cmake-modules:p ninja:p ccache:p
    • This might take a while, as it will install Qt and all the build tools required.

Compile from command line on Windows

  1. cd into the folder you cloned Prism Launcher to. Put quotation marks around the path.

  2. Now we can prepare the build itself: Run cmake -Bbuild -DCMAKE_INSTALL_PREFIX=install -DENABLE_LTO=ON -DCMAKE_OBJDUMP=/mingw64/bin/objdump.exe -DCMAKE_BUILD_TYPE=Debug -G Ninja. These options will copy the final build to the install folder after the build.

    • Replace Debug with Release if you want to build a Release build.
    • If you want to build using Qt 5, then add the -DLauncher_QT_VERSION_MAJOR=5 parameter
    • If you want to use ccache to speed up recompilations, add the parameter -DCMAKE_CXX_COMPILER_LAUNCHER=ccache

  3. Now you need to run the build itself: Run cmake --build build.

  4. Now, wait for it to compile. This could take some time, so hopefully it compiles properly.

  5. Run the command cmake --install build, and it should install Prism Launcher to whatever the -DCMAKE_INSTALL_PREFIX was.

  6. If you don't want Prism Launcher to store its data in %APPDATA%, run cmake --install build --component portable after the install process

  7. When building on Qt 5, whenever compiling, the OpenSSL DLLs aren't put into the directory to where Prism Launcher installs which are necessary in that case, meaning that you cannot log in. The best way to fix this, is just to do cp /(msystem)/bin/libcrypto-1_1.dll /(msystem)/bin/libssl-1_1.dll install. This should copy the required OpenSSL DLLs to log in. When building on Qt 6 this is not necessary because it can use schannel, the Windows tls library.

    • Replace (msystem) with the msystem you're using (e.g. clang64). On 64-bit msystems, like MSYS2 CLANG64, you have to add -x64 to the dlls.

Using Qt Creator (optional)

  1. Install Qt Creator within MSYS2 using pacboy -S qt-creator:p

    • NOTE: If you install or run Qt Creator outside of MSYS2, Qt Creator will fail to find the compiler.

  2. (Optional) Create a shortcut to C:\msys64\(msystem).exe qtcreator

    • Replace (msystem) with the msystem you're using (e.g. clang64).

  3. Open Qt Creator with the qtcreator command in MSYS2.

  4. Choose File->Open File or Project.

  5. Navigate to the Launcher source folder you cloned and choose CMakeLists.txt.

  6. When prompted to configure the project, scroll past the many Desktop Qt options without changing anything and click "Configure Project" at the bottom right.

  7. Cross your fingers, and press the "Run" button (bottom left of Qt Creator).

    • If the project builds successfully it will run and the Launcher window will pop up.

If this doesn't work for you, please let us know on our Discord sever, or Matrix Space.

macOS

Install prerequisites

Using homebrew you can install these dependencies with a single command:

brew update # in the case your repositories weren't updated
brew install qt openjdk@17 cmake ninja extra-cmake-modules # use qt@5 if you want to install qt5

XCode Command Line tools

If you don't have XCode Command Line tools installed, you can install them with this command:

xcode-select --install

Build

If you are on zsh, zsh does not ignore comments by default, run the following to ignore comments for this session:

setopt interactivecomments

Choose an installation path.

This is where the final PrismLauncher.app will be constructed when you run make install. Supply it as the CMAKE_INSTALL_PREFIX argument during CMake configuration. By default, it's in the dist folder, under PrismLauncher.

mkdir build
cd build
cmake \
 -DCMAKE_BUILD_TYPE=Release \
 -DCMAKE_INSTALL_PREFIX="dist" \
 -DCMAKE_PREFIX_PATH="/path/to/Qt/" \
 -DQt6_DIR="/path/to/Qt/" \
 -DCMAKE_OSX_DEPLOYMENT_TARGET=10.14 \
 -DLauncher_BUILD_PLATFORM=macOS \
 -DENABLE_LTO=ON # if you want to enable LTO/IPO:
#-DCMAKE_OSX_ARCHITECTURES="x86_64;arm64" # to build a universal binary (not recommended for development)
#-DLauncher_QT_VERSION_MAJOR=5 \ # if you want to use Qt 5
 ..
make install

Remember to replace /path/to/Qt/ with the actual path. For newer Qt installations, it is often in your home directory. For the Homebrew installation, it's likely to be in /opt/homebrew/opt/qt.

Note: The final app bundle may not run due to code signing issues, which
need to be fixed with codesign -fs -.

OpenBSD

Tested on OpenBSD 7.0-alpha i386. It should also work on older versions.

Build dependencies

You can use IDEs, like KDevelop or QtCreator, to open the CMake project if you want to work on the code.

Building a portable binary 

mkdir install
# configure the project
cmake -S . -B build \
   -DCMAKE_INSTALL_PREFIX=./install -DCMAKE_PREFIX_PATH=/usr/local/lib/qt5/cmake -DENABLE_LTO=ON
# build
cd build
make -j$(nproc) install
cmake --install install --component portable

Building & installing to the system

This is the preferred method of installation, and is suitable for packages.

# configure everything
cmake -S . -B build \
   -DCMAKE_BUILD_TYPE=Release \
   -DCMAKE_INSTALL_PREFIX="/usr/local" \ # /usr/local is default in OpenBSD and FreeBSD
   -DCMAKE_PREFIX_PATH=/usr/local/lib/qt5/cmake # use linux layout and point to qt5 libs
   -DENABLE_LTO=ON # if you want to enable LTO/IPO
   -DLauncher_QT_VERSION_MAJOR="5"
cd build
make -j$(nproc) install # Optionally specify DESTDIR for packages (i.e. DESTDIR=${pkgdir})

IDEs and Tooling

There are a few tools that you can set up to make your development workflow smoother. In addition, some IDEs also require a bit more setup to work with Qt and CMake.

ccache

ccache is a compiler cache. It speeds up recompilation by caching previous compilations and detecting when the same compilation is being done again.

You can download it here. After setting up, builds will be incremental, and the builds after the first one will be much faster.

VS Code

To set up VS Code, you can download the C/C++ extension, since it provides IntelliSense auto complete, linting, formatting, and various other features.

Then, you need to set up the configuration. Go into the command palette and open up C/C++: Edit Configurations (UI). There, add a new configuration for PrismLauncher.

  1. Add the path to your Qt include folder to includePath
  2. Add -L/{path to your Qt installation}/lib to compilerArgs
  3. Set compileCommands to ${workspaceFolder}/build/compile_commands.json
  4. Set cppStandard to c++14 or higher.

For step 3 to work, you also have to reconfigure CMake to generate a compile_commands.json file. To do this, add -DCMAKE_EXPORT_COMPILE_COMMANDS=ON to the end of your CMake configuration command and run it again. You should see a file at build/compile_commands.json.

Now the VS Code setup should be fully working. To test, open up some files and see if any error squiggles appear. If there are none, it's working properly!

Here is an example of what .vscode/c_cpp_properties.json looks like on macOS with Qt installed via Homebrew:

{
    "configurations": [
        {
            "name": "Mac (PrismLauncher)",
            "includePath": [
                "${workspaceFolder}/**",
                "/opt/homebrew/opt/qt@6/include/**"
            ],
            "defines": [],
            "macFrameworkPath": [
                "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks"
            ],
            "compilerPath": "/usr/bin/clang",
            "compilerArgs": [
                "-L/opt/homebrew/opt/qt@6/lib"
            ],
            "compileCommands": "${workspaceFolder}/build/compile_commands.json",
            "cStandard": "c17",
            "cppStandard": "c++17",
            "intelliSenseMode": "macos-clang-arm64"
        }
    ],
    "version": 4
}

CLion

  1. Open CLion
  2. Choose File->Open
  3. Navigate to the source folder
  4. Go to settings Ctrl+Alt+S
  5. Navigate to Toolchains in Build, Execution, Deployment
    • Set the correct build tools (see here)
    • CMake: cmake (optional)
    • Make: make (optional)
    • C Compiler: gcc
    • C++ Compiler: g++
    • Debugger: gdb (optional)
  6. Navigate to CMake in Build, Execution, Deployment
    • Set Build directory to build
  7. Navigate to Edit Configurations (see here)
    • Create a new configuration
    • Name: All
    • Target: All targets
    • Choose the newly added configuration as default

Now you should be able to build and test Prism Launcher with the Build and Run buttons.

Pages in Development: