YourWishes/Dawn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Adding compiling docs.

Browse Source
This commit is contained in:
Dominic Masters
2023-07-25 18:58:35 -07:00
parent bf1f05c335
commit bf13456067
1 changed files with 237 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

237
docs/compiling.md Normal file
View 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.