Skip to content

Latest commit

 

History

History
287 lines (189 loc) · 16 KB

Building.md

File metadata and controls

287 lines (189 loc) · 16 KB
Raw

Building Etterna

Interested in contributing to Etterna? This guide is the place to start!

Table of Contents

Getting Started

To begin, take a look at what dependencies you're going to need to start compiling. Etterna is cross-platform on Linux, macOS, and Windows. Typically, we work off of the develop branch, therefore all pull requests should be made towards develop.

Quick Start

Here are some commands for current developers and contributors to get started. More are listed at Sample CMake Commands.

cmake -G "Unix Makefiles" ..                                     # Linux
cmake -G "Visual Studio 16 2019" ..                              # Windows
cmake -DOPENSSL_ROOT_DIR="/usr/local/opt/openssl" -G "Xcode" ..  # macOS

Universal Dependencies

  • CMake (Minimum version 3.14.0) - It is recommended to get this package from the CMake website as many package managers do not have the latest version. Check your package manager before trying.
  • OpenSSL (Version 1.1.1)
    • Debian: apt install libssl-dev
    • Fedora: dnf install openssl-devel
    • Arch: pacman -S openssl
    • Alpine: apk add openssl-dev
    • macOS: brew install openssl
    • Windows: A CMake compatible version of OpenSSL is available at Shining Light Productions website. You will need the 32bit and 64bit installers if you plan on building both versions. It's recommended to uninstall old versions to make sure CMake can find the correct latest version. Direct links: 32bit, 64bit. If these links are dead, look for the OpenSSL v1.1.1 install links (EXE or MSI) on the Shining Light Productions site. Typically we use the full versions rather than the Light versions.
  • depot_tools - Installation is platform specific. To skip installing this, follow the relevant instructions in CLI Project Generation.

Linux Dependencies

While most dependencies for macOS and Windows are included in the repo, there are some linux libraries which cannot be included in the repo.

For Pop_OS!, install the Debian dependencies, then refer to the Pop_OS! Notes section below.

  • Debian: apt install build-essential libssl-dev libx11-dev libxrandr-dev libcurl4-openssl-dev libglu1-mesa-dev libpulse-dev libogg-dev libasound-dev libjack-dev
  • Fedora: dnf install openssl-static libX11-devel libcurl-devel mesa-libGLU-devel libXrandr-devel libogg-devel pulseaudio-libs-devel alsa-lib-devel jack-audio-connection-kit-devel
  • Arch: pacman -S openssl libx11 libxrandr curl mesa glu libogg pulseaudio jack
  • Alpine: apk add build-base openssl-dev libx11-dev libxrandr-dev curl-dev mesa-dev glu-dev pulseaudio-dev libogg-dev alsa-lib-dev jack-dev

Pop_OS! Notes

More recent builds of Pop_OS! are missing some required dependencies.

Python 2.7

The build requires Python 2.7 be installed and symlinked as python.

Run python --version. If it's ok, skip this section. If python --version says command not found, run the following:

sudo apt install -y python2.7
sudo ln -s /usr/bin/python2.7 /usr/local/bin/python

clang

clang is required for Crashpad. If you don't want to include Crashpad, add -DWITH_CRASHPAD=OFF when running cmake. Otherwise, install clang:

sudo apt install -y clang

Windows Dependencies

macOS Dependencies

  • YASM or NASM. They can be installed with brew commands brew install yasm or brew install nasm. They are not directly used for Etterna, though is required for ffmpeg to be built from source.

Project Generation

First, ensure you have forked Etterna, cloned to your system, and checked out develop.

There are two stages apart of CMake projects.

  1. Configuration: CMake will run through all CMakeLists.txt and ensure all code processes.
  2. Generation: CMake will take information from generation, and create the project files based on what was selected through the generation option.

CLI Project Generation

Both configuration and generation stages automatically happen one after the other when using the CLI. Start by creating a folder to hold all the output object files, usually called build, within the root of the project.

mkdir build && cd build

Etterna has game resources in the root of the project, so the output binary is either placed in the root of the project (Unix) or in the Program folder in the project root (Windows).

