Dawn/docs/COMPILING.md

Compiling, Debugging and Running

This document's purpose is to explain how to compile, debug and run the project on your machine. It is assumed that you have a basic understanding of the fundamentals of your operating system and how to use a terminal.

Preamble

The Dawn project is written almost entirely in C and C++. This includes all of the tooling used to generate the project and assets. The only non-C/C++ code is used by CMake to generate the output compilation files. This provides the Dawn project an extremely high level of portability not typically seen in other projects.

TLDR; Version

This document is going to go over the installation and configuration of the following items. If you are already familiar with these tools, you can skip to the "Downloading the Source Code" section.

• C/C++ Compiler
• CMake
• Git
• IDE You may also need python, since we depend on third-party libraries that may use python scripts to generate their own build files. This is not required for the Dawn project itself.

Pre-Configuration

In order to compile the Dawn project, you are required to have the following tools installed on your machine.

1. A C/C++ Compiler

The exact tool(s) will depend on your specific scenario. The compiler is used to take the .cpp/.hpp files and generating binaries that execute on the target machine. Typically you will use your own C/C++ compiler for the machine that you are currently running, e.g. if you are running Windows, you will use the Visual Studio compiler. If you are running Linux, you will use GCC or Clang. If you are running macOS, you will use Clang, and so-on.

If you are intending to compile on a different machine than the one you are currently running, you will need to use a cross-compiler that is specific for your use-case. You will also need to refer to the documentation for creating a new Dawn engine target.

Please follow the instructions for your specific operating system to install the appropriate C/C++ compiler.

Windows You will need to download and install Visual Studio. Visual Studio (not to be confused with Visual Studio Code) is a full IDE that bundles the official Microsoft C/C++ compiler. It is the recommended compiler for building the Dawn project on Windows.

Advanced used can also use MinGW or another compiler if they wish, however this is not officially supported.

After installing Visual Studio, you will need to install the C++ development tools. This can be done by opening the Visual Studio Installer and selecting the "Desktop development with C++" workload.

Linux You will need to install the GCC and Clang compilers. The compilers are usually installed either by default or by installing the necessary packages for your Linux distribution.

For example, on Ubuntu, you can install the GCC and Clang compilers by running the following command:

sudo apt install build-essential clang

On Arch Linux, you can install the GCC and Clang compilers by running the following command:

sudo pacman -S base-devel clang

And on Fedora, you can install the GCC and Clang compilers by running the following command:

sudo dnf install @development-tools clang

For other distributions, please refer to your distribution's documentation.

macOS You will need to install the Xcode command line tools. This can be done by done by running the following command in your terminal:

xcode-select --install

Afterwards you will need to install and enable Brew. This can be done by running the following command in your terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. CMake

CMake is a tool that is used to generate the compilation files for the Dawn project. In short this is used to create versions of the Dawn project that can be compiled on all different sets of compilers, so if you are compiling on, for example, Windows, you can use CMake to generate the compilation files for the Visual Studio compiler, or if you are compiling on Linux, you can use CMake to generate the compilation files for the GCC or Clang compilers, and so-on.

To install CMake, please follow the instructions for your specific operating system. All other operating systems can be found on the CMake downloads page.

Windows You will need to download and install CMake. The installer will guide you through the installation process and will install the CMake executable to your system. It is recommended that you add CMake to your system PATH if requested by the installer.

Linux Like installing the C/C++ compilers, you will need to install CMake using your specific Linux distribution's package manager, there is also a chance that CMake can be installed using flatpak or snap. Please refer to your distribution's documentation for more information.

For Ubuntu and other Debian-based distributions, you can install CMake by using the following command:

sudo apt install cmake

For Arch Linux, you can install CMake by using the following command:

sudo pacman -S cmake

And for Fedora, you can install CMake by using the following command:

sudo dnf install cmake

macOS You will install CMake using brew. We detailed how to install brew in the C/C++ compiler section. To install CMake, run the following command in your terminal:

brew install cmake

3. Git

Git is a version control system that is used to manage the Dawn project's source code. It is used to download the source code, and to update the source code to the latest version. It is also used to manage the project's dependencies. Git is a standard tool in the programming industry and is used to manage complex projects, especially those that are worked on by multiple people.

Git, like all of the above tools, is installed slightly differently depending on your operating system. Please follow the instructions for your specific operating system.

Windows You will need to download and install Git. The installer will guide you through the installation process and will install the Git executable to your system. It is recommended that you add Git to your system PATH if requested by the installer. You do not need to add the Context-menu items to your system.

Linux Like installing the C/C++ compilers, you will need to install Git using your specific Linux distribution's package manager. It is also likely that git would have been installed by default. Please refer to your distribution's docs for more information.

For Ubuntu and other Debian-based distributions, you can install Git by using the following command:

sudo apt install git

For Arch Linux, you can install Git by using the following command:

sudo pacman -S git

And for Fedora, you can install Git by using the following command:

sudo dnf install git

macOS You will install Git using brew. We detailed how to install brew in the C/C++ compiler section. To install Git, run the following command in your terminal:

brew install git

4. An IDE

An IDE (Integrated Development Environment) is a tool that is used to view and edit code of projects. While it is not required to use an IDE, it is recommended since it can make the process of editing and running the project much easier.

There are many different IDEs available, and often people chose an IDE that will suit their preferences and needs, however if you are unsure of which IDE you should be using, the Dawn project recommends using Visual Studio Code, not to be confused with Visual Studio.

