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