1.\" 2.\" Copyright (c) 1994 University of Maryland 3.\" All Rights Reserved. 4.\" 5.\" Permission to use, copy, modify, distribute, and sell this software and its 6.\" documentation for any purpose is hereby granted without fee, provided that 7.\" the above copyright notice appear in all copies and that both that 8.\" copyright notice and this permission notice appear in supporting 9.\" documentation, and that the name of U.M. not be used in advertising or 10.\" publicity pertaining to distribution of the software without specific, 11.\" written prior permission. U.M. makes no representations about the 12.\" suitability of this software for any purpose. It is provided "as is" 13.\" without express or implied warranty. 14.\" 15.\" U.M. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL U.M. 17.\" BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR 20.\" IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 21.\" 22.\" Author: James da Silva, Systems Design and Analysis Group 23.\" Computer Science Department 24.\" University of Maryland at College Park 25.\" $FreeBSD: src/usr.sbin/crunch/crunchgen/crunchgen.1,v 1.11.2.11 2003/03/12 22:08:13 trhodes Exp $ 26.\" $DragonFly: src/usr.sbin/crunch/crunchgen/crunchgen.1,v 1.3 2008/05/02 02:05:07 swildner Exp $ 27.\" 28.Dd November 16, 2000 29.Dt CRUNCHGEN 1 30.Os 31.Sh NAME 32.Nm crunchgen 33.Nd generates build environment for a crunched binary 34.Sh SYNOPSIS 35.Bk -words 36.Nm 37.Op Fl foql 38.Op Fl h Ar makefile-header-name 39.Op Fl m Ar makefile-name 40.Op Fl p Ar obj-prefix 41.Op Fl c Ar c-file-name 42.Op Fl e Ar exec-file-name 43.Op Ar conf-file 44.Ek 45.Sh DESCRIPTION 46A crunched binary is a program made up of many other programs linked 47together into a single executable. 48The crunched binary 49.Fn main 50function determines which component program to run by the contents of 51.Va argv[0] . 52The main reason to crunch programs together is for fitting 53as many programs as possible onto an installation or system recovery 54floppy. 55.Pp 56The 57.Nm 58utility reads in the specifications in 59.Ar conf-file 60for a crunched binary, and generates a 61.Pa Makefile 62and accompanying 63top-level C source file that when built creates the crunched executable 64file from the component programs. 65For each component program, 66.Nm 67can optionally attempt to determine the object (.o) files that make up 68the program from its source directory 69.Pa Makefile . 70This information is cached between runs. 71The 72.Nm 73utility uses the companion program 74.Xr crunchide 1 75to eliminate link-time conflicts between the component programs by 76hiding all unnecessary symbols. 77.Pp 78The 79.Nm 80utility places specific requirements on package 81.Pa Makefile Ns s 82which make it unsuitable for use with 83.No non- Ns Bx 84sources. 85In particular, the 86.Pa Makefile 87must contain the target 88.Ic depend , 89and it must define all object files in the variable 90.Va OBJS . 91In some cases, you can use a fake 92.Pa Makefile : 93before looking for 94.Pa Makefile 95in the source directory 96.Pa foo , 97.Nm 98looks for the file 99.Pa Makefile.foo 100in the current directory. 101.Pp 102After 103.Nm 104is run, the crunched binary can be built by running 105.Dq Li make -f <conf-name>.mk . 106The component programs' object files must already be built. 107An 108.Ic objs 109target, included in the output makefile, will 110run 111.Xr make 1 112in each component program's source dir to build the object 113files for the user. 114This is not done automatically since in release 115engineering circumstances it is generally not desirable to be 116modifying objects in other directories. 117.Pp 118The options are as follows: 119.Bl -tag -width indent 120.It Fl c Ar c-file-name 121Set output C file name to 122.Ar c-file-name . 123The default name is 124.Pa <conf-name>.c . 125.It Fl e Ar exec-file-name 126Set crunched binary executable file name to 127.Ar exec-file-name . 128The default name is 129.Pa <conf-name> . 130.It Fl f 131Flush cache. 132Forces the recalculation of cached parameters. 133.It Fl l 134List names. 135Lists the names this binary will respond to. 136.It Fl h Ar makefile-header-name 137Set the name of a file to be included at the beginning of the 138.Pa Makefile Ns s 139generated by 140.Nm . 141This is useful to define some make variables such as 142.Va RELEASE_CRUNCH 143or similar, which might affect the behaviour of 144.Xr make 1 145and are annoying to pass through environment variables. 146.It Fl m Ar makefile-name 147Set output 148.Pa Makefile 149name to 150.Ar makefile-name . 151The default name is 152.Pa <conf-name>.mk . 153.It Fl o 154Add 155.Dq Li make obj 156rules to each program make target. 157.It Fl p Ar obj-prefix 158Set the pathname to be prepended to the 159.Ic srcdir 160when computing the 161.Ic objdir . 162If this option is not present, then the prefix used 163is the content of the 164.Ev MAKEOBJDIRPREFIX 165environment variable, or 166.Pa /usr/obj . 167.It Fl q 168Quiet operation. 169Status messages are suppressed. 170.El 171.Sh CRUNCHGEN CONFIGURATION FILE COMMANDS 172The 173.Nm 174utility reads specifications from the 175.Ar conf-file 176that describe the components of the crunched binary. 177In its simplest 178use, the component program names are merely listed along with the 179top-level source directories in which their sources can be found. 180The 181.Nm 182utility then calculates (via the source makefiles) and caches the 183list of object files and their locations. 184For more specialized 185situations, the user can specify by hand all the parameters that 186.Nm 187needs. 188.Pp 189The 190.Ar conf-file 191commands are as follows: 192.Bl -tag -width indent 193.It Ic srcdirs Ar dirname ... 194A list of source trees in which the source directories of the 195component programs can be found. 196These dirs are searched using the 197.Bx 198.Dq Pa <source-dir>/<progname>/ 199convention. 200Multiple 201.Ic srcdirs 202lines can be specified. 203The directories are searched in the order they are given. 204.It Ic progs Ar progname ... 205A list of programs that make up the crunched binary. 206Multiple 207.Ic progs 208lines can be specified. 209.It Ic libs Ar libspec ... 210A list of library specifications to be included in the crunched binary link. 211Multiple 212.Ic libs 213lines can be specified. 214.It Ic buildopts Ar buildopts ... 215A list of build options to be added to every make target. 216.It Ic ln Ar progname linkname 217Causes the crunched binary to invoke 218.Ar progname 219whenever 220.Ar linkname 221appears in 222.Va argv[0] . 223This allows programs that change their behavior when 224run under different names to operate correctly. 225.El 226.Pp 227To handle specialized situations, such as when the source is not 228available or not built via a conventional 229.Pa Makefile , 230the following 231.Ic special 232commands can be used to set 233.Nm 234parameters for a component program. 235.Bl -tag -width indent 236.It Ic special Ar progname Ic srcdir Ar pathname 237Set the source directory for 238.Ar progname . 239This is normally calculated by searching the specified 240.Ic srcdirs 241for a directory named 242.Ar progname . 243.It Ic special Ar progname Ic objdir Ar pathname 244Set the 245.Pa obj 246directory for 247.Ar progname . 248The 249.Pa obj 250directory is normally calculated by looking for a directory 251whose name is that of the source directory prepended by 252one of the following components, in order of priority: 253the 254.Fl p 255argument passed to the command line; or, 256the value of the 257.Ev MAKEOBJDIRPREFIX 258environment variable, or 259.Pa /usr/obj . 260If the directory is not found, the 261.Ic srcdir 262itself becomes the 263.Ic objdir . 264.It Ic special Ar progname Ic buildopts Ar buildopts 265Define a set of build options that should be added to 266.Xr make 1 267targets in addition to those specified using 268.Ic buildopts 269when processing 270.Ar progname . 271.It Ic special Ar progname Ic objs Ar object-file-name ... 272Set the list of object files for program 273.Ar progname . 274This is normally calculated by constructing a temporary makefile that includes 275.Dq Ic srcdir Ns / Ns Pa Makefile 276and outputs the value of 277.Va $(OBJS) . 278.It Ic special Ar progname Ic objpaths Ar full-pathname-to-object-file ... 279Sets the pathnames of the object files for program 280.Ar progname . 281This is normally calculated by prepending the 282.Ic objdir 283pathname to each file in the 284.Ic objs 285list. 286.It Ic special Ar progname Ic objvar Ar variable_name 287Sets the name of the 288.Xr make 1 289variable which holds the list of 290object files for program 291.Ar progname . 292This is normally 293.Va OBJS 294but some 295.Pa Makefile Ns s 296might like to use other conventions or 297prepend the program's name to the variable, e.g.\& 298.Va SSHD_OBJS . 299.It Ic special Ar progname Ic lib Ar library-name ... 300Specifies libraries to be linked with object files to produce 301.Ar progname Ns Pa .lo . 302This can be useful with libraries which redefine routines in 303the standard libraries, or poorly written libraries which 304reference symbols in the object files. 305.It Ic special Ar progname Ic keep Ar symbol-name ... 306Add specified list of symbols to the keep list for program 307.Ar progname . 308An underscore 309.Pq Ql _ 310is prepended to each symbol and it becomes the argument to a 311.Fl k 312option for the 313.Xr crunchide 1 314phase. 315This option is to be used as a last resort as its use can cause a 316symbol conflict, however in certain instances it may be the only way to 317have a symbol resolve. 318.It Ic special Ar progname Ic ident Ar identifier 319Set the 320.Pa Makefile Ns / Ns Tn C 321identifier for 322.Ar progname . 323This is normally generated from a 324.Ar progname , 325mapping 326.Ql - 327to 328.Ql _ 329and ignoring all other non-identifier characters. 330This leads to programs named 331.Qq Li foo.bar 332and 333.Qq Li foobar 334to map to the same identifier. 335.El 336.Pp 337Only the 338.Ic objpaths 339parameter is actually needed by 340.Nm , 341but it is calculated from 342.Ic objdir 343and 344.Ic objs , 345which are in turn calculated from 346.Ic srcdir , 347so is sometimes convenient to specify the earlier parameters and let 348.Nm 349calculate forward from there if it can. 350.Pp 351The makefile produced by 352.Nm 353contains an optional 354.Ic objs 355target that will build the object files for each component program by 356running 357.Xr make 1 358inside that program's source directory. 359For this to work the 360.Ic srcdir 361and 362.Ic objs 363parameters must also be valid. 364If they are not valid for a particular program, that 365program is skipped in the 366.Ic objs 367target. 368.Sh EXAMPLES 369Here is an example 370.Nm 371input conf file, named 372.Dq Pa kcopy.conf : 373.Bd -literal -offset indent 374srcdirs /usr/src/bin /usr/src/sbin 375 376progs test cp echo sh fsck halt init mount umount myinstall 377progs anotherprog 378ln test [ # test can be invoked via [ 379ln sh -sh # init invokes the shell with "-sh" in argv[0] 380 381special myprog objpaths /homes/leroy/src/myinstall.o # no sources 382 383special anotherprog -DNO_FOO WITHOUT_BAR=YES 384 385libs -lutil -lcrypt 386.Ed 387.Pp 388This conf file specifies a small crunched binary consisting of some 389basic system utilities plus a homegrown install program 390.Dq Pa myinstall , 391for which no source directory is specified, but its object file is 392specified directly with the 393.Ic special 394line. 395.Pp 396Additionally when 397.Dq Pa anotherprog 398is built the arguments 399.Pp 400.Dl -DNO_FOO WITHOUT_BAR=YES 401.Pp 402are added to all build targets. 403.Pp 404The crunched binary 405.Dq Pa kcopy 406can be built as follows: 407.Bd -literal -offset indent 408% crunchgen -m Makefile kcopy.conf # gen Makefile and kcopy.c 409% make objs # build the component programs' .o files 410% make # build the crunched binary kcopy 411% kcopy sh # test that this invokes a sh shell 412$ # it works! 413.Ed 414.Pp 415At this point the binary 416.Dq Pa kcopy 417can be copied onto an install floppy 418and hard-linked to the names of the component programs. 419.Sh SEE ALSO 420.Xr crunchide 1 , 421.Xr make 1 422.Sh CAVEATS 423While 424.Nm 425takes care to eliminate link conflicts between the component programs 426of a crunched binary, conflicts are still possible between the 427libraries that are linked in. 428Some shuffling in the order of 429libraries may be required, and in some rare cases two libraries may 430have an unresolvable conflict and thus cannot be crunched together. 431.Pp 432Some versions of the 433.Bx 434build environment do not by default build the 435intermediate object file for single-source file programs. 436The 437.Dq Li make objs 438must then be used to get those object files built, or 439some other arrangements made. 440.Sh AUTHORS 441The 442.Nm 443utility was written by 444.An James da Silva Aq jds@cs.umd.edu . 445.Pp 446Copyright (c) 1994 University of Maryland. 447All Rights Reserved. 448