Visual Studio Code is a free and open-source IDE that is widely used in the industry for its simple, modern and configurable interface. For example you can configure VSCode to work on Web Projects, Game Projects, and more. It acts like a text editor with a bunch of extra tools.

In addition to installing the VSCode IDE, we will add several recommended plugins that will make editing the Dawn project easier and more seamless.

To install VSCode follow the instructions for your specific operating system on the VSCode downloads page, as it can vary a lot between operating systems.

After installing VSCode, you will need to install the following plugins, by clicking on the "Extensions" icon on the left-hand side of the VSCode window, and searching for the following plugins. You may also be able to click on the following links to install the plugins directly, but it may not work.

• C/C++
• CMake
• CMake Tools

Downloading the Source Code

Now that you have all of the necessary tools installed, you can download the source code of the project and using it to build. The source code contains all of the code of the project, as well as the assets and the build scripts. This is confidential information and should not be shared with anyone.

1. Cloning the Repository

We previously installed the git tool, which is used to download the source code of the project, and some third-party libraries. To download the source code, you will need to open a terminal and navigate to the directory where you want to download the source code to.

Afterwards, you will need to run the following command:

git clone https://git.wish.moe/YourWishes/Dawn.git

This will download the source code of the project to a new subdirectory called "Dawn" and put all of the projects' source code within there.

2. Installing the Dependencies / Libraries.

I try to keep dependencies on third-party libraries to a minimum, however there are a few libraries that are required to build the Dawn project. These libraries are not included in the source code, and must be downloaded separately. This is done using the git tool.

After you have cloned the above repository, you will need to open a terminal and navigate to the directory where you downloaded the source code to. Afterwards, you will need to run the following command:

git submodule update --init --recursive

This will fetch all of the third-party libraries that are required to build the Dawn project. This may take a while depending on your internet connection.

3. Loading the Project

This step is semi-optional. We are aiming to build the project using CMake, and the easiest way to do this is to use the CMake Tools plugin for VSCode that we installed earlier. This plugin will automatically detect the CMake files in the project and will allow us to build the project using the VSCode interface.

If you opted out of using VSCode, you will need to set up your CMake environment to suit your IDE or needs. This is outside of the scope of this document, and you will need to refer to your IDE's documentation for more information.

To load the project, you will need to open VSCode and open the Dawn project directory. Most operating systems will allow you to do this by dragging the Dawn project directory onto the VSCode window. If this does not work, you can open VSCode and click on the "File" menu, and click on "Open Folder". You will then need to navigate to the Dawn project directory and click "Open".

Afterwards you will likely be prompted autometically to configure the CMake Tools plugin. If you are not, you can click on the "CMake" icon on the left-hand side of the VSCode window, and click on "Configure". This will configure the CMake Tools plugin to use the CMake files in the Dawn project directory.

You may also be asked to select a compiler. If you are using Windows, you will need to select the Visual Studio compiler. If you are using Linux, you will need to select the GCC or Clang compiler. If you are using macOS, you will need to select the Clang compiler. If you are using a different compiler, you will need to select the appropriate compiler.

If prompted to select a build type, select "Debug".

Compiling the Project

Now that we have the project loaded into our IDE, we can compile the project. This is done using the CMake Tools plugin for VSCode. If you are not using VSCode you will need to refer to your IDE's documentation for more information.

Firstly, you will need to create a settings file to configure the project. In VSCode you can create a new folder called .vscode (Including the leading .) in the Dawn project root directory. Afterwards, you will need to create a new file called settings.json in the .vscode directory. You will then need to paste the following into the file:

{
    "cmake.configureArgs": [
      "-DDAWN_BUILD_TOOLS=true",
      "-DDAWN_BUILD_TARGET=target-liminal-win32-glfw",
      "-DDAWN_DEBUG_BUILD=true"
    ]
}

And save the file. You may want to alter the values to suit your needs. For example, if you are compiling on Linux, you will need to change target-liminal-win32-glfw to target-liminal-linux-glfw. If you are compiling on macOS, you will need to change it to target-liminal-osx-glfw. The specific configure arguments are outside of the scope of this document, and you will need to refer to the specific target documentation for more information.

After you have created the settings file, you will need to configure and build the project. To perform the build you need to click "Build" button the bottom of the VSCode window. This will compile the project and will output the resulting binaries in to a "build" directory within the Dawn project directory.

Upon clicking the "Build" button, you will see an output panel appear at the bottom of the VSCode window. This will show the process of the build, and will show any errors that may occur. This is used to debug and fix any issues that may occur during the build process.

If the build was successful, you will see a "Build finished" message in the output panel, typically read as;

[build] Build finished with exit code 0

If you do not see this message, or if the exit code is not 0, you will need to debug the issue. The output panel will show the error message which is helpful so we can debug the issue. If you are unable to debug the issue, you can ask for help in the Discord server.

Running the built project

After the build process succeeds you will be able to run the project. This is done by clicking on the Run icon, which looks like a play button, on the bottom of the VSCode window. This will run the project in production mode and will not show any debug information.

If the program hangs, crashes or does not run, you can click the Debug icon, which looks like a ladybug, on the bottom of the VSCode window. This will run the project in debug mode and will show debug information and HALT the program if there is an error detected. If program HALTS in debug mode you can use this information to debug the issue. If you are unable to debug the issue, you can ask for help in the Discord server.