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.\" 26.Dd June 14, 1994 27.Dt CRUNCHGEN 1 28.Os BSD 4 29.Sh NAME 30.Nm \&crunchgen 31.Nd generates build environment for a crunched binary 32.Sh SYNOPSIS 33.Nm \&crunchgen 34.Op Fl fql 35.Op Fl m Ar makefile-name 36.Op Fl c Ar c-file-name 37.Op Fl e Ar exec-file-name 38.Op Ar conf-file 39.Sh DESCRIPTION 40 41A crunched binary is a program made up of many other programs linked 42together into a single executable. The crunched binary main() 43function determines which component program to run by the contents of 44argv[0]. The main reason to crunch programs together is for fitting 45as many programs as possible onto an installation or system recovery 46floppy. 47 48.Pp 49.Nm Crunchgen 50reads in the specifications in 51.Ar conf-file 52for a crunched binary, and generates a Makefile and accompanying 53top-level C source file that when built create the crunched executable 54file from the component programs. For each component program, 55.Nm crunchgen 56can optionally attempt to determine the object (.o) files that make up 57the program from its source directory Makefile. This information is 58cached between runs. 59.Nm Crunchgen 60uses the companion program 61.Nm crunchide 62to eliminate link-time conflicts between the component programs by 63hiding all unnecessary symbols. 64 65.Pp 66After 67.Nm crunchgen 68is run, the crunched binary can be built by running ``make -f 69<conf-name>.mk''. The component programs' object files must already 70be built. A ``objs'' target, included in the output makefile, will 71run make in each component program's source dir to build the object 72files for the user. This is not done automatically since in release 73engineering circumstances it is generally not desireable to be 74modifying objects in other directories. 75 76.Pp 77The options are as follows: 78.Bl -tag -width indent 79.It Fl c Ar c-file-name 80Set output C file name to 81.Ar c-file-name . 82The default name is ``<conf-name>.c''. 83.It Fl e Ar exec-file-name 84Set crunched binary executable file name to 85.Ar exec-file-name . 86The default name is ``<conf-name>''. 87.It Fl f 88Flush cache. Forces the recalculation of cached parameters. 89.It Fl l 90List names. Lists the names this binary will respond to. 91.It Fl m Ar makefile-name 92Set output Makefile name to 93.Ar makefile-name . 94The default name is ``<conf-name>.mk''. 95.It Fl q 96Quiet operation. Status messages are suppressed. 97.El 98.Sh CRUNCHGEN CONFIGURATION FILE COMMANDS 99 100.Nm Crunchgen 101reads specifications from the 102.Ar conf-file 103that describe the components of the crunched binary. In its simplest 104use, the component program names are merely listed along with the 105top-level source directories in which their sources can be found. 106.Nm Crunchgen 107then calculates (via the source makefiles) and caches the 108list of object files and their locations. For more specialized 109situations, the user can specify by hand all the parameters that 110.Nm crunchgen 111needs. 112.Pp 113The 114.Ar conf-file 115commands are as follows: 116.Bl -tag -width indent 117.It Nm srcdirs Ar dirname ... 118A list of source trees in which the source directories of the 119component programs can be found. These dirs are searched using the 120BSD ``<source-dir>/<progname>/'' convention. Multiple 121.Nm srcdirs 122lines can be specified. The directories are searched in the order 123they are given. 124.It Nm progs Ar progname ... 125A list of programs that make up the crunched binary. Multiple 126.Nm progs 127lines can be specified. 128.It Nm libs Ar libspec ... 129A list of library specifications to be included in the crunched binary link. 130Multiple 131.Nm libs 132lines can be specified. 133.It Nm ln Ar progname linkname 134Causes the crunched binary to invoke 135.Ar progname 136whenever 137.Ar linkname 138appears in argv[0]. This allows programs that change their behavior when 139run under different names to operate correctly. 140.El 141 142To handle specialized situations, such as when the source is not 143available or not built via a conventional Makefile, the following 144.Nm special 145commands can be used to set 146.Nm crunchgen 147parameters for a component program. 148.Bl -tag -width indent 149.It Nm special Ar progname Nm srcdir Ar pathname 150Set the source directory for 151.Ar progname . 152This is normally calculated by searching the specified 153.Nm srcdirs 154for a directory named 155.Ar progname . 156.It Nm special Ar progname Nm objdir Ar pathname 157Set the obj directory for 158.Ar progname . 159This is normally calculated by looking for a directory named 160.Dq Pa obj 161under the 162.Ar srcdir , 163and if that is not found, the 164.Ar srcdir 165itself becomes the 166.Ar objdir . 167.It Nm special Ar progname Nm objs Ar object-file-name ... 168Set the list of object files for program 169.Ar progname . 170This is normally calculated by constructing a temporary makefile that includes 171.Dq Nm srcdir / Pa Makefile 172and outputs the value of $(OBJS). 173.It Nm special Ar progname Nm objpaths Ar full-pathname-to-object-file ... 174Sets the pathnames of the object files for program 175.Ar progname . 176This is normally calculated by prepending the 177.Nm objdir 178pathname to each file in the 179.Nm objs 180list. 181.El 182 183.Pp 184Only the 185.Nm objpaths 186parameter is actually needed by 187.Nm crunchgen , 188but it is calculated from 189.Nm objdir 190and 191.Nm objs , 192which are in turn calculated from 193.Nm srcdir , 194so is sometimes convenient to specify the earlier parameters and let 195.Nm crunchgen 196calculate forward from there if it can. 197 198.Pp 199The makefile produced by 200.Nm crunchgen 201contains an optional 202.Ar objs 203target that will build the object files for each component program by 204running make inside that program's source directory. For this to work the 205.Nm srcdir 206and 207.Nm objs 208parameters must also be valid. If they are not valid for a particular program, that 209program is skipped in the 210.Ar objs 211target. 212.Sh EXAMPLE 213Here is an example 214.Nm crunchgen 215input conf file, named 216.Dq Pa kcopy.conf : 217.Pp 218.nf 219 srcdirs /usr/src/bin /usr/src/sbin 220 221 progs test cp echo sh fsck halt init mount umount myinstall 222 ln test [ # test can be invoked via [ 223 ln sh -sh # init invokes the shell with "-sh" in argv[0] 224 225 special myprog objpaths /homes/leroy/src/myinstall.o # no sources 226 227 libs -lutil -lcrypt 228.fi 229.Pp 230This conf file specifies a small crunched binary consisting of some 231basic system utilities plus a homegrown install program ``myinstall'', 232for which no source directory is specified, but its object file is 233specified directly with the 234.Nm special 235line. 236.Pp 237The crunched binary ``kcopy'' can be built as follows: 238.Pp 239.nf 240 % crunchgen -m Makefile kcopy.conf # gen Makefile and kcopy.c 241 % make objs # build the component progams' .o files 242 % make # build the crunched binary kcopy 243 % kcopy sh # test that this invokes a sh shell 244 $ # it works! 245.fi 246.Pp 247At this point the binary ``kcopy'' can be copied onto an install floppy 248and hard-linked to the names of the component programs. 249.Sh SEE ALSO 250.Xr crunchide 1 251.Sh CAVEATS 252While 253.Nm crunch 254takes care to eliminate link conflicts between the component programs 255of a crunched binary, conflicts are still possible between the 256libraries that are linked in. Some shuffling in the order of 257libraries may be required, and in some rare cases two libraries may 258have an unresolveable conflict and thus cannot be crunched together. 259.Pp 260Some versions of the BSD build environment do not by default build the 261intermediate object file for single-source file programs. The ``make 262objs'' target must then be used to get those object files built, or 263some other arrangements made. 264.Sh AUTHOR 265.Nm Crunch 266was written by James da Silva <jds@cs.umd.edu>. 267.sp 0 268Copyright (c) 1994 University of Maryland. All Rights Reserved. 269