To generate project files, you will only need to specify the GENERATOR. The ARCHITECTURE will assume 64bit if left undefined. If any trouble occurs with OpenSSL, the most likely answer will be to define where you have it installed through the SSL_DIRECTORY variable. If depot_tools is left uninstalled or misconfigured, you may be able to run cmake but the game will not compile. To get around this, build without Crashpad: Specify -DWITH_CRASHPAD=OFF in the cmake command.

  • SSL_DIRECTORY: The root directory of your OpenSSL install. It may be required on macOS depending on the OpenSSL version which comes with your system (thought we recommend getting the latest version from homebrew).
  • GENERATOR: The generator you are choosing to use. Supported generators are listed below.
  • ARCHITECTURE: The target architecture. Currently we support Win32 and x64. This parameter is only necessary if using a Visual Studio generator. x64 will automatically be selected if the variable is left empty.
cmake -DOPENSSL_ROOT_DIR="SSL_DIRECTORY" -G "GENERATOR" -A "ARCHITECTURE"  ..

Or to build without Crashpad:

cmake -DOPENSSL_ROOT_DIR="SSL_DIRECTORY" -DWITH_CRASHPAD=OFF -G "GENERATOR" -A "ARCHITECTURE"  ..

We actively support the following CMake generators

  • macOS: Ninja, Xcode, Unix Makefiles
  • Linux: Ninja, Unix Makefiles
  • Windows: Ninja, Visual Studio 16 2019, Visual Studio 17 2022

