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