There are multiple comments remarking on the header-only implementation, confused regarding linker errors and why this is desirable. Look into stb lib, which in my opinion popularized this idea: https://github.com/nothings/stb?tab=readme-ov-file#how-do-i-...
In particular, you can define the implementation flag and include the header in a .c file with no other contents to recover the more “traditional” build set up where you have a separate TU dedicated to the library.
I quite like the flexibility it provides in terms of making “unity builds” very easy, and scaling down quite well to small, single-TU projects with minimal build set ups.
Exactly! That flexibility was one of my goals. Making integration smooth for both small embedded projects and larger codebases with unity builds — glad to hear it resonates.
I first encountered the idea relatively recently with Clay [1] and I have been a fan since. Once you get past the “huh, weird” stage it has a lot of benefits!
Thanks! Yes, stb-style header-only libs were definitely an inspiration. I know some devs find the approach confusing, especially with linker errors if *_IMPLEMENTATION isn't handled correctly.
I tried to keep it simple and clearly documented, but feedback like this helps improve it.
You're supposed to #define GIF_IMPLEMENTATION in only one of your .c files to prevent linker collisions. But yeah I don't get the point. How is this any better than the standard method of putting macros and data definitions in the .h and code in the .c? This is just going to confuse anyone who comes along later and wants to work on the code that uses this thing.
Totally fair — this pattern can be confusing at first glance.
The main motivation is ease of integration: no need to manage extra .c files, no build system tweaks, just drop in one file and go.
It’s especially useful for embedded systems, scripts, and small projects where build friction matters.
That said, I agree that for larger teams or long-term projects, the classic .h + .c split can be clearer — that’s why the implementation can easily be separated if needed.
Appreciate the feedback!
people who have to support windows do this sometimes because MS has gone for almost forty years now without ever specifying a default directory where libraries go. This is in spite of the fact that being the creator of the OS, the most-popular compiler, and the SDK should in theory give them enormous leverage to dictate where dependencies get saved.
There's this bizarre cultural difference you see between people who learned to program on windows compared to people who learned to program on unix wherein the Windows crowd don't see the value of having an easily reproducible build system because. Usually this results in some combination of needlessly-complicated scripts and checking binary builds of dependencies into version-control.
Requiring you to include a header-file while also defining a specific constant in only one place that turns the header file into a c-file is actually one of the more benign workarounds you see.
Outside FOSS UNIX clones, most OSes, including commercial OSes, tend to have a more diversified ecosystem in compilers, and which directories those compilers take their libraries from.
Not learning about how compilers, linkers and library managers actually work.
Even C++, and considering templates, if you want to use external templates optimization you need implementation files, and then there are modules (already working in clang/VC++).
So you get a header only implementation by forcing all users to do something unexpected instead of having a single C file. Seems silly and not really the point of a header only implementation.
It's not that weird, and it's explained first thing in the header and shown in the example of how to use it. You do need to read how to use the thing, and this is a simpler detail than any of the function signatures you'll have to look at.
Personally I would probably add a gif.c to my project which does nothing but include the header with the define set, at least if I'm going to need a gif decoder in more than one place. Probably many (most?) projects only need this library in one file anyway, in which case I'd just include it from that file and be done.
Great question!
It works the same way as stb-style libs: you only #define GIF_IMPLEMENTATION in one .c file (one translation unit). In all other files, you just #include "gif.h" without the define.
The header uses #ifdef GIF_IMPLEMENTATION to include implementation code only once.
So no linker errors — everything compiles cleanly as long as that rule is followed.
I’ll make this clearer in the README too, thanks!
Probably it's better to mark every functions as static in a header-only library, not just those internal ones. But I think code bloat would still be an issue if we don't use LTO or other optims across compilation units.
edit: Yeah, defining *_IMPLEMENTATION appropriately would address these issues.
I once did it for a closed-source CAM/CAE software. We wanted to generate high resolution and decent quality GIFs visualizing a progress of a numerical optimization in a few hundred animation frames. I wasn’t able to find a library which would deliver both reasonable size and good quality, so I made my own.
The trickiest part wasn’t the encoder; it’s computing the palette from RGB images. To minimize the output file size, I wanted a single palette shared by all frames.
The key piece of research was in that sample code from early 90-s https://www.ece.mcmaster.ca/~xwu/cq.c However, I had to rework it heavily because global variables and C language are too old school, also because FP32 precision is insufficient for the count of input pixels in my use case. 200 FullHD frames contain approximately 400M pixels, FP32 numbers don’t have the precision to accumulate that many of them. And the number is dangerously close to int32 limit, I have also upgraded the integer counters to int64.
This is very interesting that you did the visualization using a GIF. I have only generated mp4 videos for vidoes till now using ffmpeg and png images or through something equivalent. Was there any advantage of GIF that you found? Like may be it was easier to do on the fly or was just simple enough?
I believe the reason why management specifically asked for animated GIFs was compatibility. The GIF format is ancient and supported by everything, makes it trivial to share or embed these animation files.
Ignoring the compatibility, modern video codecs like h264 or h265 are substantially better than animated GIFs, in terms of both size and quality.
BTW I supported them as well. The only target platform of that software is modern versions of Windows. It only took couple pages of straightforward C++ because the OS includes a functional equivalent of libavcodec and libavformat libraries. Moreover, GPU drivers install and register the components to leverage the codecs implemented by hardware of these GPUs. The high-level API to encode compressed video files from a sequence of frames is MFCreateSinkWriterFromURL function.
I wonder if the README.md of this project has been generated by an LLM, or if LLMs output such READMEs mainly because of their training data and thus mistakenly gets identified as LLM-generated README. The two are not mutually exclusive I suppose.
I checked the code, it gives me "LLM vibes", too. FWIW, I am not against it. Perhaps the developer was using it here and there. Personally I do not care.
The use of the AI emoji ("Sparkles"), plus the "Example Projects" section containing no example projects, certainly doesn't help it beat the AI allegations.
It is a formally written README which is very usual in formal circle of communication, think proposal writing or papers etc. Outside, it is usual for people to do this when their primary exposure to English is through such channels or when they are not comfortable with having their personal style of talking be viewed by the public.
LLM is also similar in that sense, so it produces the same writing. It resists personal touch without being explicitly asked.
Whenever I tell an LLM to generate README.md for a project, it comes up with READMEs like this one, full of emojis (easy to generate README.md without them though).
easier to build, easier to navigate, easier to integrate
ppl who ask qustions like this must have not worked much on codebases w/ nightmarish build setups, libraries like this are so refreshing/easier to work w/
The readme just looks like it was written by AI, and the initial commit is the entire code. It just seems like AI was used at least somewhat. Just curious how much, if at all.
I submitted a link to a project[0] with similar characteristics a few days ago, before I realized it was probably entirely made by AI. That's what got me wondering this in the first place.
There are multiple comments remarking on the header-only implementation, confused regarding linker errors and why this is desirable. Look into stb lib, which in my opinion popularized this idea: https://github.com/nothings/stb?tab=readme-ov-file#how-do-i-...
In particular, you can define the implementation flag and include the header in a .c file with no other contents to recover the more “traditional” build set up where you have a separate TU dedicated to the library.
I quite like the flexibility it provides in terms of making “unity builds” very easy, and scaling down quite well to small, single-TU projects with minimal build set ups.
Exactly! That flexibility was one of my goals. Making integration smooth for both small embedded projects and larger codebases with unity builds — glad to hear it resonates.
I first encountered the idea relatively recently with Clay [1] and I have been a fan since. Once you get past the “huh, weird” stage it has a lot of benefits!
1: https://github.com/nicbarker/clay
Thanks! Yes, stb-style header-only libs were definitely an inspiration. I know some devs find the approach confusing, especially with linker errors if *_IMPLEMENTATION isn't handled correctly. I tried to keep it simple and clearly documented, but feedback like this helps improve it.
It's header-only in the sense that you cut everything that normally goes in the .c file and pasted it in the .h file.
Don't you get linker errors when a project includes this header twice in different translation units? If not, please explain how.
You're supposed to #define GIF_IMPLEMENTATION in only one of your .c files to prevent linker collisions. But yeah I don't get the point. How is this any better than the standard method of putting macros and data definitions in the .h and code in the .c? This is just going to confuse anyone who comes along later and wants to work on the code that uses this thing.
Totally fair — this pattern can be confusing at first glance. The main motivation is ease of integration: no need to manage extra .c files, no build system tweaks, just drop in one file and go. It’s especially useful for embedded systems, scripts, and small projects where build friction matters. That said, I agree that for larger teams or long-term projects, the classic .h + .c split can be clearer — that’s why the implementation can easily be separated if needed. Appreciate the feedback!
Looks like you are required to #define GIF_IMPLEMENTATION before #include "gif.h" in exactly one of your translation units.
At that point, what does header-only gain you in C (ie not C++)?
I've included many single .h/.c pair libraries before in my projects and given the of simplicity that was never a pain point.
people who have to support windows do this sometimes because MS has gone for almost forty years now without ever specifying a default directory where libraries go. This is in spite of the fact that being the creator of the OS, the most-popular compiler, and the SDK should in theory give them enormous leverage to dictate where dependencies get saved.
There's this bizarre cultural difference you see between people who learned to program on windows compared to people who learned to program on unix wherein the Windows crowd don't see the value of having an easily reproducible build system because. Usually this results in some combination of needlessly-complicated scripts and checking binary builds of dependencies into version-control.
Requiring you to include a header-file while also defining a specific constant in only one place that turns the header file into a c-file is actually one of the more benign workarounds you see.
Outside FOSS UNIX clones, most OSes, including commercial OSes, tend to have a more diversified ecosystem in compilers, and which directories those compilers take their libraries from.
Naturally people love to complain about Windows.
Also nowadays there is vcpkg and conan.
Been a good while since I worked with C/C++, but when I did it was on Windows.
As I recall I just added the files to the project, possibly configured a define or five, and then compiled.
Tedious when it's tons of directories, but a breeze with just a pair of files.
That said, I get that this buys you a bit of flexibility in build management.
Not learning about how compilers, linkers and library managers actually work.
Even C++, and considering templates, if you want to use external templates optimization you need implementation files, and then there are modules (already working in clang/VC++).
So you get a header only implementation by forcing all users to do something unexpected instead of having a single C file. Seems silly and not really the point of a header only implementation.
It's not that weird, and it's explained first thing in the header and shown in the example of how to use it. You do need to read how to use the thing, and this is a simpler detail than any of the function signatures you'll have to look at.
Personally I would probably add a gif.c to my project which does nothing but include the header with the define set, at least if I'm going to need a gif decoder in more than one place. Probably many (most?) projects only need this library in one file anyway, in which case I'd just include it from that file and be done.
Great question! It works the same way as stb-style libs: you only #define GIF_IMPLEMENTATION in one .c file (one translation unit). In all other files, you just #include "gif.h" without the define. The header uses #ifdef GIF_IMPLEMENTATION to include implementation code only once. So no linker errors — everything compiles cleanly as long as that rule is followed. I’ll make this clearer in the README too, thanks!
Probably it's better to mark every functions as static in a header-only library, not just those internal ones. But I think code bloat would still be an issue if we don't use LTO or other optims across compilation units.
edit: Yeah, defining *_IMPLEMENTATION appropriately would address these issues.
"ifdef GIF_IMPLEMENTATION"
I once did it for a closed-source CAM/CAE software. We wanted to generate high resolution and decent quality GIFs visualizing a progress of a numerical optimization in a few hundred animation frames. I wasn’t able to find a library which would deliver both reasonable size and good quality, so I made my own.
The trickiest part wasn’t the encoder; it’s computing the palette from RGB images. To minimize the output file size, I wanted a single palette shared by all frames.
The key piece of research was in that sample code from early 90-s https://www.ece.mcmaster.ca/~xwu/cq.c However, I had to rework it heavily because global variables and C language are too old school, also because FP32 precision is insufficient for the count of input pixels in my use case. 200 FullHD frames contain approximately 400M pixels, FP32 numbers don’t have the precision to accumulate that many of them. And the number is dangerously close to int32 limit, I have also upgraded the integer counters to int64.
This is very interesting that you did the visualization using a GIF. I have only generated mp4 videos for vidoes till now using ffmpeg and png images or through something equivalent. Was there any advantage of GIF that you found? Like may be it was easier to do on the fly or was just simple enough?
I believe the reason why management specifically asked for animated GIFs was compatibility. The GIF format is ancient and supported by everything, makes it trivial to share or embed these animation files.
Ignoring the compatibility, modern video codecs like h264 or h265 are substantially better than animated GIFs, in terms of both size and quality.
BTW I supported them as well. The only target platform of that software is modern versions of Windows. It only took couple pages of straightforward C++ because the OS includes a functional equivalent of libavcodec and libavformat libraries. Moreover, GPU drivers install and register the components to leverage the codecs implemented by hardware of these GPUs. The high-level API to encode compressed video files from a sequence of frames is MFCreateSinkWriterFromURL function.
How is this a header-only? It contains non-static, non-inline functions in the .h file...
I wonder if the README.md of this project has been generated by an LLM, or if LLMs output such READMEs mainly because of their training data and thus mistakenly gets identified as LLM-generated README. The two are not mutually exclusive I suppose.
I checked the code, it gives me "LLM vibes", too. FWIW, I am not against it. Perhaps the developer was using it here and there. Personally I do not care.
The use of the AI emoji ("Sparkles"), plus the "Example Projects" section containing no example projects, certainly doesn't help it beat the AI allegations.
It is a formally written README which is very usual in formal circle of communication, think proposal writing or papers etc. Outside, it is usual for people to do this when their primary exposure to English is through such channels or when they are not comfortable with having their personal style of talking be viewed by the public.
LLM is also similar in that sense, so it produces the same writing. It resists personal touch without being explicitly asked.
Whenever I tell an LLM to generate README.md for a project, it comes up with READMEs like this one, full of emojis (easy to generate README.md without them though).
No allocations, reminds me of WUFFS, which also comes with a GIF decoder: https://github.com/google/wuffs/blob/main/std/gif/decode_gif...
Why would you want another gif decoder, in C, in 2025? What's the point of cramming everything in a single file?
easier to build, easier to navigate, easier to integrate
ppl who ask qustions like this must have not worked much on codebases w/ nightmarish build setups, libraries like this are so refreshing/easier to work w/
Please share your thoughts.
How much was AI used to help create this?
Yes, I used ChatGPT to help refine the README and occasionally get suggestions for cleaner or more efficient code patterns.
But the core logic, turbo decoding modes, and embedded optimization — that’s all written, tested, and understood by me.
I see AI as a tool, not an author — it helps speed things up, but I still do the thinking.
Right for the throat. Brutal.
The readme just looks like it was written by AI, and the initial commit is the entire code. It just seems like AI was used at least somewhat. Just curious how much, if at all.
I submitted a link to a project[0] with similar characteristics a few days ago, before I realized it was probably entirely made by AI. That's what got me wondering this in the first place.
[0] https://news.ycombinator.com/item?id=44642557
I'm laughing so much right now, we live in truly hilarious (but also terrifying) times!
check op's post history you'll understand
It looks good, but I wanted to see a demo to see how it would all look in practice.
Okay, I'll do it soon.
[flagged]
Statistically so far 100% of header only C libraries that require you to define XXX_IMPLEMENTATION are fantastic, so this is probably a good library.