Lessons learned about how to make a header-file library (2013)

I agree.

Unless it's out of necessity (C++ templates), all you're doing is killing my compilation time and I don't appreciate that.

(And really, if it's that hard to add a source file to your project, your build system probably needs help.)

The best way to be friendly to be developers who want to import your library, in my opinion, is to make it compile with all warnings enabled on common compilers.

I don't agree, header file libraries are great and the apparent advantage to header/source pair are negligible in practice (I use the STB headers all the time in different projects). One advantage is that you can simply add all the configuration defines (e.g. what assert macro and allocation functions to use, all the configuration options, ...) simply in front of the include statement and you don't need to mess around with the build system or compiler command line options to define those.

Of course you usually wrap the header-only-lib in a central header/source pair of your own, so that those configuration defines and the implementation are in a single place instead of directly including the library header in different places.

I think "don't make header file libraries" is a good assumption to have, but reality is - stb libraries are one of the best library set I ever used in C/C++ domain. They are small enough to avoid "messy and a nightmare to modify" and powerful enough to be a great replacement for more "bloated" libs.

For example I recently replaced libjpeg and libpng with one stb_image.h, it reduced 100kb of executable size, improved image loading speed by around 2x, reduced crashes on invalid image data for about 30% (we use american fuzzy lop fuzzer for testing).