|CRUNCHGEN(8)||System Manager's Manual||CRUNCHGEN(8)|
generates build environment for a crunched
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. 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
crunchgen can optionally attempt to
determine the object (.o) files that make up the program from its source
directory Makefile. This information is cached in a file named
<conf-name>.cache between runs.
crunchgen is later run again with the
-h flag to eliminate link-time conflicts between the
component programs by hiding all unnecessary symbols. Some symbols may be
left visible via the
keep-list-file options. The
keep-list-file must contain a list of symbols to keep
visible, one symbol per line. Note that the C compiler prepends an
underscore in front of symbols, so to keep the C function
“foo” visible, the option “-k _foo” must be
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
The options are as follows:
-Moption causes it to mangle the symbol name to hide the symbol. It is therefore not advisable to try to run nm(1) on a crunched object file. This is due to the nature of the ELF symbol table and how some architectures use the symbol attributes for their GOT build.
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
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
The conf-file commands are as follows:
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.
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 it is sometimes
convenient to specify the earlier parameters and let
crunchgen calculate forward from there if it
The makefile produced by
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.
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 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
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.
crunchgen was written by
James da Silva
<email@example.com> at the
University of Maryland.
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
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.
|June 11, 2017||OpenBSD-current|