include boost header file using "" or <> - c++

Why does tuple documentation say to use, for example:
#include "boost/tuple/tuple.hpp"
and not
#include <boost/tuple/tuple.hpp>
I know that it's not probable my code will have a file called "boost/tuple/tuple.hpp",
but using include <> states explicitly not to look in the curent directory.
So what is the reason?

Using <> does not mean "don't look in the current directory" - It means look in an implementation defined place and then look somewhere else, also implementation defined. Either, both or neither of these could be the current directory. This is one of the more useless bits of the C++ standard.

The historical meaning of <somefile> is to look in the system-standard places. With "somefile" it means look in the current directory, plus some other places.

Afaik the reason is to differentiate between headers that belong to an application and those which are from external libraries. I can't say why they have not used this convention. It is a only a convention and not a rule.
Perhaps someone should raise this issue with the Boost maintainers?

Use <...> for boost. This is not Your code. Unless your code is boost.
Use "...." for your header files, which you inevitably have in every C++ program. This is for the reader, not for the compiler.

From msdn:
Quoted form
This form instructs the preprocessor
to look for include files in the same
directory of the file that contains
the #include statement, and then in
the directories of any files that
include (#include) that file. The
preprocessor then searches along the
path specified by the /I compiler
option, then along paths specified by
the INCLUDE environment variable.
Angle-bracket form
This form instructs the preprocessor
to search for include files first
along the path specified by the /I
compiler option, then, when compiling
from the command line, along the path
specified by the INCLUDE environment
variable.

Are you asking what the difference between the two styles of inclusion is, or for Boost's rationale? Since others have spoken regarding the difference, I'll just add my take on the latter issue:
I don't believe either is more correct, in general. It depends on how your project is structured with respect to its dependencies. For example, in my projects I typically include the relevant bits of Boost, et cetera, in a subdirectory of the project and thus tend to prefer the #include "" form. If you want to pick up the Boost installation from a more global location, you'd prefer the #include <> form.

Related

Why does Xcode 6 incorrectly include from user path before system path?

I'm trying to build a project I have done for Windows, Visual Studio under OSX using Xcode 6.1.1.
I'm running into an issue where in a file that needs to include #include <string.h>. However, in the same folder as the file that does this there is also a file that is named string.h.
Under my Visual Studio project this still resolves file, the system paths are searched first.
In the Xcode project I have made sure to set up my own paths under "User Header Search Paths" - Xcode expand to the correct path. I also set "Always Search User Paths" to No - which according to the docs says that the system paths should be searched first:
https://developer.apple.com/library/mac/documentation/DeveloperTools/Reference/XcodeBuildSettingRef/1-Build_Setting_Reference/build_setting_ref.html#//apple_ref/doc/uid/TP40003931-CH3-SW110
But yet the #include <string.h> seem to be treated as #include "string.h" for some reason.
The config is defined in the project and I've made sure the targets doesn't override this.
Is this some Xcode/OSX thing where system includes <> search the path of the including file first?
My local string.h file is located at ruby/api/string.h relative to the include path in my User Header Search Path.
Results of https://gist.github.com/thomthom/034b539bede38dd68261:
https://gist.github.com/thomthom/034b539bede38dd68261
The paths searched to satisfy an #include directive and the order in which they are searched are implementation defined. That includes whether any user-specified include paths (if even supported) are searched before, after, or instead of any default paths.
That's the case for both forms of #include directive. In particular, although it is common for implementations to perform some kind of relative search to find a file specified using the double-quoted include syntax, C does not require that. It requires only that if the implementation-defined mechanism used for resolving double-quoted includes fails, the compiler must fall back on the implementation-defined method used for resolving angle-bracketed includes.
Moreover, C specifies behavior only for the case that the given header name uniquely identifies a file to include. Depending on how one construes "uniquely", one might claim that C does not define any behavior at all in the situation you describe, on the basis that you have not uniquely identified the header you want to include. That's a bit wild, though -- I think it's better to interpret "uniquely" in light of the implementation-defined method for locating headers.
Your best bet is to avoid header names that collide with standard header names. One version of that would be to put them in a subdirectory that will lend its name as a prefix. For example, put string.h in src/myapp/, and include it as
#include "myapp/string.h"
To make that as safe as possible, ensure that directory src/ is in the include search path.
Upon viewing your gist I noticed a discrepancy from your screenshot:
HEADER_SEARCH_PATHS = /Users/thomas/SourceTree/SUbD/SUbD/../ThirdParty/include/ruby/mac /Users/thomas/SourceTree/SUbD/SUbD/../ThirdParty/include/ruby/mac/universal-darwin12.5.0
This should be:
HEADER_SEARCH_PATHS = /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include
Have same issue with file <assert.h> in Xcode 13.4.
I fixed by set "No" for build setting "Search Paths" > "Use Header Maps".
Maybe help someone.

C++ include with full path

I find #include "../app/thing.h" very ugly and I would like to be able to import from the main root of my project, like this:
#include <project/app/submodule/thing.h>
(I know <> is generally used for external but I find it very cleaner)
How can I do that, from anywhere in my project?
You simply need to ensure that your build process sets an option to specify the starting point of the search.
For example, if your header is in:
/work/username/src/project/app/submodule/thing.h
then you need to include (assuming a POSIX-compliant compiler; AFAICR, even MSVC uses /I as the analogue of -I):
-I/work/username/src
as one of the compiler options. You can use that path from anywhere in your project since it is absolute. You just need a defined way for your build system to know what the setting should be, so that when it is moved to /home/someone/src/, you have only one setting to change.
See this answer for a more complete explanation about how the differences between the two formats work. Honestly, though, I think you might want to consider restructuring your folder hierarchy if you need to jump up a folder then jump into another folder to get something. Generally speaking, it's pretty common practice to keep all files local to your program local to each other in the folder structure (i.e. in the same folder), and all files that aren't local, but may be needed (such as header files for libraries used) in a sub-folder within the main program folder, or to include them at compile time.
It is important to note that in the answer I linked above, it explains that "<>" includes are IMPLEMENTATION DEPENDENT, so we'd really need to know what compiler you're using to tell you if you could or couldn't do that.
You can simply use the include directories option of your current compiler (-I usually) to achieve this.
Also note using the "" double quotes will just add to fallback for the compiler standard headers. Files included using the <>, are only guaranteed to search files from the compiler standard headers.

are longer #include paths ever actually needed?

For example, if I had a file called foo.h, can I always just include it by doing:
#include "foo.h"
or do I sometimes have to do something like:
#include "bar/foobar/foo.h"
EDIT - are they simply used to make the compile time shorter by limiting the search for the file?
Basically, you can pass include paths as options to the C++ compiler, but it won't look for the file recursively. If you pass in the path /opt/include and do "#include "foo.h", it will _ only_ find /opt/include/foo.h, not /opt/include/dummy/foo.h.
In other words, either you pass every possible include path on the command line, or pass the root in and "navigate" by using the #include "dummy/foo.h"
Edit: #MatthieuM. made another good point below, #include "mylibrary/api.h"makes it much clearer which include file you're using than just #include "api.h", especially if you're using multiple libraries.
The compiler isn't going to recursively search your source directory. If you want to use #include "foo.h", you'll need to compile with -Ibar/foobar to tell the compiler it should look in bar/foobar for header files.
Otherwise, you'll have to use the full (relative) path. I tend to prefer this over -I, because it makes the source more independent from compiler flags (which you'll appreciate when changing between build systems).
There may be cases where there are multiple header files with the same name - in this case, a path helps to disambiguate.
I think it depends of your project settings, for example you have section like "Additional Include Directories" in Visual C++ so IDE will also search files in these directories.
The first statement #include "foo.h" will search for foo.h in the current working directory or in the directories mentioned under additional include directories.
If your header file is in some other path you need to explicitly mention it.

