Skip to content

Commit 2717ca8

Browse files
neatudariusneatudarius
committed
Update docs
1 parent af58b8a commit 2717ca8

File tree

2 files changed

+138
-25
lines changed

2 files changed

+138
-25
lines changed

‎CMakeLists.txt‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,10 @@ option(BEMAN_ITERATOR_INTERFACE_USE_DEDUCING_THIS
2727
"Make use of C++23 \"deducing this\" feature (P0847R7). Turn this off for non-conforming compilers."
2828
${COMPILER_SUPPORTS_DEDUCING_THIS})
2929

30-
option(ITERATOR_INTERFACE_BUILD_TESTING
30+
option(BEMAN_ITERATOR_INTERFACE_BUILD_TESTING
3131
"Enable building tests and test infrastructure. Default: ON. Values: {ON, OFF}." ${PROJECT_IS_TOP_LEVEL})
3232

33-
option(ITERATOR_INTERFACE_BUILD_EXAMPLES
33+
option(BEMAN_ITERATOR_INTERFACE_BUILD_EXAMPLES
3434
"Enable building examples. Default: ON. Values: {ON, OFF}." ${PROJECT_IS_TOP_LEVEL})
3535

3636
if(BEMAN_ITERATOR_INTERFACE_USE_DEDUCING_THIS
@@ -45,8 +45,8 @@ configure_file(
4545
"${PROJECT_SOURCE_DIR}/include/beman/iterator_interface/config.hpp.in"
4646
"${PROJECT_BINARY_DIR}/include/beman/iterator_interface/config.hpp" @ONLY)
4747

48-
# Build the tests if enabled via the option ITERATOR_INTERFACE_BUILD_TESTING
49-
if(ITERATOR_INTERFACE_BUILD_TESTING)
48+
# Build the tests if enabled via the option BEMAN_ITERATOR_INTERFACE_BUILD_TESTING
49+
if(BEMAN_ITERATOR_INTERFACE_BUILD_TESTING)
5050
# Fetch GoogleTest
5151
FetchContent_Declare(
5252
googletest
@@ -83,12 +83,12 @@ add_subdirectory(src/beman/iterator_interface)
8383
add_subdirectory(include/beman/iterator_interface)
8484

8585
# [CMAKE.SKIP_TESTS]
86-
if(ITERATOR_INTERFACE_BUILD_TESTING)
86+
if(BEMAN_ITERATOR_INTERFACE_BUILD_TESTING)
8787
add_subdirectory(tests/beman/iterator_interface)
8888
endif()
8989

9090
# [CMAKE.SKIP_EXAMPLES]
91-
if(ITERATOR_INTERFACE_BUILD_EXAMPLES)
91+
if(BEMAN_ITERATOR_INTERFACE_BUILD_EXAMPLES)
9292
add_subdirectory(examples)
9393
endif()
9494

‎README.md‎

Lines changed: 132 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,7 @@ SPDX-License-Identifier: 2.0 license with LLVM exceptions
77
![CI Tests](https://github.com/beman-project/iterator_interface/actions/workflows/ci.yml/badge.svg)
88

99
**Implements**:
10-
* [`std::iterator_interface` (P2727)](https://wg21.link/P2727)
11-
10+
* [`std::iterator_interface` (P2727R4)](https://wg21.link/P2727R4)
1211

1312
Source is licensed with the Apache 2.0 license with LLVM exceptions
1413

@@ -24,47 +23,161 @@ The README itself is licesed with CC0 1.0 Universal. Copy the contents and incor
2423

2524
// SPDX-License-Identifier: CC0-1.0
2625

26+
## Examples
27+
28+
Full runable examples can be found in `examples/` - please check [./examples/README.md](./examples/README.md).
29+
30+
### TODO - first example
31+
32+
The next code snippet shows iterator interface support added in [`std::iterator_interface` (P2727R4)](https://wg21.link/P2727R4):
33+
34+
```cpp
35+
TODO
36+
```
37+
38+
### TODO - second example
39+
40+
The next code snippet shows iterator interface support added in [`std::iterator_interface` (P2727R4)](https://wg21.link/P2727R4):
41+
42+
```cpp
43+
TODO
44+
```
45+
2746
## How to Build
2847

48+
### Compiler Support
49+
50+
This is a modern C++ project which can be compiled with the latest C++ standards (**C++20 or later**).
51+
52+
Default build: `C++23`. Please check `etc/${compiler}-flags.cmake`.
53+
2954
### Dependencies
3055

31-
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.
56+
This project is mainly tested on `Ubuntu 22.04` and `Ubuntu 24.04`, but it should be as portable as CMake is. This
57+
project has no C or C++ dependencies.
3258

33-
It does require few tools as build-time dependencies:
59+
Build-time dependencies:
3460

35-
- `cmake`
36-
- `ninja`, `make`, or another CMake-supported build system
37-
- CMake defaults to "Unix Makefiles" on POSIX systems
61+
* `cmake`
62+
* `ninja`, `make`, or another CMake-supported build system
63+
* CMake defaults to "Unix Makefiles" on POSIX systems
3864

3965
Example of installation on `Ubuntu 24.04`:
66+
4067
```shell
41-
# install tools
68+
# Install tools:
4269
apt-get install -y cmake make ninja-build
4370

44-
# example of toolchains
45-
apt-get install g++-14 gcc-14 clang-18 clang++-18
71+
# Example of toolchains:
72+
apt-get install \
73+
g++-14 gcc-14 gcc-13 g++-14 \
74+
clang-18 clang++-18 clang-17 clang++-17
4675
```
4776

4877
### Instructions
4978

50-
Full set of supported toolchains can be found in [.github/workflows/ci.yml](#.github/workflows/ci.yml).
51-
52-
#### Basic Build
79+
#### Preset CMake Flows
5380

54-
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:
81+
This project strives to be as normal and simple a CMake project as possible. This build workflow in particular will
82+
work, producing a static `beman.iterator_interface` library, ready to package:
5583

5684
```shell
57-
cmake --workflow --preset gcc-14
85+
$ cmake --workflow --list-presets
86+
Available workflow presets:
87+
"system"
88+
"gcc-14"
89+
"gcc-13"
90+
"gcc-12"
91+
"clang-20"
92+
"clang-19"
93+
"clang-18"
94+
"clang-17"
95+
"clang-16
96+
97+
# Run examples:
98+
$ cmake --workflow --preset gcc-14
99+
Executing workflow step 1 of 3: configure preset "gcc-14"
100+
...
101+
-- Build files have been written to: /path/to/repo/.build/gcc-14
102+
103+
Executing workflow step 2 of 3: build preset "gcc-14"
104+
105+
ninja: no work to do.
106+
107+
Executing workflow step 3 of 3: test preset "gcc-14"
108+
109+
Test project /home/dariusn/git/Beman/iterator_interface/.build/gcc-14
110+
Start 1: IteratorTest.TestGTest
111+
1/4 Test #1: IteratorTest.TestGTest ........... Passed 0.00 sec
112+
Start 2: IteratorTest.TestRepeatedChars
113+
2/4 Test #2: IteratorTest.TestRepeatedChars ... Passed 0.00 sec
114+
Start 3: IteratorTest.TestFilteredIter
115+
3/4 Test #3: IteratorTest.TestFilteredIter .... Passed 0.00 sec
116+
Start 4: IteratorTest.OperatorArrow
117+
4/4 Test #4: IteratorTest.OperatorArrow ....... Passed 0.00 sec
118+
...
119+
120+
100% tests passed, 0 tests failed out of ...
121+
122+
Total Test time (real) = 0.09 sec
58123
```
59124
60125
This should build and run the tests with GCC 14 with the address and undefined behavior sanitizers enabled.
61126
62-
#### More complex cases
127+
#### Custom CMake Flows
63128
64-
The CMake preset system suffers from combinitorial explosion. There is a makefile in the root of the repository to aid in running more configurations.
129+
##### Default Build
130+
131+
CI current build and test flows:
65132
66133
```shell
67-
make -k TOOLCHAIN=clang-18 CONFIG=Tsan VERBOSE=1
134+
# Configure build: default build production code + tests (BEMAN_ITERATOR_INTERFACE_BUILD_TESTING=ON).
135+
$ cmake -G "Ninja Multi-Config" \
136+
-DCMAKE_CONFIGURATION_TYPES="RelWithDebInfo;Asan" \
137+
-DCMAKE_TOOLCHAIN_FILE=etc/clang-19-toolchain.cmake \
138+
-B .build -S .
139+
-- The CXX compiler identification is Clang 19.0.0
140+
...
141+
-- Build files have been written to: /path/to/repo/.build
142+
143+
# Build.
144+
$ cmake --build .build --config Asan --target all -- -k 0
145+
...
146+
[12/12] Linking CXX executable ... # Note: 12 targets here (including tests).
147+
148+
# Run tests.
149+
$ ctest --build-config Asan --output-on-failure --test-dir .build
150+
Internal ctest changing into directory: /path/to/repo/.build
151+
Test project /path/to/repo/.build
152+
...
153+
100% tests passed, 0 tests failed out of 82
154+
155+
Total Test time (real) = 0.67 sec
68156
```
69157
70-
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.
158+
##### Build Production, but Skip Tests
159+
160+
By default, we build and run tests. You can provide `-DBEMAN_ITERATOR_INTERFACE_BUILD_TESTING=OFF` and completely disable building tests:
161+
162+
```shell
163+
# Configure build: build production code, skip tests (BEMAN_ITERATOR_INTERFACE_BUILD_TESTING=OFF).
164+
$ cmake -G "Ninja Multi-Config" \
165+
-DCMAKE_CONFIGURATION_TYPES="RelWithDebInfo;Asan" \
166+
-DCMAKE_TOOLCHAIN_FILE=etc/clang-19-toolchain.cmake \
167+
-DBEMAN_ITERATOR_INTERFACE_BUILD_TESTING=OFF \
168+
-B .build -S .
169+
-- The CXX compiler identification is Clang 19.0.0
170+
...
171+
-- Build files have been written to: /path/to/repo/.build
172+
173+
# Build.
174+
$ cmake --build .build --config Asan --target all -- -k 0
175+
...
176+
[5/5] Linking CXX executable ... # Note: 5 targets here (tests were not built).
177+
178+
# Check that tests are not built/installed.
179+
$ ctest --build-config Asan --output-on-failure --test-dir .build
180+
Internal ctest changing into directory: /path/to/beman/repo/.build
181+
Test project /path/to/beman/repo/.build
182+
No tests were found!!!
183+
```

0 commit comments

Comments
 (0)