Form of inclusion directive

From: Ed Brey (brey_at_[hidden])
Date: 2000-11-01 11:16:35

Currently, when a boost files includes a boost header, it generally makes
the reference via a directive of the form #include <boost/header.hpp>.

I propose that instead we use directives of the form #include "header.hpp".
There are a couple advantages to the approach:

1. Users are not required to make the outer boost directory a project-level
include directories.  I.e. a user could use code like this, if desired:

#include <3rdparty/boost/smart_ptr.hpp>

Granted, this is not a common scenario, but it allows boost to be used with
minimal intrusion, which may help in its initial acceptance by
Microsoft-corrupted individuals who are hesitant to make full use of the C++
language and worried about changing global settings from wizzer-generated
defaults.

2. It brings inclusion more parallel with namespace usage.  When a boost
class references another boost class, there is no boost:: preface, since we
are already in the boost namespace.  This emphasizes locality, which the
include directive should, too.  Unfortunately, IMHO, the standard doesn't
use something like #include <std/vector.hpp> for its include files, or we
would have a nice parallel with std::vector / <std/vector.hpp> and rational
/ "rational.hpp" (assuming vector and rational were used internally by
another boost class).

Even though the pairing doesn't fit for std, it does in principle for all
other libraries.  We don't see it in boost, since boost doesn't use any
libraries other than the standard one.  However, other libraries do, and
since boost will be used as an example to library writers, it would be nice
for it to set forth a good pattern for other libraries, like this:

#include <vector>
#include <boost/rational.hpp>
#include "something_in_mylib.hpp"
namespace mylib {
    ...  boost::rational  ...  something_in_mylib  ...
}

This works out nicely because it separates all internal and external
headers.  Internal headers get quotes; external headers get brackets.

The downside of this directive form would be if it caused the wrong file to
get included if the user happened to have a file named the same as a boost
header.  The Standard leaves a lot of include path decisions up to the
implementation, but it seems to make it pretty clear that what I propose
should work.  It specifies that when quotes are used, a search specific to
the quoted form performed, and then only if necessary, a search for the
bracketed form is performed.  This is a bit oversimplified, but the key
concept is that using the quotes provides an extra search opportunity that
comes first.  I can't think of any implementation that would makes sense
other than for that initial search to search the current directory, and then
possibly also the main project directory.  As long as the current directory
gets searched first, we're fine.  Can anyone think of a reason to be
concerned that an implementation might not do this?