mdoc(7)ify.
This commit is contained in:
Ruslan Ermilov
parent
d2a46bc99d
commit
8eee67525a
@ -24,14 +24,14 @@
|
||||
.\" University of Maryland at College Park
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd September 29, 1997
|
||||
.Dd November 16, 2000
|
||||
.Dt CRUNCHGEN 1
|
||||
.Os BSD 4
|
||||
.Sh NAME
|
||||
.Nm \&crunchgen
|
||||
.Nm crunchgen
|
||||
.Nd generates build environment for a crunched binary
|
||||
.Sh SYNOPSIS
|
||||
.Nm \&crunchgen
|
||||
.Nm crunchgen
|
||||
.Op Fl foql
|
||||
.Op Fl h Ar makefile-header-name
|
||||
.Op Fl m Ar makefile-name
|
||||
@ -40,37 +40,45 @@
|
||||
.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()
|
||||
together into a single executable.
|
||||
The crunched binary
|
||||
.Fn main
|
||||
function determines which component program to run by the contents of
|
||||
argv[0]. The main reason to crunch programs together is for fitting
|
||||
.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
|
||||
.Nm
|
||||
reads in the specifications in
|
||||
.Ar conf-file
|
||||
for a crunched binary, and generates a Makefile and accompanying
|
||||
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 crunchgen
|
||||
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 Crunchgen
|
||||
the program from its source directory
|
||||
.Pa Makefile .
|
||||
This information is cached between runs.
|
||||
.Nm
|
||||
uses the companion program
|
||||
.Nm crunchide
|
||||
.Xr crunchide 1
|
||||
to eliminate link-time conflicts between the component programs by
|
||||
hiding all unnecessary symbols.
|
||||
.Pp
|
||||
.Nm
|
||||
.Nm
|
||||
places specific requirements on package
|
||||
.Pa Makefiles
|
||||
which make it unsuitable for use with non-BSD sources. In particular, the
|
||||
.Nm Makefile
|
||||
.Pa Makefile Ns s
|
||||
which make it unsuitable for use with non-BSD sources.
|
||||
In particular, the
|
||||
.Pa Makefile
|
||||
must contain the target
|
||||
.Ar depend ,
|
||||
.Ic depend ,
|
||||
and it must define all object files in the variable
|
||||
.Ar OBJS .
|
||||
.Va OBJS .
|
||||
In some cases, you can use a fake
|
||||
.Pa Makefile :
|
||||
before looking for
|
||||
@ -84,11 +92,17 @@ in the current directory.
|
||||
.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
|
||||
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
|
||||
@ -97,43 +111,57 @@ The options are as follows:
|
||||
.It Fl c Ar c-file-name
|
||||
Set output C file name to
|
||||
.Ar c-file-name .
|
||||
The default name is ``<conf-name>.c''.
|
||||
The default name is
|
||||
.Dq <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>''.
|
||||
The default name is
|
||||
.Dq <conf-name> .
|
||||
.It Fl f
|
||||
Flush cache. Forces the recalculation of cached parameters.
|
||||
Flush cache.
|
||||
Forces the recalculation of cached parameters.
|
||||
.It Fl l
|
||||
List names. Lists the names this binary will respond to.
|
||||
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 .
|
||||
.Pa Makefile Ns s
|
||||
generated by
|
||||
.Nm No .
|
||||
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.
|
||||
.Va RELEASE_CRUNCH
|
||||
or similar, which might affect the behaviour of
|
||||
.Xr make 1
|
||||
and are annoying to pass through environment variables.
|
||||
.It Fl m Ar makefile-name
|
||||
Set output Makefile name to
|
||||
Set output
|
||||
.Pa Makefile
|
||||
name to
|
||||
.Ar makefile-name .
|
||||
The default name is ``<conf-name>.mk''.
|
||||
The default name is
|
||||
.Dq <conf-name>.mk .
|
||||
.It Fl o
|
||||
Add ``make obj'' rules to each program make target.
|
||||
Add
|
||||
.Dq Li make obj
|
||||
rules to each program make target.
|
||||
.It Fl q
|
||||
Quiet operation. Status messages are suppressed.
|
||||
Quiet operation.
|
||||
Status messages are suppressed.
|
||||
.El
|
||||
.Sh CRUNCHGEN CONFIGURATION FILE COMMANDS
|
||||
.Nm Crunchgen
|
||||
reads specifications from the
|
||||
.Nm
|
||||
reads specifications from the
|
||||
.Ar conf-file
|
||||
that describe the components of the crunched binary. In its simplest
|
||||
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
|
||||
.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
|
||||
list of object files and their locations.
|
||||
For more specialized
|
||||
situations, the user can specify by hand all the parameters that
|
||||
.Nm
|
||||
needs.
|
||||
.Pp
|
||||
@ -141,90 +169,110 @@ The
|
||||
.Ar conf-file
|
||||
commands are as follows:
|
||||
.Bl -tag -width indent
|
||||
.It Nm srcdirs Ar dirname ...
|
||||
.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
|
||||
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
|
||||
component programs can be found.
|
||||
These dirs are searched using the
|
||||
.Bx
|
||||
.Dq <source-dir>/<progname>/
|
||||
convention.
|
||||
Multiple
|
||||
.Ic srcdirs
|
||||
lines can be specified.
|
||||
.It Nm libs Ar libspec ...
|
||||
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
|
||||
.Nm libs
|
||||
.Ic libs
|
||||
lines can be specified.
|
||||
.It Nm buildopts Ar buildopts ...
|
||||
.It Ic buildopts Ar buildopts ...
|
||||
A list of build options to be added to every make target.
|
||||
.It Nm ln Ar progname linkname
|
||||
.It Ic 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.
|
||||
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 Makefile, the following
|
||||
.Nm special
|
||||
commands can be used to set
|
||||
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 Nm special Ar progname Nm srcdir Ar pathname
|
||||
.It Ic special Ar progname Ic srcdir Ar pathname
|
||||
Set the source directory for
|
||||
.Ar progname .
|
||||
This is normally calculated by searching the specified
|
||||
.Nm srcdirs
|
||||
.Ic srcdirs
|
||||
for a directory named
|
||||
.Ar progname .
|
||||
.It Nm special Ar progname Nm objdir Ar pathname
|
||||
Set the obj directory for
|
||||
.It Ic special Ar progname Ic objdir Ar pathname
|
||||
Set the
|
||||
.Dq obj
|
||||
directory for
|
||||
.Ar progname .
|
||||
This is normally calculated by looking for a directory named
|
||||
.Dq Pa obj
|
||||
.Pa obj
|
||||
under the
|
||||
.Ar srcdir ,
|
||||
and if that is not found, the
|
||||
.Ar srcdir
|
||||
.Ic srcdir ,
|
||||
and if that is not found, the
|
||||
.Ic srcdir
|
||||
itself becomes the
|
||||
.Ar objdir .
|
||||
.It Nm special Ar progname Nm buildopts Ar buildopts
|
||||
Define a set of build options that should be added to make targets
|
||||
in addition to those specified using
|
||||
.Nm buildopts
|
||||
.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 Nm special Ar progname Nm objs Ar object-file-name ...
|
||||
.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 Nm srcdir / Pa Makefile
|
||||
and outputs the value of $(OBJS).
|
||||
.It Nm special Ar progname Nm objpaths Ar full-pathname-to-object-file ...
|
||||
.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
|
||||
.Nm objdir
|
||||
.Ic objdir
|
||||
pathname to each file in the
|
||||
.Nm objs
|
||||
.Ic objs
|
||||
list.
|
||||
.It Nm special Ar progname Nm objvar Ar variable_name
|
||||
Sets the name of the Make variable which holds the list of
|
||||
.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
|
||||
.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 ...
|
||||
.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 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
|
||||
An underscore
|
||||
.Pq Ql _
|
||||
is prepended to each symbol and it becomes the argument to a
|
||||
.Fl k
|
||||
option for the
|
||||
.Xr crunchide 1
|
||||
@ -234,32 +282,36 @@ symbol conflict, however in certain instances it may be the only way to
|
||||
have a symbol resolve.
|
||||
.El
|
||||
.Pp
|
||||
Only the
|
||||
.Nm objpaths
|
||||
Only the
|
||||
.Ic objpaths
|
||||
parameter is actually needed by
|
||||
.Nm crunchgen ,
|
||||
.Nm No ,
|
||||
but it is calculated from
|
||||
.Nm objdir
|
||||
.Ic objdir
|
||||
and
|
||||
.Nm objs ,
|
||||
.Ic objs ,
|
||||
which are in turn calculated from
|
||||
.Nm srcdir ,
|
||||
so is sometimes convenient to specify the earlier parameters and let
|
||||
.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
|
||||
.Ar objs
|
||||
.Ic 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
|
||||
running
|
||||
.Xr make 1
|
||||
inside that program's source directory.
|
||||
For this to work the
|
||||
.Ic 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
|
||||
.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 EXAMPLE
|
||||
Here is an example
|
||||
@ -283,17 +335,24 @@ libs -lutil -lcrypt
|
||||
.Ed
|
||||
.Pp
|
||||
This conf file specifies a small crunched binary consisting of some
|
||||
basic system utilities plus a homegrown install program ``myinstall'',
|
||||
basic system utilities plus a homegrown install program
|
||||
.Dq myinstall ,
|
||||
for which no source directory is specified, but its object file is
|
||||
specified directly with the
|
||||
.Nm special
|
||||
.Ic special
|
||||
line.
|
||||
.Pp
|
||||
Additionally when ``anotherprog'' is built the arguments
|
||||
.Ar -DNO_FOO WITHOUT_BAR=YES
|
||||
Additionally when
|
||||
.Dq anotherprog
|
||||
is built the arguments
|
||||
.Pp
|
||||
.Dl -DNO_FOO WITHOUT_BAR=YES
|
||||
.Pp
|
||||
are added to all build targets.
|
||||
.Pp
|
||||
The crunched binary ``kcopy'' can be built as follows:
|
||||
The crunched binary
|
||||
.Dq kcopy
|
||||
can be built as follows:
|
||||
.Pp
|
||||
.Bd -literal -offset indent
|
||||
% crunchgen -m Makefile kcopy.conf # gen Makefile and kcopy.c
|
||||
@ -303,25 +362,33 @@ The crunched binary ``kcopy'' can be built as follows:
|
||||
$ # it works!
|
||||
.Ed
|
||||
.Pp
|
||||
At this point the binary ``kcopy'' can be copied onto an install floppy
|
||||
At this point the binary
|
||||
.Dq 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 crunchide 1 ,
|
||||
.Xr make 1
|
||||
.Sh CAVEATS
|
||||
While
|
||||
.Nm crunch
|
||||
.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 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
|
||||
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.
|
||||
.Sh AUTHORS
|
||||
.Nm Crunch
|
||||
.Nm
|
||||
was written by
|
||||
.An James da Silva Aq jds@cs.umd.edu .
|
||||
Copyright (c) 1994 University of Maryland. All Rights Reserved.
|
||||
.Pp
|
||||
Copyright (c) 1994 University of Maryland.
|
||||
All Rights Reserved.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user