1.\" $NetBSD: crunchgen.1,v 1.42 2021/08/01 15:52:11 andvar 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 January 2, 2020 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 FfOoq 36.Op Fl c Ar c-file-name 37.Op Fl D Ar src-root 38.Op Fl e Ar exec-file-name 39.Op Fl L Ar lib-dir 40.Op Fl m Ar makefile-name 41.Op Fl v Ar var-spec 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 e Ar exec-file-name 96Set crunched binary executable file name to 97.Ar exec-file-name . 98The default name is 99.Dq Aq Mt conf-name . 100.It Fl F 101Enable fortify. 102.It Fl f 103Flush cache. 104Forces the recalculation of cached parameters. 105.It Fl L Ar lib-dir 106Try to obtain libraries from 107.Ar lib-dir . 108.It Fl m Ar makefile-name 109Set output Makefile name to 110.Ar makefile-name . 111The default name is 112.Dq Ao conf-name Ac Ns .mk . 113.It Fl O 114Force 115.Nm 116to parse the program's Makefile in determine the list of .o files. 117Without this option 118.Nm 119expects the program's Makefile to have a program.ro target that links all 120the program objects into a single relocatable. 121.It Fl o 122Use existing object files. 123Rather than rebuilding object files via reach-over 124makefiles, instead search for and use existing object files. 125.It Fl q 126Quiet operation. 127Status messages are suppressed. 128.It Fl v Ar varspec 129Append a variable specification to the on-the fly generated Makefiles 130for the individual programs. 131.It Fl V Ar varspec 132Set the variable in the top level Makefile, and pass it in the command 133line of all sub-makes, so that it cannot be overwritten. 134.El 135.Sh CRUNCHGEN CONFIGURATION FILE COMMANDS 136.Nm 137reads specifications from the 138.Ar conf-file 139that describe the components of the crunched binary. 140In its simplest 141use, the component program names are merely listed along with the 142top-level source directories in which their sources can be found. 143.Nm 144then calculates (via the source makefiles) and caches the 145list of object files and their locations. 146For more specialized 147situations, the user can specify by hand all the parameters that 148.Nm 149needs. 150.Pp 151The 152.Ar conf-file 153commands are as follows: 154.Bl -tag -width indent 155.It Nm srcdirs Ar dirname ... 156A list of source trees in which the source directories of the 157component programs can be found. 158These dirs are searched using the 159.Bx 160.Dq Ao source-dir Ac Ns / Ns Ao progname Ac Ns / 161convention. 162Multiple 163.Em srcdirs 164lines can be specified. 165The directories are searched in the order they are given. 166.It Nm progs Ar progname ... 167A list of programs that make up the crunched binary. 168Multiple 169.Em progs 170lines can be specified. 171.It Nm libs Ar libspec ... 172A list of library specifications to be included in the crunched binary link. 173Multiple 174.Em libs 175lines can be specified. 176.It Nm ln Ar progname linkname 177Causes the crunched binary to invoke 178.Ar progname 179whenever 180.Ar linkname 181appears in argv[0]. 182This allows programs that change their behavior when 183run under different names to operate correctly. 184.El 185.Pp 186To handle specialized situations, such as when the source is not 187available or not built via a conventional Makefile, the following 188.Em special 189commands can be used to set 190.Nm 191parameters for a component program. 192.Bl -tag -width indent 193.It Nm special Ar progname Nm keepsymbols Ar symbols ... 194Don't hide the specified symbols for 195.Ar progname . 196Normally all externally visible symbols for 197a program is hidden to avoid interference. 198Multiple 199.Em keepsymbols 200lines can be specified for given 201.Ar progname . 202.It Nm special Ar progname Nm srcdir Ar pathname 203Set the source directory for 204.Ar progname . 205This is normally calculated by searching the specified 206.Em srcdirs 207for a directory named 208.Ar progname . 209.It Nm special Ar progname Nm objdir Ar pathname 210Set the obj directory for 211.Ar progname . 212This is normally calculated by looking for a directory named 213.Dq Pa obj 214under the 215.Ar srcdir , 216and if that is not found, the 217.Ar srcdir 218itself becomes the 219.Ar objdir . 220.Pp 221.Nm Note : 222This option only takes effect if the -o option to use existing object files is also 223specified. 224.It Nm special Ar progname Nm objs Ar object-file-name ... 225Set the list of object files for program 226.Ar progname . 227This is normally calculated by constructing a temporary makefile that includes 228.Dq Nm srcdir / Pa Makefile 229and outputs the value of $(OBJS). 230Multiple 231.Em objs 232lines can be specified for given 233.Ar progname . 234.It Nm special Ar progname Nm objpaths Ar full-pathname-to-object-file ... 235Sets the pathnames of the object files for program 236.Ar progname . 237This is normally calculated by prepending the 238.Em objdir 239pathname to each file in the 240.Nm objs 241list. 242Multiple 243.Em objpaths 244lines can be specified for given 245.Ar progname . 246.El 247.Pp 248Only the 249.Em objpaths 250parameter is actually needed by 251.Nm 252but it is calculated from 253.Em objdir 254and 255.Em objs , 256which are in turn calculated from 257.Em srcdir , 258so is sometimes convenient to specify the earlier parameters and let 259.Nm 260calculate forward from there if it can. 261.Pp 262The makefile produced by 263.Nm 264contains an optional 265.Ar objs 266target that will build the object files for each component program by 267running make inside that program's source directory. 268For this to work the 269.Em srcdir 270and 271.Em objs 272parameters must also be valid. 273If they are not valid for a particular program, that 274program is skipped in the 275.Ar objs 276target. 277.Pp 278The makefile produced by 279.Nm 280strips certain sections from the final binary to reduce its size. 281This includes: 282.Bl -tag -width ".Li .eh_frame_hdr" 283.It Li .eh_frame 284Unwinding tables for exceptions and backtraces. 285.It Li .eh_frame_hdr 286Index of the 287.Li .eh_frame 288section. 289.It Li .note 290Optional data for the kernel and/or runtime linker. 291.It Li .comment 292Comments in the binary. 293.It Li .ident 294Embedded source revisions used by 295.Xr ident 1 . 296.It Li .copyright 297Embedded copyright notes. 298.El 299.Sh ENVIRONMENT 300.Bl -tag -width MAKEOBJDIRPREFIX 301.It Ev MAKEOBJDIRPREFIX 302If the environment variable 303.Ev MAKEOBJDIRPREFIX 304is set, the object directory will be prefixed with the path contained in this 305environment variable. 306.Pp 307.Nm Note : 308This variable is only used if the -o option to use existing object files is also 309specified. 310.It Ev MACHINE 311If the environment variable 312.Ev MACHINE 313is set, it is used as the name of the machine type, when accessing object 314directories of the form obj.MACHINE. 315If it is not set, it defaults to the machine type returned by 316.Xr uname 3 . 317.Pp 318.Nm Note : 319This option is only used if the -o option to use existing object files is also 320specified. 321.It Ev MAKE 322If the environment variable 323.Ev MAKE 324is set, it is used as the name of the 325.Xr make 1 326executable to be called. 327If this environment variable is not set, 328.Nm 329defaults to 330.Dq make . 331.El 332.Sh EXAMPLES 333Here is an example 334.Em crunchgen 335input conf file, named 336.Dq Pa kcopy.conf : 337.Bd -literal -offset indent 338srcdirs /usr/src/bin /usr/src/sbin 339 340progs test cp echo sh fsck halt init mount umount myinstall 341ln test [ # test can be invoked via [ 342ln sh -sh # init invokes the shell with "-sh" in argv[0] 343 344special myprog objpaths /homes/leroy/src/myinstall.o # no sources 345 346libs -lutil -lcrypt 347.Ed 348.Pp 349This conf file specifies a small crunched binary consisting of some 350basic system utilities plus a home-grown install program 351.Dq myinstall , 352for which no source directory is specified, but its object file is 353specified directly with the 354.Em special 355line. 356.Pp 357The crunched binary 358.Dq kcopy 359can be built as follows: 360.Bd -literal -offset indent 361% crunchgen -m Makefile kcopy.conf # gen Makefile and kcopy.c 362% make objs # build the component programs' .o files 363% make # build the crunched binary kcopy 364% kcopy sh # test that this invokes a sh shell 365$ # it works! 366.Ed 367.Pp 368At this point the binary 369.Dq kcopy 370can be copied onto an install floppy 371and hard-linked to the names of the component programs. 372.Sh MIGRATION GUIDE 373.Nm 374used to have builtin entries for some Makefile variables, namely it 375set by default: 376.Bd -literal -offset indent 377DBG=-Os 378LDSTATIC=-static 379NOPIE= 380NOMAN= 381NOFORT= 382NOLIBCSANITIZER= 383NOSANITIZER= 384NOSSP= 385.Ed 386.Pp 387To set those defaults again, use: 388.Bd -literal -offset indent 389-V DBG=-Os \e 390-V LDSTATIC=-static -V NOPIE= \e 391-V NOMAN= \e 392-V NOFORT= -V NOLIBCSANITIZER= -V NOSANITIZER= -V NOSSP= 393.Ed 394.Pp 395The 396.Fl p 397flag that set pic mode internally set: 398.Bd -literal -offset indent 399LDSTATIC="-static -pie" 400.Ed 401.Pp 402and did not set: 403.Bd -literal -offset indent 404NOPIE= 405.Ed 406.Pp 407The remaining flags just disabled setting the variables that turned off various 408sanitizers, fortify, and stack protector. 409The mapping of those variables to the old options is: 410.Bl -tag -width XX -offset indent 411.It Fl F 412.Dv NOFORT 413.It Fl P 414.Dv NOSSP 415.It Fl S 416.Dv NOLIBCSANITIZER 417.It Fl s 418.Dv NOSANITIZER 419.El 420.Sh SEE ALSO 421.Xr crunchide 1 , 422.Xr make 1 423.Sh AUTHORS 424.Nm 425was written by 426.An James da Silva Aq Mt jds@cs.umd.edu . 427.Pp 428Copyright (c) 1994 University of Maryland. 429All Rights Reserved. 430.Sh BUGS 431While 432.Nm 433takes care to eliminate link conflicts between the component programs 434of a crunched binary, conflicts are still possible between the 435libraries that are linked in. 436Some shuffling in the order of 437libraries may be required, and in some rare cases two libraries may 438have an unresolvable conflict and thus cannot be crunched together. 439.Pp 440Some versions of the 441.Bx 442build environment do not by default build the 443intermediate object file for single-source file programs. 444The 445.Dq make objs 446target must then be used to get those object files built, or 447some other arrangements made. 448.Pp 449If a program directory being searched for is found, but contains 450no objects, other directories are not searched. 451This causes the following directive to fail: 452.Bd -literal -offset indent 453srcdirs /usr/src/usr.bin /usr/src/usr.bin/less 454progs less gzip 455.Ed 456.Pp 457as the 458.Pa /usr/src/usr.bin/less 459directory will be found with the 460.Pa /usr/src/usr.bin 461.Em srcdirs 462entry, and as it does not contain the require objects, 463.Nm 464fails to find objects for the 465.Em less 466program. 467To avoid this problem, list specific srcdirs first, and 468the more general ones later, for e.g.: 469.Bd -literal -offset indent 470srcdirs /usr/src/usr.bin/less /usr/src/usr.bin 471progs less gzip 472.Ed 473.Pp 474will not have the above problem. 475