1COOK(1) General Commands Manual COOK(1)
2
6 cook - a file construction tool
7
9 [ option... ][ filename... ]
10 -Help
11 -VERSion
12
14 The program is a tool for constructing files. It is given a set of
15 files to create, and instructions detailing how to construct them. In
16 any non-trivial program there will be prerequisites to performing the
17 actions necessary to creating any file, such as extraction from a
18 source-control system. The program provides a mechanism to define
19 these.
20 When a program is being developed or maintained, the programmer will
22 typically change one file of several which comprise the program. The
23 program examines the last-modified times of the files to see when the
24 prerequisites of a file have changed, implying that the file needs to
25 be recreated as it is logically out of date.
26 The program also provides a facility for implicit recipes, allowing
28 users to specify how to form a file with a given suffix from a file
29 with a different suffix. For example, to create filename.o from file‐
30 name.c
31 Options and filenames may be arbitrarily mixed on the command line; no
33 processing is done until all options and filenames on the command line
34 have been scanned.
35 The program will attempt to create the named files from the recipes
37 given to it. The recipes are contained in a file called Howto.cook in
38 the current directory. This file may, in turn, include other files
39 containing additional recipes.
40 If no filenames are given on the command line the targets of the first
42 recipe defined are cooked.
43
45 The valid options for are listed below. Any other options (words on
46 the command line beginning with `-') will cause a diagnostic message to
47 be issued.
48 -Action
50 Execute the commands given in the recipes. This is the
51 default.
52 -No_Action
54 Do not execute the commands given in the recipes.
55 -Book filename
57 Tells to used the named cookbook, rather than the default
58 ``Howto.cook'' file.
59 -CAScade
61 This option may be used to enable the use of cascaded ingredi‐
62 ents. This is the default.
63 -No_CAScade
65 This option may be used to disable the use of cascaded ingredi‐
66 ents.
67 -Continue
69 If cooking a target should fail, continue with other recipes
70 for which the failed target is not an ingredient, directly or
71 indirectly.
72 -No_Continue
74 If cooking a target should fail, will exit. This is the
75 default.
76 -CTime The inode st_ctime data is used to supplement the st_mtime data
78 when determining whether or not files have changed. This is
79 the default. (If you have no idea what this is, don't mess
80 with it.)
81 -No_CTime
83 Do not supplement st_mtime with st_ctime. This may be impor‐
84 tant when st_nlink changes at critical times, because making
85 and breaking hard links touches st_ctime. (If you have no idea
86 what this is, seriously, don't mess with it.)
87 -Errok
89 When a command is executed, the exit code will be ignored.
90 -No_Errok
92 When a command is executed, if the exit code is positive it
93 will be deemed to fail, and thus the recipe containing it to
94 have failed. This is the default.
95 -FingerPrint
97 When cook examines a file to determine if it has changed, it
98 uses the last-modified time information available in the file
99 system. There are times when this is altered, but the file
100 contents do not actually change. The fingerprinting facility
101 examines the file contents when it appears to have changed, and
102 compares the old fingerprint against the present file contents.
103 (See cookfp(1) for a description of the fingerprinting algo‐
104 rithm.) If the fingerprint did not change, the last-modified
105 time in the file system is ignored. Note that this has impli‐
106 cations if you are in the habit of using the touch(1) command -
107 cook will do nothing until you actually change the file.
108 -No_FingerPrint
110 Do not use fingerprints to supplement the last-modified time
111 file information. This is the default.
112 -FingerPrint_Update
114 This option may be used to scan the directory tree below the
115 current directory and update the file fingerprints. This helps
116 when you use another tool (such as RCS or ClearCase) which
117 alters the file but preserves the file's modification time.
118 -Force
120 Always perform the actions of recipes, irrespective of the
121 last-modified times of any of the ingredients. This option is
122 useful if something beyond the scope of the cookbook has been
123 modified; for example, a bug fix in a compiler.
124 -No_Force
126 Perform the actions of the recipes if any of the ingredients
127 are logically out of date. This is the default.
128 -Help
130 Provide information about how to execute on stdout, and perform
131 no other function.
132 -Include filename
134 Search the named directory before the standard places for
135 included cookbooks. Each directory so named will be scanned in
136 the order given. The standard places are $HOME/.cook then .
137 -Include_Cooked
139 This option may be used to require the cooking of files named
140 on #include-cooked and #include-cooked-nowarn include lines in
141 cookbooks. The files named will be included, if present. If
142 the files named need to be updated or created, this will be
143 done, and then the cookbook re-read. This is the default.
144 -No_Include_Cooked
146 This option may be used to inhibit the implicit cooking of
147 files named on #include-cooked and #include-cooked-nowarn
148 include lines in cookbooks. The files will be included, if
149 present, but they will not be updated or created, even if
150 required.
151 -Include_Cooked_Warning
153 This option enables the warnings about derived dependencies in
154 derived cookbooks. This is usually the default.
155 -No_Include_Cooked_Warning
157 This option disables the warnings about derived dependencies in
158 derived cookbooks.
159 -List
161 Causes to automatically redirect the stdout and stderr of the
162 session. Output will continue to come to the terminal, unless
163 is executing in the background. The name of the file will be
164 the name of the cookbook with any suffix removed and ".list"
165 appended; this will usually be Howto.list. This is the
166 default.
167 -List filename
169 Causes to automatically redirect the stdout and stderr of the
170 session into the named file. Output will continue to come to
171 the terminal, unless is executing in the background.
172 -No_List
174 No automatic redirection of the output of the session will be
175 made.
176 -No_List filename
178 No automatic redirection of the output of the session will be
179 made, however subsequent -List options will default to listing
180 to the named file.
181 -Meter
183 After each command is executed, print a summary of the com‐
184 mand's CPU usage.
185 -No_Meter
187 Do not print a CPU usage summary after each command. This is
188 the default.
189 -Pairs
191 This option may be used to generate a list of pair-wise file
192 dependencies, similar to lorder(1) output. This may be used to
193 draw file dependency diagrams. It can also be useful when
194 debugging cookbooks.
195 -Page-Length number
197 This option may be used to set the length of the page, used
198 when Cook needs to paginate output. Defaults to what the LINES
199 environment variable tells it, or the terminal emulator tells
200 it if LINES isn't set. -Page-Width number This option may be
201 used to set the width of the page, used when Cook needs to wrap
202 output (e.g. when it prints commends being executed). Defaults
203 to what the COLS environment variable tells it, or the terminal
204 emulator tells it if COLS isn't set. The maximum value for
205 number is 32767.
206 -PARallel [ number ]
208 This option may be used to specify the number of parallel exe‐
209 cutions threads. The number defaults to 4 if no specific num‐
210 ber of threads is specified. See also the parallel_jobs vari‐
211 able.
212 Use of this option on single-processor machines needs to be
214 done with great care, as it can bring other processing to a
215 complete halt. Several users doing so simultaneously on a
216 multi-processor machine will have a similar effect. It is also
217 to rapidly run out of virtual memory and temporary disk space
218 if the parallel tasks are complex.
219 -No_PARallel
221 This option may be used to specify that a single execution
222 thread is to be used. This is the default.
223 -Precious
225 When commands in the body of a recipe fail, do not delete the
226 targets of the recipe.
227 -No_Precious
229 When commands in the body of a recipe fail, delete the targets
230 of the recipe. This is the default.
231 -Reason
233 Two options are provided for tracing the inferences makes when
234 attempting to cook a target. The -Reason option will cause
235 will emit copious amounts of information about the inferences
236 it is making when cooking targets. This option may be used
237 when you think is acting strangely, or are just curious.
238 -No_Reason
240 This option may be used to cause will not emit information
241 about the inferences it is making when cooking targets. This
242 is the default.
243 -SCript
245 This option may be used to request a shell script be printed on
246 the standard output. This shell script may be used to con‐
247 struct the files; it captures many of the semantics of the
248 cookbook. This can be useful when a project needs to be dis‐
249 tributed, and the recipients do not have cook(1) installed. It
250 can also be very useful when debugging cookbooks.
251 -Silent
253 Do not echo commands before they are executed.
254 -No_Silent
256 Echo commands before they are executed. This is the default.
257 -STar
259 Emit progress indicators once a second. These progress indica‐
260 tors include
261 + Reading the cookbook
263 - Executing a collect function
264 * Building the dependency graph
266 # Walking the dependency graph
267 @ Writing fingerprint files.
268 -No_STar
270 Do not emit progress indicators. This is the default.
271 -Strip_Dot
273 Remove leading "./" from filenames before attempting to cook
274 them; applies to all filenames and all recipes. This is the
275 default.
276 -No_Strip_Dot
278 Leave leading "./" on filenames while cooking.
279 -SymLink-Ingredients
281 The option asks that, when using a search path, that non-top-
282 level recipe ingredients get a top-level symlink to the actual
283 file. This is intended for brain dead tools, like GNU Auto‐
284 conf, that don't grok search paths.
285 -No-SymLink-Ingredients
287 Do not create top level symlinks to ingredients. This is the
288 default.
289 -Tell_Position
291 This option may be used to cause the position of commands
292 (filename and line number) to be printed along with the command
293 just before it is executed (provided the -No_Silent option is
294 in force).
295 -No_Tell_Position
297 This option may be used to suppress printing the position of
298 commands (filename and line number) along with the command just
299 before it is executed. This is the default.
300 -Touch
302 Update the last-modified times of the target files, rather than
303 execute the actions bound to recipes. This can be useful if
304 you have made a modification to a file that you know will make
305 a system of files logically out of date, but has no signifi‐
306 cance; for example, adding a comment to a widely used include
307 file.
308 -No_Touch
310 Execute the actions bound to recipes, rather than update the
311 last-modified times of the target files. This is the default.
312 -TErminal
314 When listing, also send the output stream to the terminal.
315 This is the default.
316 -No_TErminal
318 When listing, do not send the output to the terminal.
319 -Time_Adjust
321 This option causes cook to check the last-modified time of the
322 targets of recipes, and updates them if necessary, to make sure
323 they are consistent with (younger than) the last-modified times
324 of the ingredients. This results in more system calls, and can
325 slow things down on some systems. This corresponds to the
326 time-adjust recipe flag.
327 -No_Time_Adjust
329 Do not update the file last-modified times after performing the
330 body of a recipe. This is the default. This corresponds to
331 the no-time-adjust recipe flag.
332 -Web
334 This option may be used to request a HTML web page be printed
335 on the standard output. This web page may be used to document
336 the file dependencies; it captures many of the semantics of the
337 cookbook. It can also be very useful when debugging cookbooks.
338 name=value
340 Assign the value to the named variable. The value may contain
341 spaces if you can convince the shell to pass them through.
342
344 The following files are used by cook:
345 Howto.cook
347 This file contains instructions to cook for how to construct
348 files.
349 This directory contains "system" cookbooks for various tools
351 and activities.
352 .cook.fp
354 This text file is used to remember fingerprints between invoca‐
355 tions.
356
358 The following environment variables are used by cook:
359 COOK May be set to contain command-line options, changing the default
361 behavior of cook. May be overridden by the command line.
362 PAGER Use to paginate the output of the -Help and -VERSion options.
364 Defaults to more(1) if not set.
365 COOK_AUTOMOUNT_POINTS
367 A colon-separated list of directories which the automounter may
368 use to mount file systems. Use with extreme care, as this dis‐
369 torts Cook's idea of the shape of the file system.
370 This feature assumes that paths below the automounter's mount
372 directory are echoes of paths without it. E.g. When /home is
373 the trigger, and /tmp_mnt/home is where the on-demand NFS mount
374 is performed, with /home appearing to processes to be a sym‐
375 link.
376 This is the behavior of the Sun automounter. The AMD auto‐
378 mounter is capable of being configured in this way, though it
379 is not typical of the examples in the manual. Nor is it typi‐
380 cal of the out-of-the-box Linux AMD configuration in many dis‐
381 tributions.
382 Defaults to ``/tmp_mnt:/a:/.automount'' if not set.
384Reference Manual Cook COOK(1)