twon/morpheus

Work in progress: Cross Platform Game Engine

Morpheus

Build Instructions

The build use CMake for build system generation and Conan 2 for dependency management. Prerequisites for building are:

• A supported C++ compiler
  • GCC, 11.x and later
  • Clang, 14.x and later
  • MSCV, 2022 and later
• Python
• Git

In general you can use your own Conan profile but the project ships with profiles for all supported configurations. I you use your own profile then ensure that if you are building again libstdc++ with GCC or Clang that you build on the C++11 and onwards version. To do so insert the following into your Conan profile under the [settings] section:

compiler.libcxx=libstdc++11

However, preferably use one of the pre-installed configurations in <project root>/.conan/profiles (which are installed via the conan config install ./conan command to the local conan configuration folder ./.conan2 as specified in the ./.conanrc file) as these are tested and known to work.

Cloning the Repo

To clone the repo use git to clone the repository to your local machine:

git clone https://github.com/Twon/Morpheus.git

Configuring Conan

To set up Conan for the repository create a repository local virtual environment for Python and activate the environment (note this step differs for different shells)

cd <project root>
python3 -m venv .venv               # Create a Python virtual env
source ./.venv/bin/activate         # Activate the virtual env for bash by source.
pip install -r ./requirements.txt   # Install all Python dependencies
conan profile detect --force        # Generate a default configuration with the local machine settings
conan config install ./.conan       # Install supported build profiles from ./.conan to ./conan2

Standard build

Now with the repository cloned and Conan configured building the repository required installing the Conan dependencies and configuring CMake. Note that since CMake 3.19 there is a new mechanism for sharing common configurations with users of your project called presets, this is now the recommended mechanism for Conan 2, which will generate default presets during the installation stage:

cd <project root>

To enable Mold linker usage for gcc and clang with Linux:

conan install ./ -pr:h .conan2/profiles/gcc/12/x64-libstdc++11-debug -pr:b .conan2/profiles/gcc/12/x64-libstdc++11-debug --build missing
source build/Debug/generators/conanbuild.sh # Access the environment variables needed to use the Mold linker with gcc and clang

To disable Mold linker usage for gcc and clang with Linux:

conan install ./ -pr:h .conan2/profiles/gcc/12/x64-libstdc++11-debug -pr:b .conan2/profiles/gcc/12/x64-libstdc++11-debug --build missing -o link_with_mold=False

Use the preset generated by Conan

cmake --preset conan-debug

Now build via CMake using the build preset generated by Conan. As a debug profile was used during the Conan install step this will create a Debug build with full symbolic information.

cmake --build --preset conan-debug

Multi-Config Build

Multi-config builds allow you to create a build folder containing sub-folders for different build configurations and build them side-by-side. Once again starting with the repository clone and Conan configured run the install stage, but this time we specity the Conan cmake tools use Ninja multi-config to generate Release, Debug, RelWithDebInfo configurations. To generate all 3 configuration we run the conan-default preset which configures CMake for these configurations.

conan install ./ -pr:h .conan2/profiles/msvc/193/x64-release -pr:b .conan2/profiles/msvc/193/x64-release --build missing -c tools.cmake.cmaketoolchain:generator="Ninja Multi-Config"
source build/generators/conanbuild.sh # Access the environment variables needed to use the Mold linker with gcc and clang
cmake --preset conan-default  # The configure stage for multi-config builds is conan-default

Now with CMake configured we select the preset conresponding to the configuration we want to build, in this case the Release configuration.

cmake --build --preset conan-release # The build stage for multi-config builds is the conan-<configuration>

Build Documentation

To build documentation we once again ensure we have cloned the repository and have configured Conan. This time when installing Conan dependencies we specify -o build_docs=True so that Conan installs the tools required to build documentation (including Doxygen).

conan install ./ -pr:h .conan2/profiles/clang/15/x64-libc++-release -pr:b .conan2/profiles/clang/15//x64-libc++-release --build missing -o build_docs=True
cmake --preset conan-release -DMORPHEUS_BUILD_DOCUMENTATION:BOOL=ON # Build with documentation enabled

cmake --build --preset conan-release --target Documentation # Build the Documentation target

Run Code Coverage

To build with code coverage we once again ensure we have cloned the repository and have configured Conan. We can install as a regular build.

conan install ./ -pr:h .conan2/profiles/gcc/12/x64-libstdc++-debug -pr:b .conan2/profiles/gcc/12/x64-libstdc++-debug
cmake --preset conan-debug -DENABLE_CODE_COVERAGE=1 # Build with code coverage enabled

