docs: move compile guide to the getting started page

GameDevTecnico · Aug 28, 2023 · d757f68 · d757f68
1 parent c13d1ad
commit d757f68
Show file tree

Hide file tree

Showing 3 changed files with 138 additions and 127 deletions.
diff --git a/README.md b/README.md
@@ -8,123 +8,26 @@
 
 ## Voxel based engine
 
-**CUBOS. aims to be a simple, but powerful engine for PC, where everything is**
-**made out of voxels.**
+**CUBOS. aims to be a simple, but powerful game engine for PC, where**
+**everything is made out of voxels.**
 
-It aims to support vast render distances and destructibility, which sets it
-apart from other engines. Written in *C++*, built with *OpenGL*, it's a
-high-performance engine.
+It is open source and free to use for any purpose. Written in *C++* and with
+data-oriented design in mind, its goal is to be both performant and highly
+flexible.
 
-## Structure
+### Learn more
 
-The source code is divided into four main parts:
-- `core`: library which is shared between the tools and the games. This
-includes some basic functionality like serialization, logging, render devices,
-input handling and others.
-- `engine`: library with code exclusive to the game execution. This includes
-the main loop, the asset manager and systems like the renderer and physics.
-- `quadrados`: a tool which helps you with the game development and which
-may depend on `core`. One example use case of `quadrados` is convert from
-external voxel formats to the internal format used by **CUBOS.**.
-- `tesseratos`: game editor made on top of multiple plugins, that can also be used individually 
-in your game using **CUBOS.**.
+Check out the project's [website](https://gamedevtecnico.github.io/cubos) which
+contains the documentation, guides and examples on how to use the engine.
 
-### Further reading
+### Who is making this engine
 
