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
Peter Miller E-Mail: pmiller@opensource.org.au
/\/\* WWW: http://miller.emu.id.au/pmiller/