Difference between <include.hpp> and "include.hpp" [duplicate]

This question already has answers here:
What is the difference between #include <filename> and #include "filename"?
(30 answers)
Closed 8 years ago.
I am new to C++.
What is the difference between including the c++ header files using "" and <>
I am trying to use some of the header files form an open source library. All header files in that library are included using <>. Now when I do the same in my header file, its failing at compile time.
<> looks firstly in the header path for the header file whereas "" looks firstly in the current directory of the file for the header.
The distinction is very largely implementation defined; the "..." form
should look first in the place where the file which includes it is
situated; the <...> no. Beyond that, both look in an implementation
defined list of places, with the additional requirement that if the
compiler doesn't find a "..." form in any of the expected places, it
reprocesses the include as if it were a <...> form.
In practice, all of the compilers I know build a list of places using
the -I or /I options, followed by a number of "standard" and
compiler defined places. This list is for <...>; "..." is searched
in the same directory as the including file, then treated as a <...>.
(Some compilers, at least, also have options to add to the list for
"...".)
I'm not sure what's happening with regards to the library. Normally,
when using a third party library, you have to add one or more -I or
/I options to tell the compiler where to find its headers. Once
you've done that, both your code and the library code should find all of
the necessary headers. The one case I can think of where an include
might work in a library header, and not in your own headers, is a
"..." style include in a library header which was included from
another library header, using a path specifier, e.g.:
LibraryFile1.hpp:
#include "Subdir/LibraryFile2.hpp"
LibraryFile2.hpp:
#include "LibraryFile3.hpp"
You will have told the compiler to look for the headers (using a -I
option) in something like LibraryRoot/include, which is where
LibraryFile1.hpp is located; LibraryFile2.hpp is relative to this
location, and in LibraryFile2.hpp, the compiler finds
LibraryFile3.hpp because it is in the same directory as the file which
includes it. If you try to include LibraryFile3.hpp directly,
however, the compiler won't find it.
File includes between <> are looked for in your compiler's path, whereas "" is looking relatively to your current directory (or absolute if you specify a path that starts with / or c:\ but this is not recommended)
On Unix systems, by default the path contains /usr/include. This path may be completed by adding -Isome_directory for it to search in it.
For example, if you have your file test.c and you want to include include/test.h, you have different choices:
Write #include "include/test.h", which will look relatively from the directory of the compiled file.
Write #include <test.h>, but this time you will need to specify -Iinclude to the compiler to add the ./include directory to the compiler's path.
Note, however, that some compilers accept the "" notation for lookups in the path, but that always confused me and is a bad thing to do.
The quotes mean include from local folder and the <> mean to include from another directory specified using a flag to g++ or MSVC or whatever compiler you are using or system headers.
<> looks in the default directory for include files, "" looks in the current directory and than in the default directory
This question is a duplicate of Question 21593. None of the above answers above are totally correct. Like many programmers, I have used the informal convention of using the "myApp.hpp" form for application specific files, and the form for library and compiler system files, i.e. files specified in /I and the INCLUDE environment variable. However, the C standard states that the search order is implementation specific.
Here's the msdn explanation copied here for your convenience).
Quoted form
The preprocessor searches for include files in this order:
1. In the same directory as the file that contains the #include statement.
2. In the directories of the currently opened include files, in the reverse order in which
they were opened. The search begins in the directory of the parent include file and
continues upward through the directories of any grandparent include files.
3. Along the path that's specified by each /I compiler option.
4. Along the paths that are specified by the INCLUDE environment variable.
Angle-bracket form
The preprocessor searches for include files in this order:
1. Along the path that's specified by each /I compiler option.
2. When compiling occurs on the command line, along the paths that are specified by the INCLUDE
environment variable.
Including a file using <> will tell the compiler to look for those files in environment-defined inclusion folders. Those folders can be standard system folders, or defined by your Makefile if you use one, etc. Using "", the compiler will look for inclusion files only in the source file's path.
So you can use "" and use absolute paths or the path which is relative to the source file you try to include in, or you can use <> after defining your inclusion folders, and just specify the name of the header file to include.
IMHO, the second option is better, especially if you use a lot of headers, or multiple libraries, etc...
To define inclusion folders at compilation time : gcc -I ... (man gcc!)

