NAME
crunchgen —
generates build environment
for a crunched binary
SYNOPSIS
crunchgen |
[-fOoq]
[-c
c-file-name]
[-D
src-root]
[-d
build-options]
[-e
exec-file-name]
[-L
lib-dir]
[-m
makefile-name]
[-v
var-spec]
conf-file |
DESCRIPTION
A crunched binary is a program made up of many other programs linked together
into a single executable. The crunched binary
main()
function determines which component program to run by the contents of argv[0].
The main reason to crunch programs together is for fitting as many programs as
possible onto an installation or system recovery floppy.
crunchgen reads in the specifications in
conf-file for a crunched binary, and generates a
Makefile and accompanying top-level C source file that when built create the
crunched executable file from the component programs. For each component
program,
crunchgen can optionally attempt to determine the
object (.o) files that make up the program from its source directory Makefile.
This information is cached between runs.
crunchgen uses the
companion program
crunchide to eliminate link-time conflicts
between the component programs by hiding all unnecessary symbols.
After
crunchgen is run, the crunched binary can be built by
running “make -f ⟨conf-name⟩.mk”. The component
programs' object files must already be built. An “objs” target,
included in the output makefile, will run make in each component program's
source dir to build the object files for the user. This is not done
automatically since in release engineering circumstances it is generally not
desirable to be modifying objects in other directories.
The options are as follows:
-
-
- -c
c-file-name
- Set output C file name to
c-file-name. The default name is
“⟨confname⟩.c”.
-
-
- -D
src-root
- Assume that relative source directory specifications begin
with src-root.
-
-
- -d
build-options
- Set the DBG variable in the generated makefile to
build-options. The default flags are -Os.
-
-
- -e
exec-file-name
- Set crunched binary executable file name to
exec-file-name. The default name is
“<conf-name>”.
-
-
- -f
- Flush cache. Forces the recalculation of cached
parameters.
-
-
- -L
lib-dir
- Try to obtain libraries from
lib-dir.
-
-
- -m
makefile-name
- Set output Makefile name to
makefile-name. The default name is
“⟨conf-name⟩.mk”.
-
-
- -O
- Force crunchgen to parse the program's
Makefile in determine the list of .o files. Without this option
crunchgen expects the program's Makefile to have a
program.ro target that links all the program objects into a single
relocatable.
-
-
- -o
- Use existing object files. Rather than rebuilding object
files via reach-over makefiles, instead search for and use existing object
files.
-
-
- -q
- Quiet operation. Status messages are suppressed.
-
-
- -v
varspec
- Append a variable specification to the on-the fly generated
Makefile.
CRUNCHGEN
CONFIGURATION FILE COMMANDS
crunchgen reads specifications from the
conf-file that describe the components of the crunched
binary. In its simplest use, the component program names are merely listed
along with the top-level source directories in which their sources can be
found.
crunchgen then calculates (via the source makefiles)
and caches the list of object files and their locations. For more specialized
situations, the user can specify by hand all the parameters that
crunchgen needs.
The
conf-file commands are as follows:
-
-
- srcdirs
dirname ...
- A list of source trees in which the source directories of
the component programs can be found. These dirs are searched using the
BSD
“⟨source-dir⟩/⟨progname⟩/”
convention. Multiple srcdirs lines can be specified. The
directories are searched in the order they are given.
-
-
- progs
progname ...
- A list of programs that make up the crunched binary.
Multiple progs lines can be specified.
-
-
- libs
libspec ...
- A list of library specifications to be included in the
crunched binary link. Multiple libs lines can be
specified.
-
-
- ln
progname linkname
- Causes the crunched binary to invoke
progname whenever linkname
appears in argv[0]. This allows programs that change their behavior when
run under different names to operate correctly.
To handle specialized situations, such as when the source is not available or
not built via a conventional Makefile, the following
special
commands can be used to set
crunchgen parameters for a
component program.
-
-
- special
progname keepsymbols
symbols ...
- Don't hide the specified symbols for
progname. Normally all externally visible symbols
for a program is hidden to avoid interference. Multiple
keepsymbols lines can be specified for given
progname.
-
-
- special
progname srcdir
pathname
- Set the source directory for
progname. This is normally calculated by searching
the specified srcdirs for a directory named
progname.
-
-
- special
progname objdir
pathname
- Set the obj directory for progname.
This is normally calculated by looking for a directory named
“obj” under the
srcdir, and if that is not found, the
srcdir itself becomes the
objdir.
Note: This option only takes effect if the -o option to
use existing object files is also specified.
-
-
- special
progname objs
object-file-name ...
- Set the list of object files for program
progname. This is normally calculated by
constructing a temporary makefile that includes
“srcdir / Makefile” and
outputs the value of $(OBJS). Multiple objs lines can be
specified for given progname.
-
-
- special
progname objpaths
full-pathname-to-object-file ...
- Sets the pathnames of the object files for program
progname. This is normally calculated by prepending
the objdir pathname to each file in the
objs list. Multiple objpaths lines can
be specified for given progname.
Only the
objpaths parameter is actually needed by
crunchgen but it is calculated from
objdir
and
objs, which are in turn calculated from
srcdir, so is sometimes convenient to specify the earlier
parameters and let
crunchgen calculate forward from there if
it can.
The makefile produced by
crunchgen contains an optional
objs target that will build the object files for each
component program by running make inside that program's source directory. For
this to work the
srcdir and
objs
parameters must also be valid. If they are not valid for a particular program,
that program is skipped in the
objs target.
The makefile produced by
crunchgen strips certain sections
from the final binary to reduce its size. This includes:
-
-
.eh_frame
- Unwinding tables for exceptions and backtraces.
-
-
.eh_frame_hdr
- Index of the
.eh_frame
section.
-
-
.note
- Optional data for the kernel and/or runtime linker.
-
-
.comment
- Comments in the binary.
-
-
.ident
- Embedded source revisions used by
ident(1).
-
-
.copyright
- Embedded copyright notes.
ENVIRONMENT
-
-
MAKEOBJDIRPREFIX
- If the environment variable
MAKEOBJDIRPREFIX
is set, the object directory will
be prefixed with the path contained in this environment variable.
Note: This variable is only used if the -o option to use
existing object files is also specified.
-
-
MACHINE
- If the environment variable
MACHINE
is set, it is used as the name of the machine type, when accessing object
directories of the form obj.MACHINE. If it is not set, it defaults to the
machine type returned by
uname(3).
Note: This option is only used if the -o option to use
existing object files is also specified.
-
-
MAKE
- If the environment variable
MAKE
is
set, it is used as the name of the
make(1) executable to be
called. If this environment variable is not set,
crunchgen defaults to “make”.
EXAMPLES
Here is an example
crunchgen input conf file, named
“
kcopy.conf”:
srcdirs /usr/src/bin /usr/src/sbin
progs test cp echo sh fsck halt init mount umount myinstall
ln test [ # test can be invoked via [
ln sh -sh # init invokes the shell with "-sh" in argv[0]
special myprog objpaths /homes/leroy/src/myinstall.o # no sources
libs -lutil -lcrypt
This conf file specifies a small crunched binary consisting of some basic system
utilities plus a home-grown install program “myinstall”, for which
no source directory is specified, but its object file is specified directly
with the
special line.
The crunched binary “kcopy” can be built as follows:
% crunchgen -m Makefile kcopy.conf # gen Makefile and kcopy.c
% make objs # build the component programs' .o files
% make # build the crunched binary kcopy
% kcopy sh # test that this invokes a sh shell
$ # it works!
At this point the binary “kcopy” can be copied onto an install
floppy and hard-linked to the names of the component programs.
SEE ALSO
crunchide(1),
make(1)
AUTHORS
crunchgen was written by
James da
Silva
<
jds@cs.umd.edu>.
Copyright (c) 1994 University of Maryland. All Rights Reserved.
BUGS
While
crunchgen takes care to eliminate link conflicts between
the component programs of a crunched binary, conflicts are still possible
between the libraries that are linked in. Some shuffling in the order of
libraries may be required, and in some rare cases two libraries may have an
unresolvable conflict and thus cannot be crunched together.
Some versions of the
BSD build environment do not by
default build the intermediate object file for single-source file programs.
The “make objs” target must then be used to get those object files
built, or some other arrangements made.
If a program directory being searched for is found, but contains no objects,
other directories are not searched. This causes the following directive to
fail:
srcdirs /usr/src/usr.bin /usr/src/usr.bin/less
progs less gzip
as the
/usr/src/usr.bin/less directory will be found with the
/usr/src/usr.bin srcdirs entry, and as it
does not contain the require objects,
crunchgen fails to
find objects for the
less program. To avoid this problem,
list specific srcdirs first, and the more general ones later, for e.g.:
srcdirs /usr/src/usr.bin/less /usr/src/usr.bin
progs less gzip
will not have the above problem.