include paths - is there a defacto standard?

[Ole Nielsby]

The standard doesn't define this but what conventions do projects use?

As I understand it,

#include <somelibrary.h>

is used for including system headers and those of frameworks such
as wxWidgets - and

#include "someheader.h"

is used for more application-specific things.

The VC8 docs say, #include <...> searches the paths set for the
project, but #include "..." tries the dir of the file with the include,
and the file that included it etc... before it searches the project
setting include paths.

Is this a defacto standard, or do compilers implement different
ways of doing it? Is there a sort of minimal conventions programmers
stick to to be compiler-independent?

 

[Ivan Vecerina]

message : The standard doesn't define this but what conventions do projects use?
:
: As I understand it,
:
: #include <somelibrary.h>
:
: is used for including system headers and those of frameworks such
: as wxWidgets - and
:
: #include "someheader.h"
:
: is used for more application-specific things.
:
: The VC8 docs say, #include <...> searches the paths set for the
: project, but #include "..." tries the dir of the file with the
include,
: and the file that included it etc... before it searches the project
: setting include paths.
:
: Is this a defacto standard, or do compilers implement different
: ways of doing it? Is there a sort of minimal conventions programmers
: stick to to be compiler-independent?

The only thing defined in the standard is that "..." first searches
for a file in some (user-defined) locations and then, if not successful,
searches the same locations as for <...>.

In practice, most compilers I know handle "..." in a similar fashion
as VC8: looking for paths relative to the currently processed file.
But there is no guarantee that other compilers will do the same.

I knew some projects/guidelines that required exclusive use of <...>
and proper specification of search paths in compiler invocation.

I personally use <...> for all 'absolute' files/paths referring to
(usually external) libraries, and "..." for (relative path) references
to files within the same module.

I think that this can be left as a stylistic choice...

 

[James Kanze]

The standard doesn't define this but what conventions do projects use?

As I understand it,

#include <somelibrary.h>

is used for including system headers and those of frameworks such
as wxWidgets - and

#include "someheader.h"

is used for more application-specific things.

The VC8 docs say, #include <...> searches the paths set for the
project, but #include "..." tries the dir of the file with the include,
and the file that included it etc... before it searches the project
setting include paths.

Is this a defacto standard, or do compilers implement different
ways of doing it?