For the OPENSSL_ROOT_DIR parameter, set the directory for where ever the openssl root directory is located. Here are possible options

  • macOS: /usr/local/opt/openssl or otherwise depending on your setup (if you're using HomeBrew, MacPorts or installed in from source)
  • Linux: This parameter is not necessary on linux. (CMake can find it on it's own)
  • Windows: CMake writes files to find the version of OpenSSL linked above. If that version is installed, it should not be necessary to specify this variable (unless you have OpenSSL installed in a non-standard location, in which case, you should set OPENSSL_ROOT_DIR to that location)

Users building without Crashpad may choose to add the -DWITH_CRASHPAD=OFF option at the beginning of the command.

Users of Linux be aware that the game builds on the Debug target by default. Here are better alternatives:

  • -DCMAKE_BUILD_TYPE=Release - Builds Release binary with no symbols, normal optimization.
  • -DCMAKE_BUILD_TYPE=RelWithDebInfo - Builds Release binary with symbols, useful for debugging if any issues arise, almost same as Release otherwise.

Sample CMake Commands

⚠️ Note: You likely want to include -DCMAKE_BUILD_TYPE=Release when running cmake. This results in a smaller build that will often perform much better.

cmake -G "Ninja" ..                                                             # Linux Ninja
cmake -G "Unix Makefiles" ..                                                    # Linux Makefiles
cmake -G "Visual Studio 16 2019" -A Win32 ..                                    # 32bit Windows
cmake -G "Visual Studio 16 2019" -A x64 ..                                      # 64bit Windows
cmake -DOPENSSL_ROOT_DIR="/usr/local/opt/openssl" -G "Xcode" ..                 # macOS Xcode
cmake -DOPENSSL_ROOT_DIR="/usr/local/opt/openssl" -G "Ninja" ..                 # macOS Ninja
cmake -DOPENSSL_ROOT_DIR="/usr/local/opt/openssl" -G "Unix Makefiles" ..        # macOS Makefiles
cmake -DWITH_CRASHPAD=OFF -G "Visual Studio 16 2019" -A x64 ..                  # Without Crashpad - 64bit Windows
cmake -DCMAKE_BUILD_TYPE=Release -G "Ninja" ..                                  # Release Configuration - Linux Ninja
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -G "Ninja" ..                           # Release + Debug Symbols - Linux Ninja
macOS Xcode Generation Note

When generating a project for Xcode, you may see errors stating No CMAKE_{C,CXX}_COMPILER could be found. Ensure that you have the Xcode command line tools installed. The command line tools can be installed with xcodeselect --install. You may also have to run xcode-select --reset to ensure the correct command line tools are apart of the system path.

GUI Project Generation

In order to compile properly, you will want to make your CMake-GUI look similar to the photo below. The first text field is the location where you cloned Etterna, the second text field is where you want to place the build object files. If necessary,OPENSSL_ROOT_DIR can be added by clicking the add entry button. It should look similar to the following image.

CMake Generation Window

NOTE: Setting OPENSSL_ROOT_DIR is unnecessary for linux users as CMake will find the location of OpenSSL on it's own.

CMake Add Cache Entry Window

Windows Users: If CMake was unable to find OpenSSL on it's own, remember to change the value correspond to the correct 32bit or 64bit version of the OpenSSL library.

Click the buttons labeled Configure. The first time this button is clicked (and a CMakeCache.txt does not exit in the build directory), CMake will ask about what generator you would like to use. If a Visual Studio generator is chosen, the Optional platform for generator will assume the 64bit option of x64 if left empty. If building the 32bit version is required, click the drop down and select Win32. Once Finish is clicked, the project will begin configuring.

CMakeSetup Window

Finally, click Generate. An Etterna.sln file should appear in the build folder. Open it , and you are ready to start coding.

Compiling

Ninja

The ninja command used is exactly the same across all operating systems. It should be noted that Ninja can only build 64bit binaries (unless you would like to compile Ninja yourself).

To install ninja, use one of the following commands

  • Debian: apt install ninja-build
  • Fedora: dnf install ninja-build
  • Arch: pacman -S ninja
  • Alpine: apk add samurai #As of 2021-11-10 ninja is not available in alpine main so use samurai instead
  • macOS: brew install ninja

To start compiling, run the cmake command with the Ninja generator, then run ninja.

Linux

Run make or ninja corresponding to the CMake generator you used.

macOS

Xcode Editor

Open the Etterna.xcodeproj file generated within the build directory, select the Etterna target, and you are ready to start coding.

Xcode CLI

xcodebuild -project Etterna.xcodeproj -configuration Release

Due to the extreme verbosity of xcodebuild, we recommend xcpretty to clean up the output.

Windows

Visual Studio Editor

Open the Etterna.sln file generated within the build directory, and you are ready to start coding.

Visual Studio CLI

If you prefer the command line, these commands should be what you are looking for. Make sure you run the proper visual studio command prompt.

msbuild Etterna.sln /p:Platform="Win32" /p:Configuration="Release"  # Only for 32bit CMake generator
msbuild Etterna.sln /p:Platform="x64"   /p:Configuration="Release"  # Only for 64bit CMake generator

Distribution

We use CMake's CPack module to build distribution files. Currently, we create distribution binaries for Windows and macOS.

Windows only prerequisite: Install the latest version of Nullsoft Scriptable Install System

To build a distribution file for the operating system you are using, run cpack in the build directory after compiling.

Static Analysis

cppcheck

cppcheck is a cross-platform static analysis tool which CMake supports by adding a target for it in your desired generator. The target named cppcheck will only be created if CMake can find the cppcheck command on your system.

  • Debian: apt install cppcheck
  • Fedora: dnf install cppcheck
  • Arch: pacman -S cppcheck
  • Alpine: apk add cppcheck
  • macOS: brew install cppcheck
  • Windows: An installer is available at the cppcheck website. Make sure that cppcheck runs when you enter the command in your CLI. If it doesn't, check your system/user path to ensure that the bin folder of where you installed cppcheck is listed there.

When cppcheck is run, it will generate a file in the build directory called cppcheck.txt which will have the output of the command. The output is saved to a file as the command produces significant output, and can take some time to run.

To run cppcheck, run the target. Running the target will be different depending on the generator you have chosen.

Documentation

C++ Docs

Etterna uses Doxygen to build it's C++ documentation. Documentation is generated in a doxygen directory, inside the build directory. CMake is setup to make a target called doxygen if the executable found in the path.

  • Debian: apt install doxygen
  • Fedora: dnf install doxygen
  • Arch: pacman -S doxygen
  • Alpine: apk add doxygen
  • macOS: brew install doxygen
  • Windows: An installer is available at the Doxygen website. As with cppcheck, make sure the executable binary directory is added to your path.

Doxygen within CMake is able to use graphviz to generate better looking relationship/hierarchy graphs. You can see how to download it for your operating system at the graphgiz download page.

LDoc

Etterna uses LDoc to generate Lua documentation. We reccomend installing LuaRocks, and then installing LDoc through LuaRocks. Similar to Doxygen, it will only create the ldoc target if it can find the ldoc command in your system path.