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. This option is to be used as a last resort as its use can cause a 208symbol conflict, however in certain instances it may be the only way to 209have a symbol resolve. 210.El 211 212.Pp 213Only the 214.Nm objpaths 215parameter is actually needed by 216.Nm crunchgen , 217but it is calculated from 218.Nm objdir 219and 220.Nm objs , 221which are in turn calculated from 222.Nm srcdir , 223so is sometimes convenient to specify the earlier parameters and let 224.Nm 225calculate forward from there if it can. 226 227.Pp 228The makefile produced by 229.Nm 230contains an optional 231.Ar objs 232target that will build the object files for each component program by 233running make inside that program's source directory. For this to work the 234.Nm srcdir 235and 236.Nm objs 237parameters must also be valid. If they are not valid for a particular program, that 238program is skipped in the 239.Ar objs 240target. 241.Sh EXAMPLE 242Here is an example 243.Nm 244input conf file, named 245.Dq Pa kcopy.conf : 246.Pp 247.nf 248 srcdirs /usr/src/bin /usr/src/sbin 249 250 progs test cp echo sh fsck halt init mount umount myinstall 251 ln test [ # test can be invoked via [ 252 ln sh -sh # init invokes the shell with "-sh" in argv[0] 253 254 special myprog objpaths /homes/leroy/src/myinstall.o # no sources 255 256 libs -lutil -lcrypt 257.fi 258.Pp 259This conf file specifies a small crunched binary consisting of some 260basic system utilities plus a homegrown install program ``myinstall'', 261for which no source directory is specified, but its object file is 262specified directly with the 263.Nm special 264line. 265.Pp 266The crunched binary ``kcopy'' can be built as follows: 267.Pp 268.nf 269 % crunchgen -m Makefile kcopy.conf # gen Makefile and kcopy.c 270 % make objs # build the component programs' .o files 271 % make # build the crunched binary kcopy 272 % kcopy sh # test that this invokes a sh shell 273 $ # it works! 274.fi 275.Pp 276At this point the binary ``kcopy'' can be copied onto an install floppy 277and hard-linked to the names of the component programs. 278.Sh SEE ALSO 279.Xr crunchide 1 280.Sh CAVEATS 281While 282.Nm crunch 283takes care to eliminate link conflicts between the component programs 284of a crunched binary, conflicts are still possible between the 285libraries that are linked in. Some shuffling in the order of 286libraries may be required, and in some rare cases two libraries may 287have an unresolvable conflict and thus cannot be crunched together. 288.Pp 289Some versions of the BSD build environment do not by default build the 290intermediate object file for single-source file programs. The ``make 291objs'' target must then be used to get those object files built, or 292some other arrangements made. 293.Sh AUTHORS 294.Nm Crunch 295was written by 296.An James da Silva Aq jds@cs.umd.edu . 297Copyright (c) 1994 University of Maryland. All Rights Reserved. 298