Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CRUNCHGEN(1)		  BSD General Commands Manual		  CRUNCHGEN(1)

     crunchgen -- generates build environment for a crunched binary

     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

     A crunched	binary is a program made up of many other programs linked to-
     gether into a single executable.  The crunched binary main() function de-
     termines 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 pro-
     grams.  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 be-
     tween 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	cir-
     cumstances	it is generally	not desirable to be modifying objects in other

     The options are as	follows:

     -c	c-file-name
	     Set output	C file name to c-file-name.  The default name is

     -D	src-root
	     Assume that relative source directory specifications begin	with

     -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

     -O	     Force crunchgen to	parse the program's Makefile in	determine the
	     list of .o	files.	Without	this option crunchgen expects the pro-
	     gram's Makefile to	have a 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 ob-
	     ject files.

     -q	     Quiet operation.  Status messages are suppressed.

     -v	varspec
	     Append a variable specification to	the on-the fly generated Make-

     crunchgen reads specifications from the conf-file that describe the com-
     ponents of	the crunched binary.  In its simplest use, the component pro-
     gram 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 loca-
     tions.  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 or-
	     der 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 be-
	     havior when run under different names to operate correctly.

     To	handle specialized situations, such as when the	source is not avail-
     able or not built via a conventional Makefile, the	following special com-
     mands 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 ex-
	     ternally visible symbols for a program is hidden to avoid inter-
	     ference.  Multiple	keepsymbols lines can be specified for given

     special progname srcdir pathname
	     Set the source directory for progname.  This is normally calcu-
	     lated by searching	the specified srcdirs for a directory named

     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 ex-
	     isting object files is also specified.

     special progname objs object-file-name ...
	     Set the list of object files for program progname.	 This is nor-
	     mally calculated by constructing a	temporary makefile that	in-
	     cludes "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 spec-
	     ified 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 particu-
     lar program, that program is skipped in the objs target.

     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 de-
		       faults to "make".

     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	di-
     rectly 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.

     crunchide(1), make(1)

     crunchgen was written by James da Silva <>.

     Copyright (c) 1994	University of Maryland.	 All Rights Reserved.

     While crunchgen takes care	to eliminate link conflicts between the	compo-
     nent programs of a	crunched binary, conflicts are still possible between
     the libraries that	are linked in.	Some shuffling in the order of li-
     braries 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 ob-
     jects, other directories are not searched.	 This causes the following di-
     rective 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.

BSD			       October 18, 2006				   BSD


Want to link to this manual page? Use this URL:

home | help