Skip to content

Commit

Permalink
[doc] Remove conan from documentation and update it
Browse files Browse the repository at this point in the history
  • Loading branch information
IAmNotHanni committed Apr 11, 2023
1 parent a723652 commit fc4f981
Show file tree
Hide file tree
Showing 7 changed files with 13 additions and 68 deletions.
1 change: 0 additions & 1 deletion documentation/source/development/benchmarking.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,5 @@ Benchmarking
============

- Inexor will use `Google Benchmark <https://github.com/google/benchmark>`__ in the future.
- Google Benchmark is also `available in conan center <https://conan.io/center/benchmark>`__, just as `Google Test <https://github.com/google/googletest>`__.
- Benchmarks can also not run in GitHub actions since testing Vulkan features would require a graphics card.
- The tests will run locally on the developer's machine along with the tests.
54 changes: 9 additions & 45 deletions documentation/source/development/building.rst
Original file line number Diff line number Diff line change
Expand Up @@ -53,9 +53,6 @@ The following CMake targets and options are available:
* - INEXOR_BUILD_BENCHMARKS
- Builds inexor-renderer-benchmarks.
- ``OFF``
* - INEXOR_CONAN_PROFILE
- To adjust the conan profile, use ``-DINEXOR_CONAN_PROFILE=<name>``.
- ``default``
* - INEXOR_BUILD_DOC
- Builds the documentation with `Sphinx <https://www.sphinx-doc.org/en/master/>`__.
- ``OFF``
Expand All @@ -68,41 +65,38 @@ The following CMake targets and options are available:
Windows
^^^^^^^

Example: Create Visual Studio 2019 project map for Debug mode including docs, tests, and benchmarks:
Example: Create Visual Studio 2022 project map for Debug mode including docs, tests, and benchmarks:

.. code-block:: shell
cmake -G "Visual Studio 16 2019" -A x64 -B./cmake-build-debug-vs/ -DCMAKE_BUILD_TYPE=Debug -DINEXOR_BUILD_DOC=ON -DINEXOR_BUILD_TESTS=ON -DINEXOR_BUILD_BENCHMARKS=ON ./
cmake -G "Visual Studio 17 2022" -A x64 -B./cmake-build-debug-vs/ -DCMAKE_BUILD_TYPE=Debug -DINEXOR_BUILD_DOC=ON -DINEXOR_BUILD_TESTS=ON -DINEXOR_BUILD_BENCHMARKS=ON ./
Example: Create Visual Studio 2019 project map for Release mode but without docs, tests, and benchmarks:
Example: Create Visual Studio 2022 project map for Release mode but without docs, tests, and benchmarks:

.. code-block:: shell
cmake -G "Visual Studio 16 2019" -A x64 -B./cmake-build-release-vs/ -DCMAKE_BUILD_TYPE=Release ./
cmake -G "Visual Studio 17 2022" -A x64 -B./cmake-build-release-vs/ -DCMAKE_BUILD_TYPE=Release ./
If you have `Ninja build system <https://ninja-build.org/>`__ installed, you can use it like this:

.. code-block:: doscon
# executing from project root assumed
# Ninja generator and Debug type
\> cmake -DINEXOR_CONAN_PROFILE=default -G Ninja -B./cmake-build-debug/ -DCMAKE_BUILD_TYPE=Debug ./
\> cmake -G Ninja -B./cmake-build-debug/ -DCMAKE_BUILD_TYPE=Debug ./
# Ninja generator and Release type
\> cmake -G Ninja -B./cmake-build-release/ -DCMAKE_BUILD_TYPE=Release ./
# Create Visual Studio Solution
\> cmake -G "Visual Studio 16 2019" -A x64 -B./cmake-build-debug-vs/ -DCMAKE_BUILD_TYPE=Debug ./
\> cmake -G "Visual Studio 17 2022" -A x64 -B./cmake-build-debug-vs/ -DCMAKE_BUILD_TYPE=Debug ./
# Build all targets
\> cmake --build ./cmake-build-debug/
.. note::
If you use CMake GUI add `CMAKE_BUILD_TYPE` with value `Debug` or `Release`. `#228 <https://github.com/inexorgame/vulkan-renderer/issues/228>`__.

