diff options
Diffstat (limited to 'usr.sbin/crunch/crunchgen/crunchgen.1')
| -rw-r--r-- | usr.sbin/crunch/crunchgen/crunchgen.1 | 475 |
1 files changed, 0 insertions, 475 deletions
diff --git a/usr.sbin/crunch/crunchgen/crunchgen.1 b/usr.sbin/crunch/crunchgen/crunchgen.1 deleted file mode 100644 index 66fe8f3..0000000 --- a/usr.sbin/crunch/crunchgen/crunchgen.1 +++ /dev/null @@ -1,475 +0,0 @@ -.\" -.\" 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. |