It seems pretty much the usual convention. I'm not sure that
other compilers try the directories of all of the including
files, however: most of the time, I think, it is the directory
of the file which does the include, then treat it like a <...>.
All of the compilers I know apply the /I or -I options to the
<...> (and thus implicitly to the "...", since the "..." uses
the <...> paths if it doesn't find the code locally). I think
some compilers have additional options which only apply to the
"..." form, as well. And of course, the only thing the standard
really says is that if the search with the "..." form fails, the

Is there a sort of minimal conventions programmers stick to to
be compiler-independent?

The usual convention seems to work well in practice: system
headers, and anything you assimulate to system headers, use
<...>, other headers use "...". You'll probably find some
variation as to what is assimulated to system headers, however:
some places will include not only third party libraries, like
wxWidgets, but also lower level in house libraries which are
used in many different projects, where as others may not even
consider major third party libraries, limiting <...> to those
libraries furnished with the compiler or bundled with the OS.

In general, I wouldn't worry about it too much, except to ensure
that local headers use "...".

 

[webinfinite]

It seems pretty much the usual convention. I'm not sure that
other compilers try the directories of all of the including
files, however: most of the time, I think, it is the directory
of the file which does the include, then treat it like a <...>.
All of the compilers I know apply the /I or -I options to the
<...> (and thus implicitly to the "...", since the "..." uses
the <...> paths if it doesn't find the code locally). I think
some compilers have additional options which only apply to the
"..." form, as well. And of course, the only thing the standard
really says is that if the search with the "..." form fails, the


The usual convention seems to work well in practice: system
headers, and anything you assimulate to system headers, use
<...>, other headers use "...". You'll probably find some
variation as to what is assimulated to system headers, however:
some places will include not only third party libraries, like
wxWidgets, but also lower level in house libraries which are
used in many different projects, where as others may not even
consider major third party libraries, limiting <...> to those
libraries furnished with the compiler or bundled with the OS.

In general, I wouldn't worry about it too much, except to ensure
that local headers use "...".

--
James Kanze (GABI Software) email:[email protected]
Conseils en informatique orientée objet/
Beratung in objektorientierter Datenverarbeitung
9 place Sémard, 78210 St.-Cyr-l'École, France, +33 (0)1 30 23 00 34

Correct me if I am wrong. My understanding is that <...> will include
the system defined path. "..." will search the user defined path where
you use -I to specify if you are using UNIX.

 

[Andre Kostur]

Correct me if I am wrong. My understanding is that <...> will include
the system defined path. "..." will search the user defined path where
you use -I to specify if you are using UNIX.

All of the compilers that I've used will apply the -I directories to both
<> and "" includes.

 

[Alf P. Steinbach]

* Andre Kostur:

All of the compilers that I've used will apply the -I directories to both
<> and "" includes.

Don't know if it has been mentioned, but the standard's guarantee is
that "..." applies some extra initial searching, then if that fails
applies the same search as <...>. The initial extra search for "..." is
unspecified but typically in the directory of the including file. ++,
depending on the compiler etc.

Cheers, & hth.,

- Alf

 

[James Kanze]

* Andre Kostur:

Don't know if it has been mentioned, but the standard's
guarantee is that "..." applies some extra initial searching,
then if that fails applies the same search as <...>. The
initial extra search for "..." is unspecified but typically in
the directory of the including file. ++, depending on the
compiler etc.

I mentionned it, but it certainly bears repeating: if <...> will
find the file, so will "...". (G++ has a deprecated option
which will violate this rule---don't use it. IIRC, g++ used to
have an option which only affected "...", but I can't find it
anywhere in the documentation; perhaps I'm confusing it with
another compiler.)

I might add that when generating dependencies, g++ has an option
to only consider the files included by "..." in the generated
dependencies. This sounds like the basis of a good rule to me:
use "..." if you want the file to be considered in the
dependencies, <...> if you don't. (You typically don't want the
system headers in your dependency checking, since this
significantly increases make times for nothing.)

 

[Ben Pfaff]

I might add that when generating dependencies, g++ has an option
to only consider the files included by "..." in the generated
dependencies.

I believe that you are mistaken, for recent versions of GCC.
From the GCC 4.1 manual:

`-MM'
Like `-M' but do not mention header files that are found in system
header directories, nor header files that are included, directly
or indirectly, from such a header.

This implies that the choice of angle brackets or double quotes in
an `#include' directive does not in itself determine whether that
header will appear in `-MM' dependency output. This is a slight
change in semantics from GCC versions 3.0 and earlier.

(GCC 3.0 is 6 years old.)

 

[James Kanze]

I believe that you are mistaken, for recent versions of GCC.
From the GCC 4.1 manual:

`-MM'
Like `-M' but do not mention header files that are found in system
header directories, nor header files that are included, directly
or indirectly, from such a header.

This implies that the choice of angle brackets or double quotes in
an `#include' directive does not in itself determine whether that
header will appear in `-MM' dependency output. This is a slight
change in semantics from GCC versions 3.0 and earlier.

So it would seem. I was looking at two different versions of
g++ when I wrote this: the latest, but also 2.95.3 (trying to
find the option to add a directory to the path only for <...>,
which I thought was there at one time), and apparently got
confused about them.

IMHO, this is a step backwards, since it no longer allows the
project to define what it considers "system". In addition to
the standard headers, for example, we use Posix, Sybase and
Reuteurs (and maybe some other stuff I'm not aware of).
Conceptually, they're all "system" for us, and it would be
preferable not to consider them when generating dependencies.
Presumable, g++ doesn't consider the Posix headers (which are in
/usr/include), but would consider the Sybase and Reuteurs
headers (which are all somewhere under /tools in our
systems)---and if the installation installed the Sybase and
Reuteurs headers under /usr/include, g++ would act differently.
(What about /usr/local/include? I have the impression that a
lot of Linux system software installs its headers there. And a
lot of Linux non-system software installs them under
/usr/include.)

 

[mojmir]

The usual convention seems to work well in practice: system
headers, and anything you assimulate to system headers, use
<...>, other headers use "...".
...
In general, I wouldn't worry about it too much, except to ensure
that local headers use "...".

What about order of includes? I met cases where the inclusion
order was important so that the user had to be very careful.

Is there any general advice like
1. inclusion of system headers
2. inclusion of standard library headers
3. inclusion of framework headers
4. inclusion of local headers
etc.?

Thanks,
Mojmir

 

[Jim Langston]

What about order of includes? I met cases where the inclusion
order was important so that the user had to be very careful.

Is there any general advice like
1. inclusion of system headers
2. inclusion of standard library headers
3. inclusion of framework headers
4. inclusion of local headers
etc.?

Thanks,
Mojmir

Personally, that's pretty much the way I always do it. I include the system
headers at the top, any 3rd party headers under those, and my headers at hte
bottom.

As for system headers/standard library headers, I tend to put stl headers at
the top.

 

[James Kanze]

Personally, that's pretty much the way I always do it. I
include the system headers at the top, any 3rd party headers
under those, and my headers at hte bottom.

There is one important exception. In the .cc files which
implement a specific header, that header should always be
included first.

As for system headers/standard library headers, I tend to put
stl headers at the top.

I tend to put each group in alphabetical order (simply because
it's the easiest order to automate.)