162 lines
6.5 KiB
Markdown
162 lines
6.5 KiB
Markdown
<br><br>
|
|
|
|
<div style="width: 100%;">
|
|
<img src="./logo/raster.png" width="128px" style="display: block; margin-left: auto; margin-right: auto;"/>
|
|
<h1 style="text-align: center; top:-1em;">fennec</h1>
|
|
<div style="text-align: center; top:-4em;">a free and open source game engine</div>
|
|
</div>
|
|
|
|
<br><br>
|
|
|
|
## Table of Contents
|
|
|
|
1. [Introduction](#introduction)
|
|
2. [Building from Source](#building-from-source)
|
|
1. [Building from Terminal](#building-from-terminal)
|
|
2. [Building on Windows](#building-on-windows)
|
|
3. [Running the Test Suite](#running-the-test-suite)
|
|
3. [Usage](#usage)
|
|
4. [Contribution](#contribution)
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<a id="introduction"></a>
|
|
## Introduction
|
|
|
|
fennec is designed to be a general purpose, educational game engine.
|
|
|
|
Interfacing with the API in C++ follows the [GNU Coding Standards](https://www.gnu.org/prep/standards/html_node/index.html).
|
|
fennec may be used both through the provided editor application, or as a standalone
|
|
library link against your application. Some main areas where the engine strays from
|
|
the GNU standard includes the following:
|
|
|
|
- [Section 4.7, Standards for Graphical Interfaces](https://www.gnu.org/prep/standards/html_node/Graphical-Interfaces.html).
|
|
fennec provides an implementation for X11, however it does not use the GTK toolkit.
|
|
- [Section 6.1, GNU Manuals](https://www.gnu.org/prep/standards/html_node/GNU-Manuals.html)
|
|
fennec does not use Texinfo and instead uses Doxygen. Otherwise, it follows the other standards of this section.
|
|
- [Section 7, The Release Process](https://www.gnu.org/prep/standards/html_node/Managing-Releases.html)
|
|
fennec follows most of the conventions in this section, however the build system used is CMake and not
|
|
Makefile. CMake, although overwhelming at first, is much more friendly to those who are learning build systems for the first time.
|
|
|
|
<br>
|
|
|
|
The C++ stdlib is reimplemented in the fennec engine.
|
|
There are a few reasons for this:
|
|
|
|
1. Standardize implementations across compilers
|
|
2. Set proper naming conventions, i.e. `std::vector` → `fennec::dynarray`
|
|
3. Optimize compilation times, binary size, and performance.
|
|
4. Inject debugging information when necessary.
|
|
5. Expose functionality in a readable manner for those interested in learning the
|
|
intricacies of the implementation.
|
|
|
|
<br>
|
|
|
|
|
|
<a id="building-from-source"></a>
|
|
## Building from Source
|
|
|
|
fennec uses the CMake build system. The CMake build script provides several
|
|
targets for building parts of the engine.
|
|
|
|
| Target | Description |
|
|
|------------------------|----------------------------------------------------------------------------------------|
|
|
| fennec | The main engine target. |
|
|
| fennec-metaprogramming | Generate metaprogramming info for the fennec library. A dependency of the main engine. |
|
|
| fennecdocs | Generate html documentation for the engine. Requires Doxygen. |
|
|
| fennecdocs-clean | Cleans the generated html documentation files. |
|
|
| fennec-test | Test suite for verifying engine functionality. |
|
|
|
|
<br>
|
|
|
|
Using an IDE will streamline the build process for you and add additional configuration
|
|
options. Eclipse, Visual Studio, and CLion provide built-in support for CMake. VSCode
|
|
is also a viable IDE but involves some extra setup.
|
|
|
|
<br>
|
|
|
|
<a id="building-from-terminal"></a>
|
|
### Building from Terminal
|
|
|
|
`build.sh` provides profiles for building the main engine. Run `./build.sh --help`
|
|
for more info.
|
|
|
|
By default, the CMake generator
|
|
used is Ninja, which requires Ninja to be installed. You can modify the
|
|
build scripts to use another build manager, see the [CMake documentation
|
|
for available generators](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html).
|
|
|
|
<br>
|
|
|
|
<a id="building-on-windows"></a>
|
|
### Building on Windows
|
|
|
|
The bash script can be run natively on Windows when WSL is enabled. You do not
|
|
need to run the script in WSL, simply use the "bash" command in Command Prompt
|
|
or PowerShell. It requires CMake and a C/C++ compiler to be installed and
|
|
configured in the PATH environment variable.
|
|
|
|
Fore more details, [see this blog post](https://blogs.windows.com/windows-insider/2016/04/06/announcing-windows-10-insider-preview-build-14316/)
|
|
for Windows Build 14316.
|
|
|
|
Otherwise, follow the sequence of commands provided in the bash script.
|
|
|
|
```console
|
|
mkdir -p build/<profile>
|
|
cd ./build/<profile>
|
|
cmake -G Ninja -DCMAKE_BUILD_TYPE=<profile> -S ../.. -B .
|
|
cmake --build . --target fennec
|
|
```
|
|
|
|
The value of `<profile>` may be one of the following:
|
|
|
|
| Profile | Description |
|
|
|----------------|----------------------------------------------------------------------------------|
|
|
| Debug | Build in debug mode, provides full debugging information to use with a debugger. |
|
|
| Release | Build in release mode, provides full optimizations, eliminating debug info. |
|
|
| RelWithDebInfo | Build in release mode with extra debug info, provides partial optimizations. |
|
|
| MinSizeRel | Build in release mode but optimizing for minimum binary size. |
|
|
|
|
|
|
<br>
|
|
|
|
If you would like to use Visual Studio without CMake, you can use the build
|
|
script to generate a Visual Studio project for the source. For a list of available
|
|
Visual Studio generators, [see this section](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html).
|
|
Running the following command will generate the Visual Studio project.
|
|
|
|
```commandline
|
|
cmake -G "Visual Studio 17 2022" -A x64
|
|
```
|
|
|
|
<br>
|
|
<br>
|
|
|
|
<a id="running-the-test-suite"></a>
|
|
## Running the Test Suite
|
|
|
|
`test.sh` provides profiles for building the test suite and executes them.
|
|
|
|
By default, it runs in debug mode and the first failed test will throw an assertion.
|
|
Any tests that involve running as an application will spawn a subprocess with a window,
|
|
and give a short description of the behaviour in the terminal. It will then have you confirm
|
|
whether the information displayed is correct.
|
|
|
|
<br>
|
|
<br>
|
|
|
|
<a id="usage"></a>
|
|
## Usage
|
|
|
|
<br>
|
|
<br>
|
|
|
|
<a id="contribution"></a>
|
|
## Contribution
|
|
|
|
There are some principles to keep in mind when contributing to fennec.
|
|
|
|
1. You must follow the style guide provided by the [GNU Coding Standard](https://www.gnu.org/prep/standards/html_node/Writing-C.html).
|
|
2. Any changes must allow all projects to be forward compatible with newer engine verisons. |