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