The #include directive
jacob navia
I added the following. I hope I got the essentials corect. Note that this is a
tutorial, i.e. should be easy on the user...
Note that the standard says nothing about directories, so it is of no
help here.
1.34.1.6 The include directive
This directive instructs the preprocessor to read a file from disk and include its
text into the current position. All the text of the file is inserted into the compiler
input stream and preprocessed just as if you would have written exactly all that text
in the current position.
This directive has two variants:
The first uses angle brackets to enclose the name of the file to include.
#include <stdio.h>
The second uses quotes to enclose the file name:
#include "myfile.h"
The first one means that the preprocessor should look for the file in the system
include directory, where the files furnished by the implementation are stored.
The second means that the preprocessor looks first in the current directory for
the mentioned file. Note that the current directory starts as the one where the
first source file is stored, the one that the compiler receives as a parameter
when invoked. Of course, this can change later if you include a file in another
directory.
For instance:
You have a file in the current directory that has an include directive like:
#include "myincludes/decls.h"
And within decls.h you have an include directive like
#include "stddecls.h"
The preprocessor starts looking for stddecls.h in "myincludes", not in the
original directory.
Michael Tsang
Hash: SHA1
jacob navia wrote:
The standard just says that the search method is "implementation-defined",
i.e. not mandated by the standard. By convention. <> files are found in the
system include directories and "" files are found in the directory the same
as the including file.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
iEYEARECAAYFAktcLboACgkQm4klUUKw07BuxQCfRq9HdGk3zup9ru+OIOJWRQH7
IGkAniZCnkyPFWoI9npjgNQRHCySo9kh
=X4rF
-----END PGP SIGNATURE-----
Flash Gordon
> I have just noticed that I forgot to include an explanation of that in
> my tutorial.
> I added the following. I hope I got the essentials corect. Note that
> this is a
> tutorial, i.e. should be easy on the user...
>
> Note that the standard says nothing about directories, so it is of no
> help here.
I think you've gone slightly too much in to the way the compiler works
rather than the way it seems to the users...
> 1.34.1.6 The include directive
> This directive instructs the preprocessor to read a file from disk and
> include its
> text into the current position. All the text of the file is inserted
> into the compiler
> input stream and preprocessed just as if you would have written exactly
> all that text
> in the current position.
The user does not need to be told it is "from disk" or about input
streams etc...
This directive instructs the compiler to include the contents of the
specified file[1] as if you had simply typed the contents at that point
in the source file.
Footnote 1: System includes need not actually be files, but the effect
is always the same.
> This directive has two variants:
> The first uses angle brackets to enclose the name of the file to include.
> #include <stdio.h>
> The second uses quotes to enclose the file name:
> #include "myfile.h"
>
> The first one means that the preprocessor should look for the file in
> the system
> include directory, where the files furnished by the implementation are
> stored.
That should probably be more like, "furnished by the implementation and
system libraries", since on *nix it certainly often includes other
optional library headers.
> The second means that the preprocessor looks first in the current
> directory for
> the mentioned file. Note that the current directory starts as the one
> where the
> first source file is stored, the one that the compiler receives as a
> parameter
> when invoked. Of course, this can change later if you include a file in
> another
> directory.
I would slightly re-word the above...
The second means that the compiler first looks include files provided by
you. With lcc-win32 this means first looking in the current directory...
> For instance:
> You have a file in the current directory that has an include directive
> like:
> #include "myincludes/decls.h"
I assume somewhere you have already mentioned that / can be used as a
directory seperator, since as you know on DOS/Windows people tend to use \
> And within decls.h you have an include directive like
> #include "stddecls.h"
> The preprocessor starts looking for stddecls.h in "myincludes", not in the
> original directory.
It's important to state up front the handling of directories is specific
to lcc-win32, since I don't think all compilers do this. Hence my
earlier suggestion of saying, "With lcc-win32 this means...". I.e. don't
belabor the point, just mention it when you start on the bits which are
implementation defined.
I've also changed to saying compiler rather than preprocessor, since
generally the user does not care, but you can obviously say preprocessor
if that is more consistent with the rest of your tutorial.
--
Flash Gordon
Eric Sosman
> [...]
> This directive has two variants:
> The first uses angle brackets to enclose the name of the file to include.
> #include <stdio.h>
> The second uses quotes to enclose the file name:
> #include "myfile.h"
... and the third of the two is described in 6.10.2p4.
After macro substitution it must resolve to one of the other
two forms, so the third form might be considered "transitory"
or "evanescent" or something, but it deserves at least a
footnote.
--
Eric Sosman
eso...@ieee-dot-org.invalid
jacob navia
True I forgot that one.
Thanks
jacob navia
>
> The user does not need to be told it is "from disk" or about input
> streams etc...
>
> This directive instructs the compiler to include the contents of the
> specified file[1] as if you had simply typed the contents at that point
> in the source file.
>
> Footnote 1: System includes need not actually be files, but the effect
> is always the same.
>
True, you are right. I changed that.
[snip]
> It's important to state up front the handling of directories is specific
> to lcc-win32, since I don't think all compilers do this. Hence my
> earlier suggestion of saying, "With lcc-win32 this means...". I.e. don't
> belabor the point, just mention it when you start on the bits which are
> implementation defined.
>
I thought all compilers do this, even if it is not defined in the standard.
> I've also changed to saying compiler rather than preprocessor, since
> generally the user does not care, but you can obviously say preprocessor
> if that is more consistent with the rest of your tutorial.
Well, the chapter is called "Inside the preprocessor", so it is OK.
Flash Gordon
> Flash Gordon a �crit :
>>
>> The user does not need to be told it is "from disk" or about input
>> streams etc...
>>
>> This directive instructs the compiler to include the contents of the
>> specified file[1] as if you had simply typed the contents at that
>> point in the source file.
>>
>> Footnote 1: System includes need not actually be files, but the effect
>> is always the same.
>
> True, you are right. I changed that.
> [snip]
That's good. Note I was suggesting as a footnote, rather than in the
main body, for explaining the system headers.
>> It's important to state up front the handling of directories is
>> specific to lcc-win32, since I don't think all compilers do this.
>> Hence my earlier suggestion of saying, "With lcc-win32 this means...".
>> I.e. don't belabor the point, just mention it when you start on the
>> bits which are implementation defined.
>
> I thought all compilers do this, even if it is not defined in the standard.
I think there are subtleties in the way the subdirectories are sometimes
handled, certainly enough that I would completely trust it. You could
say "With lcc-win32 and most other compilers...", or "With most
compilers including lcc-win32..."
In any case, I've seen headers which do not assume quite the same method
of handling directories. I.e. headers in a directory named foo which
include each other as foo/bar.h rather than assuming the directory foo
will be searched.
>> I've also changed to saying compiler rather than preprocessor, since
>> generally the user does not care, but you can obviously say
>> preprocessor if that is more consistent with the rest of your tutorial.
>
> Well, the chapter is called "Inside the preprocessor", so it is OK.
Yes, I agree, in context that makes sense.
--
Flash Gordon
Nick
> jacob navia wrote:
>> Flash Gordon a écrit :
>>>
>>> It's important to state up front the handling of directories is
>>> specific to lcc-win32, since I don't think all compilers do
>>> this. Hence my earlier suggestion of saying, "With lcc-win32 this
>>> means...". I.e. don't belabor the point, just mention it when you
>>> start on the bits which are implementation defined.
>>
>> I thought all compilers do this, even if it is not defined in the standard.
>
> I think there are subtleties in the way the subdirectories are
> sometimes handled, certainly enough that I would completely trust
> it. You could say "With lcc-win32 and most other compilers...", or
> "With most compilers including lcc-win32..."
>
> In any case, I've seen headers which do not assume quite the same
> method of handling directories. I.e. headers in a directory named foo
> which include each other as foo/bar.h rather than assuming the
> directory foo will be searched.
I've used C compilers on systems where there aren't even directories as
people commonly think of them. Partioned Data Sets for example.
--
Online waterways route planner | http://canalplan.eu
Plan trips, see photos, check facilities | http://canalplan.org.uk
jacob navia
>
> I've used C compilers on systems where there aren't even directories as
> people commonly think of them. Partioned Data Sets for example.
OK. Either
(1) You have separate name spaces for files (i.e. "directories")
(2) You don't. In that case there is only ONE namespace and it
doesn't make any sense to write
#include "subdir/foo.h"
and the problem doesn't even appear.
What it would be interesting is to see if some compiler in a
system where there are name spaces does NOT implement the schema
I mentioned.
Keith Thompson
[...]
> This directive has two variants:
> The first uses angle brackets to enclose the name of the file to include.
> #include <stdio.h>
> The second uses quotes to enclose the file name:
> #include "myfile.h"
>
> The first one means that the preprocessor should look for the file
> in the system include directory, where the files furnished by the
> implementation are stored. The second means that the preprocessor
> looks first in the current directory for the mentioned file. Note
> that the current directory starts as the one where the first source
> file is stored, the one that the compiler receives as a parameter
> when invoked. Of course, this can change later if you include a file
> in another directory.
#include "myfile.h" typically looks in the current directory (though
this isn't required), but it can also search in other places.
Many (most?) compilers have a "-I" option, or something similar,
that lets you specify which directories to search. gcc, for example,
can also use any of several environment variables to control this.
So "myfile.h" might be found in a project-specific directory, not
necessarily the current directory. This lets you, for example,
store ".h" and ".c" files in separate directories.
Your tutorial doesn't necessary need to repeat everything the standard
says, but you should definitely refer to the standard while writing
it.
--
Keith Thompson (The_Other_Keith) ks...@mib.org <http://www.ghoti.net/~kst>
Nokia
"We must do something. This is something. Therefore, we must do this."
-- Antony Jay and Jonathan Lynn, "Yes Minister"
Eric Sosman
> Flash Gordon<sm...@spam.causeway.com> writes:
>> [...]
>> In any case, I've seen headers which do not assume quite the same
>> method of handling directories. I.e. headers in a directory named foo
>> which include each other as foo/bar.h rather than assuming the
>> directory foo will be searched.
>
> I've used C compilers on systems where there aren't even directories as
> people commonly think of them. Partioned Data Sets for example.
An oddity I once encountered had to do with what "the
same directory" meant. On this system (VMS), it was possible
to construct a file name that incorporated a kind of search
path: You'd instruct the compiler to look for included files
in PATH, where PATH was defined (externally to the compiler)
as A, B, C, ... When processing #include "foo.h", the compiler
would look for A:foo.h, B:foo.h, C:foo.h, ... and use the first
foo.h that it found. Syntactically and conceptually, this PATH
construct was just part of the name of "the" directory.
The oddity came up when foo.h contained #include bar.h.
One compiler would look for PATH:bar.h, that is, for A:bar.h
then B:bar.h then C:bar.h. Another, having found B:foo.h (say),
would search only for B:bar.h. Both strategies were defensible
as searching in "the same" directory (indeed, both compilers
described their searches that way), yet the outcomes differed.
If you had the files A:bar.h and B:bar.h, and B:foo.h included
"bar.h", on compiler got A:bar.h and the other got B:bar.h.
Both compilers claimed that they searched "the same" directory,
and both were arguably right.
(Why were we using these PATH things, anyhow? The idea
was that B: was the read-only "committed" version of all the
source files, and A: contained just the sources you'd checked
out and modified. When compiling in the PATH directory, you'd
get the A: versions of the files you were actively working with
and the "reference" B: versions of whatever you hadn't touched.
Disks were smaller and more expensive in those days; the prospect
of copying twelve thousand or so source files onto a local disk
just so you could change two of them and recompile was not
attractive.)
--
Eric Sosman
eso...@ieee-dot-org.invalid
Ersek, Laszlo
> On 1/24/2010 12:05 PM, Nick wrote:
>> I've used C compilers on systems where there aren't even directories as
>> people commonly think of them.
I've immediately thought of OpenVMS when reading this. I remember
#include <sys/socket.h> and #include <socket.h> working the same way.
>
> An oddity I once encountered had to do with what "the
> same directory" meant. On this system (VMS), it was possible
> to construct a file name that incorporated a kind of search
> path: You'd instruct the compiler to look for included files
> in PATH, where PATH was defined (externally to the compiler)
> as A, B, C, ... When processing #include "foo.h", the compiler
> would look for A:foo.h, B:foo.h, C:foo.h, ... and use the first
> foo.h that it found. Syntactically and conceptually, this PATH
> construct was just part of the name of "the" directory.
>
> The oddity came up when foo.h contained #include bar.h.
> One compiler would look for PATH:bar.h, that is, for A:bar.h
> then B:bar.h then C:bar.h. Another, having found B:foo.h (say),
> would search only for B:bar.h.
This is funny because my usenet client is "ANU News - V6.2.0
(23-Jun-1997)", running on ludens.elte.hu:
ludens$ show sys/noproc
OpenVMS V8.3 on node LUDENS 24-JAN-2010 22:17:16.74 Uptime 242 16:37:08
I might have found what you describe (very long citation, sorry):
ludens$ help cc /incl
----v----
CC
/INCLUDE_DIRECTORY
/INCLUDE_DIRECTORY=(place[,...])
[...]
For the quoted form, the search order is:
1. One of the following:
o If /NESTED_INCLUDE_DIRECTORY=INCLUDE_FILE (the default) is
in effect, search the directory containing the file in
which the #include directive itself occurred. The meaning
of "directory containing" is: the RMS "resultant string"
obtained when the file in which the #include occurred was
opened, except that the filename and subsequent components
are replaced by the default file type for headers (".H", or
just "." if /ASSUME=NOHEADER_TYPE_DEFAULT is in effect).
The "resultant string" will not have translated any
concealed device logical.
o If /NESTED_INCLUDE_DIRECTORY=PRIMARY_FILE is in effect,
search the default file type for headers using the context
of the primary source file. This means that just the file
type (".H" or ".") is used for the default file-spec but,
in addition, the chain of "related file-specs" used to
maintain the sticky defaults for processing the next
top-level source file is applied when searching for the
include file.
o If /NESTED_INCLUDE_DIRECTORY=NONE is in effect, this entire
step (Step 1) is bypassed.
2. Search the places specified in the /INCLUDE_DIRECTORY
qualifier, if any. A place that can be parsed successfuly as
an OpenVMS file-spec and that does not contain an explicit file
type or version specification is edited to append the default
header file type specification (".H" or ".").
A place containing a "/" character is considered to be a
UNIX-style name. If the name in the #include directive also
contains a "/" character that is not the first character and is
not preceded by a "!" character (that is, it is not an absolute
UNIX-style pathname), then the name in the #include directive
is appended to the named place, separated by a "/" character,
before applying the decc$to_vms pathname translation function.
3. If "DECC$USER_INCLUDE" is defined as a logical name, search
"DECC$USER_INCLUDE:.H", or just "DECC$USER_INCLUDE:." if
/ASSUME=NOHEADER_TYPE_DEFAULT is in effect.
4. If the file is not found, follow the steps for the
angle-bracketed form of inclusion.
----^----
Furthermore,
ludens$ help define examples
----v----
DEFINE
Examples
[...]
7.$ DEFINE MYDISK XXX0:[MYDIR], YYY0:[TESTDIR]
In this example, the DEFINE command places the logical name
MYDISK in the process logical name table with two equivalence
names: XXX0:[MYDIR] and YYY0:[TESTDIR].
----^----
A plausible reconstruction of your old setup might be:
1. Define the DECC$USER_INCLUDE logical to a list of include
directories, all different from the directory where the .C files
resided.
2. Specify no /INCLUDE_DIRECTORY option.
3. When the .C file includes "foo.h", the compiler looks for it under
all directories specified in DECC$USER_INCLUDE.
4a. When "foo.h" includes "bar.h", the compiler looks for such a "bar.h"
per default (/NESTED_INCLUDE_DIRECTORY=INCLUDE_FILE) that is a "sibling"
of "foo.h".
4b. However, if /NESTED_INCLUDE_DIRECTORY=PRIMARY_FILE is in effect, the
compiler searches for "bar.h" as described for "foo.h" in step 3.
(Off topic again, sorry.)
Cheers,
lacos
jacob navia
[snip]
Thanks for this contribution. This means that that compiler could be
configured to acept the options for searching include files, what
is better than forcing one, as now lcc-win does.
There are still Vaxes around as it seems...
What are the characteristics of that server? (Ram/disk etc) ?
Just curious
jacob
Eric Sosman
> [... DECC #include search strategies ...]
>
> (Off topic again, sorry.)
Far worse abuses have occurred (and will again, I'm sure).
For this thread, though, I think the point is well made: Compilers
search for #include files in a variety of idiosyncratic ways, which
defy a one- or two-line description.
--
Eric Sosman
eso...@ieee-dot-org.invalid
frank
I would go farther with the -I and include an example. I would guess
that for linux users of gcc, it would look something like
gcc -I "/usr/headers/" ...
, but this can be a harder thing if windows is the platform, if lcc is
installed in say, "Program Files", which turns any path into a serious
bummer.
--
frank
Ersek, Laszlo
> There are still Vaxes around as it seems...
ludens is an Alpha.
> What are the characteristics of that server? (Ram/disk etc) ?
>
> Just curious
I've asked the sysadmin and he was kind enough to tell us.
live server: (working)
Alphaserver DS20E
2x 667 Mhz Alpha EV67 CPU
2 Gbyte RAM (will be upgraded to 4G during the next scheduled maintenance)
no internal disk
cold spare server: (turned off)
Alphaserver ES40
2x 500 MHz Alpha EV67 CPU
4 Gbyte RAM
no internal disk
storage:
HP MSA 1000 (2gbit FC SAN storage subsystem)
2 controllers
2 switches
2 shelfes (4x scsi320 buses)
8 disk (300 Gbyte 10k RPM) 2 in each bus
tape library:
HP StorageWorks MSL6030 Tape Library
1 Ultrium 2 drive
2x 15 slot magazine
ultra3-lvd (scsi160) interface
Console:
original VT520 console with hardcopy printing
Rack: an old |D|I|G|I|T|A|L| branded alphaserver (blue) rack
Web servers were moved a year ago to a dedicated machine (also VMS OS,
WASD http server, Alphaserver ES45 (4x 1000GHz Alpha EV68 cpu, 4 Gbyte
ram)).
Most components are used parts and were donated to the University,
except for the storage and the tape library, which were bought new four
years ago.
He also mentions that under VMS there are "text libraries" (TLBs)
additionally, which provide faster access to headers (and other texts)
than individual files.
If you wish, I can cite the full cc/incl help, which also details how
TLBs are searched. (Though I'm sure it's available on the web as well.)
(I can hear those *PLONK*s :()
lacos
Flash Gordon
> On 1/24/2010 5:00 PM, Ersek, Laszlo wrote:
>> [... DECC #include search strategies ...]
>>
>> (Off topic again, sorry.)
>
> Far worse abuses have occurred (and will again, I'm sure).
> For this thread, though, I think the point is well made: Compilers
> search for #include files in a variety of idiosyncratic ways, which
> defy a one- or two-line description.
I think that Jacob's original description, with my small modification,
is perfectly reasonable for a tutorial, and that was only about a four
line description.
--
Flash Gordon
frank
> Footnote 1: System includes need not actually be files, but the effect
> is always the same.
If they're not necessarliy files, what can they be?
--
frank
Keith Thompson
Anything.
frank
4 A preprocessing directive of the form
# include pp-tokens new-line
(that does not match one of the two previous forms) is permitted. The
preprocessing
tokens after include in the directive are processed just as in normal
text. (Each
identifier currently defined as a macro name is replaced by its
replacement list of
preprocessing tokens.) The directive resulting after all replacements
shall match one of
the two previous forms.148) The method by which a sequence of
preprocessing tokens
between a < and a > preprocessing token pair or a pair of " characters
is combined into a
single header name preprocessing token is implementation-defined.
Apparently pp-tokens is the output from a preprocessor. I think I've
figured out why #includes don't just include files. Doesn't cpp hand
gcc a bunck of tokens that aren't in any file?
Keith Thompson
[...]
> 4 A preprocessing directive of the form
> # include pp-tokens new-line
> (that does not match one of the two previous forms) is
> permitted. The preprocessing tokens after include in the directive
> are processed just as in normal text. (Each identifier currently
> defined as a macro name is replaced by its replacement list of
> preprocessing tokens.) The directive resulting after all
> replacements shall match one of the two previous forms.148) The
> method by which a sequence of preprocessing tokens between a < and a
> > preprocessing token pair or a pair of " characters is combined
> into a single header name preprocessing token is
> implementation-defined.
>
> Apparently pp-tokens is the output from a preprocessor.
Yes. The syntax rule
# include pp-tokens new-line
refers to them because #include directives are handled by the
proprocessor; the pp-tokens haven't been converted to tokens.
> I think I've
> figured out why #includes don't just include files.
I don't think you have. The pp-tokens in question are just the ones
that appear in the #include directive itself; they have nothing to do
with the contents or origin of the header. It's really just saying
that in either
#include "header"
or
include <header>
the "header" or <header> can be the result of macro expansion. For
example, this is valid:
#define STDIO <stdio.h>
#include STDIO
This had to be described as a special rule because both macro
expansion and #include expansion happen during the same translation
phase. If #include expansion happened in a later phase than
macro expansion, the third form would follow naturally from the
existing rules.
A header can be anything the compiler permits it to be. It's
typically a C source file, but it can be a binary file that the
compiler is able to interpret, or it can be purely internal to the
compiler. For example, the compiler, on seeing
#include <stdbool.h>
might just internally generate the appropriate macro definitions
without reading any external file. Or the compiler might use actual
files for all headers; other methods are permitted but not required.
> Doesn't cpp hand
> gcc a bunck of tokens that aren't in any file?
I'm not sure, but I don't think so. As you've seen, it does predefine
certain macros, but that's not the same thing.
Flash Gordon
> frank <abqha...@gmail.com> writes:
>> On Jan 24, 4:26 am, Flash Gordon <s...@spam.causeway.com> wrote:
>>
>>> Footnote 1: System includes need not actually be files, but the effect
>>> is always the same.
>> If they're not necessarliy files, what can they be?
>
> Anything.
One common option is a pre-compiled header, which might be in some form
of simple database. For some options without pre-compiled headers see
the discussions about things done under VMS in this very thread!
--
Flash Gordon
Richard Tobin
frank <abqha...@gmail.com> wrote:
>> Footnote 1: System includes need not actually be files, but the effect
>> is always the same.
>If they're not necessarliy files, what can they be?
For example, they might be built in to the compiler: when it sees
#include <stdio.h> it might just make the relevant declarations
visible.
-- Richard
--
Please remember to mention me / in tapes you leave behind.