initial import of NetBSD tree

1 files changed, 274 insertions, 0 deletions

diff --git a/distrib/crunch/crunchgen/crunchgen.1 b/distrib/crunch/crunchgen/crunchgen.1
new file mode 100644
index 00000000000..0e3f4bf4c2f
--- /dev/null
+++ b/distrib/crunch/crunchgen/crunchgen.1
@@ -0,0 +1,274 @@
+.\"
+.\" 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 BSD 4
+.Sh NAME
+.Nm \&crunchgen
+.Nd generates build environment for a crunched binary
+.Sh SYNOPSIS
+.Nm \&crunchgen
+.Op Fl fq
+.Op Fl m Ar makefile-name
+.Op Fl c Ar c-file-name
+.Op Fl e Ar exec-file-name
+.Op Fl D Ar src-root
+.Op Fl L Ar lib-dir
+.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 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.  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 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 q
+Quiet operation.  Status messages are suppressed.
+.It Fl D Ar src-root
+Assume that relative source directory specifications begin with
+.Ar srt-root .
+.It Fl L Ar lib-dir
+Try to obtain libraries from
+.Ar lib-dir .
+.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 crunchgen
+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 crunchgen
+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.
+.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 crunchgen
+calculate forward from there if it can.
+
+.Pp
+The makefile produced by
+.Nm crunchgen
+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 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
+.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 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
+.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 unresolveable 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 AUTHOR
+.Nm Crunch
+was written by James da Silva <jds@cs.umd.edu>.
+.sp 0
+Copyright (c) 1994 University of Maryland.  All Rights Reserved.