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