1Build(Cook) Build(Cook) 2 3NAME 4 cook - a file construction tool 5 6SPACE REQUIREMENTS 7 You will need about 5MB to unpack and build the Cook package. Your 8 mileage may vary. 9 10BEFORE YOU START 11 There are a few pieces of software you may want to fetch and install 12 before you proceed with your installation of Cook. 13 14 Please note: if you install these packages into /usr/local (for 15 example) you must ensure that the ./configure script is told to also 16 look in /usr/local/include for include files (CFLAGS), and 17 /usr/local/lib for library files (LDFLAGS). Otherwise the ./configure 18 script will incorrectly conclude that they have not been installed. 19 20 ANSI C compiler 21 You will need an ANSI C compiler to be able to compile cook. 22 If you don't have one, you may wish to consider installing the 23 GNU C compiler, it's free. 24 25 GNU Gettext 26 The Cook package has been internationalized. It can now print 27 error messages in any of the supported languages. In order to 28 do this, the GNU Gettext package must be installed before you 29 run the configure script as detailed in the next section. 30 This is because the configure script looks for it. On systems 31 which use the GNU C library, version 2.0 or later, there is no 32 need to explicitly do this as GNU Gettext is included. 33 Remember to use the GNU Gettext configure --with-gnu-gettext 34 option if your system has native gettext tools. 35 36 GNU rx 37 Cook needs regular expressions to operate correctly. Get a 38 copy from your nearest GNU mirror. On systems which use the 39 GNU C library, version 2.0 or later, there is no need to 40 explicitly do this as GNU rx is included. 41 42 GNU Groff 43 The documentation for the Cook package was prepared using the 44 GNU Groff package. This distribution includes full 45 documentation, which may be processed into PostScript or DVI 46 files at install time - if GNU Groff has been installed. You 47 must use GNU Groff version 1.15 or later. 48 49 On Solaris, you may need to edit the Makefile to change the 50 groff -man and -mm options to -mgan and -mgm instead. 51 52 Bison If your operating system does not have a native yacc(1) you 53 will need to fetch and install GNU Bison in order to build the 54 Cook package. 55 56 GCC You may also want to consider fetching and installing the GNU 57 C Compiler if you have not done so already. This is not 58 essential. 59 60 The GNU FTP archives may be found at ftp.gnu.org, and are mirrored 61 around the world. 62 63SITE CONFIGURATION 64 The Cook package is configured using the configure program included in 65 this distribution. 66 67 The configure shell script attempts to guess correct values for 68 various system-dependent variables used during compilation, and 69 creates the Makefile and common/config.h files. It also creates a 70 shell script config.status that you can run in the future to recreate 71 the current configuration. 72 73 Normally, you just cd to the directory containing Cook's source code 74 and type 75 % ./configure 76 ...lots of output... 77 % 78 If you're using csh on an old version of System V, you might need to 79 type 80 % sh configure 81 ...lots of output... 82 % 83 instead to prevent csh from trying to execute configure itself. 84 85 Running configure takes a minute or two. While it is running, it 86 prints some messages that tell what it is doing. If you don't want to 87 see the messages, run configure using the quiet option; for example, 88 % ./configure --quiet 89 % 90 91 There is a known problem with GCC 2.8.3 and HP/UX. You will need to 92 set CFLAGS = -O in the generated Makefile. (The configure script sets 93 it to CFLAGS = -O2.) This is because the code optimization breaks the 94 fingerprints. If test 46 fails (see below) this is probably the 95 reason. 96 97 To compile the Cook package in a different directory from the one 98 containing the source code, you must use a version of make that 99 supports the VPATH variable, such as GNU make. cd to the directory 100 where you want the object files and executables to go and run the 101 configure script. configure automatically checks for the source code 102 in the directory that configure is in and in .. (the parent 103 directory). If for some reason configure is not in the source code 104 directory that you are configuring, then it will report that it can't 105 find the source code. In that case, run configure with the option 106 --srcdir=DIR, where DIR is the directory that contains the source 107 code. 108 109 By default, configure will arrange for the make install command to 110 install the Cook package's files in /usr/local/bin, /usr/local/lib, 111 /usr/local/share and /usr/local/man. There are a number of options 112 which allow you to control the placement of these files. 113 114 --prefix=PATH 115 This specifies the path prefix to be used in the installation. 116 Defaults to /usr/local unless otherwise specified. 117 118 --exec-prefix=PATH 119 You can specify separate installation prefixes for 120 architecture-specific files files. Defaults to ${prefix} 121 unless otherwise specified. 122 123 --bindir=PATH 124 This directory contains executable programs. On a network, 125 this directory may be shared between machines with identical 126 hardware and operating systems; it may be mounted read-only. 127 Defaults to ${exec_prefix}/bin unless otherwise specified. 128 129 --datadir=PATH 130 This directory contains installed data, such as the 131 documentation and cookbooks distributed with Cook. On a 132 network, this directory may be shared between all machines; it 133 may be mounted read-only. Defaults to ${prefix}/share/cook 134 unless otherwise specified. A ``cook'' directory will be 135 appended if there is none in the specified path. 136 137 --libdir=PATH 138 This directory contains installed data. On a network, this 139 directory may be shared between machines with identical 140 hardware and operating systems; it may be mounted read-only. 141 Defaults to ${exec_prefix}/lib/cook unless otherwise 142 specified. A ``cook'' directory will be appended if there is 143 none in the specified path. 144 145 --mandir=PATH 146 This directory contains the on-line manual entries. On a 147 network, this directory may be shared between all machines; it 148 may be mounted read-only. Defaults to ${prefix}/man unless 149 otherwise specified. 150 151 --with-nlsdir=PATH 152 This directory contains the install error message catalogues. 153 On a network, this directory may be shared between machines 154 with identical hardware and operating systems; it may be 155 mounted read-only. Defaults to --libdir unless otherwise 156 specified. 157 158 configure ignores most other arguments that you give it; use the 159 --help option for a complete list. 160 161 On systems that require unusual options for compilation or linking 162 that the Cook package's configure script does not know about, you can 163 give configure initial values for variables by setting them in the 164 environment. In Bourne-compatible shells, you can do that on the 165 command line like this: 166 $ CC='gcc -traditional' LIBS=-lposix ./configure 167 ...lots of output... 168 $ 169 Here are the make variables that you might want to override with 170 environment variables when running configure. 171 172 Variable: CC 173 C compiler program. The default is cc. 174 175 Variable: CPPFLAGS 176 Preprocessor flags, commonly defines and include search paths. 177 Defaults to empty. It is common to use 178 CFLAGS=-I/usr/local/include to access other installed 179 packages. 180 181 Variable: INSTALL 182 Program to use to install files. The default is install if 183 you have it, cp otherwise. 184 185 Variable: LIBS 186 Libraries to link with, in the form -lfoo -lbar. The 187 configure script will append to this, rather than replace it. 188 It is common to use LIBS=-L/usr/local/lib to access other 189 installed packages. 190 191 Variable: NLSDIR 192 Similar to the --with-nlsdir option. 193 194 If you need to do unusual things to compile the package, the author 195 encourages you to figure out how configure could check whether to do 196 them, and mail diffs or instructions to the author so that they can be 197 included in the next release. 198 199BUILDING COOK 200 All you should need to do is use the 201 % make 202 ...lots of output... 203 % 204 command and wait. When this finishes you should see a directory 205 called bin containing nine files: c_incl, cook, cookfp, cooktime, 206 find_libs, make2cook and roffpp. 207 208 cook cook program is a file construction tool, and may invoke the 209 following tools in some of its recipes. 210 211 cookfp The cookfp program is a utility distributed with Cook which 212 calculates the fingerprints of files. It uses the same 213 algorithm as the fingerprints used by cook itself. For more 214 information, see cook(1) and cookfp(1). 215 216 cooktime 217 The cooktime program is a utility distributed with Cook which 218 allows the time-last-modified and time-last-accessed stamps of 219 files to be set to specific times. For more information, see 220 cooktime(1). 221 222 c_incl The c_incl program is a utility distributed with Cook which 223 examines C files and determines all the files it includes 224 directly and indirectly. For more information, see c_incl(1). 225 226 find_libs 227 The find_libs program is a utility distributed with Cook which 228 tracks down the names of library files, given cc-style library 229 options (-L and -l). For more information, see find_libs(1). 230 231 make2cook 232 The make2cook program is a utility to help convert Makefiles 233 into cookbooks. An exact 1:1 semantic mapping is not 234 possible, so some addition editing is often required. 235 236 roffpp The roffpp program is a utility distributed with Cook which 237 acts as a preprocessor for *roff files, removing source (.so) 238 directives. It accepts include search path command line 239 options just as /lib/cpp does. For more information, see 240 roffpp(1). 241 242 You can remove the program binaries and object files from the source 243 directory by using the 244 % make clean 245 ...lots of output... 246 % 247 command. To remove all of the above files, and also remove the 248 Makefile and common/config.h and config.status files, use the 249 % make distclean 250 ...lots of output... 251 % 252 command. 253 254 The file etc/configure.in is used to create configure by a GNU program 255 called autoconf. You only need to know this if you want to regenerate 256 configure using a newer version of autoconf. 257 258TESTING COOK 259 The Cook program comes with a test suite. To run this test suite, use 260 the command 261 % make sure 262 ...lots of output... 263 Passed All Tests 264 % 265 266 The tests take a few seconds each, with a few very fast, and a couple 267 very slow, but it varies greatly depending on your CPU. 268 269 If all went well, the message 270 Passed All Tests 271 should appear at the end of the make. 272 273 Known Problems 274 If test 46 fails, this is often caused by optimization bugs in gcc. 275 Edit the Makefile to change -O2 to -O, and delete common/fp/*.o to 276 cause them to be re-built. Make and test again. 277 278 If you are using Sun's tmpfs file system as your /tmp directory, some 279 tests will fail. This is because the tmpfs file system does not 280 support file locking. Set the COOK_TMP environment variable to 281 somewhere else before running the tests. Something like 282 % setenv COOK_TMP /usr/tmp 283 % 284 is usually sufficient if you are using C shell, or 285 $ COOK_TMP=/usr/tmp 286 $ export COOK_TMP 287 $ 288 if you are using Bourne shell. Remember, this must be done before 289 running the tests. 290 291 Tests 121 and 122 can sometimes have problems on Solaris, where they 292 give false negatives. If you work out why, please let the author 293 know. 294 295INSTALLING COOK 296 As explained in the SITE CONFIGURATION section, above, the Cook 297 package is installed under the /usr/local tree by default. Use the 298 --prefix=PATH option to configure if you want some other path. More 299 specific installation locations are assignable, use the --help option 300 to configure for details. 301 302 All that is required to install the Cook package is to use the 303 % make install 304 ...lots of output... 305 % 306 command. Control of the directories used may be found in the first 307 few lines of the Makefile file and the other files written by the 308 configure script; it is best to reconfigure using the configure 309 script, rather than attempting to do this by hand. 310 311PRINTED MANUALS 312 The easiest way to get copies of the manuals is to get the 313 cook.2.30.rm.ps.gz and cook.2.30.ug.ps.gz files from the archive site. 314 These are compressed PostScript files of the Reference Manual and User 315 Guide, respectively. The Reference Manual (about 36 pages) contains 316 the README file, the BUILDING file and internationalization notes, as 317 well as all of the manual pages for all of the commands. The User 318 Guide (about 56 pages) tells you how to use the Cook package. 319 320 This distribution contains the sources to all of the documentation for 321 Cook. The author used the GNU groff package and a postscript printer 322 to prepare the documentation. If you do not have this software, you 323 will need to substitute commands appropriate to your site. 324 325 If you have the GNU Groff package installed before you run the 326 configure script, the Makefile will contain instructions for 327 constructing the documentation. If you already used the make command, 328 above, this has already been done. The following command 329 % make groff_all 330 ...lots of output... 331 % 332 can be used to do this explicitly, if you managed to get to this point 333 without doing it. Please note that there may be some warnings from 334 groff, particularly for the .txt files; this is normal. 335 336 Once the documents have been formatted, you only need to print them. 337 The following command 338 % lpr lib/en/refman.ps lib/en/user-guide.ps 339 % 340 will print the English PostScript version of the Reference Manual and 341 the User Guide. Watch the make output to see what other versions are 342 available. 343 344GETTING HELP 345 If you need assistance with the Cook program, please do not hesitate 346 to contact the author at 347 Peter Miller <millerp@canb.auug.org.au> 348 Any and all feedback is welcome. 349 350 When reporting problems, please include the version number given by 351 the 352 % cook -version 353 cook version 2.30.D002 354 ...warranty disclaimer... 355 % 356 command. Please do not send this example; run the program for the 357 exact version number. 358 359 In the common/main.h file, there is a define of DEBUG in comments. If 360 the comments are removed, extensive debugging is turned on. This 361 causes some performance loss, but performs much run-time checking and 362 adds the -TRACIng command line option. 363 364 When the -TRACing option is followed by one or more file names, it 365 turns on execution traces in those source files. It is best to put 366 this option on the end of the command, so that the names of the files 367 to be traced are not confused with any other filenames or strings on 368 the command line. 369 370WINDOWS-NT 371 It is possible to build Cook for Windows-NT. I have done this using 372 the Cygnus freeware CygWin32 system, and I believe it has also once 373 been done using the commercial NutCracker system. This document only 374 describes the CygWin32 port. 375 376 The Source 377 You need to FTP the CygWin32 system from Cygnus. It can be found at 378 http://sourceware.cygnus.com/cygwin/ 379 and then follow the links. The version I used was B20.1. 380 381 Mounting Things 382 You need to mount a directory onto /tmp, or lots of things, and 383 especially bash(1), don't work. If you are in a heavily networked 384 environment, like me, you need to know that using a networked drive 385 for /tmp just doesn't work. I have no idea why. Use 386 mount C:/temp /tmp 387 instead. (Or some other local drive.) 388 389 Just a tip for all of you who, like me, know UNIX much better than you 390 know Windows-NT: the left-hand mount argument needs to be specified 391 with a drive letter (e.g. C:) rather than with a double slash (e.g. 392 not //C) unless its Windows-NT name starts with \\. 393 394 You need to mount the Cygnus bin directory at /bin, otherwise shell 395 scripts that start with #!/bin/sh don't work, among other things. 396 This includes the ./configure script, and the scripts it writes (e.g. 397 config.status). 398 mount Cygnus-Dir/H-i386-cygwin/bin /bin 399 You will want to mount your various network drives onto the same 400 places they appear on your UNIX hosts. This means that your cookbooks 401 will work without change, even if they contain absolute paths. And 402 your users don't need to learn two names for all the source files. 403 404 Don't forget your home directory. The trick is to set HOME in the 405 cygnus.bat file, before bash starts. (How you do this with one batch 406 file and multiple users I haven't yet figured out.) 407 408 You also need to set the LOGNAME and USER environment variables 409 appropriately, or test 14 will fail. 410 411 Mounts persist across Cygwin sessions. They are stored in a registry 412 file somewhere. You will not need to do all this every time! 413 414 Configure 415 The configure and build step should be the same as for UNIX, as 416 described above. All the problems I encountered were to do with 417 getting the mounts just right. (But expect it to be dog slow compared 418 to Linux or FreeBSD on the same box.) 419 420 The configure step is almost the same as for UNIX. I know you are 421 itching to get typing, but read through to the install section before 422 you configure anything. 423 bash$ ./configure 424 ...lots of output... 425 bash$ 426 427 Build 428 The build step is exactly the same as for UNIX, and you shouldn't 429 notice any difference... 430 bash$ make 431 ...lots of output... 432 bash$ 433 434 Test 435 All of the tests should pass, you only need to run them to convince 436 yourself the build worked... (a constant surprise to me, I must say!) 437 bash$ make sure 438 ...lots of output... 439 Passed All Tests 440 bash$ 441 442 If test 12 fails, it probably means you don't have /bin right. 443 444 Install 445 Installing the software works as usual, though you need to make some 446 choices right at the start (I told you to read this all the way 447 through first). If you want to use the ``/usr/local'' prefix (or any 448 other install prefix) you mount it right at the start. For anything 449 other than the ``/usr/local'' default prefix, you also needed to give 450 a ``--prefix=blahblah'' argument to the configure script, right at the 451 start. 452 bash$ make install 453 ...lots of output... 454 bash$ 455 456COPYRIGHT 457 cook version 2.30 458 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 459 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Peter 460 Miller; All rights reserved. 461 462 The Cook package is distributed in the hope that it will be useful, 463 but WITHOUT ANY WARRANTY; without even the implied warranty of 464 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 465 General Public License for more details. 466 467 It should be in the LICENSE file included with this distribution. 468 469AUTHOR 470 Peter Miller E-Mail: millerp@canb.auug.org.au 471 /\/\* WWW: http://www.canb.auug.org.au/~millerp/ 472 473Reference Manual Cook Build(Cook) 474