The build is now configured to send code-coverage flags to the compiler when building, so no build the project with coverage collection enabled, run the tests to collect coverage information and then run the coverage targets to generate the required code-coverage reports.

cmake --build --preset conan-debug                             # Build the project
ctest --preset conan-debug                                     # Run all tests to collect coverage information.
cmake --build --preset conan-debug --target coverage           # Build the coverage stats
cmake --build --preset conan-debug --target coverage-lcov      # Build a html report from the coverage information
cmake --build --preset conan-debug --target coverage-corbetura # Build a Corbertura XML coverage report

morpheus's Issues

Add Pre-compiled header support to the build system

https://gitlab.kitware.com/cmake/cmake/merge_requests/3553

Support for Data Parallel C++ / OneAPI

https://techdecoded.intel.io/big-picture/modern-threading-techniques-pro-tbb/#gs.g5hqll

https://software.intel.com/en-us/oneapi

OpenGL Rendering System

https://github.com/eug/awesome-opengl

Correct Colour Support (Physically Based Rendering approach)

Proposal p2005r0 raises this issue. Work is ongoing for a proposal to correct this. We should look to adopt this approach (or hopefully an early stage solution)

Background reading:
https://medium.com/hipster-color-science/a-beginners-guide-to-colorimetry-401f1830b65a

D3D12 Rendering System

https://www.3dgep.com/
https://devblogs.microsoft.com/directx/demystifying-full-screen-optimizations/

Add SIMD Vector & Matrix Types

Support for fbinfer in builds

May need to create a Conan package for ease use.

https://fbinfer.com/

Json loading via SIMD Json

https://github.com/lemire/simdjson

https://branchfree.org/2019/02/25/paper-parsing-gigabytes-of-json-per-second/

https://branchfree.org/

Precompiled Header Support Via CMake

http://mochan.info/c++/2019/11/12/pre-compiled-headers-gcc-clang-cmake.html

Windows R-Path support

https://docs.microsoft.com/en-us/windows/win32/sbscs/application-configuration-files

SoftwareNetwork/sw@c7ba4f5#diff-785b8715694d65132aedff85d10f3400R80

http://nibblestew.blogspot.com/2019/05/emulating-rpath-on-windows-via-binary.html

https://developercommunity.visualstudio.com/idea/566616/support-rpath-for-binaries-during-development.html

https://drive.google.com/file/d/0B3_wGJkuWLytbnIxY1J5WUs4MEk/view

VcPkg Packaging

https://docs.microsoft.com/en-us/cpp/build/vcpkg?view=vs-2019

Add core library

Open GL - Detect the number of GPUs on the host system

For Nvidia: https://cpp.hotexamples.com/examples/-/-/wglEnumGpusNV/cpp-wglenumgpusnv-function-examples.html

https://www.geeks3d.com/20090127/opengl-gpu-affinity-checker/
https://www.equalizergraphics.com/downloads/tools.html

https://registry.khronos.org/OpenGL/extensions/ARB/WGL_ARB_create_context.txt

Set up Github Action to build project via CMake

https://cristianadam.eu/20191222/using-github-actions-with-c-plus-plus-and-cmake/

Add Code Coverage Support

https://codingnest.com/how-to-get-code-coverage-from-ci/

CODECOV_TOKEN="08924b5f-0fbf-41a6-8e58-684d81190903"

Detection of hardware resources

http://open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0796r1.pdf
https://www.open-mpi.org/projects/hwloc/
https://github.com/dcdillon/cpuaff

Mutation testing

Add Travis Support

Vulkan Rendering System

General Resources

https://github.com/vinjn/awesome-vulkan
https://github.com/KhronosGroup/Vulkan-Hpp
https://github.com/KhronosGroup/Vulkan-Samples

Synchronisation

http://themaister.net/blog/2019/08/14/yet-another-blog-explaining-vulkan-synchronization/

Overview

https://zeux.io/2020/02/27/writing-an-efficient-vulkan-renderer/

Expose Compile Time Profiling (-ftime-trace) via CMake module

Ensure profile json output in the build folder are tracked an cleaned by CMake

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=92396

Add support for running GPU tests on Circle CI

Running of GPU tests is currently disabled on Travis and Appveyor as they do not support GPU. Circle CI does have support for NVidia GPUs. The project should be set up on Circle CI and GPU tests and test coverage run here: https://circleci.com/docs/2.0/configuration-reference/#gpu-executor-linux

Add doxygen support

Support C++20 Modules

Add support for modules once compiler support is there: https://accu.org/journals/overload/28/159/sidwell/#FN01

Add Metal Rendering System for Mac Os X

