Adding compiling docs.
This commit is contained in:
237
docs/compiling.md
Normal file
237
docs/compiling.md
Normal file
@ -0,0 +1,237 @@
|
|||||||
|
# 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.
|
||||||
Reference in New Issue
Block a user