usr.sbin/crunch/crunchgen/crunchgen.1

   1 .\"
   2 .\" Copyright (c) 1994 University of Maryland
   3 .\" All Rights Reserved.
   4 .\"
   5 .\" Permission to use, copy, modify, distribute, and sell this software and its
   6 .\" documentation for any purpose is hereby granted without fee, provided that
   7 .\" the above copyright notice appear in all copies and that both that
   8 .\" copyright notice and this permission notice appear in supporting
   9 .\" documentation, and that the name of U.M. not be used in advertising or
  10 .\" publicity pertaining to distribution of the software without specific,
  11 .\" written prior permission.  U.M. makes no representations about the
  12 .\" suitability of this software for any purpose.  It is provided "as is"
  13 .\" without express or implied warranty.
  14 .\"
  15 .\" U.M. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL U.M.
  17 .\" BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  18 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  19 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
  20 .\" IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  21 .\"
  22 .\" Author: James da Silva, Systems Design and Analysis Group
  23 .\"                        Computer Science Department
  24 .\"                        University of Maryland at College Park
  25 .\"
  26 .Dd January 6, 2017
  27 .Dt CRUNCHGEN 1
  28 .Os
  29 .Sh NAME
  30 .Nm crunchgen
  31 .Nd generates build environment for a crunched binary
  32 .Sh SYNOPSIS
  33 .Bk -words
  34 .Nm
  35 .Op Fl foql
  36 .Op Fl h Ar makefile-header-name
  37 .Op Fl m Ar makefile-name
  38 .Op Fl p Ar obj-prefix
  39 .Op Fl c Ar c-file-name
  40 .Op Fl e Ar exec-file-name
  41 .Ar conf-file
  42 .Ek
  43 .Sh DESCRIPTION
  44 A crunched binary is a program made up of many other programs linked
  45 together into a single executable.
  46 The crunched binary
  47 .Fn main
  48 function determines which component program to run by the contents of
  49 .Va argv[0] .
  50 The main reason to crunch programs together is for fitting
  51 as many programs as possible onto an installation or system recovery
  52 floppy.
  53 .Pp
  54 The
  55 .Nm
  56 utility reads in the specifications in
  57 .Ar conf-file
  58 for a crunched binary, and generates a
  59 .Pa Makefile
  60 and accompanying
  61 top-level C source file that when built creates the crunched executable
  62 file from the component programs.
  63 For each component program,
  64 .Nm
  65 can optionally attempt to determine the object (.o) files that make up
  66 the program from its source directory
  67 .Pa Makefile .
  68 This information is cached between runs.
  69 The
  70 .Nm
  71 utility uses the companion program
  72 .Xr crunchide 1
  73 to eliminate link-time conflicts between the component programs by
  74 hiding all unnecessary symbols.
  75 .Pp
  76 The
  77 .Nm
  78 utility places specific requirements on package
  79 .Pa Makefile Ns s
  80 which make it unsuitable for use with
  81 .No non- Ns Bx
  82 sources.
  83 In particular, the
  84 .Pa Makefile
  85 must contain the target
  86 .Ic depend ,
  87 and it must define all object files in the variable
  88 .Va OBJS .
  89 In some cases, you can use a fake
  90 .Pa Makefile :
  91 before looking for
  92 .Pa Makefile
  93 in the source directory
  94 .Pa foo ,
  95 .Nm
  96 looks for the file
  97 .Pa Makefile.foo
  98 in the current directory.
  99 .Pp
 100 After
 101 .Nm
 102 is run, the crunched binary can be built by running
 103 .Dq Li make -f <conf-name>.mk .
 104 The component programs' object files must already be built.
 105 An
 106 .Ic objs
 107 target, included in the output makefile, will
 108 run
 109 .Xr make 1
 110 in each component program's source dir to build the object
 111 files for the user.
 112 This is not done automatically since in release
 113 engineering circumstances it is generally not desirable to be
 114 modifying objects in other directories.
 115 .Pp
 116 The options are as follows:
 117 .Bl -tag -width indent
 118 .It Fl c Ar c-file-name
 119 Set output C file name to
 120 .Ar c-file-name .
 121 The default name is
 122 .Pa <conf-name>.c .
 123 .It Fl e Ar exec-file-name
 124 Set crunched binary executable file name to
 125 .Ar exec-file-name .
 126 The default name is
 127 .Pa <conf-name> .
 128 .It Fl f
 129 Flush cache.
 130 Forces the recalculation of cached parameters.
 131 .It Fl l
 132 List names.
 133 Lists the names this binary will respond to.
 134 .It Fl h Ar makefile-header-name
 135 Set the name of a file to be included at the beginning of the
 136 .Pa Makefile Ns s
 137 generated by
 138 .Nm .
 139 This is useful to define some make variables which might affect the behavior of
 140 .Xr make 1
 141 and are annoying to pass through environment variables.
 142 .It Fl m Ar makefile-name
 143 Set output
 144 .Pa Makefile
 145 name to
 146 .Ar makefile-name .
 147 The default name is
 148 .Pa <conf-name>.mk .
 149 .It Fl o
 150 Add
 151 .Dq Li make obj
 152 rules to each program make target.
 153 .It Fl p Ar obj-prefix
 154 Set the pathname to be prepended to the
 155 .Ic srcdir
 156 when computing the
 157 .Ic objdir .
 158 If this option is not present, then the prefix used
 159 is the content of the
 160 .Ev MAKEOBJDIRPREFIX
 161 environment variable, or
 162 .Pa /usr/obj .
 163 .It Fl q
 164 Quiet operation.
 165 Status messages are suppressed.
 166 .El
 167 .Sh CRUNCHGEN CONFIGURATION FILE COMMANDS
 168 The
 169 .Nm
 170 utility reads specifications from the
 171 .Ar conf-file
 172 that describe the components of the crunched binary.
 173 In its simplest
 174 use, the component program names are merely listed along with the
 175 top-level source directories in which their sources can be found.
 176 The
 177 .Nm
 178 utility then calculates (via the source makefiles) and caches the
 179 list of object files and their locations.
 180 For more specialized
 181 situations, the user can specify by hand all the parameters that
 182 .Nm
 183 needs.
 184 .Pp
 185 The
 186 .Ar conf-file
 187 commands are as follows:
 188 .Bl -tag -width indent
 189 .It Ic srcdirs Ar dirname ...
 190 A list of source trees in which the source directories of the
 191 component programs can be found.
 192 These dirs are searched using the
 193 .Bx
 194 .Dq Pa <source-dir>/<progname>/
 195 convention.
 196 Multiple
 197 .Ic srcdirs
 198 lines can be specified.
 199 The directories are searched in the order they are given.
 200 .It Ic progs Ar progname ...
 201 A list of programs that make up the crunched binary.
 202 Multiple
 203 .Ic progs
 204 lines can be specified.
 205 .It Ic libs Ar libspec ...
 206 A list of library specifications to be included in the crunched binary link.
 207 Multiple
 208 .Ic libs
 209 lines can be specified.
 210 .It Ic libs_so Ar libspec ...
 211 A list of library specifications to be dynamically linked in the
 212 crunched binary.
 213 These libraries will need to be made available via the run-time link-editor
 214 .Xr rtld 1
 215 when the component program that requires them is executed from
 216 the crunched binary.
 217 Multiple
 218 .Ic libs_so
 219 lines can be specified.
 220 The
 221 .Ic libs_so
 222 directive overrides a library specified gratuitously on a
 223 .Ic libs
 224 line.
 225 .It Ic buildopts Ar buildopts ...
 226 A list of build options to be added to every make target.
 227 .It Ic ln Ar progname linkname
 228 Causes the crunched binary to invoke
 229 .Ar progname
 230 whenever
 231 .Ar linkname
 232 appears in
 233 .Va argv[0] .
 234 This allows programs that change their behavior when
 235 run under different names to operate correctly.
 236 .El
 237 .Pp
 238 To handle specialized situations, such as when the source is not
 239 available or not built via a conventional
 240 .Pa Makefile ,
 241 the following
 242 .Ic special
 243 commands can be used to set
 244 .Nm
 245 parameters for a component program.
 246 .Bl -tag -width indent
 247 .It Ic special Ar progname Ic srcdir Ar pathname
 248 Set the source directory for
 249 .Ar progname .
 250 This is normally calculated by searching the specified
 251 .Ic srcdirs
 252 for a directory named
 253 .Ar progname .
 254 .It Ic special Ar progname Ic objdir Ar pathname
 255 Set the
 256 .Pa obj
 257 directory for
 258 .Ar progname .
 259 The
 260 .Pa obj
 261 directory is normally calculated by looking for a directory
 262 whose name is that of the source directory prepended by
 263 one of the following components, in order of priority:
 264 the
 265 .Fl p
 266 argument passed to the command line; or,
 267 the value of the
 268 .Ev MAKEOBJDIRPREFIX
 269 environment variable, or
 270 .Pa /usr/obj .
 271 If the directory is not found, the
 272 .Ic srcdir
 273 itself becomes the
 274 .Ic objdir .
 275 .It Ic special Ar progname Ic buildopts Ar buildopts
 276 Define a set of build options that should be added to
 277 .Xr make 1
 278 targets in addition to those specified using
 279 .Ic buildopts
 280 when processing
 281 .Ar progname .
 282 .It Ic special Ar progname Ic objs Ar object-file-name ...
 283 Set the list of object files for program
 284 .Ar progname .
 285 This is normally calculated by constructing a temporary makefile that includes
 286 .Dq Ic srcdir Ns / Ns Pa Makefile
 287 and outputs the value of
 288 .Va $(OBJS) .
 289 .It Ic special Ar progname Ic objpaths Ar full-pathname-to-object-file ...
 290 Sets the pathnames of the object files for program
 291 .Ar progname .
 292 This is normally calculated by prepending the
 293 .Ic objdir
 294 pathname to each file in the
 295 .Ic objs
 296 list.
 297 .It Ic special Ar progname Ic objvar Ar variable_name
 298 Sets the name of the
 299 .Xr make 1
 300 variable which holds the list of
 301 object files for program
 302 .Ar progname .
 303 This is normally
 304 .Va OBJS
 305 but some
 306 .Pa Makefile Ns s
 307 might like to use other conventions or
 308 prepend the program's name to the variable, e.g.,
 309 .Va SSHD_OBJS .
 310 .It Ic special Ar progname Ic lib Ar library-name ...
 311 Specifies libraries to be linked with object files to produce
 312 .Ar progname Ns Pa .lo .
 313 This can be useful with libraries which redefine routines in
 314 the standard libraries, or poorly written libraries which
 315 reference symbols in the object files.
 316 .It Ic special Ar progname Ic keep Ar symbol-name ...
 317 Add specified list of symbols to the keep list for program
 318 .Ar progname .
 319 An underscore
 320 .Pq Ql _
 321 is prepended to each symbol and it becomes the argument to a
 322 .Fl k
 323 option for the
 324 .Xr crunchide 1
 325 phase.
 326 This option is to be used as a last resort as its use can cause a
 327 symbol conflict, however in certain instances it may be the only way to
 328 have a symbol resolve.
 329 .It Ic special Ar progname Ic ident Ar identifier
 330 Set the
 331 .Pa Makefile Ns / Ns Tn C
 332 identifier for
 333 .Ar progname .
 334 This is normally generated from a
 335 .Ar progname ,
 336 mapping
 337 .Ql -
 338 to
 339 .Ql _
 340 and ignoring all other non-identifier characters.
 341 This leads to programs named
 342 .Qq Li foo.bar
 343 and
 344 .Qq Li foobar
 345 to map to the same identifier.
 346 .El
 347 .Pp
 348 Only the
 349 .Ic objpaths
 350 parameter is actually needed by
 351 .Nm ,
 352 but it is calculated from
 353 .Ic objdir
 354 and
 355 .Ic objs ,
 356 which are in turn calculated from
 357 .Ic srcdir ,
 358 so is sometimes convenient to specify the earlier parameters and let
 359 .Nm
 360 calculate forward from there if it can.
 361 .Pp
 362 The makefile produced by
 363 .Nm
 364 contains an optional
 365 .Ic objs
 366 target that will build the object files for each component program by
 367 running
 368 .Xr make 1
 369 inside that program's source directory.
 370 For this to work the
 371 .Ic srcdir
 372 and
 373 .Ic objs
 374 parameters must also be valid.
 375 If they are not valid for a particular program, that
 376 program is skipped in the
 377 .Ic objs
 378 target.
 379 .Sh EXAMPLES
 380 Here is an example
 381 .Nm
 382 input conf file, named
 383 .Dq Pa kcopy.conf :
 384 .Bd -literal -offset indent
 385 srcdirs /usr/src/bin /usr/src/sbin
 386
 387 progs test cp echo sh fsck halt init mount umount myinstall
 388 progs anotherprog
 389 ln test [       # test can be invoked via [
 390 ln sh -sh       # init invokes the shell with "-sh" in argv[0]
 391
 392 special myprog objpaths /homes/leroy/src/myinstall.o # no sources
 393
 394 special anotherprog -DNO_FOO WITHOUT_BAR=YES
 395
 396 libs -lutil -lcrypt
 397 .Ed
 398 .Pp
 399 This conf file specifies a small crunched binary consisting of some
 400 basic system utilities plus a homegrown install program
 401 .Dq Pa myinstall ,
 402 for which no source directory is specified, but its object file is
 403 specified directly with the
 404 .Ic special
 405 line.
 406 .Pp
 407 Additionally when
 408 .Dq Pa anotherprog
 409 is built the arguments
 410 .Pp
 411 .Dl -DNO_FOO WITHOUT_BAR=YES
 412 .Pp
 413 are added to all build targets.
 414 .Pp
 415 The crunched binary
 416 .Dq Pa kcopy
 417 can be built as follows:
 418 .Bd -literal -offset indent
 419 % crunchgen -m Makefile kcopy.conf    # gen Makefile and kcopy.c
 420 % make objs             # build the component programs' .o files
 421 % make                  # build the crunched binary kcopy
 422 % kcopy sh              # test that this invokes a sh shell
 423 $                       # it works!
 424 .Ed
 425 .Pp
 426 At this point the binary
 427 .Dq Pa kcopy
 428 can be copied onto an install floppy
 429 and hard-linked to the names of the component programs.
 430 .Pp
 431 Note that if the
 432 .Ic libs_so
 433 command had been used, copies of the libraries so named
 434 would also need to be copied to the install floppy.
 435 .Sh SEE ALSO
 436 .Xr crunchide 1 ,
 437 .Xr make 1 ,
 438 .Xr rtld 1
 439 .Sh AUTHORS
 440 .An -nosplit
 441 The
 442 .Nm
 443 utility was written by
 444 .An James da Silva Aq Mt jds@cs.umd.edu .
 445 .Pp
 446 Copyright (c) 1994 University of Maryland.
 447 All Rights Reserved.
 448 .Pp
 449 The
 450 .Ic libs_so
 451 keyword was added in 2005 by
 452 .An Adrian Steinmann Aq Mt ast@marabu.ch
 453 and
 454 .An Ceri Davies Aq Mt ceri@FreeBSD.org .
 455 .Sh CAVEATS
 456 While
 457 .Nm
 458 takes care to eliminate link conflicts between the component programs
 459 of a crunched binary, conflicts are still possible between the
 460 libraries that are linked in.
 461 Some shuffling in the order of
 462 libraries may be required, and in some rare cases two libraries may
 463 have an unresolvable conflict and thus cannot be crunched together.
 464 .Pp
 465 Some versions of the
 466 .Bx
 467 build environment do not by default build the
 468 intermediate object file for single-source file programs.
 469 The
 470 .Dq Li make objs
 471 must then be used to get those object files built, or
 472 some other arrangements made.