1.\" $NetBSD: crunchgen.1,v 1.17 2002/04/06 18:30:02 tsutsui Exp $ 2.\" 3.\" Copyright (c) 1994 University of Maryland 4.\" All Rights Reserved. 5.\" 6.\" Permission to use, copy, modify, distribute, and sell this software and its 7.\" documentation for any purpose is hereby granted without fee, provided that 8.\" the above copyright notice appear in all copies and that both that 9.\" copyright notice and this permission notice appear in supporting 10.\" documentation, and that the name of U.M. not be used in advertising or 11.\" publicity pertaining to distribution of the software without specific, 12.\" written prior permission. U.M. makes no representations about the 13.\" suitability of this software for any purpose. It is provided "as is" 14.\" without express or implied warranty. 15.\" 16.\" U.M. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL U.M. 18.\" BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 19.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 20.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR 21.\" IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 22.\" 23.\" Author: James da Silva, Systems Design and Analysis Group 24.\" Computer Science Department 25.\" University of Maryland at College Park 26.\" 27.Dd June 14, 1994 28.Dt CRUNCHGEN 1 29.Os 30.Sh NAME 31.Nm crunchgen 32.Nd generates build environment for a crunched binary 33.Sh SYNOPSIS 34.Nm "" 35.Op Fl fq 36.Bk -words 37.Op Fl m Ar makefile-name 38.Ek 39.Bk -words 40.Op Fl c Ar c-file-name 41.Ek 42.Bk -words 43.Op Fl e Ar exec-file-name 44.Ek 45.Bk -words 46.Op Fl d Ar build-options 47.Ek 48.Bk -words 49.Op Fl D Ar src-root 50.Ek 51.Bk -words 52.Op Fl L Ar lib-dir 53.Ek 54.Bk -words 55.Op Ar conf-file 56.Ek 57.Sh DESCRIPTION 58A crunched binary is a program made up of many other programs linked 59together into a single executable. The crunched binary main() 60function determines which component program to run by the contents of 61argv[0]. The main reason to crunch programs together is for fitting 62as many programs as possible onto an installation or system recovery 63floppy. 64.Pp 65.Nm 66reads in the specifications in 67.Ar conf-file 68for a crunched binary, and generates a Makefile and accompanying 69top-level C source file that when built create the crunched executable 70file from the component programs. For each component program, 71.Nm 72can optionally attempt to determine the object (.o) files that make up 73the program from its source directory Makefile. This information is 74cached between runs. 75.Nm 76uses the companion program 77.Em crunchide 78to eliminate link-time conflicts between the component programs by 79hiding all unnecessary symbols. 80.Pp 81After 82.Nm 83is run, the crunched binary can be built by running ``make -f 84\*[Lt]conf-name\*[Gt].mk''. The component programs' object files must already 85be built. A ``objs'' target, included in the output makefile, will 86run make in each component program's source dir to build the object 87files for the user. This is not done automatically since in release 88engineering circumstances it is generally not desireable to be 89modifying objects in other directories. 90.Pp 91The options are as follows: 92.Bl -tag -width indent 93.It Fl c Ar c-file-name 94Set output C file name to 95.Ar c-file-name . 96The default name is ``\*[Lt]conf-name\*[Gt].c''. 97.It Fl e Ar exec-file-name 98Set crunched binary executable file name to 99.Ar exec-file-name . 100The default name is ``\*[Lt]conf-name\*[Gt]''. 101.It Fl d Ar build-options 102Set the DBG variable in the generated makefile to 103.Ar build-options . 104The default flags are -Os. 105.It Fl f 106Flush cache. Forces the recalculation of cached parameters. 107.It Fl m Ar makefile-name 108Set output Makefile name to 109.Ar makefile-name . 110The default name is ``\*[Lt]conf-name\*[Gt].mk''. 111.It Fl o 112Use existing object files. Rather than rebuilding object files via reach-over 113makefiles, instead search for and use existing object files. 114.It Fl q 115Quiet operation. Status messages are suppressed. 116.It Fl D Ar src-root 117Assume that relative source directory specifications begin with 118.Ar src-root . 119.It Fl L Ar lib-dir 120Try to obtain libraries from 121.Ar lib-dir . 122.El 123.Sh CRUNCHGEN CONFIGURATION FILE COMMANDS 124.Nm 125reads specifications from the 126.Ar conf-file 127that describe the components of the crunched binary. In its simplest 128use, the component program names are merely listed along with the 129top-level source directories in which their sources can be found. 130.Nm 131then calculates (via the source makefiles) and caches the 132list of object files and their locations. For more specialized 133situations, the user can specify by hand all the parameters that 134.Nm 135needs. 136.Pp 137The 138.Ar conf-file 139commands are as follows: 140.Bl -tag -width indent 141.It Nm srcdirs Ar dirname ... 142A list of source trees in which the source directories of the 143component programs can be found. These dirs are searched using the 144.Bx 145``\*[Lt]source-dir\*[Gt]/\*[Lt]progname\*[Gt]/'' convention. Multiple 146.Em srcdirs 147lines can be specified. The directories are searched in the order 148they are given. 149.It Nm progs Ar progname ... 150A list of programs that make up the crunched binary. Multiple 151.Em progs 152lines can be specified. 153.It Nm libs Ar libspec ... 154A list of library specifications to be included in the crunched binary link. 155Multiple 156.Em libs 157lines can be specified. 158.It Nm ln Ar progname linkname 159Causes the crunched binary to invoke 160.Ar progname 161whenever 162.Ar linkname 163appears in argv[0]. This allows programs that change their behavior when 164run under different names to operate correctly. 165.El 166.Pp 167To handle specialized situations, such as when the source is not 168available or not built via a conventional Makefile, the following 169.Em special 170commands can be used to set 171.Nm 172parameters for a component program. 173.Bl -tag -width indent 174.It Nm special Ar progname Nm keepsymbols Ar symbols ... 175Don't hide the specified symbols for 176.Ar progname . 177Normally all externally visible symbols for 178a program is hidden to avoid interference. 179.It Nm special Ar progname Nm srcdir Ar pathname 180Set the source directory for 181.Ar progname . 182This is normally calculated by searching the specified 183.Em srcdirs 184for a directory named 185.Ar progname . 186.It Nm special Ar progname Nm objdir Ar pathname 187Set the obj directory for 188.Ar progname . 189This is normally calculated by looking for a directory named 190.Dq Pa obj 191under the 192.Ar srcdir , 193and if that is not found, the 194.Ar srcdir 195itself becomes the 196.Ar objdir . 197.br 198.Nm Note : 199This option only takes effect if the -o option to use existing object files is also 200specified. 201.It Nm special Ar progname Nm objs Ar object-file-name ... 202Set the list of object files for program 203.Ar progname . 204This is normally calculated by constructing a temporary makefile that includes 205.Dq Nm srcdir / Pa Makefile 206and outputs the value of $(OBJS). 207.It Nm special Ar progname Nm objpaths Ar full-pathname-to-object-file ... 208Sets the pathnames of the object files for program 209.Ar progname . 210This is normally calculated by prepending the 211.Em objdir 212pathname to each file in the 213.Nm objs 214list. 215.El 216.Pp 217Only the 218.Em objpaths 219parameter is actually needed by 220.Nm 221but it is calculated from 222.Em objdir 223and 224.Em objs , 225which are in turn calculated from 226.Em srcdir , 227so is sometimes convenient to specify the earlier parameters and let 228.Nm 229calculate forward from there if it can. 230.Pp 231The makefile produced by 232.Nm 233contains an optional 234.Ar objs 235target that will build the object files for each component program by 236running make inside that program's source directory. For this to work the 237.Em srcdir 238and 239.Em objs 240parameters must also be valid. If they are not valid for a particular program, that 241program is skipped in the 242.Ar objs 243target. 244.Sh ENVIRONMENT 245.Bl -tag -width MAKEOBJDIRPREFIX 246.It Ev MAKEOBJDIRPREFIX 247If the environment variable 248.Ev MAKEOBJDIRPREFIX 249is set, the object directory will be prefixed with the path contained in this 250environment variable. 251.br 252.Nm Note : 253This variable is only used if the -o option to use existing object files is also 254specified. 255.It Ev MACHINE 256If the environment variable 257.Ev MACHINE 258is set, it is used as the name of the machine type, when accessing object 259directories of the form obj.MACHINE. If it is not set, it defaults to 260the machine type returned by 261.Xr uname 3 . 262.br 263.Nm Note : 264This option is only used if the -o option to use existing object files is also 265specified. 266.It Ev MAKE 267If the environment variable 268.Ev MAKE 269is set, it is used as the name of the 270.Xr make 1 271executable to be called. If this environment variable is not set, 272.Nm 273defaults to 274.Dq make . 275.El 276.Sh EXAMPLES 277Here is an example 278.Em crunchgen 279input conf file, named 280.Dq Pa kcopy.conf : 281.Pp 282.Bd -literal -offset indent 283srcdirs /usr/src/bin /usr/src/sbin 284 285progs test cp echo sh fsck halt init mount umount myinstall 286ln test [ # test can be invoked via [ 287ln sh -sh # init invokes the shell with "-sh" in argv[0] 288 289special myprog objpaths /homes/leroy/src/myinstall.o # no sources 290 291libs -lutil -lcrypt 292.Ed 293.Pp 294This conf file specifies a small crunched binary consisting of some 295basic system utilities plus a homegrown install program ``myinstall'', 296for which no source directory is specified, but its object file is 297specified directly with the 298.Em special 299line. 300.Pp 301The crunched binary ``kcopy'' can be built as follows: 302.Pp 303.Bd -literal -offset indent 304% crunchgen -m Makefile kcopy.conf # gen Makefile and kcopy.c 305% make objs # build the component progams' .o files 306% make # build the crunched binary kcopy 307% kcopy sh # test that this invokes a sh shell 308$ # it works! 309.Ed 310.Pp 311At this point the binary ``kcopy'' can be copied onto an install floppy 312and hard-linked to the names of the component programs. 313.Sh SEE ALSO 314.Xr crunchide 1 , 315.Xr make 1 316.Sh AUTHORS 317.Nm 318was written by 319.An James da Silva Aq jds@cs.umd.edu . 320.sp 0 321Copyright (c) 1994 University of Maryland. All Rights Reserved. 322.Sh BUGS 323While 324.Nm 325takes care to eliminate link conflicts between the component programs 326of a crunched binary, conflicts are still possible between the 327libraries that are linked in. Some shuffling in the order of 328libraries may be required, and in some rare cases two libraries may 329have an unresolveable conflict and thus cannot be crunched together. 330.Pp 331Some versions of the 332.Bx 333build environment do not by default build the 334intermediate object file for single-source file programs. The ``make 335objs'' target must then be used to get those object files built, or 336some other arrangements made. 337.Pp 338If a program directory being searched for is found, but contains 339no objects, other directories are not searched. This causes the 340following directive to fail: 341.Pp 342.Bd -literal -offset indent 343srcdirs /usr/src/usr.bin /usr/src/usr.bin/less 344progs less gzip 345.Ed 346.Pp 347as the 348.Pa /usr/src/usr.bin/less 349directory will be found with the 350.Pa /usr/src/usr.bin 351.Em srcdirs 352entry, and as it does not contain the require objects, 353.Nm 354fails to find objects for the 355.Em less 356program. To avoid this problem, list specific srcdirs first, and 357the more general ones later, for eg: 358.Pp 359.Bd -literal -offset indent 360srcdirs /usr/src/usr.bin/less /usr/src/usr.bin 361progs less gzip 362.Ed 363.Pp 364will not have the above problem. 365