C++ #include semantics

This is a multiple question for the same pre-processing instruction.
1 - <> or "" ?
Apart from the info found in the MSDN:
#include Directive (C-C++)
1.a: What are the differences between the two notations?
1.b: Do all compilers implement them the same way?
1.c: When would you use the <>, and when would you use the "" (i.e. what are the criteria you would use to use one or the other for a header include)?
2 - #include {TheProject/TheHeader.hpp} or {TheHeader.hpp} ?
I've seen at least two ways of writing includes of one's project headers.
Considering that you have at least 4 types of headers, that is:
private headers of your project?
headers of your project, but which are exporting symbols (and thus, "public")
headers of another project your module links with
headers of a compiler or standard library
For each kind of headers:
2.a: Would you use <> or "" ?
2.b: Would you include with {TheProject/TheHeader.hpp}, or with {TheHeader.hpp} only?
3 - Bonus
3.a: Do you work on project with sources and/or headers within a tree-like organisation (i.e., directories inside directories, as opposed to "every file in one directory") and what are the pros/cons?
After reading all answers, as well as compiler documentation, I decided I would follow the following standard.
For all files, be them project headers or external headers, always use the pattern:
#include <namespace/header.hpp>
The namespace being at least one directory deep, to avoid collision.
Of course, this means that the project directory where the project headers are should be added as "default include header" to the makefile, too.
The reason for this choice is that I found the following information:
1. The include "" pattern is compiler-dependent
I'll give the answers below
1.a The Standard
Source:
C++14 Working Draft n3797 : https://isocpp.org/files/papers/N3797.pdf
C++11, C++98, C99, C89 (the section quoted is unchanged in all those standards)
In the section 16.2 Source file inclusion, we can read that:
A preprocessing directive of the form
#include <h-char-sequence> new-line
searches a sequence of implementation-defined places for a header identified uniquely by the specified sequence between the < and > delimiters, and causes the replacement of that directive by the entire contents of the header. How the places are specified or the header identified is implementation-defined.
This means that #include <...> will search a file in an implementation defined manner.
Then, the next paragraph:
A preprocessing directive of the form
#include "q-char-sequence" new-line
causes the replacement of that directive by the entire contents of the source file identified by the specified sequence between the " delimiters. The named source file is searched for in an implementation-defined manner. If this search is not supported, or if the search fails, the directive is reprocessed as if it read
#include <h-char-sequence> new-line
with the identical contained sequence (including > characters, if any) from the original directive.
This means that #include "..." will search a file in an implementation defined manner and then, if the file is not found, will do another search as if it had been an #include <...>
The conclusion is that we have to read the compilers documentation.
Note that, for some reason, nowhere in the standards the difference is made between "system" or "library" headers or other headers. The only difference seem that #include <...> seems to target headers, while #include "..." seems to target source (at least, in the english wording).
1.b Visual C++:
Source:
http://msdn.microsoft.com/en-us/library/36k2cdd4.aspx
#include "MyFile.hpp"
The preprocessor searches for include files in the following order:
In the same directory as the file that contains the #include statement.
In the directories of any previously opened include files in the reverse order in which they were opened. The search starts from the directory of the include file that was opened last and continues through the directory of the include file that was opened first.
Along the path specified by each /I compiler option.
(*) Along the paths specified by the INCLUDE environment variable or the development environment default includes.
#include <MyFile.hpp>
The preprocessor searches for include files in the following order:
Along the path specified by each /I compiler option.
(*) Along the paths specified by the INCLUDE environment variable or the development environment default includes.
Note about the last step
The document is not clear about the "Along the paths specified by the INCLUDE environment variable" part for both <...> and "..." includes. The following quote makes it stick with the standard:
For include files that are specified as #include "path-spec", directory searching begins with the directory of the parent file and then proceeds through the directories of any grandparent files. That is, searching begins relative to the directory that contains the source file that contains the #include directive that's being processed. If there is no grandparent file and the file has not been found, the search continues as if the file name were enclosed in angle brackets.
The last step (marked by an asterisk) is thus an interpretation from reading the whole document.
1.c g++
Source:
https://gcc.gnu.org/onlinedocs/cpp/Header-Files.html
https://gcc.gnu.org/onlinedocs/cpp/Include-Syntax.html
https://gcc.gnu.org/onlinedocs/cpp/Include-Operation.html
https://gcc.gnu.org/onlinedocs/cpp/Invocation.html
https://gcc.gnu.org/onlinedocs/cpp/Search-Path.html
https://gcc.gnu.org/onlinedocs/cpp/Once-Only-Headers.html
https://gcc.gnu.org/onlinedocs/cpp/Wrapper-Headers.html
https://gcc.gnu.org/onlinedocs/cpp/System-Headers.html
The following quote summarizes the process:
GCC [...] will look for headers requested with #include <file> in [system directories] [...] All the directories named by -I are searched, in left-to-right order, before the default directories
GCC looks for headers requested with #include "file" first in the directory containing the current file, then in the directories as specified by -iquote options, then in the same places it would have looked for a header requested with angle brackets.
#include "MyFile.hpp"
This variant is used for header files of your own program. The preprocessor searches for include files in the following order:
In the same directory as the file that contains the #include statement.
Along the path specified by each -iquote compiler option.
As for the #include <MyFile.hpp>
#include <MyFile.hpp>
This variant is used for system header files. The preprocessor searches for include files in the following order:
Along the path specified by each -I compiler option.
Inside the system directories.
1.d Oracle/Sun Studio CC
Source:
http://docs.oracle.com/cd/E19205-01/819-5265/bjadq/index.html
Note that the text contradict itself somewhat (see the example to understand). The key phrase is: "The difference is that the current directory is searched only for header files whose names you have enclosed in quotation marks."
#include "MyFile.hpp"
This variant is used for header files of your own program. The preprocessor searches for include files in the following order:
The current directory (that is, the directory containing the “including” file)
The directories named with -I options, if any
The system directory (e.g. the /usr/include directory)
#include <MyFile.hpp>
This variant is used for system header files. The preprocessor searches for include files in the following order:
The directories named with -I options, if any
The system directory (e.g. the /usr/include directory)
1.e XL C/C++ Compiler Reference - IBM/AIX
Source:
http://www.bluefern.canterbury.ac.nz/ucsc%20userdocs/forucscwebsite/c/aix/compiler.pdf
http://www-01.ibm.com/support/docview.wss?uid=swg27024204&aid=1
Both documents are titled "XL C/C++ Compiler Reference" The first document is older (8.0), but is easier to understand. The second is newer (12.1), but is a bit more difficult to decrypt.
#include "MyFile.hpp"
This variant is used for header files of your own program. The preprocessor searches for include files in the following order:
The current directory (that is, the directory containing the “including” file)
The directories named with -I options, if any
The system directory (e.g. the /usr/vac[cpp]/include or /usr/include directories)
#include <MyFile.hpp>
This variant is used for system header files. The preprocessor searches for include files in the following order:
The directories named with -I options, if any
The system directory (e.g. the /usr/vac[cpp]/include or /usr/include directory)
1.e Conclusion
The pattern "" could lead to subtle compilation error across compilers, and as I currently work both on Windows Visual C++, Linux g++, Oracle/Solaris CC and AIX XL, this is not acceptable.
Anyway, the advantage of "" described features are far from interesting anyway, so...
2. Use the {namespace}/header.hpp pattern
I saw at work (i.e. this is not theory, this is real-life, painful professional experience) two headers with the same name, one in the local project directory, and the other in the global include.
As we were using the "" pattern, and that file was included both in local headers and global headers, there was no way to understand what was really going on, when strange errors appeared.
Using the directory in the include would have saved us time because the user would have had to either write:
#include <MyLocalProject/Header.hpp>
or
#include <GlobalInclude/Header.hpp>
You'll note that while
#include "Header.hpp"
would have compiled successfully, thus, still hiding the problem, whereas
#include <Header.hpp>
would not have compiled in normal circonstances.
Thus, sticking to the <> notation would have made mandatory for the developer the prefixing of the include with the right directory, another reason to prefer <> to "".
3. Conclusion
Using both the <> notation and namespaced notation together removes from the pre-compiler the possibility to guess for files, instead searching only the default include directories.
Of course, the standard libraries are still included as usual, that is:
#include <cstdlib>
#include <vector>
I typically use <> for system headers and "" for project headers. As for paths, that is only neccessary if the file you want is in a sub-directory of an include path.
for example, if you need a file in /usr/include/SDL/, but only /usr/include/ is in your include path, then you could just use:
#include <SDL/whatever.h>
Also, keep in mind that unless the path you put starts with a /, it is relative to the current working directory.
EDIT TO ANSWER COMMENT: It depends, if there is only a few includes for a library, I'd just include it's subdirectory in the include path, but if the library has many headers (like dozens) then I'd prefer to just have it in a subdir that I specify. A good example of this is Linux's system headers. You use them like:
#include <sys/io.h>
#include <linux/limits.h>
etc.
EDIT TO INCLUDE ANOTHER GOOD ANSWER: also, if it is conceivable that two or more libraries provide headers by the same name, then the sub-directory solution basically gives each header a namespace.
To quote from the C99 standard (at a glance the wording appears to be identical in the C90 standard, but I can't cut-n-paste from that):
A preprocessing directive of the form
# include "q-char-sequence" new-line
causes the replacement of that
directive by the entire contents of
the source file identified by the
specified sequence between the "
delimiters. The named source file is
searched for in an
implementation-defined manner. If this
search is not supported, or if the
search fails, the directive is
reprocessed as if it read
# include <h-char-sequence> new-line
with the identical contained sequence
(including > characters, if any) from
the original directive.
So the locations searched by #include "whatever" is a super-set of the locations searched by #include <whatever>. The intent is that the first style would be used for headers that in general "belong" to you, and the second method would be used for headers that "belong" to the compiler/environment. Of course, there are often some grey areas - which should you use for Boost headers, for example? I'd use #include <>, but I wouldn't argue too much if someone else on my team wanted #include "".
In practice, I don't think anyone pays much attention to which form is used as long as the build doesn't break. I certainly don't recall it ever being mentioned in a code review (or otherwise, even).
I'll tackle the second part of your question:
I normally use <project/libHeader.h> when I am including headers from a 3rd party. And "myHeader.h" when including headers from within the project.
The reason I use <project/libHeader.h> instead of <libHeader.h> is because it's possible that more than one library has a "libHeader.h" file. In order to include them both you need the library name as part of the included filename.
1.a: What are the differences between the two notations?
"" starts search in the directory where C/C++ file is located. <> starts search in -I directories and in default locations (such as /usr/include). Both of them ultimately search the same set of locations, only the order is different.
1.b: Do all compilers implement them the same way?
I hope so, but I am not sure.
1.c: When would you use the <>, and when would you use the "" (i.e. what are the criteria you would use to use one or the other for a header include)?
I use "" when the include file is supposed to be next to C file, <> in all other cases. IN particular, in our project all "public" include files are in project/include directory, so I use <> for them.
2 - #include {TheProject/TheHeader.hpp} or {TheHeader.hpp} ?
As already pointed out, xxx/filename.h allows you to do things like diskio/ErrorCodes.h and netio/ErrorCodes.h
* private headers of your project?
Private header of my subsystem in project. Use "filename.h"
Public header of my subsystem in project (not visible outside the project, but accessible to other subsystems). Use or , depending on the convention adapted for the project. I'd rather use
* headers of your project, but which are exporting symbols (and thus, "public")
include exactly like the users of your library would include them. Probably
* headers of another project your module links with
Determined by the project, but certainly using <>
* headers of a compiler or standard library
Definitely <>, according to standard.
3.a: Do you work on project with sources and/or headers within a tree-like organisation (i.e., directories inside directories, as opposed to "every file in one directory") and what are the pros/cons?
I do work on a structured project. As soon as you have more than a score of files, some division will become apparent. You should go the way the code is pulling you.
If I remember right.
You use the diamond for all libraries that can be found in your "path". So any library that is in the STL, or ones that you have installed. In Linux your path is usually "/usr/include", in windows I am not sure, but I would guess it is under "C:\windows".
You use the "" then to specify everything else. "my_bla.cpp" with no starting directory information will resolve to the directory your code is residing/compiling in. or you can also specify the exact location of your include with it. Like this "c:\myproj\some_code.cpp"
The type of header doesn't matter, just the location.
Re <> vs "". At my shop, I'm very hands-off as far as matters of "style" are concerned. One of the few areas where I have a requirement is with the use of angle brackets in #include statements -- the rule is this: if you are #including an operating system or compiler file, you may use angle brackets if appropriate. In all other cases, they are forbidden. If you are #including a file written either by someone here or a 3rd party library, <> is forbidden.
The reason is this: #include "x.h" and #include don't search the same paths. #include will only search the system path and whatever you have -i'ed in. Importantly, it will not search the path where the file x.h is located, if that directory isn't included in the search path in some other way.
For example, suppose you have the following files:
c:\dev\angles\main.cpp
#include "c:\utils\mylib\mylibrary.h"
int main()
{
return 0;
}
c:\utils\mylib\mylibrary.h
#ifndef MYLIB_H
#define MYLIB_H
#include <speech.h>
namespace mylib
{
void Speak(SpeechType speechType);
};
#endif
c:\utils\mhlib\speech.h
#ifndef SPEECH_H
#define SPEECH_H
namespace mylib
{
enum SpeechType {Bark, Growl};
};
#endif
This will not compile without changing the path either by setting the PATH environment variable or -i'ing in the c:\utils\mhlib\ directory. The compiler won't be able to resove #include <speech.h> even though that file is in the same directory as mylibrary.h!
We make extensive use of relative and absolute pathnames in #include statements in our code, for two reasons.
1) By keeping libraries and components off the main source tree (ie, putting utility libraries in a special directory), we don;t couple the lifecycle of the library to the lifecycle of the application. This is particularly important when you have several distinct products that use common libraries.
2) We use Junctions to map a physical location on the hard drive to a directory on a logical drive, and then use a fully-qualified path on the logical drive in all #includes. For example:
#include "x:\utils\mylib.h" -- good, x: is a subst'ed drive, and x:\utils points to c:\code\utils_1.0 on the hard drive
#include "c:\utils_1.0\mylib.h" -- bad! the application tha t#includes mylib.h is now coupled to a specific version of the MYLIB library, and all developers must have it on the same directory on thier hard drive, c:\utils_1.0
Finally, a broad but difficult to achieve goal of my team is to be able to support 1-click compiles. This includes being able to compile the main source tree by doing nothing more than getting code from source control and then hitting 'compile'. In particular, I abhor having to set paths & machine-wide #include directories in order to be able to compile, because every little additional step you add to the set-up phase in buildign a development machine just makes it harder, easier to mess up, and it takes longer to get a new machine up to speed & generating code.
There are two primary differences between <> and "". The first is which character will end the name - there are no escape sequences in header names, and so you may be forced to do #include <bla"file.cpp> or "bla>file.cpp". That probably won't come up often, though. The other difference is that system includes aren't supposed to occur on "", just <>. So #include "iostream" is not guaranteed to work; #include <iostream> is. My personal preference is to use "" for files that are part of the project, and <> for files that aren't. Some people only use <> for standard library headers and "" for all else. Some people even use <> only for Boost and std; it depends on the project. Like all style aspects, the most important thing is to be consistent.
As for the path, an external library will specify the convention for headers; e.g. <boost/preprocessor.hpp> <wx/window.h> <Magic++.h>. In a local project, I would write all paths relative to the top-level srcdir (or in a library project where they are different, the include directory).
When writing a library, you may also find it helpful to use <> to differentiate between private and public headers, or to not -I the source directory, but the directory above, so you #include "public_header.hpp" and "src/private_header.hpp". It's really up to you.
EDIT: As for projects with directory structures, I would highly recommend them. Imagine if all of boost were in one directory (and no subnamespaces)! Directory structure is good because it lets you find files easier, and it allows you more flexibility in naming ("module\_text\_processor.hpp" as opposed to "module/text\_processor.hpp"). The latter is more natural and easier to use.
I use <...> from system header file (stdio, iostreams, string etc), and "..." for headers specific to that project.
We use #include "header.h" for headers local to the project and #include for system includes, third party includes, and other projects in the solution. We use Visual Studio, and it's much easier to use the project directory in a header include, this way whenever we create a new project, we only have to specify the include path for the directory containing all the project directories, not a separate path for each project.