1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734
|
Read Me(Cook) Read Me(Cook)
NAME
cook - a file construction tool
DESCRIPTION
The cook program is a tool for constructing files, and
maintaining referential integrity between files. It is
given a set of files to create, and recipes of how to
create and maintain them. In any non-trivial program
there will be prerequisites to performing the actions
necessary to creating any file, such as include files.
The cook program provides a mechanism to define these.
When a program is being developed or maintained, the
programmer will typically change one file of several which
comprise the program. The cook program examines the last-
modified times of the files to see when the prerequisites
of a file have changed, implying that the file needs to be
recreated as it is logically out of date.
The cook program also provides a facility for implicit
recipes, allowing users to specify how to form a file with
a given suffix from a file with a different suffix. For
example, to create filename.o from filename.c
* Cook is a replacement for * There is a make2cook
the traditional make(1) utility included in the
tool. distribution to help
* Cook is more powerful convert makefiles into
than the traditional make cookbooks.
tool.
* Cook has true variables, * Cook has a simple but
not simple macros. powerful string-based
* Cook has user defined description language with
functions. many built-in functions.
This allows sophisticated
filename specification and
manipulation without loss
of readability or
performance.
* Cook can build in * Cook is able to build
parallel. your project with multiple
* Cook can distribute parallel threads, with
builds across your LAN. support for rules which
must be single threaded.
It is possible to
distribute parallel builds
over your LAN, allowing you
to turn your network into a
virtual parallel build
engine.
Reference Manual Cook 1
Read Me(Cook) Read Me(Cook)
* Cook is able to use * Cook can be configured
fingerprints to supplement with an explicit list of
file modification times. primary source files. This
This allows build allow the dependency graph
optimization without to be constructed faster by
contorted rules. not going down dead ends,
* In addition to walking and also allows better
the dependency graph, Cook error messages when the
can turn the input rules graph can't be constructed.
into a shell script, or a This requires an accurate
web page. source file manifest.
* Cook runs on almost any * Cook has special cascade
flavor of UNIX. The source dependencies, allowing
distribution is self powerful include dependency
configuring using a GNU specification, amongst
Autoconf generated other things.
configure script.
If you are putting together a source-code distribution and
planning to write a makefile, consider writing a cookbook
instead. Although Cook takes a day or two to learn, it is
much more powerful and a bit more intuitave than the
traditional make(1) tool. And Cook doesn't interpret tab
differently to 8 space characters!
ARCHIVE SITE
The latest version of cook is available on the Web from:
URL: http://www.canb.auug.org.au/~millerp/cook/
File: cook-2.10.README # the README from the tar file
File: cook-2.10.lsm # LSM format description
File: cook-2.10.spec # RedHat package specification
File: cook-2.10.rm.ps.gz # PostScript of the Reference Manual
File: cook-2.10.ug.ps.gz # PostScript of the User Guide
File: cook-2.10.tar.gz # the complete source
This Web page also contains a few other pieces of software
written by me. Please have a look if you are interested.
Cook is also carried by sunsite.unc.edu in its Linux
archives. You will be able to find Cook on any of its
mirrors.
URL: ftp://sunsite.unc.edu/pub/Linux/devel/make/
File: cook-2.10.README # the README from the tar file
File: cook-2.10.lsm # LSM format description
File: cook-2.10.spec # RedHat package specification
File: cook-2.10.rm.ps.gz # PostScript of the Reference Manual
File: cook-2.10.ug.ps.gz # PostScript of the User Guide
File: cook-2.10.tar.gz # the complete source
This site is extensively mirrored around the world, so
look for a copy near you (you will get much better
response).
Reference Manual Cook 2
Read Me(Cook) Read Me(Cook)
MAILING LIST
A mailing list has been created so that users of cook may
exchange ideas about how to use the cook program.
Discussion may include, but is not limited to: bugs,
enhancements, and applications. The list is not
moderated.
The address of the mailing list is
cook-users@canb.auug.org.au
Please DO NOT send subscribe requests to this address.
To subscribe to this mailing list, send an email message
to majordomo@canb.auug.org.au with a message body
containing the single line
subscribe cook-users
If you have an email address which is not readily derived
from your mail headers (majordomo is only a Perl program,
after all) you will need to use a message of the form:
subscribe cook-users address
where address is the email address to which you want
messages sent.
The software which handles this mailing list CANNOT send
you a copy of the cook program.
BUILDING COOK
Full instructions for building the cook program may be
found in the BUILDING file included in this distribution.
COPYRIGHT
cook version 2.10
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994,
1995, 1996, 1997, 1998, 1999 Peter Miller; All rights
reserved.
This program is free software; you can redistribute it
and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation;
either version 2 of the License, or (at your option) any
later version.
This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public License for more
details.
You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330,
Boston, MA 02111, USA.
It should be in the LICENSE file included with this
distribution.
Reference Manual Cook 3
Read Me(Cook) Read Me(Cook)
AUTHOR
Peter Miller E-Mail: millerp@canb.auug.org.au
/\/\* WWW: http://www.canb.auug.org.au/~millerp/
Reference Manual Cook 4
Read Me(Cook) Read Me(Cook)
NEW IN THIS RELEASE
A number of features have been added to cook with this
release. The following list is only a summary; for
excruciating detail, and also acknowlegements of those who
generously sent me feedback, please see the etc/CHANGES.*
files included in this distribution.
Version 2.10
* The [print] and [write] functions now work more sensably
with the -SCript option.
* The fingerprint code has been improved. It now does
considerably fewer redundant fingeprint calculations,
resulting is some very welcome speed improvements.
* The behaviour of the remote shell invocation to cope
with rshd at the remote end failing to spawn a shell, and
it copes with the default shell at the remote end not
being the Bourne shell.
* The -PARallel behaviour has been improved, so that it
now looks for child process who have finished more than it
looks for recipes to run. This doesn't change the
semantics any, but it matches user expectations far better
(and results in shorter-lived zombie processes).
* The set meter recipe flag works once more. (It stopped
working when the parallel modifications were made, and
mysteriously forgotten until now.)
* There are some changes made to the fingerprinting code
to detect when files under ClearCase move backwards in
time (because the underlying file version is
``uncovered'') meaning that the derived (object) files
need to be rebuilt.
* There is a new [mtime-seconds] function, similar to the
[mtime] function, except that it returns seconds since the
epoch, rather than a human readable date. More useful to
handing to [expr].
* A bug has been fixed on SGI IRIX which failed to cope
with not being able to create directories because they
already exist.
* Ingredient recipes (ones with no body) may now have a
double colon rather than a single colon, even when there
is more than on target specified. Some users may find
this a more natural syntax for ingredients recipes.
* The [expr] function now reports an error when given a
number too big to represent, rather than quietly returning
wrong answers. The range of representable values depends
on your system.
Reference Manual Cook 5
Read Me(Cook) Read Me(Cook)
* Cook now works with GNU Regex correctly on Windows-NT.
Version 2.9
* There is a new ``for each'' style looping construct.
See the User Guide for more information.
* It is now possible to use regular expression patterns,
instead of Cook's native patterns. You can set this for a
whole cookbook or individual recipes. The default is to
use Cook's native patterns. See the File Name Patterns
chapter of the User Guide for more information.
* A bug which caused host-binding and single-thread to
core dump has been fixed.
* All text file input now copes with CRLF sequences, so
mixing NT and Unix builds on the one file server no longer
creates problems.
* Fingerprints are now cached per-directory, rather than
one huge file for an entire directory tree. This is more
useful in recursive build and [search_list] situations.
* The [cando], [cook] and [uptodate] functions now return
lists of successful files, rather than a simple true/false
result.
* The [in] and [matches] functions now return the list
index (1 based) of the matching word. See the User Guide
for more information.
* There is a new cook -web option, to print a HTML web
page on the standard output, representing the dependency
graph. This is useful in documenting the build process,
or debugging cookbooks.
* There is a new cook --fingerprint-update option which
scans the directory tree below the current directory and
updates the file fingerprints. This helps when you use
another tool (such as RCS or ClearCase) which alters the
file but preserves the file's modification time.
* There is a new [write] function for writing text files.
This is useful for coping with Windows-NT's absurdly short
command lines.
Version 2.8
Reference Manual Cook 6
Read Me(Cook) Read Me(Cook)
* The remote host-binding code has been improved to cope
with staggeringly long commands (which tended to make
rsh(1) barf), and also wierd and wonderfull $SHELL
settings.
* The #include directive now accepts more than one file,
to be more symmetric with the #include-cooked directive.
* A bug has been fixed where cooktime gave an incorrect
error message if setting the file's utimes failed.
* The configure script has been improved for use on non-
UNIX systems.
* There is a new builtin [cook] function, a natural
companion for the [cando] and [uptodate] functions. See
the Cook User Guide for more information.
Version 2.7
* There is a new cook_bom(1) command (Bill Of Materials).
This may be used to efficiently scan a directory tree for
files, so that ingredients lists may be produced
automatically. See cook_bom(1) for more information.
* There is a new assign-append statement, so you can now
use += to append to the value of a variable. See the User
Guide for more information.
* There is a new gate-first recipe flag, which causes the
recipe gate to be evaluated before the ingredients are
derived, rather than after.
* The c_incl(1) command has a new --interior-files option,
so you can tell it about include files that don't exist
yet. This is helpful when they are generated, i.e. they
are interior files of the dependency graph, hence the
option name.
* There is a new [interior-files] function, which returns
the files interior to the dependency graph (constructed by
a recipe), and a complementatry [leaf-files] function,
which returns the leaf files of the dependency graph (not
constructed by any recipe).
* There is a new ``no-include-cooked-warning'' flag, if
you want to suppress the warnings about derived file
dependencies in include-cooked files.
* There is a new relative_dirname built-in function,
similar to the existing dirname function, but it returns
``.'' for files with no directory part, rather than the
absolute path of the current directory.
Reference Manual Cook 7
Read Me(Cook) Read Me(Cook)
Version 2.6
* Cook has been ported to Windows-NT using CygWin32. See
the BUILDING file for details.
* There are two new functions (dos-path and un-dos-path)
for use when invoking non-CygWin32 WindowsNT programs.
See the Cook User Guide for more information.
* Fingerprints now work meaningfully with directories.
* A bug has been fixed in the pattern matching code. It
would sometimes cause core dumps.
* A bug involving fingerprints in combination with the
search_list has been fixed. Cook would occasionally
conclude that a shallow target was up-to-date when a
shallow ingredient was edited to be the same as a deeper
ingredient.
* A bug has been fixed in cooktime. It would use an
inappropriate timezone offset on some systems.
Release 2.5
* A problem which caused some tests to fail on Solaris'
tmpfs now has a work-around.
* The ``setenv'' statement has finally been documented.
It's been in the code tfor years, but I could never figure
out why folks weren't using it!
* A number of build problems on various systems have been
fixed.
Release 2.4
* There is a new form of dependencies. Known as cascaded
dependencies, they allow the user to associate additional
dependencies with an ingredient. For example, a C source
file can be associated with cascaded include dependencies.
This means that all files which depend on the C source
file, also depend on the included files. The Cook
Reference Manual has been updated to include this new
functionality.
* There is a new section of the Cook Reference Manual
giving suggestions and a template for building large
projects.
* There is a new [expr] function, to calculate simple
arithmetic expressions. See the User Guide for more
information.
* There is a new c_incl -no-recursion option, to prevent
scanning nested includes. This is of most use when
combined with the new cascade dependencies.
Reference Manual Cook 8
Read Me(Cook) Read Me(Cook)
* There is a new [exists-symlink] function, which may be
used to test for the existence of symlinks. The [exists]
function follows symbolic links, and is not useful when
manipulating the links themselves.
Release 2.3
* There are 6 new special variables: graph_leaf_file,
graph_leaf_pattern, graph_interior_file,
graph_interior_pattern, graph_exterior_file and
graph_exterior_pattern. These variables may be used to
define the leaves of the derivation graph (the accept
forms), and non-leave of the graph (the reject forms).
This can make the graph derivation faster, and greatly
improves some error messages. This functionality is of
most use when you have an exact source file manifest, e.g.
from a software configuration management system. See the
User Guide for more information.
* The %0 pattern element has been extended to permit the
matching of absolute paths.
Release 2.2.2
* There is a new statement type, allowing functions to be
invoked as subroutines in any place where a command may be
invoked. See the User Guide for more information.
* A number of problems with installing Cook have been
fixed. This includes changing -mgm to -mm for the
documnetation formatting, and missing include dependencies
and missing rules for installing the man pages.
* There is a new ``print'' builtin function. When
combined with the new function call statement, this
provides a way of printing information without invoking
``echo''. See the User Guide for more information.
* Cook now defaults the language to ``en'' internally if
neoither the LANG nor LANGUAGE environment variable was
set. This gives better error messages.
Release 2.2.1
* A bug was fixed where a recipe would fail to trigger if
some, but not all, of its targets were not present, but
the existing targets were up-to-date. This bug was
introduced in the inference engine re-write.
Release 2.2
Reference Manual Cook 9
Read Me(Cook) Read Me(Cook)
* The c_incl utility has had two new languages added. It
now understands M4, and also has an ``optimistic''
language which can scan many assemblers and even some
high-level languages. See c_incl(1) for more information.
* The c_incl utility also has a new --no-absolute-path
option, to supress scanning and reporting of such files.
See c_incl(1) for more information.
* There is a new warning added for dependencies on derived
ingredients when this information resides solely in
derived cookbooks included using the #include-cooked
facility. This assists in detecting problems which may
preclude a successful ``clean'' build.
* This release adds a number of cookbook functions to the
distrubuted cookbooks. These may be used by adding a
#include "functions"
line to your cookbook. See the Cook User Guide for more
information.
* This release fixes a bug where the graph walking phase
ignored interrupts until something went wrong.
* This release fixes a bug where make2cook did not
correctly translate ``%'' into sematicly equivalent Cook
constructs.
Release 2.1
* It is possible to specify that a command is to be
executed on a specific machine or machines. This can be
useful for restrictively licensed third party software
tools.
* The parallel functionality has been extended to
implement a virtual parallel machine on a LAN.
* Fingerprinting has been enhanced to be more informative,
and to adjust file modification times so that subsequest
fingerprint-less runs will not find too much to do.
* The #line directive is now available, for better
diagnostics of generated cookbooks. The __FILE__ and
__LINE__ variable are also available.
* There is now a thread-id variable, to obtain a thread-
unique value for use in generating temporary file names or
variable names, etc, which are unique to a thread.
* Added the wordlist function and the command-line-goals
variable for compatibility with GNU Make. Updated
make2cook to understand them.
Reference Manual Cook 10
Read Me(Cook) Read Me(Cook)
Release 2.0.1
* An install problem in the generated Makefile, to do with
the the manuals, has been fixed.
Release 2.0
Development of this release was generously supported by
Endocardial Solutions, Inc.
* Parallel execution is now supported. If you have a
multi-processor machine, you can specify the number of
parallel processing threads with the -PARallel command
line option, or via the [parallel_jobs] variable. By
using the [os node] function, the [parallel_jobs] variable
can be set appropriately for the host machine
automatically by the cookbook. There is a new single-
thread keyword to support single threading recipes which
cannot be paralleized.
* The dependency graph is now constructed differently.
This gives exactly the same results, but the order of
evaluation of recipes is a little more random. This
different graph construction is able to give better error
messages, better -Reason information, and allows the
introduction of parallel recipe evaluation if you have a
multi-processor computer.
* Recipes which use c_incl(1) to calculate their
dependencies in the ingredients section will need a small
modification - they will need to use the --Absent-Program-
Ignore option. See the User Guide for more information.
* You can now print pair-wise file dependencies by using
the -PAirs option.
* You can now print a shell script which approximates the
actions cook would take when building the targets by using
the -SCript option.
* There is a new ``shallow'' recipe flag, allowing you to
specify that the targets of a recipe are required to be in
the top-level directory, not further down the search_list
path.
* You may now define user-written functions in the
cookbook to supplement the built-in functions. Your
functions will be called in the same manner as built-in
functions. There are new function and return keywords to
support definition of functions.
* The progress indicators produced by the -STar option now
have more detail: + means that the cook book is being
read, * means that the graph is being constructed, and #
means that the graph is being walked.
Reference Manual Cook 11
Read Me(Cook) Read Me(Cook)
Release 1.11
* Fixed a bug in the pattern matching which caused %0
(when not at the start of the pattern) to fail to match
the empty string.
* The install locations have been changed slightly to
conform better to the GNU filesystem standards, and to
take advantage of the additional install location options
of the configure scripts generated by GNU Autoconf.
Release 1.10
* Error messages have been internationalized. It is now
possible to get error messages in your native language, if
it is supported.
* The cook command now accepts a -no-include-cooked
option, to disable any cooking of the #include-cooked
files.
* The cook -TRace option has been renamed -Reason. This
is thought to more accurately reflect what it does.
* The cook -Reason output has been changed to cite
cookbook file names and line numbers, in order to be more
useful. In addition, more reason messages carry location
information.
Release 1.9
* There are new ``f77'' and ``g77'' cookbooks, to allow
Fortran sources, in addition to C sources.
* There is a new [options] function, which expands to the
current settings of the command line options. This is
useful for recursive cook directory structures. See the
Reference Manual for more information.
* There is a new ``recursive'' cookbook, to assist in
constructing recursive cook structures.
* The find_libs program now understands about shared
libraries.
* A bug which made the builtin [glob] function far to
generous has been corrected.
* A bug which caused some expression evaluation errors to
be ignored has been corrected.
* The ``set update'' flag has been re-named the ``set
time-adjust'' flag, to more closely describe what it does.
The old name will continue to work indefinitely.
* There is a new ``set time-adjust-back'' flag, which sets
recipe target times to be exactly one (1) second younger
Reference Manual Cook 12
Read Me(Cook) Read Me(Cook)
than the youngest ingredient. This is usually an
adjustment into the recent past.
Release 1.8
* The fingerprint code has been improved to work better
with the search_list functionality.
* The diagnostics have been improved when cook ``don't
know how''. A list of attempted ingredients is included
in the error message.
* There is a new mkdir recipe flag. This creates recipe
target directories before the recipe body is run. See the
Reference Manual for more information.
* There is a new unlink recipe flag. This unlinks recipe
targets before the recipe body is run. See the Reference
Manual for more information.
* There is a new recurse recipe flag. This overrides the
infinite loop recipe heuristic, allowing recipes to recuse
upon themselves if one of their ingredients matches one of
their targets. See the Reference Manual for more
information.
Release 1.7
* The AIX code to handle archive files has been fixed.
* The fingerprint code now works on 64-bit systems.
Release 1.6
* Fixed a bug in the leading-dot removal code, and added
an option to make it user-settable. Fixed a bug in the
search_path depth code.
Release 1.5
* The c_incl program now correctly prints the names of
absent include files, causing them to be cooked correctly
in a greater number of cases.
* Recipes with no ingredients are now only applied if the
target is absent. To still use the previous behaviour,
use the "set force" clause on the recipe.
* It is now possible to supplement the last-modified time
with a fingerprint, so cook does even fewer unnecesary
recompilations than before. Put the statement
set fingerprint;
somewhere near the top of your Howto.cook file for this to
be the default for your project.
* There is a new form of include directive:
#include-cooked filename...
When files are included in this way, cook will check to
Reference Manual Cook 13
Read Me(Cook) Read Me(Cook)
make sure they are up-to-date. If not, they will be
cooked, and then cook will start again and re-read the
cookbook. This is most often used for maintaining
include-dependency files.
* Cook now configured using a program called configure,
distributed with the package. The configure program is
generated by GNU Autoconf. See the BUILDING file for more
details.
* The semantics of search_list have been improved. It is
now guaranteed that when ingredients change they result in
targets earlier in the search_list being updated.
* There is now a make2cook translator, to translate
Makefile files into Howto.cook files. Most of the GNU
Make extensions are understood. There is no exact
semantic mapping between make and cook, so manual editing
is sometimes required. See make2cook(1) for more
information.
* Cook now understands archive member references, in the
same format as used by make, et al. Archive member
references benefit from stat caching and fingerprinting,
just as normal files do.
Release 1.4
* The cook program is now known to work on more systems.
Most changes were aimed at improving portability, or
avoiding problems specific to some systems.
* The GNU long option name convention is now understood.
Option names for cook were always long, so this mostly
consists of ignoring the extra leading '-'. The
"--foo=bar" convention is also understood for options with
arguments.
* Tests which fail now tell you what it was they were
testing for. This will give the user some idea of what is
happening.
Reference Manual Cook 14
|