https://github.com/johnjohnlin/libfstpp
A faster reimplementation of Gtkwave FST format Writer API
https://github.com/johnjohnlin/libfstpp
Last synced: 3 months ago
JSON representation
A faster reimplementation of Gtkwave FST format Writer API
- Host: GitHub
- URL: https://github.com/johnjohnlin/libfstpp
- Owner: johnjohnlin
- License: mit
- Created: 2026-01-16T14:15:26.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2026-02-07T19:13:50.000Z (4 months ago)
- Last Synced: 2026-02-08T04:12:23.655Z (4 months ago)
- Language: C++
- Homepage:
- Size: 18.4 MB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# """"" This repo is archived and now hosted by [GtkWave](https://github.com/gtkwave/libfstwriter). """""
# """"" This repo is archived and now hosted by [GtkWave](https://github.com/gtkwave/libfstwriter). """""
# """"" This repo is archived and now hosted by [GtkWave](https://github.com/gtkwave/libfstwriter). """""
# High-Performance FST Waveform Writer
A C++14 re-implementation of the **Fast Signal Trace (FST)** waveform writer, originally designed for [GtkWave](http://gtkwave.sourceforge.net/).
## 🚀 Overview
This project provides a highly optimized, standard-compliant C++ implementation of the FST writer API. The core of this project is written in **C++14** to ensure maximum compatibility with EDA tools and environments (which is usually a bit outdated), specifically targeting performance improvements for *Verilator* simulations.
The unittests are written in C++20.
### Key Features
- **C++14**: The core of this project is written in clean C++14 to maximize compatibility. Using `vector` and `string` can eliminate most resource management code compared to C.
- **High Performance**: Optimized for speed to reduce simulation overhead (2x faster than the original `fstapi` when used with Verilator). This is mainly because we process data as binary instead of strings used by the original `fstapi.c`.
- **Drop-in Compatibility**: Includes an optional C-compatible wrapper `fstapi.cpp`, providing the same writer interface as the original `fstapi.c`.
- **Robust Testing**: Comprehensive unit tests written in C++20 to ensure correctness. Coverage is also generated and checked (70% line and 70% function coverage).
- **Bit-true**: The implementation is bit-true to the original `fstapi.c` (tested in unittests).
## Regression Reports (WIP due to permission issue)
We generate a detailed regression summary for every push on the `master` branch.
To view it:
1. Go to the **Commit Detail** page (click the **Commit SHA**, usually above the files list).
2. Look for a comment by `github-actions[bot]`.
3. Click the link "Click Here to View Summary". This takes you to the **Job Summary** page of the Action run, where you can see the pass/fail status and coverage metrics.
## 📂 Project Structure
Every file of this project is under the `src` directory, which also includes third-party files:
```
fstcpp/ # 🌟 MAIN: Core C++ implementation
├── Writer.h # - The new C++ API header
└─── Writer.cpp # - The implementation
gtkwave/ # 📚 ORIGINAL: Original GtkWave files
├── fstapi.cpp # - C-style wrapper for backward compatibility
├── fstapi.c # - REFERENCE: the original GtkWave implementation
└── fstapi.h # - The original GtkWave header file used by both fstapi.cpp and fstapi.c
integration_test/ # 🧪 TESTS: Integration tests generated by Verilator
```
---
## 🛠️ Build & Testing & Installation
### Prerequisites
* C++20 compatible compiler (GCC/Clang)
* CMake (3.10 or higher)
* Ninja (optional, recommended for speed)
### Setup for Development (VS Code)
To configure the project with debug symbols and prepare it for *VS Code*+*clangd*:
```bash
# Generate build files using Ninja
cmake -G Ninja -B build/debug -DCMAKE_BUILD_TYPE=Debug src
```
### Manual Build for Development (No coverage test)
If you prefer running steps manually, our repository follows a very standard CMake workflow, here is an example:
```bash
cmake -G Ninja -B build/debug -DCMAKE_BUILD_TYPE=Debug src
cd build/debug
ninja -j$(nproc)
ctest -j$(nproc)
```
### Testing and Verification
To run the full regression suite (build, test, and coverage) just like the CI server:
```bash
./run_regression.sh --coverage
```
By default, it will create `build/regression` directory.
### Installation
There is no standard installation step now, just copy the files in `src/fstcpp` to your project. If you want to use the C-style wrapper, also copy `src/gtkwave/fstapi.cpp` and `src/gtkwave/fstapi.h` to your project.
The dependencies are `ZLIB` and `lz4`, which are quite easy to install on most Linux distributions.
---
## 📚 References
* [FST Waveform Specification (Unofficial)](https://blog.timhutt.co.uk/fst_spec/) - A great resource for understanding the FST format internals.
* [Benchmark](https://github.com/yodalee/verilator_snapshot) - Contains performance benchmarks.
## 📄 License
The main source code of this repository is licensed under the **MIT License**.
See the [LICENSE](LICENSE) file for more details.
### Details
The `src` directory of this project contains a mix of original code and redistributed files:
* **MIT**
* **`fstcpp/`**: The core of this project.
* **`gtkwave/`**: Redistributed from GtkWave.
* **`integration_test/`**: `Simple.sv` and `Simple_tb.test.cpp` are part of this project.
* **Boost Software License**
* **`fstcpp/string_view.h`**: Lightweight `string_view` implementation.
* **Verilator License**
* **`integration_test/`**: Generated by Verilator 5.042.
**AI usage notice:** The files in this repository are assisted by *Gemini 3 Pro* with *AntiGravity*.