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