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