Skip to content

Commit 959adde

Browse files
SpectraL519SpectraL519
committed
readme update
1 parent c147b71 commit 959adde

2 files changed

Lines changed: 123 additions & 52 deletions

File tree

‎README.md‎

Lines changed: 121 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -4,109 +4,179 @@
44
</a>
55
</p>
66

7-
<br />
8-
97
<div align="center">
108

119
[![G++](https://github.com/SpectraL519/cpp-gl/actions/workflows/gpp.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/gpp.yaml)
1210
[![Clang++](https://github.com/SpectraL519/cpp-gl/actions/workflows/clang.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/clang.yaml)
11+
12+
</div>
13+
14+
<div align="center">
15+
1316
[![Code Formatting](https://github.com/SpectraL519/cpp-gl/actions/workflows/format.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/format.yaml)
1417
[![Benchmarks Smoke Test](https://github.com/SpectraL519/cpp-gl/actions/workflows/benchmarks.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/benchmarks.yaml)
18+
[![changelog](https://img.shields.io/badge/changelog-blue.svg?logo=github)](https://github.com/SpectraL519/cpp-gl/releases)
1519

1620
</div>
1721

1822
<br />
1923

24+
## Documentation
25+
26+
The complete, versioned documentation, including detailed tutorials, quick start guides, and architectural overviews, is hosted online:
27+
28+
**[Explore the CPP-GL Documentation](https://spectral519.github.io/cpp-gl/latest/)**
29+
30+
<br/>
31+
2032
## Overview
2133

22-
- The goal of the project was to create a higlhy customizable, intuitive and easy to work with graph library for the modern C++ standards.
23-
- The `CPP-GL` library's implementation relies solely on the C++ standard library (it does not require installing any additional tools) and is designed to be compatible with the C++ standard tools, e.g. range-based loops, std algorithms, the [ranges library](https://en.cppreference.com/w/cpp/ranges), stream operations, etc.
24-
- The library relies heavily on [concepts](https://en.cppreference.com/w/cpp/language/constraints) to acheive abstraction instead of interfaces and abstract classes to minimize the overhead associated with virtual tables and dynamic dispatch.
34+
CPP-GL is a highly customizable, intuitive, and concept-driven graph and hypergraph library designed for modern C++ standards.
2535

26-
> [!NOTE]
27-
> `v1.0.*` and `v1.0-prerelease-*` versions of the library have been developed as the Bachelor of Engineering project at the *Wrocław University of Science and Technology*
28-
>
29-
> Faculty: *W04N - Faculty of Information and Communication Technology*
30-
>
31-
> Field of study: *Algorithmic Computer Science*
36+
Designed strictly around modern C++ paradigms, the library heavily leverages templates and concepts to deliver an API that is exceptionally fast, generic, and type-safe. It relies solely on the C++ standard library, meaning it requires no external dependencies and integrates perfectly with modern C++ tools such as range-based loops, the `<ranges>` library, standard algorithms, stream operations, and more.
3237

33-
<br />
38+
<br/>
3439

35-
## Table of content
40+
## Module Architecture: GL vs. HGL
3641

37-
- [Overview](#overview)
38-
- [Table of content](#table-of-content)
39-
- [Installing the library](#installing-the-library)
40-
- [CMake integration](#cmake-integration)
41-
- [Documentation - TODO](#documentation---todo)
42-
- [Dev notes - TODO](#dev-notes---todo)
43-
- [Compiler support](#compiler-support)
44-
- [Licence](#licence)
42+
To accommodate different mathematical models without compromising API clarity or performance, the library is strictly partitioned into two primary modules:
4543

46-
<br />
44+
- **GL (Graph Library):** The core module dedicated to standard graphs. It handles both directed and undirected topologies where edges represent connections between exactly two vertices. It provides a comprehensive suite of utilities including structural generators, graph modifiers, and a broad spectrum of classical graph algorithms.
45+
- **HGL (Hypergraph Library):** A specialized module dedicated to hypergraphs, where a single hyperedge represents a higher-order connection between an arbitrary number of vertices. It features generalized traversal algorithms and incidence-based memory models tailored for complex, multi-way relationships.
4746

48-
## Installing the library
47+
<br/>
4948

50-
The use the `CPP-GL` library in your project you can download the source code from the [releases](https://github.com/SpectraL519/cpp-gl/releases) page and add the `<cpp-gl-root>/include` path to the include directories of your project.
49+
## Core Features
5150

52-
<br />
51+
Because both modules share the same fundamental design philosophy, they offer a unified, symmetrical feature set tailored to their respective mathematical domains:
5352

54-
## CMake integration
53+
- **Shared Zero-Cost Infrastructure:** By relying on C++20 concepts instead of virtual interfaces and dynamic dispatch, CPP-GL eliminates vtable overhead while enforcing strict compile-time contracts. Crucially, the **HGL module is built strictly on top of the GL module**, directly reusing its core infrastructure (ID types, traits, memory structures) to ensure maximum code reuse, while allowing the GL module to remain completely standalone for standard graph use cases.
54+
- **Unified Topology APIs:** The `gl::graph` and `hgl::hypergraph` classes offer consistent interfaces that completely abstract away the underlying memory models. Users can seamlessly swap between different backend representations without rewriting traversal logic, property accesses, or algorithm calls.
55+
- **Flexible Memory Layouts:** The library provides a comprehensive suite of memory-efficient representations. Users can choose between dynamic container-based layouts (Lists and Matrices) and highly optimized, cache-friendly contiguous array structures (Flat Lists and Flat Matrices). The HGL module further extends this by allowing users to specify the orientation of the memory models to optimize generalized incidence queries.
56+
- **Customizable Element Properties:** Vertices, edges, and hyperedges can carry arbitrary, user-defined payloads. Whether assigning standard metric weights and colors or attaching complex, application-specific data structures, the library's traits system ensures that property injection and access remain strictly type-safe and performant.
57+
- **Extensible Algorithmic Engines:** The library features a strictly decoupled algorithm design. Powerful, generic search templates serve as the underlying engines, allowing custom algorithms to be built on the fly by simply injecting zero-cost callbacks. Built upon these generic engines is a rich, out-of-the-box library of concrete algorithms—covering everything from classic pathfinding to advanced, multi-way reachability semantics for directed hypergraphs.
58+
- **Robust I/O Facilities:** Native serialization and formatting tools make it simple to pipe topologies directly to and from standard C++ streams and files. Both the GL and HGL modules share a unified set of stream options for visual output, while relying on dedicated, easily parsable flat-text formats (GSF and HGSF) to ensure fast and predictable data serialization.
5559

56-
The `CPP-GL` library can also be included in a `CMake` project by adding the following to the `CMakeLists.txt` file of your project:
60+
<br/>
5761

58-
```cmake
59-
cmake_minimum_required(VERSION 3.12)
62+
## Compiler Support
63+
64+
| Compiler | Min version |
65+
| :-: | :-: |
66+
| GNU G++ | 14 |
67+
| Clang | 18 |
68+
69+
> [!NOTE] C++23 Support
70+
>
71+
> Although currently the project has been properly verified using only the G++ and Clang compilers, it should work fine with other compilers with C++23 support like MSVC.
72+
73+
<br/>
74+
75+
## Installation & Integration
76+
77+
CPP-GL is a header-only template library. It can be integrated into a project either by directly including the headers or via CMake.
6078

79+
### Option A: CMake `FetchContent` (Recommended)
80+
81+
The easiest way to integrate CPP-GL is to fetch it directly from the GitHub repository during the CMake configuration phase:
82+
83+
```cmake
84+
cmake_minimum_required(VERSION 3.14)
6185
project(my_project LANGUAGES CXX)
6286
63-
# Include FetchContent module
6487
include(FetchContent)
6588
66-
# Fetch the CPP-GL library
6789
FetchContent_Declare(
6890
cpp-gl
69-
GIT_REPOSITORY https://github.com/SpectraL519/cpp-gl.git
70-
GIT_TAG <tag> # here you can specify the desired tag or branch
91+
GIT_REPOSITORY [https://github.com/SpectraL519/cpp-gl.git](https://github.com/SpectraL519/cpp-gl.git)
92+
GIT_TAG <tag> # Specify the desired version tag, branch, or specific commit.
7193
)
7294
7395
FetchContent_MakeAvailable(cpp-gl)
7496
75-
# Define the executable for the project
7697
add_executable(my_project main.cpp)
7798
7899
set_target_properties(my_project PROPERTIES
79-
CXX_STANDARD 23 # or newer
100+
CXX_STANDARD 23 # The CPP-GL library requires C++23.
80101
CXX_STANDARD_REQUIRED YES
81102
)
82103
83-
# Link against the cpp-gl library
84104
target_link_libraries(my_project PRIVATE cpp-gl)
85105
```
86106

87-
<br />
107+
### Option B: Including the Headers Directly
88108

89-
## Documentation - TODO
109+
If CMake is not being used, simply download the desired version of the library from the [Releases Page](https://github.com/SpectraL519/cpp-gl/releases) and add the `include` directory of the library to the project via the `-I<cpp-gl-dir>/include` flag.
90110

91-
<br />
111+
<br/>
92112

93-
## Dev notes - TODO
113+
## Benchmarks
94114

95-
<br />
115+
Performance and zero-cost abstraction are primary goals of this library. A comprehensive evaluation suite built on top of **Google Benchmark** provides a structured way to measure, filter, and report the library's performance across various graph algorithms and memory layouts.
96116

97-
## Compiler support
117+
For detailed performance metrics, configuration instructions (including BGL integration), and CLI usage, please refer to the **[Benchmarks Guide](benchmarks/README.md)**.
98118

99-
| Compiler | Min version |
100-
| :-: | :-: |
101-
| GNU G++ | 14 |
102-
| Clang | 18 |
119+
<br/>
103120

104-
> [!NOTE] C++23 Support
121+
## Developer Notes
122+
123+
To build the testing and documentation suites locally, follow the guides below.
124+
125+
### Running Tests
126+
127+
The library features a comprehensive test suite powered by **Doctest** and orchestrated via CMake. The test executables for both the `gl` and `hgl` modules can be built and run as follows:
128+
129+
```bash
130+
# Configure the project with tests enabled
131+
cmake -B build -DBUILD_TESTS=ON
132+
133+
# Build the test executables (replace <n> with the core count)
134+
cmake --build build/ -j<n>
135+
136+
# Execute the tests
137+
./build/tests/gl
138+
./build/tests/hgl
139+
```
140+
141+
### Code Formatting
142+
143+
The project enforces strict code formatting using `clang-format-18`. A custom Python script is provided to streamline the formatting process across the repository.
144+
145+
To format the entire repository:
146+
147+
```bash
148+
python scripts/format.py -exe clang-format-18
149+
```
150+
151+
To format only the files modified in the last commit:
152+
153+
```bash
154+
python scripts/format.py -m -exe clang-format-18
155+
```
156+
157+
> [!NOTE] If `clang-format-18` is your system's default, you can omit the `-exe` flag.
158+
159+
### Building the Documentation
160+
161+
The documentation is generated using Doxygen (for XML extraction), a custom Python script for concept parsing, and MkDocs (via `mike` for versioning). The process is automated via a Makefile.
162+
163+
To build and serve the documentation locally:
164+
165+
```bash
166+
make serve-docs
167+
```
168+
169+
To clean the documentation build directories:
170+
```bash
171+
make clean-docs
172+
```
173+
174+
> [!NOTE] Python Dependency Management
105175
>
106-
> Although currently the project has been properly verified using only the G++ and Clang compilers it should work fine with other compilers with C++23 support like MSVC.
176+
> The documentation build scripts rely on **[uv](https://docs.astral.sh/uv/)** to simplify Python dependency management within the project. Ensure `uv` is installed on the system before attempting to build the documentation.
107177
108-
<br />
178+
<br/>
109179

110-
## Licence
180+
## License
111181

112-
The `CPP-GL` project uses the [MIT Licence](https://mit-license.org/) which can be found in the [LICENCE](/LICENSE.md#mit-licence) file
182+
The `CPP-GL` project uses the [MIT License](https://mit-license.org/) which can be found in the [LICENSE](LICENSE.md) file.

‎benchmarks/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ This directory contains the performance evaluation suite for the CPP-GL library.
1414

1515
## Building the Benchmarks
1616

17-
To configure and build the benchmark executable, use the following standard CMake commands:
17+
To configure and build the benchmark executable, use the following standard CMake commands from the project root:
1818

1919
```shell
2020
cmake -B build_bench -DBUILD_BENCHMARKS=ON -DCMAKE_BUILD_TYPE=Release
@@ -30,6 +30,7 @@ cmake -B build_bench -DBUILD_BENCHMARKS=ON -DBENCH_INCLUDE_BGL=ON -DCMAKE_BUILD_
3030
```
3131

3232
> [!NOTE]
33+
>
3334
> BGL comparative benchmarks are only defined for specific benchmark suites where a direct equivalent exists in Boost.
3435
3536
<br/>

0 commit comments

Comments
 (0)