C++ Header style - c++

What's the preferred policy of header files in C++ projects: <test.h> or "test.h"?
In my experience I use:
#include <test_lib.h> to include C/C++ headers, third-part libraries (boost and etc.) which path specified in project settings.
#include "my_test.h" - it's used for headers files existing in project.
Any other practices can be applied here?
Is it ok to include header files with relative paths: like #include "../new_test.h"? Or is it better to move relative paths to project settings?

Angle brackets are use to include system headers. Theoretically, IIRC, they're not even necessarily files. In practice, <> means do not search current directory, only the include path, whereas "" means look in current directory and then search the include path.
As for relative paths, it probably depends on your environment, I'd suggest path relative to your project include path (as specified by -I).

This MSDN article explains how preprocessor searches for headers depending on the #include syntax form. Your style is good as Visual C++, Windows Framework, Boost and headers of other frameworks/packages are (usually) outside your project's directory.
Regarding your second question, my advice is to avoid relative paths. If you move around that header, you'll need to adjust that relative path by changing your code which is a bad idea. I'd rather put it within angle brackets and add path to it to /I option. E.g. you want to include C:\frameworks\frameworkA\include\a.h in your project, you can use #include <a.h> and \I "C:\frameworks\frameworkA\include"
It is maybe more descriptive if you add path to the framework root to /I and then put partial path to its header within angle brackets. E.g. #include <frameworkA\include\a.h> and /I "C:\frameworks". Now it's clear in the code that a.h belongs to frameworkA.
Use relative paths only for headers that are within your project's directory (e.g. if you organise code into modules which are in subdirectories of your project and which are not intended to be moved around).

You can use either. The <test.h> can be used by using the -I <directory containing test.h> option when compiling. In general, and this is a practice I follow, I tend to use <test.h> for all header files, irrespective of whether they are third-party header files or ones that I have written.
It might be a good idea to refrain from using relative paths "../test.h". From personal experience, this way of writing #include statements forces you to cement your directory structure. If you decided to move test.h tomorrow to a different directory, you would have to go into each one of the header files and change the relative path for test.h to the new path - a time consuming exercise. Better to shift this to the makefile (via -I) and then deal with it from there.

Related

How to include header files without quotation marks?

I'm kind of new to programming so please go easy on me. Anyways, I know about including header files that you, yourself, have defined. For example:
#include "yourHeader.h"
I'm trying to use FLTK for its GUI options, however, many of its header files include other header files using an include like this:
#include <FL/Blah.h>
instead of this:
#include "FL/Blah.h"
I would have to go every header file that has the include in angle brackets and change them to quotation marks for them to work. I am currently working in CodeBlocks right now, if that matters. Is there any way to include the header files using angle brackets instead of quotation marks, or am I stuck with having to go into the header files themselves and manually swapping them all out?
Generally, the header file from
#include "headerfile"
will searched in the current source path. If the search fails, it is reprocessed as if
#include <header file>
does.
Your FLTK library is using include like the following?
#include <FL/Blah.h>
The FL's parent path should be in the predefined INCLUDE path. You may edit you Makefile or project settings.
You can add the folder which contains all your headers to your include path while compiling.
How to add a default include path for GCC in Linux?
Some background
Ok there are two set of include search path.
The user include path:
This is usually only the current directory (also known as ".").
Note: It may be others but for simplicity lets just use "." in the examples below.
Then there is the system include path:
This is usually a few places in your machines (could be /usr/include and /usr/local/include).
Note: It may be others but for simplicity lets just assume these in the examples below.
How it usually works.
There are caveats and not all compilers work exactly the same. But the following are a good rules of thumb.
When you include a file using quotes "".
#include "yourHeader.h"
It will search for this file in all the directories specified in the "user include path". If it fails to find them there it will then look in all the directories specified by the "system include path". So your compiler will search for the following files:
./yourHeader.h
/usr/include/yourHeader.h
/usr/local/include/yourHeader.h
It will use the first one it finds.
When you use the <> in the include:
#include <FL/Blah.h>
It will search for the files in the "system include path" first. Then depending on your compiler may optionally search the "user include path" (but lets assume not for now).
So in this case it will search for the files:
/usr/include/FL/Blah.h
/usr/local/include/FL/Blah.h
It will use the first one it finds.
Modifying the Default
So these are the default paths that will be searched for a file. But your compiler will allow you to add extra paths to both of these search paths (usually). It depends on your compiler how to add search paths.
For gcc (and probably clang) it uses -I and -isystem (and probably more)
Expectations.
When you see <> in the include header it usually means this is an already installed library that you are looking for. So your code assumes that the FLTK library has already been installed on your machine.
When you see "" in the include header you should assume that it is a local file that belongs to the project.

Prefer location relative or include path path relative includes within your own library in C++

