From 1f3139426c6e74b686d69fb36efb3fa5d06f521b Mon Sep 17 00:00:00 2001 From: Ricardo Antunes Date: Sat, 9 Mar 2024 14:48:20 +0000 Subject: [PATCH] docs: improve getting started page --- docs/pages/1_getting_started/main.md | 84 ++++++++++++++-------------- 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/docs/pages/1_getting_started/main.md b/docs/pages/1_getting_started/main.md index 378bf6ed8a..b880a51f3a 100644 --- a/docs/pages/1_getting_started/main.md +++ b/docs/pages/1_getting_started/main.md @@ -14,18 +14,19 @@ repository with git. ### Dependencies -The following dependencies are used to compile **CUBOS.**: - -| Name | Importance | Submodule Path | Installed Separately | Version* | -| --------------------------------------------------- | ------------------------- | ------------------ | -------------------- | -------- | -| [CMake](https://cmake.org/) | Essential | - | Yes | - | -| [glad](https://github.com/Dav1dde/glad) | Essential | `core/lib/glad` | No | 2.0.4 | -| [glfw](https://github.com/glfw/glfw) | Essential | `core/lib/glfw` | Optionally | 3.3.8 | -| [glm](https://github.com/g-truc/glm) | Essential | `core/lib/glm` | Optionally | 0.9.9.8 | -| [stduuid](https://github.com/mariusbancila/stduuid) | Essential | `core/lib/stduuid` | No | 1.2.3 | -| [doctest](https://github.com/doctest/doctest) | Required for tests | `core/lib/doctest` | Optionally | 2.4.11 | -| [imgui](https://github.com/ocornut/imgui) | Required for imgui plugin | `engine/lib/imgui` | No | 1.89.9 | -| [json](https://github.com/nlohmann/json) | Essential | `core/lib/json` | No | 3.11.2 | +The following dependencies are used to compile **CUBOS**: + +| Name | Importance | Submodule Path | Installed Separately | Version* | +| --------------------------------------------------- | ------------------ | ------------------- | -------------------- | -------- | +| [CMake](https://cmake.org/) | Essential | - | Yes | - | +| [glad](https://github.com/Dav1dde/glad) | Essential | `core/lib/glad` | No | 2.0.4 | +| [glfw](https://github.com/glfw/glfw) | Essential | `core/lib/glfw` | Optionally | 3.3.8 | +| [glm](https://github.com/g-truc/glm) | Essential | `core/lib/glm` | Optionally | 0.9.9.8 | +| [stduuid](https://github.com/mariusbancila/stduuid) | Essential | `core/lib/stduuid` | No | 1.2.3 | +| [doctest](https://github.com/doctest/doctest) | Required for tests | `core/lib/doctest` | Optionally | 2.4.11 | +| [json](https://github.com/nlohmann/json) | Essential | `core/lib/json` | No | 3.11.2 | +| [imgui](https://github.com/ocornut/imgui) | Essential | `engine/lib/imgui` | No | 1.89.9 | +| [imgui](https://github.com/ocornut/imgui) | Essential | `engine/lib/implot` | No | 1.89.9 | *versions tested in CI and installed by submodules, others might work @@ -52,50 +53,49 @@ git config --local include.path ../.gitconfig ### Compiling -If you chose to install some dependencies separately, you must pass the -corresponding `-D` flag to CMake. For example, if you installed GLFW, GLM and -CMake separately you would pass the following flags to CMake: +The easiest way to compile **CUBOS** is by opening its directory in an IDE with CMake support. We recommend using [Visual Studio Code](https://code.visualstudio.com/) with the CMake and C++ extensions installed, as it is cross-platform, and most of the team is using it. -```bash -cmake -H. -Bbuild -DGLFW_USE_SUBMODULE=OFF -DGLM_USE_SUBMODULE=OFF -``` - -If you are using submodules, you can simply run the following command from the -root directory of the repository: +The IDE you choose most probably provides a way to set CMake options through the UI. +In *Visual Studio Code*, you can do this by pressing `Ctrl + Shift + P` and choosing `CMake: Edit CMake Cache (UI)`. +Alternatively, you can change options directly through the `CMakeCache.txt` on the directory you chose to build the project in (usually `build/`). -```bash -cmake -H. -Bbuild -``` +*Visual Studio Code*'s CMake extension allows you to set a *build* target. You can set this target, for example, to `cubos-core`, in order to compile only the `core`. To compile it, just press the build button. The following is a list of all the options available to configure the engine: -| Name | Description | -| ----------------------- | ------------------------------------ | -| `WITH_GLFW` | Use GLFW? (Required for now) | -| `WITH_OPENGL` | Use OpenGL? (Required for now) | -| `GLFW_USE_SUBMODULE` | Compile glfw from source? | -| `GLM_USE_SUBMODULE` | Compile glm from source? | -| `DOCTEST_USE_SUBMODULE` | Compile doctest from source? | -| `BUILD_CORE_SAMPLES` | Build **CUBOS.** `core` samples? | -| `BUILD_CORE_TESTS` | Build **CUBOS.** `core` tests? | -| `BUILD_ENGINE_SAMPLES` | Build **CUBOS.** `engine` samples? | -| `BUILD_ENGINE_TESTS` | Build **CUBOS.** `engine` tests? | -| `BUILD_DOCUMENTATION` | Build the documentation? | -| `ENABLE_COVERAGE` | Enable code coverage? (GCC only) | -| `FIX_CLANG_TIDY_ERRORS` | Fix clang-tidy errors automatically? | +| Name | Description | +| -------------------------- | ------------------------------------ | +| `WITH_GLFW` | Use GLFW? (Required for now) | +| `WITH_OPENGL` | Use OpenGL? (Required for now) | +| `GLFW_USE_SUBMODULE` | Compile glfw from source? | +| `GLM_USE_SUBMODULE` | Compile glm from source? | +| `DOCTEST_USE_SUBMODULE` | Compile doctest from source? | +| `BUILD_CORE_SAMPLES` | Build **CUBOS** `core` samples? | +| `BUILD_CORE_TESTS` | Build **CUBOS** `core` tests? | +| `BUILD_ENGINE_SAMPLES` | Build **CUBOS** `engine` samples? | +| `BUILD_ENGINE_TESTS` | Build **CUBOS** `engine` tests? | +| `BUILD_TESSERATOS_SAMPLES` | Build **TESSERATOS** samples? | +| `BUILD_DOCUMENTATION` | Build the documentation? | +| `ENABLE_COVERAGE` | Enable code coverage? (GCC only) | +| `FIX_CLANG_TIDY_ERRORS` | Fix clang-tidy errors automatically? | + +After you change an option's value, make sure to reconfigure CMake! In *Visual Studio Code*, you can do this by pressing `Ctrl + Shift + P` and choosing `CMake: Configure`. ## Running the examples and tests +In *Visual Studio Code*, the CMake extension allows you to set the *debug* targets. That target can then by launched/debugged by pressing the launch/debug button. + ### Examples -Both the `core` and the `engine` contain examples which you can run to check if +Both `core`, `engine` and `tesseratos` contain examples which you can run to check if things are running correctly. To build them, you must enable the -`BUILD_CORE_SAMPLES` and/or `BUILD_ENGINE_SAMPLES` options. +`BUILD_CORE_SAMPLES`, `BUILD_ENGINE_SAMPLES` and/or `BUILD_TESSERATOS_SAMPLES` options. +This will show new multiple targets, one for each example. ### Testing -**CUBOS.** uses *doctest* for unit testing the engine. To build them, you must -enable the `BUILD_CORE_TESTS` and/or `BUILD_ENGINE_TESTS` options. +**CUBOS** uses *doctest* for unit testing the engine. To build them, you must +enable the `BUILD_CORE_TESTS` and/or `BUILD_ENGINE_TESTS` options. You can run the tests through the targets `cubos-core-tests` and `cubos-engine-tests`. ## Whats next?