1C_INCL(1)                   General Commands Manual                  C_INCL(1)
2
3
4

NAME

6       c_incl - determine dependencies
7

SYNOPSIS

9       c_incl [ option...  ] filename
10       c_incl -Help
11       c_incl -VERSion
12

DESCRIPTION

14       The c_incl program is used to traverse source files looking for include
15       dependencies suitable for [collect]ion or #include-cooked-ing by cook.
16
17       The filename ``-'' is understood to mean the standard input.  When  you
18       use this file name, caching is ignored.
19
20       Several  input  languages  are  supported,  see  the  options  list for
21       details.
22

OPTIONS

24       The following options are understood.
25
26       -C      The source file is a C source file.  It is assumed that it will
27               have the dependencies resolved by the cpp(1) command.  The same
28               include semantics as the cpp(1) command will be employed.  This
29               is the default.  This is short-hand for ``--language=c''
30
31       --Language=name
32               This  option  may be used to specify the language of the source
33               file.  Know names include  ``C'',  ``M4'',  ``optimistic''  and
34               ``roff''.
35
36               The  ``optimistic''  language will take on almost anything.  It
37               accepts an include keyword in any case, including  mixed,  with
38               leading  white space, but at most one leading punctuation char‐
39               acter.  It assumes that the filename follows the  include  key‐
40               word  and  does  not contain white space, and does not start or
41               end with punctuation characters  (it  strips  off  any  it  may
42               find).   The rest of the line is ignored.  The drawback is that
43               it will sometimes recognise commands and other  text  as  unin‐
44               tended  include directives, hence the name.  This is often used
45               to recognise include directives in a wide variety of  assembler
46               input.
47
48       -Roff   The  source file is a *roff source file.  It is assumed that it
49               will have the dependencies resolved by the  roffpp(1)  command.
50               The  same  include  semantics  as the roffpp(1) command will be
51               employed.  This is short-hand for ``--language=roff''
52
53       -Verbose
54               Tell what is happening.
55
56       -Ipath
57               Specify include path, a la cc(1).
58
59       -I-
60               Any directories you specify with  -I  options  before  the  -I-
61               option  are searched only for the case of #include "file"; they
62               are  not  searched for #include <file>.
63
64               If  additional  directories are specified with -I options after
65               the -I-, these directories are searched for all #include direc‐
66               tives.  (Ordinarily all -I directories are used this way.)
67
68               In addition, the -I- option inhibits the  use  of  the  current
69               directory (where the current input file came from) as the first
70               search directory for #include "file".  There is no way to over‐
71               ride  this  effect  of -I-.  With -I. you can specify searching
72               the directory which was current when c_incl was invoked.   That
73               is  not  exactly  the  same  as  what  the preprocessor does by
74               default, but it is often satisfactory.
75
76               The -I- option does not inhibit the use of the standard  system
77               directories  for  header  files.   Thus, -I- and -No_System are
78               independent.
79
80       -Absolute_Paths
81               This option may be used to allow absolute paths in the  output.
82               This is usually the default.
83
84       -No_Absolute_Paths
85               This option may be used to exclude absolute paths from the out‐
86               put.
87
88       -Absent_Local_Ignore
89               For files included using a #include  ''filename.h''  directive,
90               ignore the file if it cannot be found.
91
92       -Absent_Local_Mention
93               For  files  included using a #include ''filename.h'' directive,
94               print the file name even if the file cannot be found.  This  is
95               the default (it probably needs to be built).
96
97       -Absent_Local_Error
98               For  files  included using a #include ''filename.h'' directive,
99               print a fatal error if the file cannot be found.
100
101       -Absent_System_Ignore
102               For files included  with  a  #include  <filename.h>  directive,
103               ignore the file if it cannot be found.  This is the default (it
104               was probably ifdef'ed out).
105
106       -Absent_System_Mention
107               For files included  with  a  #include  <filename.h>  directive,
108               print the file name even if the file cannot be found.
109
110       -Absent_System_Error
111               For  files  included  with  a  #include <filename.h> directive,
112               print a fatal error if the file cannot be found.
113
114       -Absent_Program_Ignore
115               If the file named on the command line cannot be  found,  behave
116               as if the file were found, but was empty.
117
118       -Absent_Program_Error
119               If  the file named on the command line cannot be found, print a
120               fatal error message.  This is the default.
121
122       -Escape_Newlines
123               This option may be used to request that newlines in the  output
124               are escaped with backslash (``\'') characters.
125
126       -Help
127               Give information on how to use c_incl.
128
129       -EXclude filename
130               This  option  may  be used to nominate include file names which
131               are not to be used.
132
133       -VERSion
134               Tell what version of c_incl is being run.
135
136       -Interior_Files filename...
137               This option may be used to  tell  c_incl  about  include  files
138               which  don't  exist  yet.  This is because they are interior to
139               the dependency graph, but cook(1) hasn't  finished  walking  it
140               yet.  Often used with Cook's [interior-files] function.  (Note:
141               the filename list has an arbitrary number of files; it ends  at
142               the next option or end-of-line, so you need to be careful where
143               you put the input filename.)
144
145       -No_System
146               Do not search the /usr/include directory.  By default  this  is
147               searched  last.   This  option  implies  the -No_Absolute_Paths
148               option, unless explicitly contradicted.
149
150       -CAche
151               This option may be used  to  turn  caching  on.   This  is  the
152               default.
153
154       -No_Cache
155               This option may be used to turn caching off.
156
157       -PREfix string
158               This  option  may  be  used to print a string before any of the
159               filenames are printed.  It will not be printed if no file names
160               are printed.
161
162       -Quote_FileNames
163               This  option  may be used to have c_incl quote filenames.  This
164               permits filenames to contain characters which  are  special  to
165               Cook, including spaces.
166
167       -SUFfix string
168               This  option  may  be  used  to print a string after all of the
169               filenames are printed.  It will not be printed if no file names
170               are printed.
171
172       -Output filename
173               This  option  may be used to specify the output file.  Defaults
174               to the standard output if not set.
175
176       -No_Source_Relative_Includes
177               This option will give a  fatal  error  if  a  #include  ''file‐
178               name.h''  directive  is  used.   This is necessary when you are
179               using Cook's search_list functionality  to  stitch  together  a
180               baseline and a private work area.
181
182       -RECursion
183               This  option  may  be used to specify that nested include files
184               are to be scanned, so that their includes may also  be  discov‐
185               ered.  This is the default.
186
187       -No_RECursion
188               This option may be use to specify that nested include files are
189               not to be scanned.  This option is recommended for use with the
190               Cook  cascade-for  recipes.   This  option  implies  -No_Cache,
191               unless a -Cache option is specified.
192
193       -Remove_Leading_Path path
194               This option may be  used  to  remove  path  prefixes  from  the
195               included  filenames.  May be used more than once.  This is nec‐
196               essary when you are using Cook's search_list  functionality  to
197               stitch  together a baseline and a private work area; usually as
198               ``[prepost "-rlp=" "" [search_list]]''
199
200       -STripdot
201               This option may be used to specify that leading  redundant  dot
202               directories  are  to  be  removed from paths before processing.
203               This is the default.
204
205       -No_STripdot
206               This option may be used to specify that leading  redundant  dot
207               directories  need  not be removed from paths before processing.
208               (Some path flattening may still occur.)
209
210       -Substitute_Leading_Path from to
211               This option may be  used  to  modify  path  prefixes  from  the
212               included  filenames.  May be used more than once.  This is nec‐
213               essary when you are performing heterogeneous builds in the same
214               directory  tree.   By  using  an  ``arch'' variable to hold the
215               architecture, and placing each architecture's objects in a sep‐
216               arate  directory tree, this option may be used as ``-slp [arch]
217               "'[arch]'"'' (The outer quotes protect  from  Cook,  the  inner
218               quotes  protect  from  the  shell.)  If you need more intricate
219               editing, used sed(1).
220
221       Any other options will generate an error.
222

CACHING

224       The caching mechanism use by the c_incl program caches the  results  of
225       searching  files  for  include files (in a file called .c_inclrc in the
226       current directory).  The cache is only refreshed when a file changes.
227
228       The use of this cache has been shown to dramatically increase the  per‐
229       formance  of  the  c_incl program.  Typically, only a small proportions
230       files in a project change between builds,  resulting  in  a  very  high
231       cache hit rate.
232
233       When using caching, always use the same command line options, otherwise
234       weird and wonderful things will happen.
235
236       The .c_inclrc file is a binary file.  If you wish to rebuild the cache,
237       simply  delete  this file with the rm(1) command.  Being a binary file,
238       the .c_inclrc file is not portable across machines  or  operating  sys‐
239       tems,  so you will need to delete it when you move your sources.  It is
240       a binary file for performance.
241
242       Accesses to the .c_inclrc file use  file  locking,  so  recipies  using
243       c_incl need not use the single-thread clause.
244
245
246
247Reference Manual                     Cook                            C_INCL(1)
Impressum