Whenever I start developing a new shared library in C++ I come across the same question:
Should I use includes relative to the position of the current file or includes relative to the (potential) include paths (-I) to refer to other header files within my project, i.e. the same library?
I checked with some of the library headers installed on my system.
boost appears to use includes relative to the include path and <>brackets to include other boost headers, i.e. #include <boost/move/move.hpp>
poppler on the other hand appears to use some weird relative paths with "", sometimes relative to the current location and sometimes relative to its base (I didn't even know that this works), .e.g. in fofi/FoFiEncodings.hthere is an #include "goo/gtypes.h" where fofi and goo are directories on the same level
many others simply include files with "" and their location relative paths, mainly files in the same directory
Does it depend on the directory structure (i.e. its complexity) of the shared library itself, i.e. location relative paths work well with simple layouts but have drawbacks with more cross references like in boost? Are there any technical reasons or pitfalls why one might work but the other doesn't (portability, compiler dependent behavior, ...)?
Boost uses brackets instead of quotes. This means that it isn't an absolute path, but that the search starts relative to the list of linclude directories that was provided to the compiler. So it's a variant of the relative path.
A really absolute path is a bad idea because if another developper installs the source code at another location, he/she'll not be able to compile unless he/she changes all the header references in the sources.
Edit:
If you develop a library that is general enough and designed to be shared across several (possibly unrelated) projects, the bracket option should be the preferred one. This lets you the freedom to install the library wherever you want, and also to switch libraries (different versions for different projects) very easily.
If you develop a more specific library in the context of a larger solution, mainly to isolate reusable code, the quoted relative path is an option. If later you want to reuse that library in another context, you would have to install its sources in the new solutions directory so that the relative paths still work. So the use case is a little different (narrow sharing and occasional reuse in the context of very specific projects).
In your source file, do whatever you want/prefer.
For public headers, relative path is the preferred way, as user might place your headers in a specific place and use not exactly the same include directive.
I mean, suppose that your hierarchy is:
lib/headers/sub1/h1.h
lib/headers/sub2/h2.h
lib/headers/lib.h
lib/src/..
with directive to set include path to lib,
user should do #include <headers/lib.h>, but then your lib.h should look like:
#include "headers/sub1/h1.h"
#include "headers/sub2/h2.h"
and sub1/h1.h to
#include "headers/sub2/h2.h"
With directive to set include path to lib/headers,
user should do #include <lib.h>, but then your lib.h should look like:
#include "sub1/h1.h"
#include "sub2/h2.h"
and sub1/h1.h to
#include "sub2/h2.h"
So depending of directive set by user, your code won't compile for user.
With relative path, for both above directives, your files would be identical
lib.h:
#include "sub1/h1.h"
#include "sub2/h2.h"
and sub1/h1.h to
#include "../sub2/h2.h"

Using (relative) paths to shortcut in include statements in C++

I started coding in C++ few days ago. I am using windows as my OS for writing code. I have been keeping all of my "well-written" codes in a single location. Now, I am working on a project that requires the use of those codes. So, I planned to include those files that I require as header files in my project. However, to make my project "self-contained", I created shortcuts of those folders that I require and kept them in the source folder of my new project and decided to use relative paths to the shortcuts in the "include" statements in my project.
However, I am getting an error. Is there any way to use relative (or, in general, absolute) paths to shortcuts in the include statements of C++ in windows?
Thanks.
It really depends on how you include the header files.
If you include with double-quotes, like e.g.
#include "some_header_file.h"
Then the relative path is from the current files location.
If you include using angle-brackets, like e.g.
#include <some_header_file.h>
Then the relative path is based on the system include paths.
You can always add a path to the system include path. How to do it depend on your environment and compiler. If you're using Visual Studio you go into the project properties dialog, and in the "C/C++" / "General" tab there is a field called "Additional Include Directories" where you can add directories. (This is for VS 2015, might be a little different on other versions.)
Regarding double quotes inclusion. Lets say your project hierarchy looks like this (on disk!):
Project
|-- Include
|-- Source
| `-- MoreSource
`-- Other
In Project/Source you have your source files, and if one of them want to include a header file from Project/Include, then it will look something like
#include "../Include/header.h"
Now if you have a source file in Project/Source/MoreSource that want to include the same header file it will be
#include "../../Include/header.h"
It could be useful to add the Project/Include directory to the system header search path. You can still use double-quotes to include the files, since if they are not found then the preprocessor will search the system paths as well, but you don't need the "full" relative path. If you add Project/Include to the system header path, you could write just
#include "header.h"
Or
#include <header.h>
Be careful though, if you have a header file with the same name as an actual system header file you might have some trouble.
From https://superuser.com/questions/253935/what-is-the-difference-between-symbolic-link-and-shortcut
You can't include folder shortcut since it's a file, not a folder.
You can read the guide to create symbolic link on windows.

C++ Organization on the File System

I come from a Java/AS3/Javascript background where all of my classes are organized into packages that help denote their functionality.
In starting a C++ project I sought to mimic this file system structure in mostly the same way but I've been running into issues with the includes.
Currently I have an src directory with the main.cpp file inside it. Then I have some root directories and with other files inside. Here's an example:
src
->main.cpp
->window
---->Window.h
---->Window.cpp
main.cpp includes Window.h with the statement #include "Window.h" and everything builds just fine. But if i restart Visual Studio, it complains that it can't find "Window.h".
In looking a open source projects, I've seen some that just have all the source files in one directory with no nesting for easy includes I suppose. Some have the headers and cpp files separated.
What is the correct way (or at least a way that will cause less headaches) to organize a large-ish C++ project on the file system?
Thanks!
Breaking it out like you've tried to do is reasonable and easy enough to accomplish.
You just need to set your project's include paths. From Visual Studio, right click on the project name and click "Properties". From there, in the tree control on the left hand side, expand "C/C++", and then select "General" in the tree. The first option on the right hand side should then be "Additional Include Directories".
There you have several options:
You can specify specific include directories (separated by semicolons). For instance, if you had folders "Window" and "Printing" you could put in:
..\Window;..\Printing
Which would allow you to include the files from window and printing easily, like this:
#include <Window.h> // from src/window
#include <Printing.h> // from src/printing
The above approach has some drawbacks, as you can easily collide with names from other libraries you may be using, making the include ORDER very important.
A better approach (in my opinion) is to add the following as an include path:
..\
This will make it search the parent directory when looking for includes. This allows you to be more verbose in your include paths, like this:
#include <Window/Window.h> // it's more clear where these are coming from
#include <Printing/Printing.h> // and much less likely to collide with other library
// header files
It makes sense to follow the Java example and arrange source files by C++ namespace. Create sub-folders under your /src directory that correspond to the namespaces.

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.