Skip to content

Commit f6a9d50

Browse files
SpectraL519SpectraL519
committed
readme update
1 parent c147b71 commit f6a9d50

2 files changed

Lines changed: 119 additions & 52 deletions

File tree

‎README.md‎

Lines changed: 117 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -4,109 +4,175 @@
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+
---
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+
## Module Architecture: GL vs. HGL
3439

35-
## Table of content
40+
To accommodate different mathematical models without compromising API clarity or performance, the library is strictly partitioned into two primary modules:
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+
- **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.
43+
- **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.
4544

46-
<br />
45+
## Core Features
4746

48-
## Installing the library
47+
Because both modules share the same fundamental design philosophy, they offer a unified, symmetrical feature set tailored to their respective mathematical domains:
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+
- **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.
50+
- **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.
51+
- **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.
52+
- **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.
53+
- **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.
54+
- **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.
5155

52-
<br />
56+
---
5357

54-
## CMake integration
58+
## Compiler Support
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+
| Compiler | Min version |
61+
| :-: | :-: |
62+
| GNU G++ | 14 |
63+
| Clang | 18 |
5764

58-
```cmake
59-
cmake_minimum_required(VERSION 3.12)
65+
> [!NOTE] C++23 Support
66+
>
67+
> 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.
68+
69+
---
6070

71+
## Installation & Integration
72+
73+
CPP-GL is a header-only template library. It can be integrated into a project either by directly including the headers or via CMake.
74+
75+
### Option A: CMake `FetchContent` (Recommended)
76+
77+
The easiest way to integrate CPP-GL is to fetch it directly from the GitHub repository during the CMake configuration phase:
78+
79+
```cmake
80+
cmake_minimum_required(VERSION 3.14)
6181
project(my_project LANGUAGES CXX)
6282
63-
# Include FetchContent module
6483
include(FetchContent)
6584
66-
# Fetch the CPP-GL library
6785
FetchContent_Declare(
6886
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
87+
GIT_REPOSITORY [https://github.com/SpectraL519/cpp-gl.git](https://github.com/SpectraL519/cpp-gl.git)
88+
GIT_TAG <tag> # Specify the desired version tag, branch, or specific commit.
7189
)
7290
7391
FetchContent_MakeAvailable(cpp-gl)
7492
75-
# Define the executable for the project
7693
add_executable(my_project main.cpp)
7794
7895
set_target_properties(my_project PROPERTIES
79-
CXX_STANDARD 23 # or newer
96+
CXX_STANDARD 23 # The CPP-GL library requires C++23.
8097
CXX_STANDARD_REQUIRED YES
8198
)
8299
83-
# Link against the cpp-gl library
84100
target_link_libraries(my_project PRIVATE cpp-gl)
85101
```
86102

87-
<br />
103+
### Option B: Including the Headers Directly
88104

89-
## Documentation - TODO
105+
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.
90106

91-
<br />
107+
---
92108

93-
## Dev notes - TODO
109+
## Benchmarks
94110

95-
<br />
111+
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.
96112

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

99-
| Compiler | Min version |
100-
| :-: | :-: |
101-
| GNU G++ | 14 |
102-
| Clang | 18 |
115+
---
103116

104-
> [!NOTE] C++23 Support
117+
## Developer Notes
118+
119+
To build the testing and documentation suites locally, follow the guides below.
120+
121+
### Running Tests
122+
123+
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:
124+
125+
```bash
126+
# Configure the project with tests enabled
127+
cmake -B build -DBUILD_TESTS=ON
128+
129+
# Build the test executables (replace <n> with the core count)
130+
cmake --build build/ -j<n>
131+
132+
# Execute the tests
133+
./build/tests/gl
134+
./build/tests/hgl
135+
```
136+
137+
### Code Formatting
138+
139+
The project enforces strict code formatting using `clang-format-18`. A custom Python script is provided to streamline the formatting process across the repository.
140+
141+
To format the entire repository:
142+
143+
```bash
144+
python scripts/format.py -exe clang-format-18
145+
```
146+
147+
To format only the files modified in the last commit:
148+
149+
```bash
150+
python scripts/format.py -m -exe clang-format-18
151+
```
152+
153+
> [!NOTE] If `clang-format-18` is your system's default, you can omit the `-exe` flag.
154+
155+
### Building the Documentation
156+
157+
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.
158+
159+
To build and serve the documentation locally:
160+
161+
```bash
162+
make serve-docs
163+
```
164+
165+
To clean the documentation build directories:
166+
```bash
167+
make clean-docs
168+
```
169+
170+
> [!NOTE] Python Dependency Management
105171
>
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.
172+
> 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.
107173
108-
<br />
174+
---
109175

110-
## Licence
176+
## License
111177

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
178+
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)