Cyan4973 / Cyan4973/xxHash

Simple source code to integrate

Open
#550 23 comments 3 reactions 0 assignees View on GitHub
Long-term
Dominant language
C
Stars
11.2k
Forks
913
Avg merge
10h 9m
Merged PRs (30d)
4

Description

One of the strong points of `xxhash` is its integration story : it's enough to grab a single file `xxhash.h` and there you have the entire library available in your program.

However, this only applies to people who trust the source code. In some cases, when a programmer feels he should inspect the source code before integration, the large source size of `xxhash.h` can feel daunting by itself.

One idea could be to split the source code into more dedicated units, resulting in more focused code bases. If someone is only interested in `XXH32()` or `XXH64()`, they could integrate, or even copy/paste, just this code.
A good example of this strategy is [Stefan Brumme's simple xxHash C++ libraries](https://create.stephan-brumme.com/xxhash/).
To reach the same level of clarity,`XXH3` would have to be split even further, alongside its vector variants.
And of course, one-shot and streaming variants would preferably be separated too.

This could work. But it would also result in a more complex multi-files code base, making the integration story more difficult.

A potential work-around could be to split the source code into these dedicated units, and then have an automated build system which regenerates the "complete" amalgamated `xxhash.h` library, so that current user base can still benefit from the 1-file integration story.

Splitting is not too difficult, though requires quite some work, hence some available time.
The amalgamation process can be a bit more tricky, especially if an important objective is that `xxhash.h` must remain an approachable source file which can be read and debugged, as readability experience can be hurt by a dumb amalgamation process.

Supersedes #543.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the monolithic xxhash.h and the issue's proposed split between XXH32(), XXH64(), XXH3, vector, one-shot, and streaming code. There are no tests or other entry points named in the issue. Done would mean focused source units plus an automated way to regenerate a readable, complete xxhash.h without breaking the existing one-file integration path.

Written by the indexing model from the issue text.

Assessment

Tech stack
c
Domain
build-system
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.