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?

einpoklum
  • 2,478
  • 1
  • 13
  • 30
  • 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 '21 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 '21 at 11:48
  • Add a softlink as `include/foo/foo.h` to `../foo.h`. ;-) – Andrew Henle Nov 22 '21 at 21:18
  • @einpoklum: so the library name is `printflib`, and your user wants you to use it by writing `#include `, is that correct? – Doc Brown Nov 23 '21 at 06:17

3 Answers3

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.

Philip Kendall
  • 22,899
  • 9
  • 58
  • 61
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.

Doc Brown
  • 199,015
  • 33
  • 367
  • 565
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.

Andrew Henle
  • 357
  • 2
  • 4