1COOK(1) General Commands Manual COOK(1)
2
6 cook - a file construction tool
7
9 cook [ option... ][ filename... ]
10 cook -Help
11 cook -VERSion
12
14 The cook program is a tool for constructing files. It is given a set
15 of files to create, and instructions detailing how to construct them.
16 In any non-trivial program there will be prerequisites to performing
17 the actions necessary to creating any file, such as extraction from a
18 source-control system. The cook program provides a mechanism to
19 define 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 cook program examines the last-modified times of the files to see when
24 the prerequisites of a file have changed, implying that the file needs
25 to be recreated as it is logically out of date.
26 The cook program also provides a facility for implicit recipes,
28 allowing users to specify how to form a file with a given suffix from
29 a file with a different suffix. For example, to create filename.o
30 from filename.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 cook program will attempt to create the named files from the
37 recipes given to it. The recipes are contained in a file called
38 Howto.cook in the currect directory. This file may, in turn, include
39 other files 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 cook are listed below. Any other options (words
46 on the command line beginning with `-') will cause a diagnostic
47 message to 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 cook 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
62 ingredients. This is the default.
63 -No_CAScade
65 This option may be used to disable the use of cascaded
66 ingredients.
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, cook will exit. This is the
75 default.
76 -Errok
78 When a command is executed, the exit code will be ignored.
79 -No_Errok
81 When a command is executed, if the exit code is positive it
82 will be deemed to fail, and thus the recipe containing it to
83 have failed. This is the default.
84 -FingerPrint
86 When cook examines a file to determine if it has changed, it
87 uses the last-modified time information available in the file
88 system. There are times when this is altered, but the file
89 contents do not actually change. The fingerprinting facility
90 examines the file contents when it appears to have changed,
91 and compares the old fingerprint against the present file
92 contents. (See cookfp(1) for a description of the
93 fingerprinting algorithm.) If the fingerprint did not change,
94 the last-modified time in the file system is ignored. Note
95 that this has implications if you are in the habit of using
96 the touch(1) command - cook will do nothing until you actually
97 change the file.
98 -No_FingerPrint
100 Do not use fingerprints to supplement the last-modified time
101 file information. This is the default.
102 -FingerPrint_Update
104 This option may be used to scan the directory tree below the
105 current directory and update the file fingerprints. This
106 helps when you use another tool (such as RCS or ClearCase)
107 which alters the file but preserves the file's modification
108 time.
109 -Force
111 Always perform the actions of recipes, irrespective of the
112 last-modified times of any of the ingredients. This option is
113 useful if something beyond the scope of the cookbook has been
114 modified; for example, a bug fix in a compiler.
115 -No_Force
117 Perform the actions of the recipes if any of the ingredients
118 are logically out of date. This is the default.
119 -Help
121 Provide information about how to execute cook on stdout, and
122 perform no other function.
123 -Include filename
125 Search the named directory before the standard places for
126 included cookbooks. Each directory so named will be scanned
127 in the order given. The standard places are $HOME/.cook then
128 /usr/share/cook.
129 -Include_Cooked
131 This option may be used to require the cooking of files named
132 on #include-cooked and #include-cooked-nowarn include lines in
133 cookbooks. The files named will be included, if present. If
134 the files named need to be updated or created, this will be
135 done, and then the cookbook re-read. This is the default.
136 -No_Include_Cooked
138 This option may be used to inhibit the implicit cooking of
139 files named on #include-cooked and #include-cooked-nowarn
140 include lines in cookbooks. The files will be included, if
141 present, but they will not be updated or created, even if
142 required.
143 -Include_Cooked_Warning
145 This option enables the warnings about derived dependencies in
146 derived cookbooks. This is usually the default.
147 -No_Include_Cooked_Warning
149 This option disables the warnings about derived dependencies
150 in derived cookbooks.
151 -List
153 Causes cook to automatically redirect the stdout and stderr of
154 the session. Output will continue to come to the terminal,
155 unless cook is executing in the background. The name of the
156 file will be the name of the cookbook with any suffix removed
157 and ".list" appended; this will usually be Howto.list. This
158 is the default.
159 -List filename
161 Causes cook to automatically redirect the stdout and stderr of
162 the session into the named file. Output will continue to come
163 to the terminal, unless cook is executing in the background.
164 -No_List
166 No automatic redirection of the output of the session will be
167 made.
168 -No_List filename
170 No automatic redirection of the output of the session will be
171 made, however subsequent -List options will default to listing
172 to the named file.
173 -Meter
175 After each command is executed, print a summary of the
176 command's CPU usage.
177 -No_Meter
179 Do not print a CPU usage summary after each command. This is
180 the default.
181 -Pairs
183 This option may be used to generate a list of pair-wise file
184 dependencies, similar to lorder(1) output. This may be used
185 to draw file dependency diagrams. It can also be useful when
186 debugging cookbooks.
187 -PARallel [ number ]
189 This option may be used to specify the number of parallel
190 executions threads. The number defaults to 4 if no specific
191 number of threads is specified. See also the parallel_jobs
192 variable.
193 Use of this option on single-processor machines needs to be
195 done with great care, as it can bring other processing to a
196 complete halt. Several users doing so simultaneously on a
197 multi-processor machine will have a similar effect. It is
198 also to rapidly run out of virtual memory and temporary disk
199 space if the parallel tasks are complex.
200 -No_PARallel
202 This option may be used to specify that a single execution
203 thread is to be used. This is the default.
204 -Precious
206 When commands in the body of a recipe fail, do not delete the
207 targets of the recipe.
208 -No_Precious
210 When commands in the body of a recipe fail, delete the targets
211 of the recipe. This is the default.
212 -Reason
214 Two options are provided for tracing the inferences cook makes
215 when attempting to cook a target. The -Reason option will
216 cause cook will emit copious amounts of information about the
217 inferences it is making when cooking targets. This option may
218 be used when you think cook is acting strangely, or are just
219 curious.
220 -No_Reason
222 This option may be used to cause cook will not emit
223 information about the inferences it is making when cooking
224 targets. This is the default.
225 -SCript
227 This option may be used to request a shell script be printed
228 on the standard output. This shell script may be used to
229 construct the files; it captures many of the semantics of the
230 cookbook. This can be useful when a project needs to be
231 distributed, and the recipients do not have cook(1) installed.
232 It can also be very useful when debugging cookbooks.
233 -Silent
235 Do not echo commands before they are executed.
236 -No_Silent
238 Echo commands before they are executed. This is the default.
239 -STar
241 Emit progress indicators once a second. These progress
242 indicators include
243 + Reading the cookbook
245 - Executing a collect function
246 * Building the dependency graph
247 # Walking the dependency graph
248 @ Writing fingerprint files.
249 -No_STar
251 Do not emit progress indicators. This is the default.
252 -Strip_Dot
254 Remove leading "./" from filenames before attempting to cook
255 them; applies to all filenames and all recipes. This is the
256 default.
257 -No_Strip_Dot
259 Leave leading "./" on filenames while cooking.
260 -SymLink-Ingredients
262 The option asks that, when using a search path, that non-top-
263 level recipe ingredients get a top-level symlink to the actual
264 file. This is intended for brain dead tools, like GNU
265 Autoconf, that don't grok search paths.
266 -No-SymLink-Ingredients
268 Do not creatye top leve symlinks to ingredients. This is the
269 default.
270 -Tell_Position
272 This option may be used to cause the position of commands
273 (filename and line number) to be printed along with the
274 command just before it is executed (provided the -No_Silent
275 option is in force).
276 -No_Tell_Position
278 This option may be used to suppress printing the position of
279 commands (filename and line number) along with the command
280 just before it is executed. This is the default.
281 -Touch
283 Update the last-modified times of the target files, rather
284 than execute the actions bound to recipes. This can be useful
285 if you have made a modification to a file that you know will
286 make a system of files logically out of date, but has no
287 significance; for example, adding a comment to a widely used
288 include file.
289 -No_Touch
291 Execute the actions bound to recipes, rather than update the
292 last-modified times of the target files. This is the default.
293 -TErminal
295 When listing, also send the output stream to the terminal.
296 This is the default.
297 -No_TErminal
299 When listing, do not send the output to the terminal.
300 -Time_Adjust
302 This option causes cook to check the last-modified time of the
303 targets of recipes, and updates them if necessary, to make
304 sure they are consistent with (younger than) the last-modified
305 times of the ingredients. This results in more system calls,
306 and can slow things down on some systems. This correspondes
307 to the time-adjust recipe flag.
308 -No_Time_Adjust
310 Do not update the file last-modified times after performing
311 the body of a recipe. This is the default. This correspondes
312 to the no-time-adjust recipe flag.
313 -Web
315 This option may be used to request a HTML web page be printed
316 on the standard output. This web page may be used to document
317 the file dependencies; it captures many of the semantics of
318 the cookbook. It can also be very useful when debugging
319 cookbooks.
320 name=value
322 Assign the value to the named variable. The value may contain
323 spaces if you can convince the shell to pass them through.
324 All options may be abbreviated; the abbreviation is documented as the
326 upper case letters, all lower case letters and underscores (_) are
327 optional. You must use consecutive sequences of optional letters.
328 All options are case insensitive, you may type them in upper case or
330 lower case or a combination of both, case is not important.
331 For example: the arguments "-help", "-HEL" and "-h" are all
333 interpreted to mean the -Help option. The argument "-hlp" will not be
334 understood, because consecutive optional characters were not supplied.
335 Options and other command line arguments may be mixed arbitrarily on
337 the command line.
338 The GNU long option names are understood. Since all option names for
340 cook are long, this means ignoring the extra leading '-'. The
341 "--option=value" convention is also understood.
342
344 The cook command will exit with a status of 1 on any error. The cook
345 command will only exit with a status of 0 if there are no errors.
346
348 The following files are used by cook:
349 Howto.cook
351 This file contains instructions to cook for how to construct
352 files.
353 /usr/share/cook
355 This directory contains "system" cookbooks for various tools
356 and activities.
357 .cook.fp
359 This text file is used to remember fingerprints between
360 invokations.
361
363 The following environment variables are used by cook:
364 COOK May be set to contain command-line options, changing the
366 default behaviour of cook. May be overridden by the command
367 line.
368 PAGER Use to paginate the output of the -Help and -VERSion options.
370 Defaults to more(1) if not set.
371 COOK_AUTOMOUNT_POINTS
373 A colon-separated list of directories which the automounter
374 may use to mount file systems. Use with extreme care, as this
375 distorts Cook's idea of the shape of the filesystem.
376 This feature assumes that paths below the automounter's mount
378 directory are echoes of paths without it. E.g. When /home is
379 the trigger, and /tmp_mnt/home is where the on-demand NFS
380 mount is performed, with /home appearing to processes to be a
381 symlink.
382 This is the behavior of the Sun automounter. The AMD
384 automounter is capable of being configured in this way, though
385 it is not typical of the examples in the manual. Nor is it
386 typical of the out-of-the-box Linux AMD configuration in many
387 distributions.
388 Defauls to ``/tmp_mnt:/a:/.automount'' if not set.
390
392 cook version 2.30
393 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
394 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Peter
395 Miller; All rights reserved.
396 The cook program comes with ABSOLUTELY NO WARRANTY; for details use
398 the 'cook -VERSion License' command. This is free software and you
399 are welcome to redistribute it under certain conditions; for details
400 use the 'cook -VERSion License' command.
401
403 Peter Miller E-Mail: millerp@canb.auug.org.au
404 /\/\* WWW: http://www.canb.auug.org.au/~millerp/
405Reference Manual Cook COOK(1)