## Table of Contents
1. [Introduction](#introduction)
1. [Coding Standards](#coding-standards)
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)
4. [Usage](#usage)
5. [Contribution](#contribution)
## Introduction
fennec is designed to be a general purpose, educational game engine.
fennec may be used through the provided editor application, or as a standalone
library to link against your application.
### Coding Standards
Interfacing with the API in C++ follows the [GNU Coding Standards](https://www.gnu.org/prep/standards/html_node/index.html).
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.
fennec Standards:
* As per the GNU standard, macros should be `SCREAMING_SNAKE_CASE`. Additionally, Macros should be preceded by `_`.
Macros that wrap C-Style functions may use normal `snake_case`.
- Header Guards should be implemented using `#ifndef`, `#define`, and `#endif` for portability.
The naming convention for Header Guards is as follows: `___H`.
I.E. the engine file `fennec/lang/utility.h` has the Header Guard `FENNEC_LANG_UTILITY_H`.
* Helper Functions, in the case of classes, should be private.
In the case of global functions, helpers should be placed in a similarly named file in a subdirectory and namespace called `detail`.
Helper functions should be documented with C-Style comments, however it is not necessary to provide Doxygen documentation.
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.
## Building from Source
fennec uses the CMake build manager. The CMake build script provides several
targets for building parts of the engine.
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.
| 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. |
| Dependency | Notes |
|-------------------|----------------------------------------------------------------------------------------------------------|
| C/C++ Compiler | GCC/G++ is the compiler that fennec is designed around, however, Clang, MSVC, and MinGW may also be used |
| CMake | The build manager used by the engine |
| A build system | Any build system will work, however, `build.sh` uses Ninja by default. |
| A memory debugger | Any memory debugger will work, however, `test.sh` uses Valgrind by default. |
| Doxygen | Doxygen is required for building the documentation for fennec. This is an optional dependency |
| Graphviz | Graphviz is a required dependency for Doxygen |
### 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).
### 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.
The script will require the build [dependencies](#dependencies) installed and configured to be available on 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/
cd ./build/
cmake -G Ninja -DCMAKE_BUILD_TYPE= -S ../.. -B .
cmake --build . --target fennec
```
The value of `` 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. |
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
```
## 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.
## Usage
## 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.
