> So what's the compelling reason to ship these as a single source file, instead of using the more logical and standard solution of a single header and a single source file?

C doesn't have a packaging format or dependency manager, so having to keep track of two files would be pretty cumbersome.

In general, STB-style headers simplify C/C++ build system shenanigans.

E.g. one benefit is that you can configure the implementation via preprocessor defines without the defines leaking into the build system. Just add the config defines in front of the implementation include.

It's also trivial to write "extension headers" which need to directly peek into the (otherwise private) implementation of the base library. Just include the extension header implementation after the base library implementation.

PS: but also see: https://github.com/nothings/stb#why-single-file-headers

> In general, STB-style headers simplify C/C++ build system shenanigans.

Too vague. How is it better, concretely?

> E.g. one benefit is that you can configure the implementation via preprocessor defines without the defines leaking into the build system

That's not a benefit. How is this:

   #define LIB_IMPLEMENTATION
   #define LIB_KNOB 123
   #include "lib.h"

Any better than the two-file version:

   #define LIB_KNOB 123
   #include "lib.c"

?

> It's also trivial to write "extension headers" which need to directly peek into the (otherwise private) implementation of the base library. Just include the extension header implementation after the base library implementation.

I'm not sure what this means. Can you give an example? Is this being used in the above library?

> PS: but also see: https://github.com/nothings/stb#why-single-file-headers

OK, that only offers this explanation:

> Why not two files, one a header and one an implementation? The difference between 10 files and 9 files is not a big deal, but the difference between 2 files and 1 file is a big deal. You don't need to zip or tar the files up, you don't have to remember to attach two files, etc.

This is kind of nonsense to me. The difference between 2 files and 1 file is barely relevant, and doesn't weigh against the awkwardness of having no clear distinction between declarations and definitions, and having to pull in definitions by setting a magic preprocessor header.

    > Any better than the two-file version:
    >    #define LIB_KNOB 123
    >    #include "lib.c"

See, now you have 3 files, the .h/.c file pair of the library, and your own implementation source file with the configuration which includes a .c file. How is this better than having two files?

> Too vague. How is it better, concretely?

I can only assume from that question that you haven't had the "pleasure" to work much with C/C++ build systems yet, at least when it comes to integrating 3rd party libraries.

Re. extension headers:

    #define IMPLEMENTATION
    #include "base_library.h"
    #include "extension_library.h"

Since the implementation of the base library is in the same compilation unit as the extension library, the extension library has direct access to the private implementation details of the base library without having to add a separate 'private but actually public API'.

> no clear distinction between declarations and definitions

STB-style libraries have this clear distinction, C++ style header-only libraries don't.

> See, now you have 3 files, the .h/.c file pair of the library, and your own implementation source file with the configuration which includes a .c file.

The third source file is what the library authors suggested; I'd just create a seperate Makefile target for the implementation, which is then linked into the binary. (Yes, that's an extra target, but that costs very little and allows you to avoid unnecessary rebuilds.)

Why don't you give me a concrete counterexample where the single-header-setup makes things simpler? If it's so obviously beneficial it shouldn't be so hard to come up with a concrete example.

> #define IMPLEMENTATION > #include "base_library.h" > #include "extension_library.h"

Thanks for explaining, but that doesn't really motivate having a single file, since you could just as easily do:

  #include "base_library.c"
  #include "extension_library.c"

And you've saved a line (and removed the need for obscure preprocessor macros).

> ... without having to add a separate 'private but actually public API'.

Personally, I'd say this is exactly the right way to model this, but even if you disagree: it sounds like this simplifies things mainly for the library/extension authors, and not the library users, because if the extension author forward-declares the implementation details they depend on, there is no additional file to manage for the users either.

> The difference between 2 files and 1 file is barely relevant,

To you. To me doing Rust stuff, it's been quite helpful to have single-file C programs; it makes it a lot easier to compile and link things.