Improve README file

README.md

@@ -24,7 +24,7 @@ Its direct usage is usually not needed.
 
 ### Usage: default projection in constrained algorithms
 
- The following code snippet illustrates how we can achieve a default projection using `beman::exemplar::identity`:
+The following code snippet illustrates how we can achieve a default projection using `beman::exemplar::identity`:
 
 ```cpp
 #include <beman/exemplar/identity.hpp>
@@ -79,67 +79,185 @@ int main()
 
 ```
 
-Full runnable examples can be found in `examples/` (e.g., [./examples/identity_as_default_projection.cpp](./examples/identity_as_default_projection.cpp)).
+Full runnable examples can be found in [`examples/`](examples/).
 
-## Building beman.exemplar
+## Dependency
 
-### Dependencies
-<!-- TODO Darius: rewrite section!-->
+### Build Environment
 
-This project has no C or C++ dependencies.
+This project requires minimal **C++17** and **CMake 3.25** to build.
 
-Build-time dependencies:
+This project pulls [Google Test](https://github.com/google/googletest)
+from GitHub as a development dependency for its testing framework,
+thus requiring an active internet connection to configure.
+You can disable this behavior by setting cmake option
+[`BEMAN_EXEMPLAR_BUILD_TESTS`](#beman_exemplar_build_tests) to `OFF`
+when configuring the project.
 
-- `cmake`
-- `ninja`, `make`, or another CMake-supported build system
-  - CMake defaults to "Unix Makefiles" on POSIX systems
+However,
+some examples and tests will not be compiled
+unless provided compiler support **C++20** or ranges capabilities enabled.
 
-#### How to install dependencies
+> [!TIP]
+>
+> You will be able to see if there's any examples that isn't enabled due to
+> compiler capabilities or minimum C++ version it is configured to in the logs.
+>
+> Below is an example:
+>
+> ```txt
+> -- Looking for __cpp_lib_ranges
+> -- Looking for __cpp_lib_ranges - not found
+> CMake Warning at examples/CMakeLists.txt:12 (message):
+>   Missing range support! Skip: identity_as_default_projection
+>
+>
+> Examples to be built: identity_direct_usage
+> ```
 
-<!-- TODO Darius: rewrite section!-->
+### Supported Platforms
 
-<details>
-<summary>Dependencies install exemplar on Ubuntu 24.04  </summary>
+This project officially supports:
 
-<!-- TODO Darius: rewrite section!-->
+- GNU GCC Compiler \[version 12-14\]
+- LLVM Clang++ Compiler \[version 17-20\]
+- AppleClang compiler on Mac OS
+- MSVC compiler on Windows
 
-```shell
-# Install tools:
-apt-get install -y cmake make ninja-build
+> [!NOTE]
+>
+> Versions outside of this range would likely work as well,
+> especially if you're using a version above the given range
+> (e.g. HEAD/ nightly).
+> These development environments are verified using our CI configuration.
+
+## Development
+
+### Develop using GitHub Codespace
+
+This project supports [GitHub Codespace](https://github.com/features/codespaces)
+via [Development Containers](https://containers.dev/),
+which allows rapid development and instant hacking in your browser.
+
+You can create a codespace for this project by clicking this badge:
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/bemanproject/exemplar)
+
+For more detailed documentation regarding creating and developing inside of
+GitHub codespaces, please reference [this doc](https://docs.github.com/en/codespaces/).
+
+> [!NOTE]
+>
+> The codespace container may take up to 5 minutes to build and spin-up,
+> this is normal as we need to build a custom docker container to setup
+> an environment appropriate for beman projects.
 
-# Toolchains:
-apt-get install                           \
-  g++-14 gcc-14 gcc-13 g++-14             \
-  clang-18 clang++-18 clang-17 clang++-17
+### Develop locally on Ubuntu
+
+Beman projects requires [recent versions of CMake](#build-environment),
+we advice you download CMake directly from [CMake's website](https://cmake.org/download/)
+or install via the [Kitware apt library](https://apt.kitware.com/).
+
+A [supported compiler](#supported-platforms) should be available from your package manager.
+Alternatively you could use an install script from official compiler venders.
+
+Here is an example of how to install the latest stable version of clang
+as per [the official LLVM install guide](https://apt.llvm.org/).
+
+```bash
+bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"
 ```
 
-</details>
+### Configure and Build the project using CMake Preset
 
-<details>
-<summary>Dependencies install exemplar on MAC OS $VERSION </summary>
+This project recommands using [CMake Preset](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html)
+to configure, build and test the project.
+Appropriate presets for major compilers has been included by default.
+You can use `cmake --list-presets` to see all available presets.
+
+Here is an example to invoke the `gcc-debug` preset.
 
-<!-- TODO Darius: rewrite section!-->
 ```shell
-# TODO
+cmake --workflow --preset gcc-debug
 ```
 
-</details>
+Generally, there's two kinds of presets, `debug` and `release`.
 
-<details>
-<summary>Dependencies install exemplar on Windows $VERSION  </summary>
-<!-- TODO Darius: rewrite section!-->
+The `debug` presets are designed to aid development,
+thus it has as much sanitizers turned on as possible.
 
-```shell
-# TODO
+> [!NOTE]
+>
+> The set of sanitizer supports are different across compilers,
+> you can checout the exact set compiler arguments by looking at the toolchain
+> files under the [`cmake`](cmake/) directory.
+
+The `release` presets are designed for use in production environments,
+thus it has the highest optimization turned on (e.g. `O3`).
+
+### Configure and Build the project manually
+
+While [CMake Preset](#configure-and-build-the-project-using-cmake-preset) is
+convient,
+you might want to pass extra config/ compiler arguments for configuration.
+
+To configure, build and test the project with extra arguments,
+you can run this sets of command.
+
+```bash
+cmake -B build -S . -DCMAKE_CXX_STANDARD=20 # Your extra arguments here.
+cmake --build build
+ctest --test-dir build
 ```
 
-</details>
+> [!IMPORTANT]
+>
+> Beman projects are
+> [passive projects](https://github.com/bemanproject/beman/blob/main/docs/BEMAN_STANDARD.md#cmake),
+> therefore,
+> you will need to specify C++ version via `CMAKE_CXX_STANDARD`
+> when manually configuring the project.
+
+### Project specific configure arguments
+
+When configuring the project manually,
+you can pass an array of project specific CMake configs to customize your build.
+
+Project specific options are prefixed with `BEMAN_EXEMPLAR`.
+You can see the list of available options with:
+
+```bash
+cmake -LH | grep "BEMAN_EXEMPLAR" -C 2
+```
 
-### How to build beman.exemplar
+#### `BEMAN_EXEMPLAR_BUILD_TESTS`
+
+Enable building tests and test infrastructure. Default: ON.
+Values: { ON, OFF }.
+
+You can configure the project to have this option turned off via:
+
+```bash
+cmake -B build -S . -DCMAKE_CXX_STANDARD=20 -DBEMAN_EXEMPLAR_BUILD_TESTS=OFF
+```
+
+> [!TIP]
+> Because this project requires Google Tests as part of its development
+> dependency,
+> disable building tests avoids the project from pulling Google Tests from
+> GitHub.
+
+#### `BEMAN_EXEMPLAR_BUILD_EXAMPLES`
+
+Enable building examples. Default: ON. Values: { ON, OFF }.
+
+### Produce a static library
+
+<!--
+TODO
+-->
 
-This project strives to be as normal and simple a CMake project as possible.
-This build workflow in particular will work,
-producing a static `libbeman.exemplar.a` library, ready to package with its headers:
+Producing a static `libbeman.exemplar.a` library, ready to package with its headers:
 
 ```shell
 cmake --workflow --preset gcc-debug