2

I'm maintaining a small C library; let's call it libfoo. It has quite a few users (actually it's complicated - it's the main fork of a highly popular library which has been abandoned); and it sports a spiffy CMake-based build mechanism. My repo directory structure is:

<root>
  |
  +--- src
  |     |
  |     + foo.h
  |     |
  |     + foo.c
  |
  ... other stuff

And when it's installed, the structure is: m. My library directory structure is:

<root>
  |
  +--- include
  |     |
  |     + foo.h
  |     
  +--- lib
  |     |
  |     + foo.a (or foo.so, never mind)
  |
  ... other stuff

Now, one of my users is telling me: "I want to be able to include your library's include file by writing #include <foo/foo.h>, not #include "foo.h" or #include <foo.h>, and your layout is not letting me do that. You should fix it!"

My question: Should I? Or rather, is this enough of strong convention, or a legitimate need, for it to be a justifiable expectation from me?

4
  • 1
    It seems as if your library only requires a single header file. In this case, there is no real difference between "foo/foo.h" and "foo.h". Can you ask the user for reasons why he needs this specific layout? Changing the include path breaks the library for other users, so there must be strong reasons for doing so.
    – pschill
    Nov 22, 2021 at 11:43
  • @pschill: I have asked them, and am waiting for their response. But I suspect that in my specific case it's because glibc has a non-standard header file with the same name as mine (printf.h). But my question is more general.
    – einpoklum
    Nov 22, 2021 at 11:48
  • Add a softlink as include/foo/foo.h to ../foo.h. ;-) Nov 22, 2021 at 21:18
  • @einpoklum: so the library name is printflib, and your user wants you to use it by writing #include <printf/printf.h>, is that correct?
    – Doc Brown
    Nov 23, 2021 at 6:17

3 Answers 3

7

Picking out some reasonably well known C libraries:

  • Expat uses #include <expat.h>
  • Glib uses #include <glib.h>
  • Jansson uses #include <jansson.h>
  • SQLite uses #include <sqlite3.h>

On the other hand, GTK, which is very much part of the same family as Glib, uses #include <gtk/gtk.h> so this isn't universal - but I think you can certainly say that it isn't a particularly strong convention.

4

There are two reasons for using an additional subdirectory for include files:

  1. Avoiding potential naming collisions

  2. You want to be prepared for the case when the lib may offer more than one include file in the future, without breaking backwards compatibility

If, however,

  • one can pick a sufficiently unique name for the main include which makes name collisions unlikely, and

  • the intention ist to avoid more than one include files, for ease-of-use, at least over the next few years,

then using an additional subdirectory is pointless.

3

Given your recent comment:

But I suspect that in my specific case it's because glibc has a non-standard header file with the same name as mine (printf.h).

I'd think including your header as #include <foo/foo.h> would be better. Without that, you're conflicting with a somewhat commonly-used header file that isn't going to change.

But my question is more general.

In general, someone's going to complain either way so there's no real general answer, hence my "Add a softlink..." comment above.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.