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

NAME

6       cook - a file construction tool
7

SYNOPSIS

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

DESCRIPTION

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
21       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
27       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
32       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
36       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
41       If no filenames are given on the command line the targets of the  first
42       recipe defined are cooked.
43

OPTIONS

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
49       -Action
50               Execute  the  commands  given  in  the  recipes.   This  is the
51               default.
52
53       -No_Action
54               Do not execute the commands given in the recipes.
55
56       -Book filename
57               Tells  to used the named  cookbook,  rather  than  the  default
58               ``Howto.cook'' file.
59
60       -CAScade
61               This  option may be used to enable the use of cascaded ingredi‐
62               ents.  This is the default.
63
64       -No_CAScade
65               This option may be used to disable the use of cascaded ingredi‐
66               ents.
67
68       -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
73       -No_Continue
74               If  cooking  a  target  should  fail,  will  exit.  This is the
75               default.
76
77       -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
82       -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
88       -Errok
89               When a command is executed, the exit code will be ignored.
90
91       -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
96       -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
109       -No_FingerPrint
110               Do not use fingerprints to supplement  the  last-modified  time
111               file information.  This is the default.
112
113       -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
119       -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
125       -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
129       -Help
130               Provide information about how to execute on stdout, and perform
131               no other function.
132
133       -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
138       -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
145       -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
152       -Include_Cooked_Warning
153               This  option enables the warnings about derived dependencies in
154               derived cookbooks.  This is usually the default.
155
156       -No_Include_Cooked_Warning
157               This option disables the warnings about derived dependencies in
158               derived cookbooks.
159
160       -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
168       -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
173       -No_List
174               No automatic redirection of the output of the session  will  be
175               made.
176
177       -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
182       -Meter
183               After  each  command  is  executed, print a summary of the com‐
184               mand's CPU usage.
185
186       -No_Meter
187               Do not print a CPU usage summary after each command.   This  is
188               the default.
189
190       -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
196       -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
207       -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
213               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
220       -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
224       -Precious
225               When  commands  in the body of a recipe fail, do not delete the
226               targets of the recipe.
227
228       -No_Precious
229               When commands in the body of a recipe fail, delete the  targets
230               of the recipe.  This is the default.
231
232       -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
239       -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
244       -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
252       -Silent
253               Do not echo commands before they are executed.
254
255       -No_Silent
256               Echo commands before they are executed.  This is the default.
257
258       -STar
259               Emit progress indicators once a second.  These progress indica‐
260               tors include
261
262                          +       Reading the cookbook
263                          -       Executing a collect function
264
265                          *       Building the dependency graph
266                          #       Walking the dependency graph
267                          @       Writing fingerprint files.
268
269       -No_STar
270               Do not emit progress indicators.  This is the default.
271
272       -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
277       -No_Strip_Dot
278               Leave leading "./" on filenames while cooking.
279
280       -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
286       -No-SymLink-Ingredients
287               Do not create top level symlinks to ingredients.  This  is  the
288               default.
289
290       -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
296       -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
301       -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
309       -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
313       -TErminal
314               When listing, also send the  output  stream  to  the  terminal.
315               This is the default.
316
317       -No_TErminal
318               When listing, do not send the output to the terminal.
319
320       -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
328       -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
333       -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
339       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

FILES

344       The following files are used by cook:
345
346       Howto.cook
347               This file contains instructions to cook for  how  to  construct
348               files.
349
350               This  directory  contains  "system" cookbooks for various tools
351               and activities.
352
353       .cook.fp
354               This text file is used to remember fingerprints between invoca‐
355               tions.
356

ENVIRONMENT VARIABLES

358       The following environment variables are used by cook:
359
360       COOK   May be set to contain command-line options, changing the default
361              behavior of cook.  May be overridden by the command line.
362
363       PAGER   Use to paginate the output of the -Help and  -VERSion  options.
364               Defaults to more(1) if not set.
365
366       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
371               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
377               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
383               Defaults to ``/tmp_mnt:/a:/.automount'' if not set.
384
385
386
387Reference Manual                     Cook                              COOK(1)
Impressum