Click above to get retro games delivered to your door ever month!

When using the #include preprocessor directive, a header is identified by a
sequence of characters placed between the "<" and ">" delimiters (e.g.,
<file>) and a source file is identified by a sequence of characters enclosed
by quotation marks (e.g., "file").  Watcom C/C++ makes a distinction between
the use of "<>" or quotation marks to surround the name of the file to be
included.  The search techniques for header files and source files are
slightly different.  Consider the following example.

Example:

     #include <stdio.h>  /* a system header file */
     #include "stdio.h"  /* your own header or source file */

You should use "<" and ">" when referring to standard or system header files
and quotation marks when referring to your own header and source files.

The character sequence placed between the delimiters in an #include
directive represents the name of the file to be included.  The file name may
include drive, path, and extension.

It is not necessary to include the drive and path specifiers in the file
specification when the file resides on a different drive or in a different
directory.  Watcom C/C++ provides a mechanism for looking up include files
which may be located in various directories and disks of the computer
system.  Watcom C/C++ searches directories for header and source files in
the following order (the search stops once the file has been located):

 1. If the file specification enclosed in quotation marks ("file-spec") or
    angle brackets (<file-spec>) contains the complete drive and path
    specification, that file is included (provided it exists).  No other
    searching is performed.  The drive need not be specified in which case
    the current drive is assumed.

 2. If the file specification is enclosed in quotation marks, the current
    directory is searched.

 3. Next, if the file specification is enclosed in quotation marks, the
    directory of the file containing the #include directive is searched.  If
    the current file is also an #include file, the directory of the parent
    file is searched next.  This search continues recursively through all
    the nested #include files until the original source file's directory is
    searched.

 4. Next, if the file specification enclosed in quotation marks
    ("file-spec") or in angle brackets (<file-spec>), each directory listed
    in the "i" path is searched (in the order that they were specified).

 5. Next, each directory listed in the <os>_INCLUDE environment variable is
    searched (in the order that they were specified).  The environment
    variable name is constructed from the current build target name.  The
    default build targets are:

    DOS
        when the host operating system is DOS,

    OS2
        when the host operating system is OS/2,

    NT
        when the host operating system is Windows NT/95, or

    QNX
        when the host operating system is QNX.

    For example, the environment variable OS2_INCLUDE will be searched if
    the build target is "OS2".  The build target would be OS/2 if:

     1. the host operating system is OS/2 and the "bt" option was not
        specified, or

     2. the "bt=OS2" option was explicitly specified.

 6. Next, each directory listed in the INCLUDE environment variable is
    searched (in the order that they were specified).

 7. Finally, if the file specification is enclosed in quotation marks, an
    adjacent "H" directory (i.e., ..\H) is searched if it exists.

In the above example, <stdio.h> and "stdio.h" could refer to two different
files if there is a STDIO.H in the current directory and one in the Watcom
C/C++ include file directory (\WATCOM\H) and the current directory is not
listed in an "i" path or the INCLUDE environment variable.

The compiler will search the directories listed in "i" paths (see
description of the "i" option) and the INCLUDE environment variable in a
manner analogous to that which the operating system shell will use when
searching for programs by using the PATH environment variable.

The "SET" command is used to define an INCLUDE environment variable that
contains a list of directories.  A command of the form


     SET INCLUDE=[d:]path;[d:]path...

is issued before running Watcom C/C++ the first time.  The brackets indicate
that the drive "d:" is optional and the ellipsis indicates that any number
of paths may be specified.  For Windows NT, use the "System" icon in the
Control Panel to define environment variables.

We illustrate the use of the #include directive in the following example.

Example:

     #include <stdio.h>
     #include <time.h>
     #include <dos.h>


     #include "common.c"

     int main()
       {
         initialize();
         update_files();
         create_report();
         finalize();
       }


     #include "part1.c"
     #include "part2.c"

If the above text is stored in the source file REPORT.C in the current
directory then we might issue the following commands to compile the
application.

Example:

     C>rem -- Two places to look for include files
     C>set include=c:\watcom\h;b:\headers
     C>rem -- Now compile application specifying a
     C>rem    third location for include files
     C>compiler_name report /fo=..\obj\ /i=..\source

In the above example, the "SET" command is used to define the INCLUDE
environment variable.  It specifies that the \WATCOM\H directory (of the "C"
disk) and the \HEADERS directory (a directory of the "B" disk) are to be
searched.

The Watcom C/C++ "i" option defines a third place to search for include
files.  The advantage of the INCLUDE environment variable is that it need
not be specified each time the compiler is run.