476 lines
12 KiB
Groff
476 lines
12 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 December 23, 2005
|
|
.Dt CRUNCHGEN 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm crunchgen
|
|
.Nd generates build environment for a crunched binary
|
|
.Sh SYNOPSIS
|
|
.Bk -words
|
|
.Nm
|
|
.Op Fl foql
|
|
.Op Fl h Ar makefile-header-name
|
|
.Op Fl m Ar makefile-name
|
|
.Op Fl p Ar obj-prefix
|
|
.Op Fl c Ar c-file-name
|
|
.Op Fl e Ar exec-file-name
|
|
.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
|
|
.Fn main
|
|
function determines which component program to run by the contents of
|
|
.Va 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
|
|
The
|
|
.Nm
|
|
utility reads in the specifications in
|
|
.Ar conf-file
|
|
for a crunched binary, and generates a
|
|
.Pa Makefile
|
|
and accompanying
|
|
top-level C source file that when built creates 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
|
|
.Pa Makefile .
|
|
This information is cached between runs.
|
|
The
|
|
.Nm
|
|
utility uses the companion program
|
|
.Xr crunchide 1
|
|
to eliminate link-time conflicts between the component programs by
|
|
hiding all unnecessary symbols.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility places specific requirements on package
|
|
.Pa Makefile Ns s
|
|
which make it unsuitable for use with
|
|
.No non- Ns Bx
|
|
sources.
|
|
In particular, the
|
|
.Pa Makefile
|
|
must contain the target
|
|
.Ic depend ,
|
|
and it must define all object files in the variable
|
|
.Va OBJS .
|
|
In some cases, you can use a fake
|
|
.Pa Makefile :
|
|
before looking for
|
|
.Pa Makefile
|
|
in the source directory
|
|
.Pa foo ,
|
|
.Nm
|
|
looks for the file
|
|
.Pa Makefile.foo
|
|
in the current directory.
|
|
.Pp
|
|
After
|
|
.Nm
|
|
is run, the crunched binary can be built by running
|
|
.Dq Li make -f <conf-name>.mk .
|
|
The component programs' object files must already be built.
|
|
An
|
|
.Ic objs
|
|
target, included in the output makefile, will
|
|
run
|
|
.Xr make 1
|
|
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
|
|
.Pa <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
|
|
.Pa <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
|
|
.Pa Makefile Ns s
|
|
generated by
|
|
.Nm .
|
|
This is useful to define some make variables such as
|
|
.Va RELEASE_CRUNCH
|
|
or similar, which might affect the behavior of
|
|
.Xr make 1
|
|
and are annoying to pass through environment variables.
|
|
.It Fl m Ar makefile-name
|
|
Set output
|
|
.Pa Makefile
|
|
name to
|
|
.Ar makefile-name .
|
|
The default name is
|
|
.Pa <conf-name>.mk .
|
|
.It Fl o
|
|
Add
|
|
.Dq Li make obj
|
|
rules to each program make target.
|
|
.It Fl p Ar obj-prefix
|
|
Set the pathname to be prepended to the
|
|
.Ic srcdir
|
|
when computing the
|
|
.Ic objdir .
|
|
If this option is not present, then the prefix used
|
|
is the content of the
|
|
.Ev MAKEOBJDIRPREFIX
|
|
environment variable, or
|
|
.Pa /usr/obj .
|
|
.It Fl q
|
|
Quiet operation.
|
|
Status messages are suppressed.
|
|
.El
|
|
.Sh CRUNCHGEN CONFIGURATION FILE COMMANDS
|
|
The
|
|
.Nm
|
|
utility 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.
|
|
The
|
|
.Nm
|
|
utility 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 Ic 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
|
|
.Dq Pa <source-dir>/<progname>/
|
|
convention.
|
|
Multiple
|
|
.Ic srcdirs
|
|
lines can be specified.
|
|
The directories are searched in the order they are given.
|
|
.It Ic progs Ar progname ...
|
|
A list of programs that make up the crunched binary.
|
|
Multiple
|
|
.Ic progs
|
|
lines can be specified.
|
|
.It Ic libs Ar libspec ...
|
|
A list of library specifications to be included in the crunched binary link.
|
|
Multiple
|
|
.Ic libs
|
|
lines can be specified.
|
|
.It Ic libs_so Ar libspec ...
|
|
A list of library specifications to be dynamically linked in the
|
|
crunched binary.
|
|
These libraries will need to be made available via the run-time link-editor
|
|
.Xr rtld 1
|
|
when the component program that requires them is executed from
|
|
the crunched binary.
|
|
Multiple
|
|
.Ic libs_so
|
|
lines can be specified.
|
|
The
|
|
.Ic libs_so
|
|
directive overrides a library specified gratuitously on a
|
|
.Ic libs
|
|
line.
|
|
.It Ic buildopts Ar buildopts ...
|
|
A list of build options to be added to every make target.
|
|
.It Ic ln Ar progname linkname
|
|
Causes the crunched binary to invoke
|
|
.Ar progname
|
|
whenever
|
|
.Ar linkname
|
|
appears in
|
|
.Va 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
|
|
.Pa Makefile ,
|
|
the following
|
|
.Ic special
|
|
commands can be used to set
|
|
.Nm
|
|
parameters for a component program.
|
|
.Bl -tag -width indent
|
|
.It Ic special Ar progname Ic srcdir Ar pathname
|
|
Set the source directory for
|
|
.Ar progname .
|
|
This is normally calculated by searching the specified
|
|
.Ic srcdirs
|
|
for a directory named
|
|
.Ar progname .
|
|
.It Ic special Ar progname Ic objdir Ar pathname
|
|
Set the
|
|
.Pa obj
|
|
directory for
|
|
.Ar progname .
|
|
The
|
|
.Pa obj
|
|
directory is normally calculated by looking for a directory
|
|
whose name is that of the source directory prepended by
|
|
one of the following components, in order of priority:
|
|
the
|
|
.Fl p
|
|
argument passed to the command line; or,
|
|
the value of the
|
|
.Ev MAKEOBJDIRPREFIX
|
|
environment variable, or
|
|
.Pa /usr/obj .
|
|
If the directory is not found, the
|
|
.Ic srcdir
|
|
itself becomes the
|
|
.Ic objdir .
|
|
.It Ic special Ar progname Ic buildopts Ar buildopts
|
|
Define a set of build options that should be added to
|
|
.Xr make 1
|
|
targets in addition to those specified using
|
|
.Ic buildopts
|
|
when processing
|
|
.Ar progname .
|
|
.It Ic special Ar progname Ic 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 Ic srcdir Ns / Ns Pa Makefile
|
|
and outputs the value of
|
|
.Va $(OBJS) .
|
|
.It Ic special Ar progname Ic 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
|
|
.Ic objdir
|
|
pathname to each file in the
|
|
.Ic objs
|
|
list.
|
|
.It Ic special Ar progname Ic objvar Ar variable_name
|
|
Sets the name of the
|
|
.Xr make 1
|
|
variable which holds the list of
|
|
object files for program
|
|
.Ar progname .
|
|
This is normally
|
|
.Va OBJS
|
|
but some
|
|
.Pa Makefile Ns s
|
|
might like to use other conventions or
|
|
prepend the program's name to the variable, e.g.\&
|
|
.Va SSHD_OBJS .
|
|
.It Ic special Ar progname Ic lib Ar library-name ...
|
|
Specifies libraries to be linked with object files to produce
|
|
.Ar progname Ns Pa .lo .
|
|
This can be useful with libraries which redefine routines in
|
|
the standard libraries, or poorly written libraries which
|
|
reference symbols in the object files.
|
|
.It Ic special Ar progname Ic keep Ar symbol-name ...
|
|
Add specified list of symbols to the keep list for program
|
|
.Ar progname .
|
|
An underscore
|
|
.Pq Ql _
|
|
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.
|
|
.It Ic special Ar progname Ic ident Ar identifier
|
|
Set the
|
|
.Pa Makefile Ns / Ns Tn C
|
|
identifier for
|
|
.Ar progname .
|
|
This is normally generated from a
|
|
.Ar progname ,
|
|
mapping
|
|
.Ql -
|
|
to
|
|
.Ql _
|
|
and ignoring all other non-identifier characters.
|
|
This leads to programs named
|
|
.Qq Li foo.bar
|
|
and
|
|
.Qq Li foobar
|
|
to map to the same identifier.
|
|
.El
|
|
.Pp
|
|
Only the
|
|
.Ic objpaths
|
|
parameter is actually needed by
|
|
.Nm ,
|
|
but it is calculated from
|
|
.Ic objdir
|
|
and
|
|
.Ic objs ,
|
|
which are in turn calculated from
|
|
.Ic 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
|
|
.Ic objs
|
|
target that will build the object files for each component program by
|
|
running
|
|
.Xr make 1
|
|
inside that program's source directory.
|
|
For this to work the
|
|
.Ic srcdir
|
|
and
|
|
.Ic objs
|
|
parameters must also be valid.
|
|
If they are not valid for a particular program, that
|
|
program is skipped in the
|
|
.Ic objs
|
|
target.
|
|
.Sh EXAMPLES
|
|
Here is an example
|
|
.Nm
|
|
input conf file, named
|
|
.Dq Pa kcopy.conf :
|
|
.Bd -literal -offset indent
|
|
srcdirs /usr/src/bin /usr/src/sbin
|
|
|
|
progs test cp echo sh fsck halt init mount umount myinstall
|
|
progs anotherprog
|
|
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
|
|
|
|
special anotherprog -DNO_FOO WITHOUT_BAR=YES
|
|
|
|
libs -lutil -lcrypt
|
|
.Ed
|
|
.Pp
|
|
This conf file specifies a small crunched binary consisting of some
|
|
basic system utilities plus a homegrown install program
|
|
.Dq Pa myinstall ,
|
|
for which no source directory is specified, but its object file is
|
|
specified directly with the
|
|
.Ic special
|
|
line.
|
|
.Pp
|
|
Additionally when
|
|
.Dq Pa anotherprog
|
|
is built the arguments
|
|
.Pp
|
|
.Dl -DNO_FOO WITHOUT_BAR=YES
|
|
.Pp
|
|
are added to all build targets.
|
|
.Pp
|
|
The crunched binary
|
|
.Dq Pa kcopy
|
|
can be built as follows:
|
|
.Bd -literal -offset indent
|
|
% 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!
|
|
.Ed
|
|
.Pp
|
|
At this point the binary
|
|
.Dq Pa kcopy
|
|
can be copied onto an install floppy
|
|
and hard-linked to the names of the component programs.
|
|
.Pp
|
|
Note that if the
|
|
.Ic libs_so
|
|
command had been used, copies of the libraries so named
|
|
would also need to be copied to the install floppy.
|
|
.Sh SEE ALSO
|
|
.Xr crunchide 1 ,
|
|
.Xr make 1 ,
|
|
.Xr rtld 1
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The
|
|
.Nm
|
|
utility was written by
|
|
.An James da Silva Aq jds@cs.umd.edu .
|
|
.Pp
|
|
Copyright (c) 1994 University of Maryland.
|
|
All Rights Reserved.
|
|
.Pp
|
|
The
|
|
.Ic libs_so
|
|
keyword was added in 2005 by
|
|
.An Adrian Steinmann Aq ast@marabu.ch
|
|
and
|
|
.An Ceri Davies Aq ceri@FreeBSD.org .
|
|
.Sh CAVEATS
|
|
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 unresolvable 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
|
|
.Dq Li make objs
|
|
must then be used to get those object files built, or
|
|
some other arrangements made.
|