Proposal(Draft): New Folder Structure for zbench

[hendriknielaender]

Overview

This proposal outlines a new folder structure for the zbench project to improve modularity and maintainability. Some of the folder structure we already have, other parts are not yet part of the project like formats. It is more of a draft, to keep an eye of the growing codebase.

Proposed Folder Structure

The new folder structure is organized as follows:

/zbench
|-- /lib                     # Source files for the core functionalities
|   |-- /benchmark           # Benchmark related functionalities
|   |   |-- benchmark.zig    # Core benchmark logic
|   |   |-- config.zig       # Benchmark configuration structures
|   |   |-- definition.zig   # Benchmark definition and management
|   |   |-- result.zig       # Result handling and output formats
|   |   |-- statistics.zig   # Statistics calculations
|   |   |-- tracking_allocator.zig
|   |
|   |-- /output             # Different output formats
|   |   |-- json_base.zig    # Base JSON functionality
|   |   |-- bmf.zig          # BMF-specific JSON format
|   |   |-- github.zig       # GitHub Actions-specific JSON format
|   |   |-- custom.zig       # Other custom formats
|   |   |-- color.zig        # Color output control
|   |
|   |-- /util                # Utility functions and helpers
|   |   |-- ...
|   |
|   |-- zbench.zig             # Entry point that ties everything together
|
|-- /docs                    # Documentation for the project
|   |-- intro.md
|   |-- quickstart.md
|   |-- advanced.md
|
|-- /examples                # Examples files
    |-- basic.zig            # Examples for all different use cases
|-- /tests                   # Test files
    |-- benchmark_test.zig   # Tests for benchmarking functionalities

Advantages of the New Structure

• Modularity: By separating core functionalities, utility functions, and output formats into distinct directories, the codebase becomes easier to navigate and manage. This modularity allows developers to quickly understand the layout and purpose of each component.
• Scalability: The structure facilitates the addition of new features and formats without cluttering existing code, thereby supporting the project's growth.
• Maintainability: A clear separation of concerns, especially with utilities and formatting being isolated, simplifies maintenance and reduces the risk of changes in one area impacting others.
• Testing and Documentation: Dedicated directories for tests and documentation encourage the development of comprehensive tests and proper documentation, which are crucial for long-term stability and usability.

[FObersteiner]

I think this is a good idea! Reading the proposed structure, I was wondering what we want do be :) src and main.zig suggests a binary (application) to me - isn't it a library actually?

[hendriknielaender]

Good point, adjusted it to lib and zbench.zig.

[FObersteiner]

since you're at it, I was also wondering if the util directory is needed :) Some ideas:

• rename "formats" to "output", then color.zig would fit in there
• statistics and tracking_allocator might also go into "benchmark"
• config and definition could maybe go in one zig file ?
• github actions: isn't that yaml ?

[hendriknielaender]

True, adjusted to output and moved these files to benchmark. I will also put in all other files into the graph. Currently this was more a basic draft, but with all files mentioned the process will be cleaner.

Merging files i would see in another PR, since this will already be a bigger change.

Ahh for the github actions i meant the output format from an actual benchmark action (see: https://github.com/benchmark-action/github-action-benchmark)

[FObersteiner]

Once Zig 0.14 stable is out, should we implement the new directory structure?

@hendriknielaender what is your plan for continuing support of Zig 0.13? We could have one more tagged release (0.9.2) which includes #99, then move to Zig 0.14 with the main branch, what do you think? I'm kind of eager to get zbench to 0.14 since I want to include some benchmarks in zdt; and the next zdt release will require Zig 0.14 since I'm using the labeled switch ;-)

[hendriknielaender]

Yeah, we should do that.

I'm thinking about supporting the latest master branch. My current experience so far is that we should be able to support that.

I will do a release for 0.9.2, then we can move forward.