- Choose any IDE that CMake can generate a project map for. If in doubt use `Visual Studio 2019 <https://visualstudio.microsoft.com/>`__.
- Choose any IDE that CMake can generate a project map for. If in doubt use `Visual Studio 2022 <https://visualstudio.microsoft.com/>`__.
- Clone the source code. Free and good tools are `GitHub Desktop <https://desktop.github.com/>`__ or `GitKraken Git GUI <https://www.gitkraken.com/git-client>`__.
- Open CMake and select the root folder which contains ``CMakeLists.txt`` (not just ``src`` folder!).
- You can choose any location for the ``build`` folder.
- Click "Configure" and select your IDE (in doubt ``Visual Studio 16 2019``). Click "Finish".
- CMake will now set up dependencies automatically for you using conan package manager. This might take a while. If this fails, you really should open a ticket!
- Click "Configure" and select your IDE (in doubt ``Visual Studio 17 2022``). Click "Finish".
- CMake will now set up dependencies automatically for you. This might take a while. If this fails, you really should open a ticket!
- Click "Generate". You can now open the Visual Studio project file in your ``build`` folder.
- For debugging, please check that the root directory of the repository is set as working directory in Visual Studio. Usually, CMake should take care of this already.
- You are now ready to start debugging! Our main branch must be stable at all cost.
Expand Down Expand Up @@ -142,19 +136,12 @@ Install dependencies and tools:
| | ninja-build \ |
| | clang-tidy \ |
| | vulkan-sdk \ |
| | python3 \ |
| | python3-pip |
| | $ pip3 install \ |
| | wheel \ |
| | setuptools \ |
| | conan |
| | |
+--------+---------------------------------------+
| Gentoo | .. code-block:: shell-session |
| | |
| | # emerge \ |
| | dev-util/cmake \ |
| | dev-util/conan \ |
| | dev-util/vulkan-headers \ |
| | dev-util/vulkan-tools \ |
| | dev-vcs/git \ |
Expand Down Expand Up @@ -202,12 +189,6 @@ Install dependencies and tools:
| | ninja-build \ |
| | clang-tidy \ |
| | vulkan-sdk \ |
| | python3 \ |
| | python3-pip |
| | $ pip3 install \ |
| | wheel \ |
| | setuptools \ |
| | conan |
| | |
+--------+---------------------------------------+
| Arch | Follow the |
Expand Down Expand Up @@ -241,12 +222,6 @@ Install dependencies and tools:
| | vulkan-headers \ |
| | vulkan-tools \ |
| | vulkan-validation-layers \ |
| | python3 \ |
| | python-pip |
| | $ pip3 install \ |
| | wheel \ |
| | setuptools \ |
| | conan |
| | |
+--------+---------------------------------------+
| Fedora | Install the required packages: |
Expand Down Expand Up @@ -289,12 +264,6 @@ Install dependencies and tools:
| | xkeyboard-config-devel \ |
| | glslang-devel |
| | |
| | Install conan: [#f1]_ [#f2]_ |
| | |
| | .. code-block:: shell-session |
| | |
| | $ pip install conan |
| | |
+--------+---------------------------------------+
| Other | Planned. `We would love to see a |
| | pull request on this file if you get |
Expand Down Expand Up @@ -335,8 +304,3 @@ If you have any trouble please `open a ticket <https://github.com/inexorgame/vul
$ cmake --build build --target inexor-vulkan-renderer-example
$ ./build/bin/inexor-vulkan-renderer-example
.. rubric:: Footnotes

.. [#f1] Make sure that ``$PATH`` includes the directory which contains ``conan`` (normally ``$HOME/.local/bin``). Bash includes this directory by default, zsh does **not**.
.. [#f2] Make sure that you have version ``12.2`` `in conan's config file <https://docs.conan.io/en/latest/extending/custom_settings.html>`__
16 changes: 1 addition & 15 deletions documentation/source/development/engine-design/main.rst
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@ Source code
├── CHANGELOG.rst
├── CMakeLists.txt
├── CODE_OF_CONDUCT.md
├── conanfile.py «Conan configuration»
├── CONTRIBUTING.md
├── LICENSE.md
├── README.rst
Expand Down Expand Up @@ -63,21 +62,8 @@ Dependency management
=====================

- In general we try to keep the number of dependencies at a minimum.
- We avoid to add dependencies directly to the project repository because they increase the size of the repository and we have to update them manually.
- Dependencies are downloaded directly by CMake.

- Instead, we prefer to use `conan package manager <https://conan.io/>`__ which allows us to get most dependencies from `conan center <https://conan.io/center/>`__.

Conan package manager
---------------------

- The list of currently used dependencies can be found in ``conanfile.py`` in the root folder of the repository.
- You must have installed `CMake <https://cmake.org/>`__ and `conan package manager <https://conan.io/>`__ in oder to download the dependencies automatically from conan center when running CMake.
- For details please read :ref:`building Instructions<BUILDING>` (:ref:`BUILDING Windows`/:ref:`BUILDING Linux`).

Dependency folder
-----------------

- If we really need a dependency which is not yet available through conan center, we add it manually to the ``third_party`` folder.

Criteria for library selection
------------------------------
Expand Down
3 changes: 0 additions & 3 deletions documentation/source/development/getting-started.rst
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,6 @@ Required Software
`Python <https://www.python.org/>`__ with `pip <https://pypi.org/project/pip/>`__
Required for generating the documentation and the C++ package manager.

`Conan <https://conan.io/>`__
C++ package manager to get the required libraries (dependencies).

`CMake <https://cmake.org/>`__
The build generator which generates project files for various IDEs.

Expand Down
2 changes: 1 addition & 1 deletion documentation/source/development/static-code-analysis.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,5 @@ We analyze our source code regularly using `static code analysis <https://en.wik
The following tools are used:

- `Clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`__.
- `Microsoft Visual Studio code analysis <https://docs.microsoft.com/en-us/visualstudio/code-quality/?view=vs-2019>`__.
- `Microsoft Visual Studio code analysis <https://docs.microsoft.com/en-us/visualstudio/code-quality/?view=vs-2022>`__.
- `Valgrind <https://valgrind.org/>`__, `Callgrind <https://valgrind.org/docs/manual/cl-manual.html>`__ and `Cachegrind <https://valgrind.org/docs/manual/cg-manual.html>`__.
1 change: 0 additions & 1 deletion documentation/source/development/test-automation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@ Test automation
===============

- Inexor will use `Google Test <https://github.com/google/googletest>`__ for `automated software testing <https://en.wikipedia.org/wiki/Test_automation>`__ in the future.
- Because Google Test is `available in conan center <https://conan.io/center/gtest>`__, we will be able to add this to our list of dependencies easily.
- Running automatic tests using GitHub actions is not possible for Vulkan features since this requires a graphics card to be present.
- There are some services which offer test automation for rendering, but they are not free.
- The tests would have to run on the developer's machine locally.
4 changes: 2 additions & 2 deletions documentation/source/faq/main.rst
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ Inexor is a MIT-licensed open-source project which develops a new 3D octree game
- Automatic `unit testing <https://github.com/google/googletest>`__ and `benchmarking <https://github.com/google/benchmark>`__.
- `Static code analysis <https://en.wikipedia.org/wiki/Static_program_analysis>`__ with `clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`__.
- `Automatic code formatting <https://clang.llvm.org/docs/ClangFormat.html>`__ using `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`__.
- `CMake <https://cmake.org/>`__ project setup with `conan package manager <https://conan.io/center/>`__ integration.
- `CMake <https://cmake.org/>`__ project setup.

You can find Vulkan example code online which follows the mantra "don't use this in production - it's tutorial code". Inexor disagrees with this as we believe that defeats its own purpose. If example code is not meant to be used in some other projects then there's something wrong with that example code. Many projects don't use a proper memory management library like `VMA <https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator>`__ or they do not abstract their code using `RAII <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-raii>`__, but use a lot of code duplication instead. Inexor is designed to be used in production. Bear in mind however that Inexor is also still far away from being a finished game engine.

Expand All @@ -70,7 +70,7 @@ What is the current state of the project?

We are still in very early development, but this project can already offer:

- A modern C++17 codebase with a setup for CMake and conan package manager.
- A modern C++20 codebase with CMake setup.
- Stable builds for Windows and Linux using `Continuous Integration (CI) <https://en.wikipedia.org/wiki/Continuous_integration>`__.
- A `rendergraph <https://de.slideshare.net/DICEStudio/framegraph-extensible-rendering-architecture-in-frostbite>`__ in early development.
- `ImGui <https://github.com/ocornut/imgui>`__ integration using separate renderpasses.
Expand Down

0 comments on commit fc4f981

Please sign in to comment.