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