357 lines
11 KiB
Groff
357 lines
11 KiB
Groff
.\" $NetBSD: crunchgen.1,v 1.13 2001/10/04 11:20:39 wiz Exp $
|
|
.\"
|
|
.\" 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
|
|
.\"
|
|
.Dd June 14, 1994
|
|
.Dt CRUNCHGEN 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm crunchgen
|
|
.Nd generates build environment for a crunched binary
|
|
.Sh SYNOPSIS
|
|
.Nm ""
|
|
.Op Fl fq
|
|
.Bk -words
|
|
.Op Fl m Ar makefile-name
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl c Ar c-file-name
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl e Ar exec-file-name
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl D Ar src-root
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl L Ar lib-dir
|
|
.Ek
|
|
.Bk -words
|
|
.Op Ar conf-file
|
|
.Ek
|
|
.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
|
|
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
|
|
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
|
|
uses the companion program
|
|
.Em 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 desireable 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 d Ar build-options
|
|
Set the DBG variable in the generated makefile to
|
|
.Ar build-options .
|
|
The default flags are -Os.
|
|
.It Fl f
|
|
Flush cache. Forces the recalculation of cached parameters.
|
|
.It Fl m Ar makefile-name
|
|
Set output Makefile name to
|
|
.Ar makefile-name .
|
|
The default name is ``<conf-name>.mk''.
|
|
.It Fl o
|
|
Use existing object files. Rather than rebuilding object files via reach-over
|
|
makefiles, instead search for and use existing object files.
|
|
.It Fl q
|
|
Quiet operation. Status messages are suppressed.
|
|
.It Fl D Ar src-root
|
|
Assume that relative source directory specifications begin with
|
|
.Ar src-root .
|
|
.It Fl L Ar lib-dir
|
|
Try to obtain libraries from
|
|
.Ar lib-dir .
|
|
.El
|
|
.Sh CRUNCHGEN CONFIGURATION FILE COMMANDS
|
|
.Nm
|
|
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
|
|
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
|
|
.Bx
|
|
``<source-dir>/<progname>/'' convention. Multiple
|
|
.Em 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
|
|
.Em progs
|
|
lines can be specified.
|
|
.It Nm libs Ar libspec ...
|
|
A list of library specifications to be included in the crunched binary link.
|
|
Multiple
|
|
.Em 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
|
|
.Pp
|
|
To handle specialized situations, such as when the source is not
|
|
available or not built via a conventional Makefile, the following
|
|
.Em 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
|
|
.Em 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 .
|
|
.br
|
|
.Nm Note :
|
|
This option only takes effect if the -o option to use existing object files is also
|
|
specified.
|
|
.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
|
|
.Em objdir
|
|
pathname to each file in the
|
|
.Nm objs
|
|
list.
|
|
.El
|
|
.Pp
|
|
Only the
|
|
.Em objpaths
|
|
parameter is actually needed by
|
|
.Nm
|
|
but it is calculated from
|
|
.Em objdir
|
|
and
|
|
.Em objs ,
|
|
which are in turn calculated from
|
|
.Em 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
|
|
.Em srcdir
|
|
and
|
|
.Em 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 ENVIRONMENT
|
|
.Bl -tag -width MAKEOBJDIRPREFIX
|
|
.It Ev MAKEOBJDIRPREFIX
|
|
If the environment variable
|
|
.Ev MAKEOBJDIRPREFIX
|
|
is set, the object directory will be prefixed with the path contained in this
|
|
environment variable.
|
|
.br
|
|
.Nm Note :
|
|
This variable is only used if the -o option to use existing object files is also
|
|
specified.
|
|
.It Ev MACHINE
|
|
If the environment variable
|
|
.Ev 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
|
|
.Xr uname 3 .
|
|
.br
|
|
.Nm Note :
|
|
This option is only used if the -o option to use existing object files is also
|
|
specified.
|
|
.It Ev MAKE
|
|
If the environment variable
|
|
.Ev MAKE
|
|
is set, it is used as the name of the
|
|
.Xr make 1
|
|
executable to be called. If this environment variable is not set,
|
|
.Nm
|
|
defaults to
|
|
.Dq make .
|
|
.El
|
|
.Sh EXAMPLES
|
|
Here is an example
|
|
.Em crunchgen
|
|
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
|
|
.Em 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 progams' .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 ,
|
|
.Xr make 1
|
|
.Sh AUTHORS
|
|
.Nm
|
|
was written by
|
|
.An James da Silva Aq jds@cs.umd.edu .
|
|
.sp 0
|
|
Copyright (c) 1994 University of Maryland. All Rights Reserved.
|
|
.Sh BUGS
|
|
While
|
|
.Nm
|
|
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 unresolveable conflict and thus cannot be crunched together.
|
|
.Pp
|
|
Some versions of the
|
|
.Bx
|
|
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.
|
|
.Pp
|
|
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:
|
|
.Pp
|
|
.nf
|
|
srcdirs /usr/src/usr.bin /usr/src/usr.bin/less
|
|
progs less gzip
|
|
.fi
|
|
.Pp
|
|
as the
|
|
.Pa /usr/src/usr.bin/less
|
|
directory will be found with the
|
|
.Pa /usr/src/usr.bin
|
|
.Em srcdirs
|
|
entry, and as it does not contain the require objects,
|
|
.Nm
|
|
fails to find objects for the
|
|
.Em less
|
|
program. To avoid this problem, list specific srcdirs first, and
|
|
the more general ones later, for eg:
|
|
.Pp
|
|
.nf
|
|
srcdirs /usr/src/usr.bin/less /usr/src/usr.bin
|
|
progs less gzip
|
|
.fi
|
|
.Pp
|
|
will not have the above problem.
|