840cf958b8
of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc.
299 lines
9.6 KiB
Groff
299 lines
9.6 KiB
Groff
.\"
|
|
.\" Copyright (c) 1994 University of Maryland
|
|
.\" All Rights Reserved.
|
|
.\"
|
|
.\" Permission to use, copy, modify, distribute, and sell this software and its
|
|
.\" documentation for any purpose is hereby granted without fee, provided that
|
|
.\" the above copyright notice appear in all copies and that both that
|
|
.\" copyright notice and this permission notice appear in supporting
|
|
.\" documentation, and that the name of U.M. not be used in advertising or
|
|
.\" publicity pertaining to distribution of the software without specific,
|
|
.\" written prior permission. U.M. makes no representations about the
|
|
.\" suitability of this software for any purpose. It is provided "as is"
|
|
.\" without express or implied warranty.
|
|
.\"
|
|
.\" U.M. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL U.M.
|
|
.\" BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
|
|
.\" IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.\" Author: James da Silva, Systems Design and Analysis Group
|
|
.\" Computer Science Department
|
|
.\" University of Maryland at College Park
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd September 29, 1997
|
|
.Dt CRUNCHGEN 1
|
|
.Os BSD 4
|
|
.Sh NAME
|
|
.Nm \&crunchgen
|
|
.Nd generates build environment for a crunched binary
|
|
.Sh SYNOPSIS
|
|
.Nm \&crunchgen
|
|
.Op Fl fql
|
|
.Op Fl h Ar makefile-header-name
|
|
.Op Fl m Ar makefile-name
|
|
.Op Fl c Ar c-file-name
|
|
.Op Fl e Ar exec-file-name
|
|
.Op Ar conf-file
|
|
.Sh 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.
|
|
|
|
.Pp
|
|
.Nm Crunchgen
|
|
reads in the specifications in
|
|
.Ar 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,
|
|
.Nm 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.
|
|
.Nm Crunchgen
|
|
uses the companion program
|
|
.Nm crunchide
|
|
to eliminate link-time conflicts between the component programs by
|
|
hiding all unnecessary symbols.
|
|
|
|
.Pp
|
|
After
|
|
.Nm
|
|
is run, the crunched binary can be built by running ``make -f
|
|
<conf-name>.mk''. The component programs' object files must already
|
|
be built. A ``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.
|
|
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width indent
|
|
.It Fl c Ar c-file-name
|
|
Set output C file name to
|
|
.Ar c-file-name .
|
|
The default name is ``<conf-name>.c''.
|
|
.It Fl e Ar exec-file-name
|
|
Set crunched binary executable file name to
|
|
.Ar exec-file-name .
|
|
The default name is ``<conf-name>''.
|
|
.It Fl f
|
|
Flush cache. Forces the recalculation of cached parameters.
|
|
.It Fl l
|
|
List names. Lists the names this binary will respond to.
|
|
.It Fl h Ar makefile-header-name
|
|
Set the name of a file to be included at the beginning of the
|
|
Makefiles generated by
|
|
.Nm crunchgen .
|
|
This is useful to define some make variables such as
|
|
.Ar RELEASE_CRUNCH
|
|
or similar, which might affect the behaviour of make and
|
|
are annoying to pass through environment variables.
|
|
.It Fl m Ar makefile-name
|
|
Set output Makefile name to
|
|
.Ar makefile-name .
|
|
The default name is ``<conf-name>.mk''.
|
|
.It Fl q
|
|
Quiet operation. Status messages are suppressed.
|
|
.El
|
|
.Sh CRUNCHGEN CONFIGURATION FILE COMMANDS
|
|
|
|
.Nm Crunchgen
|
|
reads specifications from the
|
|
.Ar 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.
|
|
.Nm 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
|
|
.Nm
|
|
needs.
|
|
.Pp
|
|
The
|
|
.Ar conf-file
|
|
commands are as follows:
|
|
.Bl -tag -width indent
|
|
.It Nm srcdirs Ar 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
|
|
.Nm srcdirs
|
|
lines can be specified. The directories are searched in the order
|
|
they are given.
|
|
.It Nm progs Ar progname ...
|
|
A list of programs that make up the crunched binary. Multiple
|
|
.Nm progs
|
|
lines can be specified.
|
|
.It Nm libs Ar libspec ...
|
|
A list of library specifications to be included in the crunched binary link.
|
|
Multiple
|
|
.Nm libs
|
|
lines can be specified.
|
|
.It Nm ln Ar progname linkname
|
|
Causes the crunched binary to invoke
|
|
.Ar progname
|
|
whenever
|
|
.Ar linkname
|
|
appears in argv[0]. This allows programs that change their behavior when
|
|
run under different names to operate correctly.
|
|
.El
|
|
|
|
To handle specialized situations, such as when the source is not
|
|
available or not built via a conventional Makefile, the following
|
|
.Nm special
|
|
commands can be used to set
|
|
.Nm
|
|
parameters for a component program.
|
|
.Bl -tag -width indent
|
|
.It Nm special Ar progname Nm srcdir Ar pathname
|
|
Set the source directory for
|
|
.Ar progname .
|
|
This is normally calculated by searching the specified
|
|
.Nm srcdirs
|
|
for a directory named
|
|
.Ar progname .
|
|
.It Nm special Ar progname Nm objdir Ar pathname
|
|
Set the obj directory for
|
|
.Ar progname .
|
|
This is normally calculated by looking for a directory named
|
|
.Dq Pa obj
|
|
under the
|
|
.Ar srcdir ,
|
|
and if that is not found, the
|
|
.Ar srcdir
|
|
itself becomes the
|
|
.Ar objdir .
|
|
.It Nm special Ar progname Nm objs Ar object-file-name ...
|
|
Set the list of object files for program
|
|
.Ar progname .
|
|
This is normally calculated by constructing a temporary makefile that includes
|
|
.Dq Nm srcdir / Pa Makefile
|
|
and outputs the value of $(OBJS).
|
|
.It Nm special Ar progname Nm objpaths Ar full-pathname-to-object-file ...
|
|
Sets the pathnames of the object files for program
|
|
.Ar progname .
|
|
This is normally calculated by prepending the
|
|
.Nm objdir
|
|
pathname to each file in the
|
|
.Nm objs
|
|
list.
|
|
.It Nm special Ar progname Nm objvar Ar variable_name
|
|
Sets the name of the Make variable which holds the list of
|
|
object files for program
|
|
.Ar progname .
|
|
This is normally
|
|
.Nm OBJS
|
|
but some Makefiles might like to use other conventions or
|
|
prepend the program's name to the variable, e.g.
|
|
.Nm SSHD_OBJS .
|
|
.It Nm special Ar progname Nm keep Ar symbol-name ...
|
|
Add specified list of symbols to the keep list for program
|
|
.Ar progname .
|
|
An underscore is prepended to each symbol and it becomes the argument to a
|
|
.Fl k
|
|
option for the
|
|
.Xr crunchide 1
|
|
phase.
|
|
This option is to be used as a last resort as its use can cause a
|
|
symbol conflict, however in certain instances it may be the only way to
|
|
have a symbol resolve.
|
|
.El
|
|
|
|
.Pp
|
|
Only the
|
|
.Nm objpaths
|
|
parameter is actually needed by
|
|
.Nm crunchgen ,
|
|
but it is calculated from
|
|
.Nm objdir
|
|
and
|
|
.Nm objs ,
|
|
which are in turn calculated from
|
|
.Nm srcdir ,
|
|
so is sometimes convenient to specify the earlier parameters and let
|
|
.Nm
|
|
calculate forward from there if it can.
|
|
|
|
.Pp
|
|
The makefile produced by
|
|
.Nm
|
|
contains an optional
|
|
.Ar 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
|
|
.Nm srcdir
|
|
and
|
|
.Nm objs
|
|
parameters must also be valid. If they are not valid for a particular program, that
|
|
program is skipped in the
|
|
.Ar objs
|
|
target.
|
|
.Sh EXAMPLE
|
|
Here is an example
|
|
.Nm
|
|
input conf file, named
|
|
.Dq Pa kcopy.conf :
|
|
.Pp
|
|
.nf
|
|
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
|
|
.fi
|
|
.Pp
|
|
This conf file specifies a small crunched binary consisting of some
|
|
basic system utilities plus a homegrown install program ``myinstall'',
|
|
for which no source directory is specified, but its object file is
|
|
specified directly with the
|
|
.Nm special
|
|
line.
|
|
.Pp
|
|
The crunched binary ``kcopy'' can be built as follows:
|
|
.Pp
|
|
.nf
|
|
% 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!
|
|
.fi
|
|
.Pp
|
|
At this point the binary ``kcopy'' can be copied onto an install floppy
|
|
and hard-linked to the names of the component programs.
|
|
.Sh SEE ALSO
|
|
.Xr crunchide 1
|
|
.Sh CAVEATS
|
|
While
|
|
.Nm crunch
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Sh AUTHORS
|
|
.Nm Crunch
|
|
was written by
|
|
.An James da Silva Aq jds@cs.umd.edu .
|
|
Copyright (c) 1994 University of Maryland. All Rights Reserved.
|