5 ms·

Whoever maintains this needs to pay a bit closer attention to _how_ single-header libs are implemented. In particular, stuffing non-inline functions into .h is

by eps 6y ago

Whoever maintains this needs to pay a bit closer attention to _how_ single-header libs are implemented. In particular, stuffing non-inline functions into .h is, ultimately, a malpractice. Yes, you get to have a single .h, but you end up creating an instance of each function for every .c that includes this .h. Example - https://github.com/tronkko/dirent/blob/master/include/dirent.h https://github.com/tronkko/dirent/blob/master/include/dirent...

rsaarelm 6y ago
That's why you wrap the function implementations in an #ifdef and instruct the library user to set the corresponding define in exactly one place, like the list maintainer does in his own single header libraries: https://github.com/nothings/stb/blob/b42009b3b9d4ca35bc703f5310eedc74f584be58/stb_image.h#L4-L13 https://github.com/nothings/stb/blob/b42009b3b9d4ca35bc703f5...
- eps 6y ago
  Sure, that's an option.
  - jb1991 6y ago
    It’s not just an option, that’s how most header only libraries are explicitly created.
    - eps 6y ago
      I don't disagree. My top comment was that if you are maintaining a list of single-header libs, might also pay attention to whether they are implemented properly.
    - spacechild1 6y ago
      I haven't used a single C++ header-only library which required a #define. But that's because in C++ the "inline" keyword creates a weak symbol, so you can #include a header in several places and there will only ever be a single implmentation. For function templates this happens automatically, btw. IMO, if you need a #define like this, you're are not really writing a header-only library, that's basically just a source file in disguise. You could just as well distribute headers + a single source file and just ask the user to add this one source file to their build system (which should really be a trivial task). EDITED for more clarity about C vs C++.
      - mmm_grayons 6y ago
        Also, while it's easier to just include another header file, it can have a pretty serious impact on build times. If you compare the same program with header-only libraries to one with libraries using the normal header declaration/source definition split, it's much faster. I never worried about this too much in C, but C++ takes long enough to build as it is. <grumble> As a sidenote, I remember my brain hurting when I learned about C++ just redefining `inline`. It would have made much more sense to just define a new keyword. </grumble>
        spacechild1 6y ago
        Personally, I think people should only do C++ header-only libraries if technically necessary (e.g. heavy reliance on templates). Otherwise it just unnecessarily hurts compile times, as you've correctly noted, because the compiler still has to parse all those "inline" functions.
mariusor 6y ago
Sorry for speaking out of turn here, but the author, Sean Barrett, is a pretty well known figure in the game industry and his stb_X libraries are used _a lot_ in the indie game dev circles. I would bet they are aware of most of the reasons that you might come up for why single file libs are not good, and yet they authored a bunch of them. As another poster remarked in this discussion, he has a good overview for how to create a robust single header library: https://github.com/nothings/stb/blob/master/docs/stb_howto.txt https://github.com/nothings/stb/blob/master/docs/stb_howto.t... If you can offer some good arguments against those, instead of generic dogma, then we can have a discussion. :)
- eps 6y ago
  His own libraries are implemented correctly. If you can first understand the point of a comment, instead of not understanding it, the we can indeed have a discussion.
  - mariusor 6y ago
    Probably you should clarify what you mean in the top post. I still can't see anything but a dig on why single header libraries are wrong. Apologies if that's not the case.
    - spacechild1 6y ago
      I think OP was quite clear. They didn't say that single header libraries are wrong per se, but that it's bad practice to not declare functions in headers as inline, because it can cause accidental code duplication. EDIT: I see now that this advice is only valid for C++, where the "inline" keyword creates a weak symbol. I forgot that this doesn't work in C. Anyway, the #define trick is only necessary for C, in C++ you would simply declare all functions as "inline" (which automatically happens for function templates, btw)
      - ludocode 6y ago
        Minor nitpick, but inline and weak are not the same thing. Weak linkage is a property that is resolved by the dynamic linker (at runtime startup); inline linkage is a property that is resolved by the static linker (at compile-time linking.) GCC calls inline "vague linkage" and it only uses weak linkage if the platform does not have COMDAT support: https://gcc.gnu.org/onlinedocs/gcc/Vague-Linkage.html https://gcc.gnu.org/onlinedocs/gcc/Vague-Linkage.html
