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 fq 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 m Ar makefile-name 90Set output Makefile name to 91.Ar makefile-name . 92The default name is ``<conf-name>.mk''. 93.It Fl q 94Quiet operation. Status messages are suppressed. 95.El 96.Sh CRUNCHGEN CONFIGURATION FILE COMMANDS 97 98.Nm Crunchgen 99reads specifications from the 100.Ar conf-file 101that describe the components of the crunched binary. In its simplest 102use, the component program names are merely listed along with the 103top-level source directories in which their sources can be found. 104.Nm Crunchgen 105then calculates (via the source makefiles) and caches the 106list of object files and their locations. For more specialized 107situations, the user can specify by hand all the parameters that 108.Nm crunchgen 109needs. 110.Pp 111The 112.Ar conf-file 113commands are as follows: 114.Bl -tag -width indent 115.It Nm srcdirs Ar dirname ... 116A list of source trees in which the source directories of the 117component programs can be found. These dirs are searched using the 118BSD ``<source-dir>/<progname>/'' convention. Multiple 119.Nm srcdirs 120lines can be specified. The directories are searched in the order 121they are given. 122.It Nm progs Ar progname ... 123A list of programs that make up the crunched binary. Multiple 124.Nm progs 125lines can be specified. 126.It Nm libs Ar libspec ... 127A list of library specifications to be included in the crunched binary link. 128Multiple 129.Nm libs 130lines can be specified. 131.It Nm ln Ar progname linkname 132Causes the crunched binary to invoke 133.Ar progname 134whenever 135.Ar linkname 136appears in argv[0]. This allows programs that change their behavior when 137run under different names to operate correctly. 138.El 139 140To handle specialized situations, such as when the source is not 141available or not built via a conventional Makefile, the following 142.Nm special 143commands can be used to set 144.Nm crunchgen 145parameters for a component program. 146.Bl -tag -width indent 147.It Nm special Ar progname Nm srcdir Ar pathname 148Set the source directory for 149.Ar progname . 150This is normally calculated by searching the specified 151.Nm srcdirs 152for a directory named 153.Ar progname . 154.It Nm special Ar progname Nm objdir Ar pathname 155Set the obj directory for 156.Ar progname . 157This is normally calculated by looking for a directory named 158.Dq Pa obj 159under the 160.Ar srcdir , 161and if that is not found, the 162.Ar srcdir 163itself becomes the 164.Ar objdir . 165.It Nm special Ar progname Nm objs Ar object-file-name ... 166Set the list of object files for program 167.Ar progname . 168This is normally calculated by constructing a temporary makefile that includes 169.Dq Nm srcdir / Pa Makefile 170and outputs the value of $(OBJS). 171.It Nm special Ar progname Nm objpaths Ar full-pathname-to-object-file ... 172Sets the pathnames of the object files for program 173.Ar progname . 174This is normally calculated by prepending the 175.Nm objdir 176pathname to each file in the 177.Nm objs 178list. 179.El 180 181.Pp 182Only the 183.Nm objpaths 184parameter is actually needed by 185.Nm crunchgen , 186but it is calculated from 187.Nm objdir 188and 189.Nm objs , 190which are in turn calculated from 191.Nm srcdir , 192so is sometimes convenient to specify the earlier parameters and let 193.Nm crunchgen 194calculate forward from there if it can. 195 196.Pp 197The makefile produced by 198.Nm crunchgen 199contains an optional 200.Ar objs 201target that will build the object files for each component program by 202running make inside that program's source directory. For this to work the 203.Nm srcdir 204and 205.Nm objs 206parameters must also be valid. If they are not valid for a particular program, that 207program is skipped in the 208.Ar objs 209target. 210.Sh EXAMPLE 211Here is an example 212.Nm crunchgen 213input conf file, named 214.Dq Pa kcopy.conf : 215.Pp 216.nf 217 srcdirs /usr/src/bin /usr/src/sbin 218 219 progs test cp echo sh fsck halt init mount umount myinstall 220 ln test [ # test can be invoked via [ 221 ln sh -sh # init invokes the shell with "-sh" in argv[0] 222 223 special myprog objpaths /homes/leroy/src/myinstall.o # no sources 224 225 libs -lutil -lcrypt 226.fi 227.Pp 228This conf file specifies a small crunched binary consisting of some 229basic system utilities plus a homegrown install program ``myinstall'', 230for which no source directory is specified, but its object file is 231specified directly with the 232.Nm special 233line. 234.Pp 235The crunched binary ``kcopy'' can be built as follows: 236.Pp 237.nf 238 % crunchgen -m Makefile kcopy.conf # gen Makefile and kcopy.c 239 % make objs # build the component progams' .o files 240 % make # build the crunched binary kcopy 241 % kcopy sh # test that this invokes a sh shell 242 $ # it works! 243.fi 244.Pp 245At this point the binary ``kcopy'' can be copied onto an install floppy 246and hard-linked to the names of the component programs. 247.Sh SEE ALSO 248.Xr crunchide 1 249.Sh CAVEATS 250While 251.Nm crunch 252takes care to eliminate link conflicts between the component programs 253of a crunched binary, conflicts are still possible between the 254libraries that are linked in. Some shuffling in the order of 255libraries may be required, and in some rare cases two libraries may 256have an unresolveable conflict and thus cannot be crunched together. 257.Pp 258Some versions of the BSD build environment do not by default build the 259intermediate object file for single-source file programs. The ``make 260objs'' target must then be used to get those object files built, or 261some other arrangements made. 262.Sh AUTHOR 263.Nm Crunch 264was written by James da Silva <jds@cs.umd.edu>. 265.sp 0 266Copyright (c) 1994 University of Maryland. All Rights Reserved. 267