475 lines
13 KiB
Groff
475 lines
13 KiB
Groff
.\" $NetBSD: crunchgen.1,v 1.42 2021/08/01 15:52:11 andvar 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 January 2, 2020
|
|
.Dt CRUNCHGEN 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm crunchgen
|
|
.Nd generates build environment for a crunched binary
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl FfOoq
|
|
.Op Fl c Ar c-file-name
|
|
.Op Fl D Ar src-root
|
|
.Op Fl e Ar exec-file-name
|
|
.Op Fl L Ar lib-dir
|
|
.Op Fl m Ar makefile-name
|
|
.Op Fl v Ar var-spec
|
|
.Op Fl V Ar var-spec
|
|
.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
|
|
.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 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
|
|
.Dq make -f Ao conf-name Ac Ns .mk .
|
|
The component programs' object files must already be built.
|
|
An
|
|
.Dq 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
|
|
.Dq Ao confname Ac Ns .c .
|
|
.It Fl D Ar src-root
|
|
Assume that relative source directory specifications begin with
|
|
.Ar src-root .
|
|
.It Fl e Ar exec-file-name
|
|
Set crunched binary executable file name to
|
|
.Ar exec-file-name .
|
|
The default name is
|
|
.Dq Aq Mt conf-name .
|
|
.It Fl F
|
|
Enable fortify.
|
|
.It Fl f
|
|
Flush cache.
|
|
Forces the recalculation of cached parameters.
|
|
.It Fl L Ar lib-dir
|
|
Try to obtain libraries from
|
|
.Ar lib-dir .
|
|
.It Fl m Ar makefile-name
|
|
Set output Makefile name to
|
|
.Ar makefile-name .
|
|
The default name is
|
|
.Dq Ao conf-name Ac Ns .mk .
|
|
.It Fl O
|
|
Force
|
|
.Nm
|
|
to parse the program's Makefile in determine the list of .o files.
|
|
Without this option
|
|
.Nm
|
|
expects the program's Makefile to have a program.ro target that links all
|
|
the program objects into a single relocatable.
|
|
.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 v Ar varspec
|
|
Append a variable specification to the on-the fly generated Makefiles
|
|
for the individual programs.
|
|
.It Fl V Ar varspec
|
|
Set the variable in the top level Makefile, and pass it in the command
|
|
line of all sub-makes, so that it cannot be overwritten.
|
|
.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
|
|
.Dq Ao source-dir Ac Ns / Ns Ao progname Ac Ns /
|
|
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 keepsymbols Ar symbols ...
|
|
Don't hide the specified symbols for
|
|
.Ar progname .
|
|
Normally all externally visible symbols for
|
|
a program is hidden to avoid interference.
|
|
Multiple
|
|
.Em keepsymbols
|
|
lines can be specified for given
|
|
.Ar progname .
|
|
.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 .
|
|
.Pp
|
|
.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).
|
|
Multiple
|
|
.Em objs
|
|
lines can be specified for given
|
|
.Ar progname .
|
|
.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.
|
|
Multiple
|
|
.Em objpaths
|
|
lines can be specified for given
|
|
.Ar progname .
|
|
.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.
|
|
.Pp
|
|
The makefile produced by
|
|
.Nm
|
|
strips certain sections from the final binary to reduce its size.
|
|
This includes:
|
|
.Bl -tag -width ".Li .eh_frame_hdr"
|
|
.It Li .eh_frame
|
|
Unwinding tables for exceptions and backtraces.
|
|
.It Li .eh_frame_hdr
|
|
Index of the
|
|
.Li .eh_frame
|
|
section.
|
|
.It Li .note
|
|
Optional data for the kernel and/or runtime linker.
|
|
.It Li .comment
|
|
Comments in the binary.
|
|
.It Li .ident
|
|
Embedded source revisions used by
|
|
.Xr ident 1 .
|
|
.It Li .copyright
|
|
Embedded copyright notes.
|
|
.El
|
|
.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.
|
|
.Pp
|
|
.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 .
|
|
.Pp
|
|
.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 :
|
|
.Bd -literal -offset indent
|
|
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
|
|
.Ed
|
|
.Pp
|
|
This conf file specifies a small crunched binary consisting of some
|
|
basic system utilities plus a home-grown install program
|
|
.Dq myinstall ,
|
|
for which no source directory is specified, but its object file is
|
|
specified directly with the
|
|
.Em special
|
|
line.
|
|
.Pp
|
|
The crunched binary
|
|
.Dq 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 kcopy
|
|
can be copied onto an install floppy
|
|
and hard-linked to the names of the component programs.
|
|
.Sh MIGRATION GUIDE
|
|
.Nm
|
|
used to have builtin entries for some Makefile variables, namely it
|
|
set by default:
|
|
.Bd -literal -offset indent
|
|
DBG=-Os
|
|
LDSTATIC=-static
|
|
NOPIE=
|
|
NOMAN=
|
|
NOFORT=
|
|
NOLIBCSANITIZER=
|
|
NOSANITIZER=
|
|
NOSSP=
|
|
.Ed
|
|
.Pp
|
|
To set those defaults again, use:
|
|
.Bd -literal -offset indent
|
|
-V DBG=-Os \e
|
|
-V LDSTATIC=-static -V NOPIE= \e
|
|
-V NOMAN= \e
|
|
-V NOFORT= -V NOLIBCSANITIZER= -V NOSANITIZER= -V NOSSP=
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fl p
|
|
flag that set pic mode internally set:
|
|
.Bd -literal -offset indent
|
|
LDSTATIC="-static -pie"
|
|
.Ed
|
|
.Pp
|
|
and did not set:
|
|
.Bd -literal -offset indent
|
|
NOPIE=
|
|
.Ed
|
|
.Pp
|
|
The remaining flags just disabled setting the variables that turned off various
|
|
sanitizers, fortify, and stack protector.
|
|
The mapping of those variables to the old options is:
|
|
.Bl -tag -width XX -offset indent
|
|
.It Fl F
|
|
.Dv NOFORT
|
|
.It Fl P
|
|
.Dv NOSSP
|
|
.It Fl S
|
|
.Dv NOLIBCSANITIZER
|
|
.It Fl s
|
|
.Dv NOSANITIZER
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr crunchide 1 ,
|
|
.Xr make 1
|
|
.Sh AUTHORS
|
|
.Nm
|
|
was written by
|
|
.An James da Silva Aq Mt jds@cs.umd.edu .
|
|
.Pp
|
|
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 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 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:
|
|
.Bd -literal -offset indent
|
|
srcdirs /usr/src/usr.bin /usr/src/usr.bin/less
|
|
progs less gzip
|
|
.Ed
|
|
.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 e.g.:
|
|
.Bd -literal -offset indent
|
|
srcdirs /usr/src/usr.bin/less /usr/src/usr.bin
|
|
progs less gzip
|
|
.Ed
|
|
.Pp
|
|
will not have the above problem.
|