1C_INCL(1) General Commands Manual C_INCL(1)
2
6 c_incl - determine dependencies
7
9 c_incl [ option... ] filename
10 c_incl -Help
11 c_incl -VERSion
12
14 The c_incl program is used to traverse source files looking for
15 include dependencies suitable for [collect]ion or #include-cooked-ing
16 by cook.
17 The filename ``-'' is understood to mean the standard input. When you
19 use this file name, caching is ignored.
20 Several input languages are supported, see the options list for
22 details.
23
25 The following options are understood.
26 -C The source file is a C source file. It is assumed that it
28 will have the dependencies resolved by the cpp(1) command.
29 The same include semantics as the cpp(1) command will be
30 employed. This is the default. This is short-hand for
31 ``--language=c''
32 --Language=name
34 This option may be used to specify the language of the source
35 file. Know names include ``C'', ``M4'', ``optimistic'' and
36 ``roff''.
37 The ``optimistic'' language will take on almost anything. It
39 accepts an include keyword in any case, including mixed, with
40 leading white space, but at most one leading punctuation
41 character. It assumes that the filename follows the include
42 keyword and does not contain white space, and does not start
43 or end with punctuation characters (it strips off any it may
44 find). The rest of the line is ignored. The drawback is that
45 it will sometimes recognise commands and other text as
46 unintended include directives, hence the name. This is often
47 used to recognise include directives in a wide variety of
48 assembler input.
49 -Roff The source file is a *roff source file. It is assumed that it
51 will have the dependencies resolved by the roffpp(1) command.
52 The same include semantics as the roffpp(1) command will be
53 employed. This is short-hand for ``--language=roff''
54 -Verbose
56 Tell what is happening.
57 -Ipath
59 Specify include path, a la cc(1).
60 -I-
62 Any directories you specify with -I options before the -I-
63 option are searched only for the case of #include "file"; they
64 are not searched for #include <file>.
65 If additional directories are specified with -I options
67 after the -I-, these directories are searched for all
68 #include directives. (Ordinarily all -I directories are used
69 this way.)
70 In addition, the -I- option inhibits the use of the current
72 directory (where the current input file came from) as the
73 first search directory for #include "file". There is no way
74 to override this effect of -I-. With -I. you can specify
75 searching the directory which was current when c_incl was
76 invoked. That is not exactly the same as what the
77 preprocessor does by default, but it is often satisfactory.
78 The -I- option does not inhibit the use of the standard system
80 directories for header files. Thus, -I- and -No_System are
81 independent.
82 -Absolute_Paths
84 This option may be used to allow absolute paths in the output.
85 This is usually the default.
86 -No_Absolute_Paths
88 This option may be used to exclude absolute paths from the
89 output.
90 -Absent_Local_Ignore
92 For files included using a #include ''filename.h'' directive,
93 ignore the file if it cannot be found.
94 -Absent_Local_Mention
96 For files included using a #include ''filename.h'' directive,
97 print the file name even if the file cannot be found. This is
98 the default (it probably needs to be built).
99 -Absent_Local_Error
101 For files included using a #include ''filename.h'' directive,
102 print a fatal error if the file cannot be found.
103 -Absent_System_Ignore
105 For files included with a #include <filename.h> directive,
106 ignore the file if it cannot be found. This is the default
107 (it was probably ifdef'ed out).
108 -Absent_System_Mention
110 For files included with a #include <filename.h> directive,
111 print the file name even if the file cannot be found.
112 -Absent_System_Error
114 For files included with a #include <filename.h> directive,
115 print a fatal error if the file cannot be found.
116 -Absent_Program_Ignore
118 If the file named on the command line cannot be found, behave
119 as if the file were found, but was empty.
120 -Absent_Program_Error
122 If the file named on the command line cannot be found, print a
123 fatal error message. This is the default.
124 -Escape_Newlines
126 This option may be used to request that newlines in the output
127 are escaped with backslash (``\'') characters.
128 -Help
130 Give information on how to use c_incl.
131 -EXclude filename
133 This option may be used to nominate include file names which
134 are not to be used.
135 -VERSion
137 Tell what version of c_incl is being run.
138 -Interior_Files filename...
140 This option may be used to tell c_incl about include files
141 which don't exist yet. This is because they are interior to
142 the dependency graph, but cook(1) hasn't finished walking it
143 yet. Often used with Cook's [interior-files] function.
144 (Note: the filename list has an arbitrary number of files; it
145 ends at the next option or end-of-line, so you need to be
146 careful where you put the input filename.)
147 -No_System
149 Do not search the /usr/include directory. By default this is
150 searched last. This option implies the -No_Absolute_Paths
151 option, unless explicitly contradicted.
152 -CAche
154 This option may be used to turn caching on. This is the
155 default.
156 -No_Cache
158 This option may be used to turn caching off.
159 -PREfix string
161 This option may be used to print a string before any of the
162 filenames are printed. It will not be printed if no file
163 names are printed.
164 -Quote_FileNames
166 This option may be used to have c_incl quote filenames. This
167 permits filenames to contain characters which are special to
168 Cook, including spaces.
169 -SUFfix string
171 This option may be used to print a string after all of the
172 filenames are printed. It will not be printed if no file
173 names are printed.
174 -Output filename
176 This option may be used to specify the output file. Defaults
177 to the standard output if not set.
178 -No_Source_Relative_Includes
180 This option will give a fatal error if a #include
181 ''filename.h'' directive is used. This is necessary when you
182 are using Cook's search_list functionality to stitch together
183 a baseline and a private work area.
184 -RECursion
186 This option may be used to specify that nested include files
187 are to be scanned, so that their includes may also be
188 discovered. This is the default.
189 -No_RECursion
191 This option may be use to specify that nested include files
192 are not to be scanned. This option is recommended for use
193 with the Cook cascade-for recipes. This option implies
194 -No_Cache, unless a -Cache option is specified.
195 -Remove_Leading_Path path
197 This option may be used to remove path prefixes from the
198 included filenames. May be used more than once. This is
199 necessary when you are using Cook's search_list functionality
200 to stitch together a baseline and a private work area; usually
201 as ``[prepost "-rlp=" "" [search_list]]''
202 -STripdot
204 This option may be used to specify that leading redundant dot
205 directories are to be removed from paths before processing.
206 This is the default.
207 -No_STripdot
209 This option may be used to specify that leading redundant dot
210 directories need not be removed from paths before processing.
211 (Some path flattening may still occur.)
212 -Substitute_Leading_Path from to
214 This option may be used to modify path prefixes from the
215 included filenames. May be used more than once. This is
216 necessary when you are performing heterogeneous builds in the
217 same directory tree. By using an ``arch'' variable to hold
218 the architecture, and placing each architecture's objects in a
219 separate directory tree, this option may be used as ``-slp
220 [arch] "'[arch]'"'' (The outer quotes protect from Cook, the
221 inner quotes protect from the shell.) If you need more
222 intricate editing, used sed(1).
223 Any other options will generate an error.
225 All options may be abbreviated; the abbreviation is documented as the
227 upper case letters, all lower case letters and underscores (_) are
228 optional. You must use consecutive sequences of optional letters.
229 All options are case insensitive, you may type them in upper case or
231 lower case or a combination of both, case is not important.
232 For example: the arguments "-help", "-HEL" and "-h" are all
234 interpreted to mean the -Help option. The argument "-hlp" will not be
235 understood, because consecutive optional characters were not supplied.
236 Options and other command line arguments may be mixed arbitrarily on
238 the command line.
239 The GNU long option names are understood. Since all option names for
241 c_incl are long, this means ignoring the extra leading '-'. The
242 "--option=value" convention is also understood.
243
245 The caching mechanism use by the c_incl program caches the results of
246 searching files for include files (in a file called .c_inclrc in the
247 current directory). The cache is only refreshed when a file changes.
248 The use of this cache has been shown to dramatically increase the
250 performance of the c_incl program. Typically, only a small
251 proportions files in a project change between builds, resulting in a
252 very high cache hit rate.
253 When using caching, always use the same command line options,
255 otherwise weird and wonderful things will happen.
256 The .c_inclrc file is a binary file. If you wish to rebuild the
258 cache, simply delete this file with the rm(1) command. Being a binary
259 file, the .c_inclrc file is not portable across machines or operating
260 systems, so you will need to delete it when you move your sources. It
261 is a binary file for performance.
262 Accesses to the .c_inclrc file use file locking, so recipies using
264 c_incl need not use the single-thread clause.
265
267 The c_incl command will exit with a status of 1 on any error. The
268 c_incl command will only exit with a status of 0 if there are no
269 errors.
270
272 c_incl version 2.30
273 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
274 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Peter
275 Miller; All rights reserved.
276 The c_incl program comes with ABSOLUTELY NO WARRANTY; for details use
278 the 'c_incl -VERSion License' command. This is free software and you
279 are welcome to redistribute it under certain conditions; for details
280 use the 'c_incl -VERSion License' command.
281
283 Peter Miller E-Mail: millerp@canb.auug.org.au
284 /\/\* WWW: http://www.canb.auug.org.au/~millerp/
285Reference Manual Cook C_INCL(1)