Update docs

CMakeLists.txt

@@ -27,10 +27,10 @@ option(BEMAN_ITERATOR_INTERFACE_USE_DEDUCING_THIS
   "Make use of C++23 \"deducing this\" feature (P0847R7). Turn this off for non-conforming compilers."
   ${COMPILER_SUPPORTS_DEDUCING_THIS})
 
-option(ITERATOR_INTERFACE_BUILD_TESTING
+option(BEMAN_ITERATOR_INTERFACE_BUILD_TESTING
        "Enable building tests and test infrastructure. Default: ON. Values: {ON, OFF}." ${PROJECT_IS_TOP_LEVEL})
 
-option(ITERATOR_INTERFACE_BUILD_EXAMPLES
+option(BEMAN_ITERATOR_INTERFACE_BUILD_EXAMPLES
        "Enable building examples. Default: ON. Values: {ON, OFF}." ${PROJECT_IS_TOP_LEVEL})
 
 if(BEMAN_ITERATOR_INTERFACE_USE_DEDUCING_THIS
@@ -45,8 +45,8 @@ configure_file(
   "${PROJECT_SOURCE_DIR}/include/beman/iterator_interface/config.hpp.in"
   "${PROJECT_BINARY_DIR}/include/beman/iterator_interface/config.hpp" @ONLY)
 
-# Build the tests if enabled via the option ITERATOR_INTERFACE_BUILD_TESTING
-if(ITERATOR_INTERFACE_BUILD_TESTING)
+# Build the tests if enabled via the option BEMAN_ITERATOR_INTERFACE_BUILD_TESTING
+if(BEMAN_ITERATOR_INTERFACE_BUILD_TESTING)
   # Fetch GoogleTest
   FetchContent_Declare(
     googletest
@@ -83,12 +83,12 @@ add_subdirectory(src/beman/iterator_interface)
 add_subdirectory(include/beman/iterator_interface)
 
 # [CMAKE.SKIP_TESTS]
-if(ITERATOR_INTERFACE_BUILD_TESTING)
+if(BEMAN_ITERATOR_INTERFACE_BUILD_TESTING)
   add_subdirectory(tests/beman/iterator_interface)
 endif()
 
 # [CMAKE.SKIP_EXAMPLES]
-if(ITERATOR_INTERFACE_BUILD_EXAMPLES)
+if(BEMAN_ITERATOR_INTERFACE_BUILD_EXAMPLES)
   add_subdirectory(examples)
 endif()
 

README.md

@@ -7,8 +7,7 @@ SPDX-License-Identifier: 2.0 license with LLVM exceptions
 ![CI Tests](https://github.com/beman-project/iterator_interface/actions/workflows/ci.yml/badge.svg)
 
 **Implements**:
-* [`std::iterator_interface` (P2727)](https://wg21.link/P2727)
-
+* [`std::iterator_interface` (P2727R4)](https://wg21.link/P2727R4)
 
 Source is licensed with the Apache 2.0 license with LLVM exceptions
 
@@ -24,47 +23,161 @@ The README itself is licesed with CC0 1.0 Universal. Copy the contents and incor
 
 // SPDX-License-Identifier: CC0-1.0
 
+## Examples
+
+Full runable examples can be found in `examples/` - please check [./examples/README.md](./examples/README.md).
+
+### TODO - first example
+
+The next code snippet shows iterator interface support added in [`std::iterator_interface` (P2727R4)](https://wg21.link/P2727R4):
+
+```cpp
+TODO
+```
+
+### TODO - second example
+
+The next code snippet shows iterator interface support added in [`std::iterator_interface` (P2727R4)](https://wg21.link/P2727R4):
+
+```cpp
+TODO
+```
+
 ## How to Build
 
+### Compiler Support
+
+This is a modern C++ project which can be compiled with the latest C++ standards (**C++20 or later**).
+
+Default build: `C++23`. Please check `etc/${compiler}-flags.cmake`.
+
 ### Dependencies
 
-This project is mainly tested on `Ubuntu 22.04` and `Ubuntu 24.04`, but it should be as portable as CMake is. This project has zero C or C++ dependencies.
+This project is mainly tested on `Ubuntu 22.04` and `Ubuntu 24.04`, but it should be as portable as CMake is. This
+project has no C or C++ dependencies.
 
-It does require few tools as build-time dependencies:
+Build-time dependencies:
 
-- `cmake`
-- `ninja`, `make`, or another CMake-supported build system
-  - CMake defaults to "Unix Makefiles" on POSIX systems
+* `cmake`
+* `ninja`, `make`, or another CMake-supported build system
+  * CMake defaults to "Unix Makefiles" on POSIX systems
 
 Example of installation on `Ubuntu 24.04`:
+
 ```shell
-# install tools
+# Install tools:
 apt-get install -y cmake make ninja-build
 
-# example of toolchains
-apt-get install g++-14 gcc-14 clang-18 clang++-18
+# Example of toolchains:
+apt-get install                           \
+  g++-14 gcc-14 gcc-13 g++-14             \
+  clang-18 clang++-18 clang-17 clang++-17
 ```
 
 ### Instructions
 
-Full set of supported toolchains can be found in [.github/workflows/ci.yml](#.github/workflows/ci.yml).
-
-#### Basic Build
+#### Preset CMake Flows
 
-This project strives to be as normal and simple a CMake project as possible. This build workflow in particular will work, producing a static `beman_optional26` library, ready to package:
+This project strives to be as normal and simple a CMake project as possible. This build workflow in particular will
+work, producing a static `beman.iterator_interface` library, ready to package:
 
 ```shell
-cmake --workflow --preset gcc-14
+$ cmake --workflow --list-presets
+Available workflow presets:
+  "system"
+  "gcc-14"
+  "gcc-13"
+  "gcc-12"
+  "clang-20"
+  "clang-19"
+  "clang-18"
+  "clang-17"
+  "clang-16
+
+# Run examples:
+$ cmake --workflow --preset gcc-14
+Executing workflow step 1 of 3: configure preset "gcc-14"
+...
+-- Build files have been written to: /path/to/repo/.build/gcc-14
+
+Executing workflow step 2 of 3: build preset "gcc-14"
+
+ninja: no work to do.
+
+Executing workflow step 3 of 3: test preset "gcc-14"
+
+Test project /home/dariusn/git/Beman/iterator_interface/.build/gcc-14
+    Start 1: IteratorTest.TestGTest
+1/4 Test #1: IteratorTest.TestGTest ...........   Passed    0.00 sec
+    Start 2: IteratorTest.TestRepeatedChars
+2/4 Test #2: IteratorTest.TestRepeatedChars ...   Passed    0.00 sec
+    Start 3: IteratorTest.TestFilteredIter
+3/4 Test #3: IteratorTest.TestFilteredIter ....   Passed    0.00 sec
+    Start 4: IteratorTest.OperatorArrow
+4/4 Test #4: IteratorTest.OperatorArrow .......   Passed    0.00 sec
+...
+
+100% tests passed, 0 tests failed out of ...
+
+Total Test time (real) =   0.09 sec
 ```
 
 This should build and run the tests with GCC 14 with the address and undefined behavior sanitizers enabled.
 
-#### More complex cases
+#### Custom CMake Flows
 
-The CMake preset system suffers from combinitorial explosion. There is a makefile in the root of the repository to aid in running more configurations.
+##### Default Build
+
+CI current build and test flows:
 
 ```shell
-make -k TOOLCHAIN=clang-18  CONFIG=Tsan  VERBOSE=1
+# Configure build: default build production code + tests (BEMAN_ITERATOR_INTERFACE_BUILD_TESTING=ON).
+$ cmake -G "Ninja Multi-Config" \
+      -DCMAKE_CONFIGURATION_TYPES="RelWithDebInfo;Asan" \
+      -DCMAKE_TOOLCHAIN_FILE=etc/clang-19-toolchain.cmake \
+      -B .build -S .
+-- The CXX compiler identification is Clang 19.0.0
+...
+-- Build files have been written to: /path/to/repo/.build
+
+# Build.
+$ cmake --build .build --config Asan --target all -- -k 0
+...
+[12/12] Linking CXX executable ... # Note: 12 targets here (including tests).
+
+# Run tests.
+$ ctest --build-config Asan --output-on-failure --test-dir .build
+Internal ctest changing into directory: /path/to/repo/.build
+Test project /path/to/repo/.build
+...
+100% tests passed, 0 tests failed out of 82
+
+Total Test time (real) =   0.67 sec
 ```
 
-The makefile will use your system compiler, `c++`, if no toolchain name is provided, otherwise it will use the toolchain in the etc/ directory to perform the build. The Ninja multi config generator is used, with configurations for `RelWithDebugInfo`, `Debug`, `Tsan`, and `Asan` configured by default.
+##### Build Production, but Skip Tests
+
+By default, we build and run tests. You can provide `-DBEMAN_ITERATOR_INTERFACE_BUILD_TESTING=OFF` and completely disable building tests:
+
+```shell
+# Configure build: build production code, skip tests (BEMAN_ITERATOR_INTERFACE_BUILD_TESTING=OFF).
+$ cmake -G "Ninja Multi-Config" \
+      -DCMAKE_CONFIGURATION_TYPES="RelWithDebInfo;Asan" \
+      -DCMAKE_TOOLCHAIN_FILE=etc/clang-19-toolchain.cmake \
+      -DBEMAN_ITERATOR_INTERFACE_BUILD_TESTING=OFF \
+      -B .build -S .
+-- The CXX compiler identification is Clang 19.0.0
+...
+-- Build files have been written to: /path/to/repo/.build
+
+# Build.
+$ cmake --build .build --config Asan --target all -- -k 0
+...
+[5/5] Linking CXX executable ... # Note: 5 targets here (tests were not built).
+
+# Check that tests are not built/installed.
+$ ctest --build-config Asan --output-on-failure --test-dir .build
+Internal ctest changing into directory: /path/to/beman/repo/.build
+Test project /path/to/beman/repo/.build
+No tests were found!!!
+```