Skip to content

Commit e03170e

Browse files
JeffGarlandJeffGarland
authored
Merge pull request #19 from bemanproject/18-add-initial-paper-draft-and-various-cleanups
add draft paper text - cleanup for readme
2 parents 073a607 + 940980c commit e03170e

File tree

2 files changed

+417
-151
lines changed

2 files changed

+417
-151
lines changed

‎README.md‎

Lines changed: 64 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
2+
SPDX-License-Identifier: CC0-1.0
33
-->
44

55
# beman.scope: Generic Scope Guard
@@ -56,198 +56,111 @@ For discussions of this library see:
5656

5757
`beman.scope` is a C++ library conforming to [The Beman Standard](https://github.com/bemanproject/beman/blob/main/docs/BEMAN_STANDARD.md).
5858

59-
**Implements**: TODO
59+
**Implements**: D3610R0 Scope Guard for C++29
6060

6161
**Status**: [Under development and not yet ready for production use.](https://github.com/bemanproject/beman/blob/main/docs/BEMAN_LIBRARY_MATURITY_MODEL.md#under-development-and-not-yet-ready-for-production-use)
6262

6363
## Usage
6464

65-
TODO
65+
The following is an example of using `scope_fail` to trigger and action when the scope
66+
is exited with an exception. `scope_success` and `scope_exit` provide similar capability
67+
but with different checked conditions on exiting the scope.
6668

67-
### Example Usage
69+
```c++
70+
#include <beman/scope/scope.hpp>
6871

69-
TODO
7072

71-
Full runnable examples can be found in `examples/`.
72-
73-
## Building beman.scope
74-
75-
### Dependencies
76-
77-
This project has no C or C++ dependencies.
78-
79-
Build-time dependencies:
80-
81-
- `cmake`
82-
- `ninja`, `make`, or another CMake-supported build system
83-
- CMake defaults to "Unix Makefiles" on POSIX systems
84-
85-
#### How to install dependencies
86-
87-
<!-- TODO Darius: rewrite section!-->
88-
89-
<details>
90-
<summary>Dependencies install scope on Ubuntu 24.04 </summary>
91-
92-
<!-- TODO Darius: rewrite section!-->
93-
94-
```shell
95-
# Install tools:
96-
apt-get install -y cmake make ninja-build
73+
bool triggered = false;
74+
{
75+
scope_fail guard([&]() { triggered = true; });
76+
// no exception thrown
77+
}
78+
// triggered == false
79+
try {
80+
scope_fail guard([&]() { triggered = true; });
9781

98-
# Toolchains:
99-
apt-get install \
100-
g++-14 gcc-14 gcc-13 g++-14 \
101-
clang-18 clang++-18 clang-17 clang++-17
102-
```
103-
104-
</details>
82+
throw std::runtime_error( "trigger failure" );
10583

106-
<details>
107-
<summary>Dependencies install scope on MAC OS $VERSION </summary>
84+
} catch (...) { // expected }
10885

109-
<!-- TODO Darius: rewrite section!-->
110-
```shell
111-
# TODO
86+
// triggered == true
11287
```
11388
114-
</details>
89+
`unique_resource` is a cutomizeable RAII type similar to `unique_ptr`.
11590
116-
<details>
117-
<summary>Dependencies install scope on Windows $VERSION </summary>
118-
<!-- TODO Darius: rewrite section!-->
91+
```c++
92+
#include <beman/scope/scope.hpp>
11993
120-
```shell
121-
# TODO
122-
```
94+
{
95+
auto file = beman::scope::unique_resource(
96+
fopen("example.txt", "w"), // function to acquire the FILE*
97+
[](FILE* f) { // function to cleanup on destruction
98+
if (f) {
99+
fclose(f); // Release (cleanup) the resource
100+
}
101+
}
102+
);
123103
124-
</details>
104+
// use file via f->
105+
}
125106
126-
### How to build beman.scope
127-
128-
Beman scope is header only.
129-
130-
```shell
131-
cmake --workflow --preset gcc-debug
132-
cmake --workflow --preset gcc-release
133-
cmake --install build/gcc-release --prefix /opt/beman.scope
107+
// Resource is automatically released when `file` goes out of scope
108+
std::cout << "File has been closed \n";
134109
```
135110

136-
<details>
137-
<summary> Build beman.scope (verbose logs) </summary>
138-
139-
```shell
140-
# Configure beman.scope via gcc-debug workflow for development.
141-
$ cmake --workflow --preset gcc-debug
142-
Executing workflow step 1 of 3: configure preset "gcc-debug"
143-
144-
Preset CMake variables:
145-
146-
CMAKE_BUILD_TYPE="Debug"
147-
CMAKE_CXX_COMPILER="g++"
148-
CMAKE_CXX_FLAGS="-fsanitize=address -fsanitize=pointer-compare -fsanitize=pointer-subtract -fsanitize=leak -fsanitize=undefined"
149-
CMAKE_CXX_STANDARD="20"
150-
151-
TODO
152-
153-
# Run examples.
154-
$ TODO
155-
156-
```
157-
158-
</details>
159-
160-
<details>
161-
<summary> Install beman.scope (verbose logs) </summary>
162-
163-
```shell
164-
# Install build artifacts from `build` directory into `opt/beman.scope` path.
165-
$ cmake --install build/gcc-release --prefix /opt/beman.scope
166-
-- Install configuration: "RelWithDebInfo"
167-
-- Up-to-date: /opt/beman.scope/lib/libbeman.exemplar.a
168-
-- Up-to-date: /opt/beman.scope/include/beman/exemplar/identity.hpp
111+
Full runnable examples can be found in `examples/`.
169112

113+
## Integrate beman.scope into your project
170114

171-
# Check tree.
172-
$ tree /opt/beman.scope
173-
/opt/beman.scope
174-
├── include
175-
│   └── beman
176-
│   └── scope
177-
│   └── scope.hpp
115+
Beman.scope is a header-only library that currently relies on TS implementations
116+
and is thus currently available only on GCC13 and up, or Clang 19 and up -- in C++20 mode.
178117

118+
As a header only library no building is required to use in a project -- simply make
119+
the `include` directory available add add the following to your source.
179120

180-
4 directories, 2 files
121+
```cpp
122+
#include <beman/scope/scope.hpp>
181123
```
182124

183-
</details>
184-
185-
<details>
186-
<summary> Disable tests build </summary>
187-
188-
To build this project with tests disabled (and their dependencies),
189-
simply use `BEMAN_EXEMPLAR_BUILD_TESTING=OFF` as documented in upstream [CMake documentation](https://cmake.org/cmake/help/latest/module/CTest.html):
190-
191-
```shell
192-
cmake -B build -S . -DBEMAN_EXEMPLAR_BUILD_TESTING=OFF
193-
```
125+
## Building beman.scope
194126

195-
</details>
127+
Building is only required to run tests and examples.
196128

197-
## Integrate beman.scope into your project
129+
### Build Dependencies
198130

199-
<details>
200-
<summary> Use beman.scope directly from C++ </summary>
201-
<!-- TODO Darius: rewrite section!-->
131+
The library itself has no build dependencies other than Catch2 for testing
132+
and cmake.
202133

203-
If you want to use `beman.scope` from your project,
204-
you can include `beman/scope/*.hpp` files from your C++ source files
134+
Build-time dependencies:
205135

206-
```cpp
207-
#include <beman/scope/identity.hpp>
208-
```
136+
- `cmake`
137+
- `ninja`, `make`, or another CMake-supported build system
138+
- CMake defaults to "Unix Makefiles" on POSIX systems
209139

210-
and directly link with `libbeman.scope.a`
140+
### How to build beman.scope
211141

212142
```shell
213-
# Assume /opt/beman.scope staging directory.
214-
$ c++ -o identity_usage examples/identity_usage.cpp \
215-
-I /opt/beman.scope/include/ \
216-
-L/opt/beman.scope/lib/ -lbeman.exemplar
143+
cmake --workflow --preset gcc-debug
144+
cmake --workflow --preset gcc-release
145+
cmake --install build/gcc-release --prefix /opt/beman.scope
217146
```
218147

219-
</details>
220-
221-
<details>
222-
<summary> Use beman.scope directly from CMake </summary>
223-
224-
<!-- TODO Darius: rewrite section! Add examples. -->
148+
# License
225149

226-
For CMake based projects, you will need to use the `beman.scope` CMake module to define the `beman::exemplar` CMake target:
150+
Source is licensed with the Apache 2.0 license with LLVM exceptions
227151

228-
```cmake
229-
find_package(beman.scope REQUIRED)
230-
```
231-
232-
You will also need to add `beman::scope`
233-
to the link libraries of any libraries or executables that include `beman/scope/*.hpp` in their source or header file.
234-
235-
```cmake
236-
target_link_libraries(yourlib PUBLIC beman::scope)
237-
```
152+
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
238153

239-
</details>
154+
Documentation and associated papers are licensed with the Creative Commons Attribution 4.0 International license.
240155

241-
<details>
242-
<summary> Use beman.scope from other build systems </summary>
156+
// SPDX-License-Identifier: CC-BY-4.0
243157

244-
<!-- TODO Darius: rewrite section! Add examples. -->
158+
The intent is that the source and documentation are available for use by people how they wish.
245159

246-
Build systems that support `pkg-config` by providing a `beman.scope.pc` file.
247-
Build systems that support interoperation via `pkg-config` should be able to detect `beman.scope` for you automatically.
160+
The README itself is licensed with CC0 1.0 Universal. Copy the contents and incorporate in your own work as you see fit.
248161

249-
</details>
162+
// SPDX-License-Identifier: CC0-1.0
250163

251-
## Contributing
164+
# Contributing
252165

253166
Please do! Issues and pull requests are appreciated.

0 commit comments

Comments
 (0)