Include precedence <> vs "" for system libraries (Unix-like OSes)

[Kim Walisch]

Many system libraries offer a main header file in the root directory
e.g. /usr/include which then includes a few other headers located
inside a directory also installed in /usr/include. Below are a few
examples from my Linux box:

/usr/include/ruby.h
/usr/include/ruby

/usr/include/krb5.h
/usr/include/krb5

/usr/include/lzma.h
/usr/include/lzma

/usr/include/gssapi.h
/usr/include/gssapi

Now if you look inside the headers above some include their other
headers using <> while others use "", e.g.:

cat /usr/include/gssapi.h | grep include
#include <gssapi/gssapi.h>

cat /usr/include/ruby.h | grep include
#include "ruby/ruby.h"

The second version using "" seems more correct to me. I wonder if using
<> might potentially cause issues when 2 versions of the library are
installed e.g. one in /usr/include and another in /usr/local/include (
will the header inside /usr/include reference its other headers inside
/usr/local/include instead of /usr/include?).

So my question is: Are both (<> & "") uses safe or should one be
preferred over the other?

Thanks,
Kim


--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.moderated. First time posters: Do this! ]

[FredK]

The only difference between the two is that when using "" the compiler will
first look for the include file in the local directory in which the
compilation command is executed, then if it is not found will continue to
search in the system-dependent standard include path (except, of course,
this is all after searching in any directories named with -I flags on the
command line)

[James Kuyper]

On 10/26/2015 10:42 AM, Kim Walisch wrote:
>
> Many system libraries offer a main header file in the root directory
> e.g. /usr/include which then includes a few other headers located
> inside a directory also installed in /usr/include. Below are a few
> examples from my Linux box:
>
> /usr/include/ruby.h
> /usr/include/ruby
>
> /usr/include/krb5.h
> /usr/include/krb5
>
> /usr/include/lzma.h
> /usr/include/lzma
>
> /usr/include/gssapi.h
> /usr/include/gssapi

Keep in mind that not a single one of those files is a C++ standard
library header. Also keep in mind that the actual locations of those
files can vary from one computer to another, even on Unix-like systems,
to say nothing of other operating systems.

> Now if you look inside the headers above some include their other
> headers using <> while others use "", e.g.:
>
> cat /usr/include/gssapi.h | grep include
> #include <gssapi/gssapi.h>
>
> cat /usr/include/ruby.h | grep include
> #include "ruby/ruby.h"
>
> The second version using "" seems more correct to me. I wonder if using
> <> might potentially cause issues when 2 versions of the library are
> installed e.g. one in /usr/include and another in /usr/local/include (
> will the header inside /usr/include reference its other headers inside
> /usr/local/include instead of /usr/include?).
>
> So my question is: Are both (<> & "") uses safe or should one be
> preferred over the other?

The only thing required by the C++ standard is that there be an
implementation-defined list of locations that is searched when using
#include <file.h>, and a possibly different implementation-defined set
of locations that is searched when you use #include "file.h". The only
standard distinction between them is that if you use #include "file.h",
and the search fails, it then retries the search exactly as if you had
used #include <file.h>. Thus, #include <file.h> is a more tightly
constrained search than #include "file.h".

What this means depends upon how the implementation chooses to define
the search locations. But as a rule, I think you should use #include <>
only for C standard headers and operating-system headers, and #include
"" for all others. This is just my opinion - the standard says nothing
about that issue.
--
James Kuyper

[marlow...@googlemail.com]

On Monday, October 26, 2015 at 8:40:22 PM UTC, James Kuyper wrote:
> > So my question is: Are both (<> & "") uses safe or should one be
> > preferred over the other?

James sums it up very well:-

> The only thing required by the C++ standard is that there be an
> implementation-defined list of locations that is searched when using
> #include <file.h>, and a possibly different implementation-defined set
> of locations that is searched when you use #include "file.h". The only
> standard distinction between them is that if you use #include "file.h",
> and the search fails, it then retries the search exactly as if you had
> used #include <file.h>. Thus, #include <file.h> is a more tightly
> constrained search than #include "file.h".
>
> What this means depends upon how the implementation chooses to define
> the search locations.

[snip]
> --
> James Kuyper

I think the upshot of this is that it is yet another style issue, like tabs
versus spaces or the one true brace style. You can't say that one way is
better than another, only what the house style is. I have seen people argue
over which style is inherently superior to no avail. I must confess, I have
even started such arguments myself in the past. But I don't bother any more.
I just stick with the house style, whatever that is.


--

[James K. Lowden]

On Mon, 26 Oct 2015 08:42:13 CST
Kim Walisch <kim.w...@googlemail.com> wrote:

> cat /usr/include/gssapi.h | grep include
> #include <gssapi/gssapi.h>
>
> cat /usr/include/ruby.h | grep include
> #include "ruby/ruby.h"
>
> The second version using "" seems more correct to me.

....

> So my question is: Are both (<> & "") uses safe or should one be
> preferred over the other?

The use of <> is better. Using "" invites error, although you have to
work at it.

Traditionally the difference between <> and "" is whether or not the
current working directory of the compiler process is searched before
the regular search path is consulted. I can't find it documented in
cpp(1) for GNU, but that is (among other things) what happens. (While
cpp isn't used by c++, your question still holds for C if the files
could be used by a C compiler.)

I don't have ruby installed, but I can fake out my compiler:

$ cat ruby/ruby.h
#define ONE 1

$ printf '#include <ruby/ruby.h>\n' | cpp -dD | tail -3
<stdin>:1:23: fatal error: ruby/ruby.h: No such file or directory
compilation terminated.
....

$ printf '#include "ruby/ruby.h"\n' | cpp -dD | tail -3
# 1 "ruby/ruby.h" 1
#define ONE 1
# 1 "<stdin>" 2

If your project has a "ruby" directory, you can't have a file
"ruby/ruby.h" because ruby's own header file will read that file
instead of the intended one. If /usr/include/ruby.h had used <>
instead of "", your project directory would be excluded from the search
path. That is, your file could have both lines

#include <ruby.h>
#include "ruby/ruby.h"

with no conflict or ambiguity.

The usual use of "" is for include files that are specific to a project
and will never be installed to a standard location. On rare occasions,
"" might be used to override a standard include file, but I don't
remember the last time I did that. Nowadays the preprocessor/compiler
has many better command-line options for expressing the search path.

--jkl