-You can find more information about how the engine is structured in the
-[documentation](https://gamedevtecnico.github.io/cubos/).
+**CUBOS.** is developed by a small team at
+[GameDev Técnico](https://www.instagram.com/gamedevtecnico/), a student group
+at [Instituto Superior Técnico](https://tecnico.ulisboa.pt/) who make games.
+Our goal is to build a game engine from the ground up and have fun doing it.
 
-## Contributing
-
-Check out the [contribution guidelines](CONTRIBUTE.md) for more information.
-
-## Getting the engine
-
-### Executables
-
-There are no releases of **CUBOS.** so far. We will update this section once
-we release official binaries.
-<!--Official binaries for **CUBOS.** can be found
-on the [releases](https://github.com/GameDevTecnico/cubos/releases) page.-->
-
-### Building from the source code
-
-#### Dependencies
-
-The following dependencies are used to compile **CUBOS.**:
-
-| Name                                                | Importance         | Submodule Path     | Installed Separately |
-| --------------------------------------------------- | ------------------ | ------------------ | -------------------- |
-| [CMake](https://cmake.org/)                         | Essential          | -                  | Yes                  |
-| [json](https://github.com/nlohmann/json)            | Essential          | -                  | No                   |
-| [glad](https://github.com/Dav1dde/glad)             | Essential          | -                  | No                   |
-| [glfw](https://github.com/glfw/glfw)                | Essential          | `core/lib/glfw`    | Optionally           |
-| [glm](https://github.com/g-truc/glm)                | Essential          | `core/lib/glm`     | Optionally           |
-| [fmt](https://github.com/fmtlib/fmt)                | Essential          | `core/lib/fmt`     | Optionally           |
-| [spdlog](https://github.com/gabime/spdlog)          | Essential          | `core/lib/spdlog`  | Optionally           |
-| [stduuid](https://github.com/mariusbancila/stduuid) | Essential          | `core/lib/stduuid` | No                   |
-| [doctest](https://github.com/doctest/doctest)       | Required for tests | `core/lib/doctest` | Optionally           |
-
-Dependencies marked as *Essential* are required to compile the engine.
-**CUBOS.** uses [CMake](https://cmake.org/) as its build system, so you must
-install it to compile the engine.
-
-Most dependencies come as submodules, so, you may choose whether to install
-them separately or not. If you choose to install some or all of them
-separately, you can do so easily by using the package manager of your choice.
-If you use Windows, it should be easier to simply install all of them with the
-engine by cloning the whole repository with the `--recursive` flag.
-
-#### 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 separetely you would pass the following flags to CMake:
-
-`cmake -H. -Bbuild -DGLFW_USE_SUBMODULE=OFF -DGLM_USE_SUBMODULE=OFF`
-
-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?       |
-| `SPDLOG_USE_SUBMODULE`  | Compile spdlog from source?        |
-| `FMT_USE_SUBMODULE`     | Compile fmt 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?   |
-
-### Samples
-
-Both the `core` and the `engine` contain samples that you can run to get an
-idea of how the engine works.
-
-### Testing
-
-**CUBOS.** uses *doctest* for unit testing the engine.
-To test the engine's core you can use the following
-command: `cd build/core && ctest`.
-
-## Who is making this engine
-
-We are  [GameDev Técnico](https://www.instagram.com/gamedevtecnico/), a student
-group from [Instituto Superior Técnico](https://tecnico.ulisboa.pt/en/) who
-makes games. Our goal is to build a game engine from the ground up. 
-
-Find us at:
-
-[Twitter](https://twitter.com/GameDevTecnico)
-
-[Facebook](https://www.facebook.com/Game-Dev-T%C3%A9cnico-107405047487324/)
-
-[Instagram](https://www.instagram.com/gamedevtecnico/)
-
-[Youtube](https://www.youtube.com/channel/UCpJf5Ih7SE9wAgaZ_OF9qYA)
-
-[itch.io](https://gamedevtecnico.itch.io/)
+### Join us
 
+If you're a student and interested in joining us, please fill out
+[this form](https://forms.gle/A7ChMqC2qN9tHo6j8).
diff --git a/docs/pages/1_getting_started/main.md b/docs/pages/1_getting_started/main.md
@@ -2,4 +2,97 @@
 
 @brief How to download, build and run the engine and where to go from there.
 
-@note Under construction.
+## Building the engine from source
+
+@note This guide assumes you're familiar with the basics of git.
+
+### Getting the code
+
+The **CUBOS.** source code is [hosted on GitHub](https://github.com/GameDevTecnico/cubos),
+so the easiest and only way to get the code right now is to clone the
+repository with git.
+
+### Dependencies
+
+The following dependencies are used to compile **CUBOS.**:
+
+| Name                                                | Importance         | Submodule Path     | Installed Separately |
+| --------------------------------------------------- | ------------------ | ------------------ | -------------------- |
+| [CMake](https://cmake.org/)                         | Essential          | -                  | Yes                  |
+| [json](https://github.com/nlohmann/json)            | Essential          | -                  | No                   |
+| [glad](https://github.com/Dav1dde/glad)             | Essential          | -                  | No                   |
+| [glfw](https://github.com/glfw/glfw)                | Essential          | `core/lib/glfw`    | Optionally           |
+| [glm](https://github.com/g-truc/glm)                | Essential          | `core/lib/glm`     | Optionally           |
+| [fmt](https://github.com/fmtlib/fmt)                | Essential          | `core/lib/fmt`     | Optionally           |
+| [spdlog](https://github.com/gabime/spdlog)          | Essential          | `core/lib/spdlog`  | Optionally           |
+| [stduuid](https://github.com/mariusbancila/stduuid) | Essential          | `core/lib/stduuid` | No                   |
+| [doctest](https://github.com/doctest/doctest)       | Required for tests | `core/lib/doctest` | Optionally           |
+
+Dependencies marked as *Essential* are required to compile the engine. If they
+are installed separately, you must first install them manually. If they're not,
+it means they come as submodules and you can install them with the engine by
+cloning the whole repository with the `--recursive` flag. If you've already
+cloned the repository, you can install them by running the following command
+from the root directory of the repository:
+
+```bash
+git submodule update --init --recursive
+```
+
+### 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:
+
+```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:
+
+```bash
+cmake -H. -Bbuild
+```
+
+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?         |
+| `SPDLOG_USE_SUBMODULE`  | Compile spdlog from source?          |
+| `FMT_USE_SUBMODULE`     | Compile fmt 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? |
+
+## Running the examples and tests
+
+### Examples
+
+Both the `core` and the `engine` 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.
+
+### 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.
+
+## Whats next?
+
+We recommend you start by reading the @ref features "feature guide", which
+introduces you to important concepts and features of the engine, such as what
+is an ECS and how it is used in **CUBOS.**.
+
+The @ref examples "examples page" is also a good place to go if you want to
+see how specific parts of the engine are used in practice.
diff --git a/docs/pages/2_features/main.md b/docs/pages/2_features/main.md
@@ -1,25 +1,40 @@
-# Feature guide {#features}
+# Feature Guide {#features}
 
-@brief High-level introduction to design of the **CUBOS.** engine and its
-features.
-
-Before you continue further, here's a quick overview of the engine's design.
+This is a brief introduction to the **CUBOS.** engine and its features. Before
+diving into the documentation of each class and function, it's recommended to
+read through this guide.
 
 ## Overview
 
-The **CUBOS.** engine is split into two libraries: @ref core and @ref engine.
-Each is on their own namespace, which corresponds to a sub-folder in the
+The **CUBOS.** engine is divided into two libraries: @ref core and @ref engine.
+Each library has its own namespace, which corresponds to a sub-folder in the
 include path.
 
-@ref core provides platform abstraction, containers and utilities, as well as
-the @ref core-ecs "ECS" module. @ref engine builds on top of @ref core and
-provides higher-level features, such as rendering and collisions.
+@ref core provides platform abstraction, containers, utilities, and the
+@ref core-ecs "ECS" module. @ref engine builds on top of @ref core and provides
+higher-level features such as rendering and collisions.
+
+The core library is divided into modules, each of which covers a specific area
+of functionality. For example, graphics-related functionality is on the
+@ref cubos::core::gl namespace, under the include path `cubos/core/gl`.
+
+The engine library is divided into plugins, each of which extends the engine's
+functionality in some way. You'll learn more about plugins below. For each
+plugin, there is a corresponding directory in the include path. Categories of
+plugins are also divided into sub-folders, with their own namespaces.
+
+### Tooling
+
+Other than the core and engine libraries, the project also contains *Quadrados*
+and *Tesseratos*. *Quadrados* is a CLI tool which contains utilities used
+during game development. *Tesseratos* is our in-house editor, which is still
+in its early stages of development.
 
 ## Learn more
 
-Each of the following pages provides a high-level description of a feature of
-the engine. It's recommended to read through these first before diving into
-documentation of each class and function.
+The following guides explain basic concepts of the engine. Its recommend to
+read through these first to understand the overall principles and only then
+dive into the documentation of each class and function.
 
 - @subpage features-ecs - @copybrief features-ecs
 - @subpage features-plugins - @copybrief features-plugins