# libfstwriter

**Repository Path**: lasimu/libfstwriter

## Basic Information

- **Project Name**: libfstwriter
- **Description**: 镜像仓库
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-08
- **Last Updated**: 2026-08-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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 (85% line and 85% function coverage).
- **Bit-true**: The implementation is bit-true to the original `fstapi.c` (tested in unittests).

## Regression Reports (WIP due to GitHub Actions permission issue)
We generate a detailed regression summary for every push on the `main` 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

- `fstcpp/`: 🌟 MAIN Core C++ implementation, header, and unittests.
  - `fstcpp_writer.h`: The new C++ API header.
  - `fstcpp_writer.cpp`: The implementation.
- `integration_test/`: 🧪 TESTS Integration tests generated by Verilator.
  - `verilator_share/`
    - `gtkwave/`: 📚 ORIGINAL GtkWave files copied from `libfst`.
      - `fstapi.cpp`: C-style wrapper for backward compatibility.
      - `fstapi.c`: REFERENCE - the original GtkWave implementation.
      - `fstapi.h`: The original GtkWave header file.
    - `*.patch`: Patches for Verilator runtime.
    - other files: Copied from Verilator 5.044 runtime (5.042 should also work) by `setup_runtime.sh`.
  - other folders: individual integration tests.

---

## 🛠️ Build & Testing & Installation

### Prerequisites
* C++20 compatible compiler (GCC/Clang)
* CMake (3.10 or higher)
* Ninja (optional, recommended for speed)
* Verilator (5.044 is tested, but a bit older version might work too)

### Setup for Development

First, setup the Verilator runtime and generate the integration test files. This usually only needs to be run once unless you modify the Verilog files in `tests/`:

```bash
./integration_test/setup_runtime.sh
```

Then, 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 -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .
```

### 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 .
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. The regression script automatically calls `setup_runtime.sh`:

```bash
./run_regression.sh --coverage
```

By default, it will create `build/regression` directory.

### Installation

There is no standard installation step now, just copy the `fstcpp/` folder to your project, and remove `*.test.cpp`. If you want to use the C-style wrapper, also copy `integration_test/verilator_share/gtkwave/fstapi.(cpp|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 root directory of this project contains a mix of original code and redistributed files:

* **MIT**
  * **`fstcpp/`**: The core of this project.
  * **`integration_test/`**: Without explicitly mentioned, all SystemVerilog files and the testbench CPP files are part of this project.
    * **`verilator_share/gtkwave/`**: Redistributed from `libfst`, which is MIT license.
    * **`verilator_share/gtkwave/fstapi.cpp`**: A compatibility layer wrapping this project into `libfst`'s original C-interface.
    * **`*/verilated/`**: Generated by Verilator 5.044 (5.042 also supported). They are derivative works and inherit the original MIT license of the SystemVerilog source.
* **LGPL v3**
  * **`integration_test/verilator_share/`**: Copied from Verilator runtime by `setup_runtime.sh` (patched for bit-true).
* Projects that we have cited:
  * [Verilator](https://github.com/verilator/verilator/)
  * [libfst](https://github.com/gtkwave/libfst/)

**AI usage notice:** The files in this repository are assisted by *Gemini 3 Pro* with *AntiGravity*.