NAME¶
c_incl - determine dependencies
SYNOPSIS¶
c_incl [
option... ]
filename
c_incl -Help
c_incl -VERSion
DESCRIPTION¶
The
c_incl program is used to traverse source files looking for include
dependencies suitable for [collect]ion or #include-cooked-ing by cook.
The filename ``-'' is understood to mean the standard input. When you use this
file name, caching is ignored.
Several input languages are supported, see the options list for details.
OPTIONS¶
The following options are understood.
- -C
- The source file is a C source file. It is assumed that it
will have the dependencies resolved by the cpp(1) command. The same
include semantics as the cpp(1) command will be employed. This is
the default. This is short-hand for ``--language=c''
- --Language=name
This option may be used to specify the
language of the source file. Know names include ``C'', ``M4'', ``optimistic''
and ``roff''.
The ``optimistic'' language will take on almost anything. It accepts an include
keyword in any case, including mixed, with leading white space, but at most
one leading punctuation character. It assumes that the filename follows the
include keyword and does not contain white space, and does not start or end
with punctuation characters (it strips off any it may find). The rest of the
line is ignored. The drawback is that it will sometimes recognise commands and
other text as unintended include directives, hence the name. This is often
used to recognise include directives in a wide variety of assembler
input.
- -Roff
- The source file is a *roff source file. It is assumed that
it will have the dependencies resolved by the roffpp(1) command.
The same include semantics as the roffpp(1) command will be
employed. This is short-hand for ``--language=roff''
- -Verbose
- Tell what is happening.
- -Ipath
-
Specify include path, a la cc(1).
- -I-
Any directories you specify with
-I
options before the
-I- option are searched only for the case of
#include "file"; they are not searched for
#include
<file>.
If additional directories are specified with
-I options after the
-I-, these directories are searched for all
#include directives.
(Ordinarily all
-I directories are used this way.)
In addition, the
-I- option inhibits the use of the current directory
(where the current input file came from) as the first search directory for
#include "file". There is no way to override this effect of
-I-. With
-I. you can specify searching the directory which was
current when c_incl was invoked. That is not exactly the same as what the
preprocessor does by default, but it is often satisfactory.
The
-I- option does not inhibit the use of the standard system
directories for header files. Thus,
-I- and
-No_System are
independent.
- -Absolute_Paths
- This option may be used to allow absolute paths in the
output. This is usually the default.
- -No_Absolute_Paths
- This option may be used to exclude absolute paths from the
output.
- -Absent_Local_Ignore
-
For files included using a #include ''filename.h'' directive, ignore
the file if it cannot be found.
- -Absent_Local_Mention
-
For files included using a #include ''filename.h'' directive, print
the file name even if the file cannot be found. This is the default (it
probably needs to be built).
- -Absent_Local_Error
-
For files included using a #include ''filename.h'' directive, print a
fatal error if the file cannot be found.
- -Absent_System_Ignore
-
For files included with a #include <filename.h> directive,
ignore the file if it cannot be found. This is the default (it was
probably ifdef'ed out).
- -Absent_System_Mention
-
For files included with a #include <filename.h> directive,
print the file name even if the file cannot be found.
- -Absent_System_Error
-
For files included with a #include <filename.h> directive,
print a fatal error if the file cannot be found.
- -Absent_Program_Ignore
-
If the file named on the command line cannot be found, behave as if the file
were found, but was empty.
- -Absent_Program_Error
-
If the file named on the command line cannot be found, print a fatal error
message. This is the default.
- -Escape_Newlines
- This option may be used to request that newlines in the
output are escaped with backslash (``\'') characters.
- -Help
-
Give information on how to use c_incl.
- -EXclude filename
- This option may be used to nominate include file names
which are not to be used.
- -VERSion
-
Tell what version of c_incl is being run.
- -Interior_Files filename...
- This option may be used to tell c_incl about include
files which don't exist yet. This is because they are interior to the
dependency graph, but cook(1) hasn't finished walking it yet. Often
used with Cook's [interior-files] function. ( Note: the
filename list has an arbitrary number of files; it ends at the next
option or end-of-line, so you need to be careful where you put the input
filename.)
- -No_System
-
Do not search the /usr/include directory. By default this is searched
last. This option implies the -No_Absolute_Paths option, unless explicitly
contradicted.
- -CAche
-
This option may be used to turn caching on. This is the default.
- -No_Cache
-
This option may be used to turn caching off.
- -PREfix string
-
This option may be used to print a string before any of the filenames are
printed. It will not be printed if no file names are printed.
- -Quote_FileNames
- This option may be used to have c_incl quote
filenames. This permits filenames to contain characters which are special
to Cook, including spaces.
- -SUFfix string
-
This option may be used to print a string after all of the filenames are
printed. It will not be printed if no file names are printed.
- -Output filename
- This option may be used to specify the output file.
Defaults to the standard output if not set.
- -No_Source_Relative_Includes
- This option will give a fatal error if a #include
''filename.h'' directive is used. This is necessary when you are using
Cook's search_list functionality to stitch together a baseline and a
private work area.
- -RECursion
- This option may be used to specify that nested include
files are to be scanned, so that their includes may also be discovered.
This is the default.
- -No_RECursion
- This option may be use to specify that nested include files
are not to be scanned. This option is recommended for use with the
Cook cascade-for recipes. This option implies - No_Cache, unless a
-Cache option is specified.
- -Remove_Leading_Path path
- This option may be used to remove path prefixes from the
included filenames. May be used more than once. This is necessary when you
are using Cook's search_list functionality to stitch together a baseline
and a private work area; usually as ``[prepost "-rlp="
"" [search_list]]''
- -STripdot
- This option may be used to specify that leading redundant
dot directories are to be removed from paths before processing. This is
the default.
- -No_STripdot
- This option may be used to specify that leading redundant
dot directories need not be removed from paths before processing. (Some
path flattening may still occur.)
- -Substitute_Leading_Path from to
- This option may be used to modify path prefixes from the
included filenames. May be used more than once. This is necessary when you
are performing heterogeneous builds in the same directory tree. By using
an ``arch'' variable to hold the architecture, and placing each
architecture's objects in a separate directory tree, this option may be
used as ``-slp [arch] "'[arch]'"'' (The outer quotes protect
from Cook, the inner quotes protect from the shell.) If you need more
intricate editing, used sed(1).
Any other options will generate an error.
All options may be abbreviated; the abbreviation is documented as the upper case
letters, all lower case letters and underscores (_) are optional. You must use
consecutive sequences of optional letters.
All options are case insensitive, you may type them in upper case or lower case
or a combination of both, case is not important.
For example: the arguments "-help", "-HEL" and
"-h" are all interpreted to mean the
-Help option. The
argument "-hlp" will not be understood, because consecutive optional
characters were not supplied.
Options and other command line arguments may be mixed arbitrarily on the command
line.
The GNU long option names are understood. Since all option names for
c_incl are long, this means ignoring the extra leading '-'. The "
--option=value" convention is also
understood.
CACHING¶
The caching mechanism use by the
c_incl program caches the results of
searching files for include files (in a file called
.c_inclrc in the
current directory). The cache is only refreshed when a file changes.
The use of this cache has been shown to dramatically increase the performance of
the
c_incl program. Typically, only a small proportions files in a
project change between builds, resulting in a very high cache hit rate.
When using caching, always use the same command line options, otherwise weird
and wonderful things will happen.
The
.c_inclrc file is a binary file. If you wish to rebuild the cache,
simply delete this file with the
rm(1) command. Being a binary file,
the
.c_inclrc file is not portable across machines or operating
systems, so you will need to delete it when you move your sources. It is a
binary file for performance.
Accesses to the
.c_inclrc file use file locking, so recipies using
c_incl need not use the single-thread clause.
EXIT STATUS¶
The
c_incl command will exit with a status of 1 on any error. The
c_incl command will only exit with a status of 0 if there are no
errors.
COPYRIGHT¶
c_incl version 2.33
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Peter Miller
The
c_incl program comes with ABSOLUTELY NO WARRANTY; for details use the
'
c_incl -VERSion License' command. This is free software and you are
welcome to redistribute it under certain conditions; for details use the '
c_incl -VERSion License' command.
AUTHOR¶