dvfjsdhgfv 6y ago
But this is precisely what #ifndef is for.
- eps 6y ago
  Look at the linked code.
deleted 6y ago
[deleted]
tom_ 6y ago
The readme includes a disclaimer that covers exactly this sort of case: "I have not personally verified that any specific lilbrary is as advertised, or is quality software."

by eps 6y ago

rsaarelm 6y ago

That's why you wrap the function implementations in an #ifdef and instruct the library user to set the corresponding define in exactly one place, like the list maintainer does in his own single header libraries: https://github.com/nothings/stb/blob/b42009b3b9d4ca35bc703f5310eedc74f584be58/stb_image.h#L4-L13 https://github.com/nothings/stb/blob/b42009b3b9d4ca35bc703f5...

eps 6y ago
Sure, that's an option.
- jb1991 6y ago
  It’s not just an option, that’s how most header only libraries are explicitly created.
  - eps 6y ago
    I don't disagree. My top comment was that if you are maintaining a list of single-header libs, might also pay attention to whether they are implemented properly.
  - spacechild1 6y ago
    I haven't used a single C++ header-only library which required a #define. But that's because in C++ the "inline" keyword creates a weak symbol, so you can #include a header in several places and there will only ever be a single implmentation. For function templates this happens automatically, btw. IMO, if you need a #define like this, you're are not really writing a header-only library, that's basically just a source file in disguise. You could just as well distribute headers + a single source file and just ask the user to add this one source file to their build system (which should really be a trivial task). EDITED for more clarity about C vs C++.
    - mmm_grayons 6y ago
      Also, while it's easier to just include another header file, it can have a pretty serious impact on build times. If you compare the same program with header-only libraries to one with libraries using the normal header declaration/source definition split, it's much faster. I never worried about this too much in C, but C++ takes long enough to build as it is. <grumble> As a sidenote, I remember my brain hurting when I learned about C++ just redefining `inline`. It would have made much more sense to just define a new keyword. </grumble>
      - spacechild1 6y ago
        Personally, I think people should only do C++ header-only libraries if technically necessary (e.g. heavy reliance on templates). Otherwise it just unnecessarily hurts compile times, as you've correctly noted, because the compiler still has to parse all those "inline" functions.

mariusor 6y ago

Sorry for speaking out of turn here, but the author, Sean Barrett, is a pretty well known figure in the game industry and his stb_X libraries are used _a lot_ in the indie game dev circles. I would bet they are aware of most of the reasons that you might come up for why single file libs are not good, and yet they authored a bunch of them. As another poster remarked in this discussion, he has a good overview for how to create a robust single header library: https://github.com/nothings/stb/blob/master/docs/stb_howto.txt https://github.com/nothings/stb/blob/master/docs/stb_howto.t... If you can offer some good arguments against those, instead of generic dogma, then we can have a discussion. :)

eps 6y ago
His own libraries are implemented correctly. If you can first understand the point of a comment, instead of not understanding it, the we can indeed have a discussion.
- mariusor 6y ago
  Probably you should clarify what you mean in the top post. I still can't see anything but a dig on why single header libraries are wrong. Apologies if that's not the case.
  - spacechild1 6y ago
    I think OP was quite clear. They didn't say that single header libraries are wrong per se, but that it's bad practice to not declare functions in headers as inline, because it can cause accidental code duplication. EDIT: I see now that this advice is only valid for C++, where the "inline" keyword creates a weak symbol. I forgot that this doesn't work in C. Anyway, the #define trick is only necessary for C, in C++ you would simply declare all functions as "inline" (which automatically happens for function templates, btw)
    - ludocode 6y ago
      Minor nitpick, but inline and weak are not the same thing. Weak linkage is a property that is resolved by the dynamic linker (at runtime startup); inline linkage is a property that is resolved by the static linker (at compile-time linking.) GCC calls inline "vague linkage" and it only uses weak linkage if the platform does not have COMDAT support: https://gcc.gnu.org/onlinedocs/gcc/Vague-Linkage.html https://gcc.gnu.org/onlinedocs/gcc/Vague-Linkage.html

dvfjsdhgfv 6y ago

But this is precisely what #ifndef is for.

eps 6y ago
Look at the linked code.

deleted 6y ago

[deleted]

tom_ 6y ago

The readme includes a disclaimer that covers exactly this sort of case: "I have not personally verified that any specific lilbrary is as advertised, or is quality software."