https://metalbyexample.com/up-and-running-1/
https://developer.apple.com/videos/play/wwdc2014/604/
https://github.com/naleksiev/mtlpp
http://cocoadevcentral.com/d/learn_objectivec/

Ensure Reproducible Builds

https://blog.conan.io/2019/09/02/Deterministic-builds-with-C-C++.html

https://reproducible-builds.org/

https://diffoscope.org

Set up Sonar Cube using Azure Pipelines

https://beardedplatypus.github.io/sonarcloud-static-code-analysis-in-a-c-project.html

Integrate Stacktrace from Exeption

Extend and integrate Ed's Stacktrace from Exception solution to that is also supports Mac OS: https://github.com/ecatmur/stacktrace-from-exception

https://htmlpreview.github.io/?https://github.com/ecatmur/stacktrace-from-exception/blob/main/P2490R3.html
https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2301r1.html

Automate adding all targets to code coverage

https://stackoverflow.com/questions/45092198/cmake-how-do-i-change-properties-on-subdirectory-project-targets

Chose an error handling approach for the project

Let's avoid exceptions or error code. Either Outcome/Expected style handling or static exceptions one adopted:

http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0709r0.pdf
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0323r3.pdf
https://ned14.github.io/outcome/motivation/

Handling Disappointment in C++ (status code vs expected):http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0157r0.html

CppCon 2019: Phil Nash “The Dawn of a New Error”

Detect CPU Topology Via HWLoc

https://github.com/open-mpi/hwloc

Align concurrency::Generator with std::generator specification

https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2502r2.pdf

Manage Vulkan dependencies

Vulkan SDK Conan Package: https://github.com/alaingalvan/conan-vulkan-hpp

Vulkan-Hppc Conan Package: https://github.com/madebr/conan-vulkan_hpp

Mac Specific:
Molten VK Cask: https://formulae.brew.sh/formula/molten-vk
Source code: https://github.com/Homebrew/homebrew-core/blob/master/Formula/molten-vk.rb

Official Molten VK Cask Discussion: KhronosGroup/MoltenVK#509

Efficient Hash Table Implementation

https://martin.ankerl.com/2019/04/01/hashmap-benchmarks-01-overview/

https://github.com/martinus/robin-hood-hashing

Add support for std::error_codes for API used internally

https://akrzemi1.wordpress.com/2017/07/12/your-own-error-code/
https://github.com/ned14/status-code

Example added for Vulkan in this change: a783992

Dynamic Loading Of Vulkan

Something similar to how GLEW works for OpenGL but for Vulkan. This could be a sub-project which parses the Vulkan API structure from the XML doc in the Vulkan-Docs repository.

However, for now, this can leverage an existing solution such as Volk: https://github.com/zeux/volk

Build Doxygen Documentation as a Github action

Build documentation as at workflow and deploy to Github pages for the project.

Add Conan Support

Profiler Support

https://optick.dev/

Build Tests For Padding In Optimised Data Structures

https://linux.die.net/man/1/pahole

Add Fuzz Testing

https://llvm.org/docs/LibFuzzer.html

Additional Data Structures

https://github.com/igushev/IgushArray

Support importing of 3D assets

Can leverage a wide variety of asset formats via https://github.com/assimp/assimp

Pick a mocking framework for testing

https://github.com/dascandy/hippomocks
https://github.com/eranpeer/FakeIt
https://github.com/rollbear/trompeloeil
https://stackoverflow.com/questions/2827319/is-google-mock-a-good-mocking-framework
https://en.wikipedia.org/wiki/List_of_unit_testing_frameworks#C.2B.2B

Add AppVeyor support

Add Linear Algebra types implemented using SIMD types.

Proposal for standard library maths linear algebra types: http://open-std.org/JTC1/SC22/WG21/docs/papers/2019/p1385r3.pdf

Task Distribution Via Intel TBB

https://techdecoded.intel.io/big-picture/modern-threading-techniques-pro-tbb/#gs.g5hqll

Add Github Action Support For The Intel Compiler

https://github.com/nemequ/icc-travis

Procedural City Creation

https://www.shamusyoung.com/twentysidedtale/?p=2940

Entity Component System In The World Model

http://cowboyprogramming.com/2007/01/05/evolve-your-heirachy/

https://www.reddit.com/r/cpp/comments/cx21wv/entt_v31_is_out_gaming_meets_modern_c_a_fast_and/

https://www.reddit.com/r/cpp/comments/doxpxk/entt_ecs_v320_is_out_perfect_soa_to_the_rescue/

Support a generic exception handler with support for Lippincott functions

http://cppsecrets.blogspot.com/2013/12/using-lippincott-function-for.html