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](https://visualstudio.microsoft.com/downloads/).
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](http://www.mingw.org/) 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:
```bash
sudo apt install build-essential clang
```

On Arch Linux, you can install the GCC and Clang compilers by running the
following command:
```bash
sudo pacman -S base-devel clang
```

And on Fedora, you can install the GCC and Clang compilers by running the
following command:
```bash
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:
```bash
xcode-select --install
```

Afterwards you will need to install and enable [Brew](https://brew.sh/). This
can be done by running the following command in your terminal:
```bash
/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](https://cmake.org/download/).

**Windows**
You will need to download and install [CMake](https://cmake.org/download/). 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:
```bash
sudo apt install cmake
```

For Arch Linux, you can install CMake by using the following command:
```bash
sudo pacman -S cmake
```

And for Fedora, you can install CMake by using the following command:
```bash
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:
```bash
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](https://git-scm.com/downloads). 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:
```bash
sudo apt install git
```

For Arch Linux, you can install Git by using the following command:
```bash
sudo pacman -S git
```

And for Fedora, you can install Git by using the following command:
```bash
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:
```bash
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](https://code.visualstudio.com/),
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](https://code.visualstudio.com/download), 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++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
- [CMake](https://marketplace.visualstudio.com/items?itemName=twxs.cmake)
- [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.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:
```bash
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:
```bash
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:
```json
{
    "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;
```bash
[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.