1.\" $NetBSD: crunchgen.1,v 1.28 2009/03/12 12:36:48 joerg 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 October 18, 2006 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 fOoq 36.Bk -words 37.Op Fl c Ar c-file-name 38.Ek 39.Bk -words 40.Op Fl D Ar src-root 41.Ek 42.Bk -words 43.Op Fl d Ar build-options 44.Ek 45.Bk -words 46.Op Fl e Ar exec-file-name 47.Ek 48.Bk -words 49.Op Fl L Ar lib-dir 50.Ek 51.Bk -words 52.Op Fl m Ar makefile-name 53.Ek 54.Bk -words 55.Op Fl v Ar var-spec 56.Ek 57.Ar conf-file 58.Sh DESCRIPTION 59A crunched binary is a program made up of many other programs linked 60together into a single executable. 61The crunched binary 62.Fn main 63function determines which component program to run by the contents of 64argv[0]. 65The main reason to crunch programs together is for fitting as many 66programs as possible onto an installation or system recovery floppy. 67.Pp 68.Nm 69reads in the specifications in 70.Ar conf-file 71for a crunched binary, and generates a Makefile and accompanying 72top-level C source file that when built create the crunched executable 73file from the component programs. 74For each component program, 75.Nm 76can optionally attempt to determine the object (.o) files that make up 77the program from its source directory Makefile. 78This information is cached between runs. 79.Nm 80uses the companion program 81.Em crunchide 82to eliminate link-time conflicts between the component programs by 83hiding all unnecessary symbols. 84.Pp 85After 86.Nm 87is run, the crunched binary can be built by running 88.Dq make -f Ao conf-name Ac Ns .mk . 89The component programs' object files must already be built. 90An 91.Dq objs 92target, included in the output makefile, will 93run make in each component program's source dir to build the object 94files for the user. 95This is not done automatically since in release 96engineering circumstances it is generally not desirable to be 97modifying objects in other directories. 98.Pp 99The options are as follows: 100.Bl -tag -width indent 101.It Fl c Ar c-file-name 102Set output C file name to 103.Ar c-file-name . 104The default name is 105.Dq Ao confname Ac Ns .c . 106.It Fl D Ar src-root 107Assume that relative source directory specifications begin with 108.Ar src-root . 109.It Fl d Ar build-options 110Set the DBG variable in the generated makefile to 111.Ar build-options . 112The default flags are -Os. 113.It Fl e Ar exec-file-name 114Set crunched binary executable file name to 115.Ar exec-file-name . 116The default name is 117.Dq Aq conf-name . 118.It Fl f 119Flush cache. 120Forces the recalculation of cached parameters. 121.It Fl L Ar lib-dir 122Try to obtain libraries from 123.Ar lib-dir . 124.It Fl m Ar makefile-name 125Set output Makefile name to 126.Ar makefile-name . 127The default name is 128.Dq Ao conf-name Ac Ns .mk . 129.It Fl O 130Force 131.Nm 132to parse the program's Makefile in determine the list of .o files. 133Without this option 134.Nm 135expects the program's Makefile to have a program.ro target that links all 136the program objects into a single relocatable. 137.It Fl o 138Use existing object files. 139Rather than rebuilding object files via reach-over 140makefiles, instead search for and use existing object files. 141.It Fl q 142Quiet operation. 143Status messages are suppressed. 144.It Fl v Ar varspec 145Append a variable specification to the on-the fly generated Makefile. 146.El 147.Sh CRUNCHGEN CONFIGURATION FILE COMMANDS 148.Nm 149reads specifications from the 150.Ar conf-file 151that describe the components of the crunched binary. 152In its simplest 153use, the component program names are merely listed along with the 154top-level source directories in which their sources can be found. 155.Nm 156then calculates (via the source makefiles) and caches the 157list of object files and their locations. 158For more specialized 159situations, the user can specify by hand all the parameters that 160.Nm 161needs. 162.Pp 163The 164.Ar conf-file 165commands are as follows: 166.Bl -tag -width indent 167.It Nm srcdirs Ar dirname ... 168A list of source trees in which the source directories of the 169component programs can be found. 170These dirs are searched using the 171.Bx 172.Dq Ao source-dir Ac Ns / Ns Ao progname Ac Ns / 173convention. 174Multiple 175.Em srcdirs 176lines can be specified. 177The directories are searched in the order they are given. 178.It Nm progs Ar progname ... 179A list of programs that make up the crunched binary. 180Multiple 181.Em progs 182lines can be specified. 183.It Nm libs Ar libspec ... 184A list of library specifications to be included in the crunched binary link. 185Multiple 186.Em libs 187lines can be specified. 188.It Nm ln Ar progname linkname 189Causes the crunched binary to invoke 190.Ar progname 191whenever 192.Ar linkname 193appears in argv[0]. 194This allows programs that change their behavior when 195run under different names to operate correctly. 196.El 197.Pp 198To handle specialized situations, such as when the source is not 199available or not built via a conventional Makefile, the following 200.Em special 201commands can be used to set 202.Nm 203parameters for a component program. 204.Bl -tag -width indent 205.It Nm special Ar progname Nm keepsymbols Ar symbols ... 206Don't hide the specified symbols for 207.Ar progname . 208Normally all externally visible symbols for 209a program is hidden to avoid interference. 210Multiple 211.Em keepsymbols 212lines can be specified for given 213.Ar progname . 214.It Nm special Ar progname Nm srcdir Ar pathname 215Set the source directory for 216.Ar progname . 217This is normally calculated by searching the specified 218.Em srcdirs 219for a directory named 220.Ar progname . 221.It Nm special Ar progname Nm objdir Ar pathname 222Set the obj directory for 223.Ar progname . 224This is normally calculated by looking for a directory named 225.Dq Pa obj 226under the 227.Ar srcdir , 228and if that is not found, the 229.Ar srcdir 230itself becomes the 231.Ar objdir . 232.Pp 233.Nm Note : 234This option only takes effect if the -o option to use existing object files is also 235specified. 236.It Nm special Ar progname Nm objs Ar object-file-name ... 237Set the list of object files for program 238.Ar progname . 239This is normally calculated by constructing a temporary makefile that includes 240.Dq Nm srcdir / Pa Makefile 241and outputs the value of $(OBJS). 242Multiple 243.Em objs 244lines can be specified for given 245.Ar progname . 246.It Nm special Ar progname Nm objpaths Ar full-pathname-to-object-file ... 247Sets the pathnames of the object files for program 248.Ar progname . 249This is normally calculated by prepending the 250.Em objdir 251pathname to each file in the 252.Nm objs 253list. 254Multiple 255.Em objpaths 256lines can be specified for given 257.Ar progname . 258.El 259.Pp 260Only the 261.Em objpaths 262parameter is actually needed by 263.Nm 264but it is calculated from 265.Em objdir 266and 267.Em objs , 268which are in turn calculated from 269.Em srcdir , 270so is sometimes convenient to specify the earlier parameters and let 271.Nm 272calculate forward from there if it can. 273.Pp 274The makefile produced by 275.Nm 276contains an optional 277.Ar objs 278target that will build the object files for each component program by 279running make inside that program's source directory. 280For this to work the 281.Em srcdir 282and 283.Em objs 284parameters must also be valid. 285If they are not valid for a particular program, that 286program is skipped in the 287.Ar objs 288target. 289.Sh ENVIRONMENT 290.Bl -tag -width MAKEOBJDIRPREFIX 291.It Ev MAKEOBJDIRPREFIX 292If the environment variable 293.Ev MAKEOBJDIRPREFIX 294is set, the object directory will be prefixed with the path contained in this 295environment variable. 296.Pp 297.Nm Note : 298This variable is only used if the -o option to use existing object files is also 299specified. 300.It Ev MACHINE 301If the environment variable 302.Ev MACHINE 303is set, it is used as the name of the machine type, when accessing object 304directories of the form obj.MACHINE. 305If it is not set, it defaults to the machine type returned by 306.Xr uname 3 . 307.Pp 308.Nm Note : 309This option is only used if the -o option to use existing object files is also 310specified. 311.It Ev MAKE 312If the environment variable 313.Ev MAKE 314is set, it is used as the name of the 315.Xr make 1 316executable to be called. 317If this environment variable is not set, 318.Nm 319defaults to 320.Dq make . 321.El 322.Sh EXAMPLES 323Here is an example 324.Em crunchgen 325input conf file, named 326.Dq Pa kcopy.conf : 327.Pp 328.Bd -literal -offset indent 329srcdirs /usr/src/bin /usr/src/sbin 330 331progs test cp echo sh fsck halt init mount umount myinstall 332ln test [ # test can be invoked via [ 333ln sh -sh # init invokes the shell with "-sh" in argv[0] 334 335special myprog objpaths /homes/leroy/src/myinstall.o # no sources 336 337libs -lutil -lcrypt 338.Ed 339.Pp 340This conf file specifies a small crunched binary consisting of some 341basic system utilities plus a home-grown install program 342.Dq myinstall , 343for which no source directory is specified, but its object file is 344specified directly with the 345.Em special 346line. 347.Pp 348The crunched binary 349.Dq kcopy 350can be built as follows: 351.Pp 352.Bd -literal -offset indent 353% crunchgen -m Makefile kcopy.conf # gen Makefile and kcopy.c 354% make objs # build the component programs' .o files 355% make # build the crunched binary kcopy 356% kcopy sh # test that this invokes a sh shell 357$ # it works! 358.Ed 359.Pp 360At this point the binary 361.Dq kcopy 362can be copied onto an install floppy 363and hard-linked to the names of the component programs. 364.Sh SEE ALSO 365.Xr crunchide 1 , 366.Xr make 1 367.Sh AUTHORS 368.Nm 369was written by 370.An James da Silva Aq jds@cs.umd.edu . 371.Pp 372Copyright (c) 1994 University of Maryland. All Rights Reserved. 373.Sh BUGS 374While 375.Nm 376takes care to eliminate link conflicts between the component programs 377of a crunched binary, conflicts are still possible between the 378libraries that are linked in. 379Some shuffling in the order of 380libraries may be required, and in some rare cases two libraries may 381have an unresolvable conflict and thus cannot be crunched together. 382.Pp 383Some versions of the 384.Bx 385build environment do not by default build the 386intermediate object file for single-source file programs. 387The 388.Dq make objs 389target must then be used to get those object files built, or 390some other arrangements made. 391.Pp 392If a program directory being searched for is found, but contains 393no objects, other directories are not searched. 394This causes the following directive to fail: 395.Pp 396.Bd -literal -offset indent 397srcdirs /usr/src/usr.bin /usr/src/usr.bin/less 398progs less gzip 399.Ed 400.Pp 401as the 402.Pa /usr/src/usr.bin/less 403directory will be found with the 404.Pa /usr/src/usr.bin 405.Em srcdirs 406entry, and as it does not contain the require objects, 407.Nm 408fails to find objects for the 409.Em less 410program. 411To avoid this problem, list specific srcdirs first, and 412the more general ones later, for e.g.: 413.Pp 414.Bd -literal -offset indent 415srcdirs /usr/src/usr.bin/less /usr/src/usr.bin 416progs less gzip 417.Ed 418.Pp 419will not have the above problem. 420