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 January 6, 2017 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.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 which might affect the behavior of 141.Xr make 1 142and are annoying to pass through environment variables. 143.It Fl m Ar makefile-name 144Set output 145.Pa Makefile 146name to 147.Ar makefile-name . 148The default name is 149.Pa <conf-name>.mk . 150.It Fl o 151Add 152.Dq Li make obj 153rules to each program make target. 154.It Fl p Ar obj-prefix 155Set the pathname to be prepended to the 156.Ic srcdir 157when computing the 158.Ic objdir . 159If this option is not present, then the prefix used 160is the content of the 161.Ev MAKEOBJDIRPREFIX 162environment variable, or 163.Pa /usr/obj . 164.It Fl q 165Quiet operation. 166Status messages are suppressed. 167.El 168.Sh CRUNCHGEN CONFIGURATION FILE COMMANDS 169The 170.Nm 171utility reads specifications from the 172.Ar conf-file 173that describe the components of the crunched binary. 174In its simplest 175use, the component program names are merely listed along with the 176top-level source directories in which their sources can be found. 177The 178.Nm 179utility then calculates (via the source makefiles) and caches the 180list of object files and their locations. 181For more specialized 182situations, the user can specify by hand all the parameters that 183.Nm 184needs. 185.Pp 186The 187.Ar conf-file 188commands are as follows: 189.Bl -tag -width indent 190.It Ic srcdirs Ar dirname ... 191A list of source trees in which the source directories of the 192component programs can be found. 193These dirs are searched using the 194.Bx 195.Dq Pa <source-dir>/<progname>/ 196convention. 197Multiple 198.Ic srcdirs 199lines can be specified. 200The directories are searched in the order they are given. 201.It Ic progs Ar progname ... 202A list of programs that make up the crunched binary. 203Multiple 204.Ic progs 205lines can be specified. 206.It Ic libs Ar libspec ... 207A list of library specifications to be included in the crunched binary link. 208Multiple 209.Ic libs 210lines can be specified. 211.It Ic libs_so Ar libspec ... 212A list of library specifications to be dynamically linked in the 213crunched binary. 214These libraries will need to be made available via the run-time link-editor 215.Xr rtld 1 216when the component program that requires them is executed from 217the crunched binary. 218Multiple 219.Ic libs_so 220lines can be specified. 221The 222.Ic libs_so 223directive overrides a library specified gratuitously on a 224.Ic libs 225line. 226.It Ic buildopts Ar buildopts ... 227A list of build options to be added to every make target. 228.It Ic ln Ar progname linkname 229Causes the crunched binary to invoke 230.Ar progname 231whenever 232.Ar linkname 233appears in 234.Va argv[0] . 235This allows programs that change their behavior when 236run under different names to operate correctly. 237.El 238.Pp 239To handle specialized situations, such as when the source is not 240available or not built via a conventional 241.Pa Makefile , 242the following 243.Ic special 244commands can be used to set 245.Nm 246parameters for a component program. 247.Bl -tag -width indent 248.It Ic special Ar progname Ic srcdir Ar pathname 249Set the source directory for 250.Ar progname . 251This is normally calculated by searching the specified 252.Ic srcdirs 253for a directory named 254.Ar progname . 255.It Ic special Ar progname Ic objdir Ar pathname 256Set the 257.Pa obj 258directory for 259.Ar progname . 260The 261.Pa obj 262directory is normally calculated by looking for a directory 263whose name is that of the source directory prepended by 264one of the following components, in order of priority: 265the 266.Fl p 267argument passed to the command line; or, 268the value of the 269.Ev MAKEOBJDIRPREFIX 270environment variable, or 271.Pa /usr/obj . 272If the directory is not found, the 273.Ic srcdir 274itself becomes the 275.Ic objdir . 276.It Ic special Ar progname Ic buildopts Ar buildopts 277Define a set of build options that should be added to 278.Xr make 1 279targets in addition to those specified using 280.Ic buildopts 281when processing 282.Ar progname . 283.It Ic special Ar progname Ic objs Ar object-file-name ... 284Set the list of object files for program 285.Ar progname . 286This is normally calculated by constructing a temporary makefile that includes 287.Dq Ic srcdir Ns / Ns Pa Makefile 288and outputs the value of 289.Va $(OBJS) . 290.It Ic special Ar progname Ic objpaths Ar full-pathname-to-object-file ... 291Sets the pathnames of the object files for program 292.Ar progname . 293This is normally calculated by prepending the 294.Ic objdir 295pathname to each file in the 296.Ic objs 297list. 298.It Ic special Ar progname Ic objvar Ar variable_name 299Sets the name of the 300.Xr make 1 301variable which holds the list of 302object files for program 303.Ar progname . 304This is normally 305.Va OBJS 306but some 307.Pa Makefile Ns s 308might like to use other conventions or 309prepend the program's name to the variable, e.g., 310.Va SSHD_OBJS . 311.It Ic special Ar progname Ic lib Ar library-name ... 312Specifies libraries to be linked with object files to produce 313.Ar progname Ns Pa .lo . 314This can be useful with libraries which redefine routines in 315the standard libraries, or poorly written libraries which 316reference symbols in the object files. 317.It Ic special Ar progname Ic keep Ar symbol-name ... 318Add specified list of symbols to the keep list for program 319.Ar progname . 320An underscore 321.Pq Ql _ 322is prepended to each symbol and it becomes the argument to a 323.Fl k 324option for the 325.Xr crunchide 1 326phase. 327This option is to be used as a last resort as its use can cause a 328symbol conflict, however in certain instances it may be the only way to 329have a symbol resolve. 330.It Ic special Ar progname Ic ident Ar identifier 331Set the 332.Pa Makefile Ns / Ns Tn C 333identifier for 334.Ar progname . 335This is normally generated from a 336.Ar progname , 337mapping 338.Ql - 339to 340.Ql _ 341and ignoring all other non-identifier characters. 342This leads to programs named 343.Qq Li foo.bar 344and 345.Qq Li foobar 346to map to the same identifier. 347.El 348.Pp 349Only the 350.Ic objpaths 351parameter is actually needed by 352.Nm , 353but it is calculated from 354.Ic objdir 355and 356.Ic objs , 357which are in turn calculated from 358.Ic srcdir , 359so is sometimes convenient to specify the earlier parameters and let 360.Nm 361calculate forward from there if it can. 362.Pp 363The makefile produced by 364.Nm 365contains an optional 366.Ic objs 367target that will build the object files for each component program by 368running 369.Xr make 1 370inside that program's source directory. 371For this to work the 372.Ic srcdir 373and 374.Ic objs 375parameters must also be valid. 376If they are not valid for a particular program, that 377program is skipped in the 378.Ic objs 379target. 380.Sh EXAMPLES 381Here is an example 382.Nm 383input conf file, named 384.Dq Pa kcopy.conf : 385.Bd -literal -offset indent 386srcdirs /usr/src/bin /usr/src/sbin 387 388progs test cp echo sh fsck halt init mount umount myinstall 389progs anotherprog 390ln test [ # test can be invoked via [ 391ln sh -sh # init invokes the shell with "-sh" in argv[0] 392 393special myprog objpaths /homes/leroy/src/myinstall.o # no sources 394 395special anotherprog -DNO_FOO WITHOUT_BAR=YES 396 397libs -lutil -lcrypt 398.Ed 399.Pp 400This conf file specifies a small crunched binary consisting of some 401basic system utilities plus a homegrown install program 402.Dq Pa myinstall , 403for which no source directory is specified, but its object file is 404specified directly with the 405.Ic special 406line. 407.Pp 408Additionally when 409.Dq Pa anotherprog 410is built the arguments 411.Pp 412.Dl -DNO_FOO WITHOUT_BAR=YES 413.Pp 414are added to all build targets. 415.Pp 416The crunched binary 417.Dq Pa kcopy 418can be built as follows: 419.Bd -literal -offset indent 420% crunchgen -m Makefile kcopy.conf # gen Makefile and kcopy.c 421% make objs # build the component programs' .o files 422% make # build the crunched binary kcopy 423% kcopy sh # test that this invokes a sh shell 424$ # it works! 425.Ed 426.Pp 427At this point the binary 428.Dq Pa kcopy 429can be copied onto an install floppy 430and hard-linked to the names of the component programs. 431.Pp 432Note that if the 433.Ic libs_so 434command had been used, copies of the libraries so named 435would also need to be copied to the install floppy. 436.Sh SEE ALSO 437.Xr crunchide 1 , 438.Xr make 1 , 439.Xr rtld 1 440.Sh AUTHORS 441.An -nosplit 442The 443.Nm 444utility was written by 445.An James da Silva Aq Mt jds@cs.umd.edu . 446.Pp 447Copyright (c) 1994 University of Maryland. 448All Rights Reserved. 449.Pp 450The 451.Ic libs_so 452keyword was added in 2005 by 453.An Adrian Steinmann Aq Mt ast@marabu.ch 454and 455.An Ceri Davies Aq Mt ceri@FreeBSD.org . 456.Sh CAVEATS 457While 458.Nm 459takes care to eliminate link conflicts between the component programs 460of a crunched binary, conflicts are still possible between the 461libraries that are linked in. 462Some shuffling in the order of 463libraries may be required, and in some rare cases two libraries may 464have an unresolvable conflict and thus cannot be crunched together. 465.Pp 466Some versions of the 467.Bx 468build environment do not by default build the 469intermediate object file for single-source file programs. 470The 471.Dq Li make objs 472must then be used to get those object files built, or 473some other arrangements made. 474