xref: /freebsd/usr.sbin/crunch/crunchgen/crunchgen.1 (revision fb7f926e3dbe461d04d334f2d5a45587e92b44f1)
1de566360SJordan K. Hubbard.\"
2de566360SJordan K. Hubbard.\" Copyright (c) 1994 University of Maryland
3de566360SJordan K. Hubbard.\" All Rights Reserved.
4de566360SJordan K. Hubbard.\"
5de566360SJordan K. Hubbard.\" Permission to use, copy, modify, distribute, and sell this software and its
6de566360SJordan K. Hubbard.\" documentation for any purpose is hereby granted without fee, provided that
7de566360SJordan K. Hubbard.\" the above copyright notice appear in all copies and that both that
8de566360SJordan K. Hubbard.\" copyright notice and this permission notice appear in supporting
9de566360SJordan K. Hubbard.\" documentation, and that the name of U.M. not be used in advertising or
10de566360SJordan K. Hubbard.\" publicity pertaining to distribution of the software without specific,
11de566360SJordan K. Hubbard.\" written prior permission.  U.M. makes no representations about the
12de566360SJordan K. Hubbard.\" suitability of this software for any purpose.  It is provided "as is"
13de566360SJordan K. Hubbard.\" without express or implied warranty.
14de566360SJordan K. Hubbard.\"
15de566360SJordan K. Hubbard.\" U.M. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
16de566360SJordan K. Hubbard.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL U.M.
17de566360SJordan K. Hubbard.\" BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
18de566360SJordan K. Hubbard.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
19de566360SJordan K. Hubbard.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
20de566360SJordan K. Hubbard.\" IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21de566360SJordan K. Hubbard.\"
22de566360SJordan K. Hubbard.\" Author: James da Silva, Systems Design and Analysis Group
23de566360SJordan K. Hubbard.\"			   Computer Science Department
24de566360SJordan K. Hubbard.\"			   University of Maryland at College Park
25de566360SJordan K. Hubbard.\"
26de566360SJordan K. Hubbard.Dd June 14, 1994
27de566360SJordan K. Hubbard.Dt CRUNCHGEN 1
28de566360SJordan K. Hubbard.Os BSD 4
29de566360SJordan K. Hubbard.Sh NAME
30de566360SJordan K. Hubbard.Nm \&crunchgen
31de566360SJordan K. Hubbard.Nd generates build environment for a crunched binary
32de566360SJordan K. Hubbard.Sh SYNOPSIS
33de566360SJordan K. Hubbard.Nm \&crunchgen
34fb7f926eSPoul-Henning Kamp.Op Fl fql
35de566360SJordan K. Hubbard.Op Fl m Ar makefile-name
36de566360SJordan K. Hubbard.Op Fl c Ar c-file-name
37de566360SJordan K. Hubbard.Op Fl e Ar exec-file-name
38de566360SJordan K. Hubbard.Op Ar conf-file
39de566360SJordan K. Hubbard.Sh DESCRIPTION
40de566360SJordan K. Hubbard
41de566360SJordan K. HubbardA crunched binary is a program made up of many other programs linked
42de566360SJordan K. Hubbardtogether into a single executable.  The crunched binary main()
43de566360SJordan K. Hubbardfunction determines which component program to run by the contents of
44de566360SJordan K. Hubbardargv[0].  The main reason to crunch programs together is for fitting
45de566360SJordan K. Hubbardas many programs as possible onto an installation or system recovery
46de566360SJordan K. Hubbardfloppy.
47de566360SJordan K. Hubbard
48de566360SJordan K. Hubbard.Pp
49de566360SJordan K. Hubbard.Nm Crunchgen
50de566360SJordan K. Hubbardreads in the specifications in
51de566360SJordan K. Hubbard.Ar conf-file
52de566360SJordan K. Hubbardfor a crunched binary, and generates a Makefile and accompanying
53de566360SJordan K. Hubbardtop-level C source file that when built create the crunched executable
54de566360SJordan K. Hubbardfile from the component programs.  For each component program,
55de566360SJordan K. Hubbard.Nm crunchgen
56de566360SJordan K. Hubbardcan optionally attempt to determine the object (.o) files that make up
57de566360SJordan K. Hubbardthe program from its source directory Makefile.  This information is
58de566360SJordan K. Hubbardcached between runs.
59de566360SJordan K. Hubbard.Nm Crunchgen
60de566360SJordan K. Hubbarduses the companion program
61de566360SJordan K. Hubbard.Nm crunchide
62de566360SJordan K. Hubbardto eliminate link-time conflicts between the component programs by
63de566360SJordan K. Hubbardhiding all unnecessary symbols.
64de566360SJordan K. Hubbard
65de566360SJordan K. Hubbard.Pp
66de566360SJordan K. HubbardAfter
67de566360SJordan K. Hubbard.Nm crunchgen
68de566360SJordan K. Hubbardis run, the crunched binary can be built by running ``make -f
69de566360SJordan K. Hubbard<conf-name>.mk''.  The component programs' object files must already
70de566360SJordan K. Hubbardbe built.  A ``objs'' target, included in the output makefile, will
71de566360SJordan K. Hubbardrun make in each component program's source dir to build the object
72de566360SJordan K. Hubbardfiles for the user.  This is not done automatically since in release
73de566360SJordan K. Hubbardengineering circumstances it is generally not desireable to be
74de566360SJordan K. Hubbardmodifying objects in other directories.
75de566360SJordan K. Hubbard
76de566360SJordan K. Hubbard.Pp
77de566360SJordan K. HubbardThe options are as follows:
78de566360SJordan K. Hubbard.Bl -tag -width indent
79de566360SJordan K. Hubbard.It Fl c Ar c-file-name
80de566360SJordan K. HubbardSet output C file name to
81de566360SJordan K. Hubbard.Ar c-file-name .
82de566360SJordan K. HubbardThe default name is ``<conf-name>.c''.
83de566360SJordan K. Hubbard.It Fl e Ar exec-file-name
84de566360SJordan K. HubbardSet crunched binary executable file name to
85de566360SJordan K. Hubbard.Ar exec-file-name .
86de566360SJordan K. HubbardThe default name is ``<conf-name>''.
87de566360SJordan K. Hubbard.It Fl f
88de566360SJordan K. HubbardFlush cache.  Forces the recalculation of cached parameters.
89fb7f926eSPoul-Henning Kamp.It Fl l
90fb7f926eSPoul-Henning KampList names.  Lists the names this binary will respond to.
91de566360SJordan K. Hubbard.It Fl m Ar makefile-name
92de566360SJordan K. HubbardSet output Makefile name to
93de566360SJordan K. Hubbard.Ar makefile-name .
94de566360SJordan K. HubbardThe default name is ``<conf-name>.mk''.
95de566360SJordan K. Hubbard.It Fl q
96de566360SJordan K. HubbardQuiet operation.  Status messages are suppressed.
97de566360SJordan K. Hubbard.El
98de566360SJordan K. Hubbard.Sh CRUNCHGEN CONFIGURATION FILE COMMANDS
99de566360SJordan K. Hubbard
100de566360SJordan K. Hubbard.Nm Crunchgen
101de566360SJordan K. Hubbardreads specifications from the
102de566360SJordan K. Hubbard.Ar conf-file
103de566360SJordan K. Hubbardthat describe the components of the crunched binary.  In its simplest
104de566360SJordan K. Hubbarduse, the component program names are merely listed along with the
105de566360SJordan K. Hubbardtop-level source directories in which their sources can be found.
106de566360SJordan K. Hubbard.Nm Crunchgen
107de566360SJordan K. Hubbardthen calculates (via the source makefiles) and caches the
108de566360SJordan K. Hubbardlist of object files and their locations.  For more specialized
109de566360SJordan K. Hubbardsituations, the user can specify by hand all the parameters that
110de566360SJordan K. Hubbard.Nm crunchgen
111de566360SJordan K. Hubbardneeds.
112de566360SJordan K. Hubbard.Pp
113de566360SJordan K. HubbardThe
114de566360SJordan K. Hubbard.Ar conf-file
115de566360SJordan K. Hubbardcommands are as follows:
116de566360SJordan K. Hubbard.Bl -tag -width indent
117de566360SJordan K. Hubbard.It Nm srcdirs Ar dirname ...
118de566360SJordan K. HubbardA list of source trees in which the source directories of the
119de566360SJordan K. Hubbardcomponent programs can be found.  These dirs are searched using the
120de566360SJordan K. HubbardBSD ``<source-dir>/<progname>/'' convention.  Multiple
121de566360SJordan K. Hubbard.Nm srcdirs
122de566360SJordan K. Hubbardlines can be specified.  The directories are searched in the order
123de566360SJordan K. Hubbardthey are given.
124de566360SJordan K. Hubbard.It Nm progs Ar progname ...
125de566360SJordan K. HubbardA list of programs that make up the crunched binary.  Multiple
126de566360SJordan K. Hubbard.Nm progs
127de566360SJordan K. Hubbardlines can be specified.
128de566360SJordan K. Hubbard.It Nm libs Ar libspec ...
129de566360SJordan K. HubbardA list of library specifications to be included in the crunched binary link.
130de566360SJordan K. HubbardMultiple
131de566360SJordan K. Hubbard.Nm libs
132de566360SJordan K. Hubbardlines can be specified.
133de566360SJordan K. Hubbard.It Nm ln Ar progname linkname
134de566360SJordan K. HubbardCauses the crunched binary to invoke
135de566360SJordan K. Hubbard.Ar progname
136de566360SJordan K. Hubbardwhenever
137de566360SJordan K. Hubbard.Ar linkname
138de566360SJordan K. Hubbardappears in argv[0].  This allows programs that change their behavior when
139de566360SJordan K. Hubbardrun under different names to operate correctly.
140de566360SJordan K. Hubbard.El
141de566360SJordan K. Hubbard
142de566360SJordan K. HubbardTo handle specialized situations, such as when the source is not
143de566360SJordan K. Hubbardavailable or not built via a conventional Makefile, the following
144de566360SJordan K. Hubbard.Nm special
145de566360SJordan K. Hubbardcommands can be used to set
146de566360SJordan K. Hubbard.Nm crunchgen
147de566360SJordan K. Hubbardparameters for a component program.
148de566360SJordan K. Hubbard.Bl -tag -width indent
149de566360SJordan K. Hubbard.It Nm special Ar progname Nm srcdir Ar pathname
150de566360SJordan K. HubbardSet the source directory for
151de566360SJordan K. Hubbard.Ar progname .
152de566360SJordan K. HubbardThis is normally calculated by searching the specified
153de566360SJordan K. Hubbard.Nm srcdirs
154de566360SJordan K. Hubbardfor a directory named
155de566360SJordan K. Hubbard.Ar progname .
156de566360SJordan K. Hubbard.It Nm special Ar progname Nm objdir Ar pathname
157de566360SJordan K. HubbardSet the obj directory for
158de566360SJordan K. Hubbard.Ar progname .
159de566360SJordan K. HubbardThis is normally calculated by looking for a directory named
160de566360SJordan K. Hubbard.Dq Pa obj
161de566360SJordan K. Hubbardunder the
162de566360SJordan K. Hubbard.Ar srcdir ,
163de566360SJordan K. Hubbardand if that is not found, the
164de566360SJordan K. Hubbard.Ar srcdir
165de566360SJordan K. Hubbarditself becomes the
166de566360SJordan K. Hubbard.Ar objdir .
167de566360SJordan K. Hubbard.It Nm special Ar progname Nm objs Ar object-file-name ...
168de566360SJordan K. HubbardSet the list of object files for program
169de566360SJordan K. Hubbard.Ar progname .
170de566360SJordan K. HubbardThis is normally calculated by constructing a temporary makefile that includes
171de566360SJordan K. Hubbard.Dq Nm srcdir / Pa Makefile
172de566360SJordan K. Hubbardand outputs the value of $(OBJS).
173de566360SJordan K. Hubbard.It Nm special Ar progname Nm objpaths Ar full-pathname-to-object-file ...
174de566360SJordan K. HubbardSets the pathnames of the object files for program
175de566360SJordan K. Hubbard.Ar progname .
176de566360SJordan K. HubbardThis is normally calculated by prepending the
177de566360SJordan K. Hubbard.Nm objdir
178de566360SJordan K. Hubbardpathname to each file in the
179de566360SJordan K. Hubbard.Nm objs
180de566360SJordan K. Hubbardlist.
181de566360SJordan K. Hubbard.El
182de566360SJordan K. Hubbard
183de566360SJordan K. Hubbard.Pp
184de566360SJordan K. HubbardOnly the
185de566360SJordan K. Hubbard.Nm objpaths
186de566360SJordan K. Hubbardparameter is actually needed by
187de566360SJordan K. Hubbard.Nm crunchgen ,
188de566360SJordan K. Hubbardbut it is calculated from
189de566360SJordan K. Hubbard.Nm objdir
190de566360SJordan K. Hubbardand
191de566360SJordan K. Hubbard.Nm objs ,
192de566360SJordan K. Hubbardwhich are in turn calculated from
193de566360SJordan K. Hubbard.Nm srcdir ,
194de566360SJordan K. Hubbardso is sometimes convenient to specify the earlier parameters and let
195de566360SJordan K. Hubbard.Nm crunchgen
196de566360SJordan K. Hubbardcalculate forward from there if it can.
197de566360SJordan K. Hubbard
198de566360SJordan K. Hubbard.Pp
199de566360SJordan K. HubbardThe makefile produced by
200de566360SJordan K. Hubbard.Nm crunchgen
201de566360SJordan K. Hubbardcontains an optional
202de566360SJordan K. Hubbard.Ar objs
203de566360SJordan K. Hubbardtarget that will build the object files for each component program by
204de566360SJordan K. Hubbardrunning make inside that program's source directory.  For this to work the
205de566360SJordan K. Hubbard.Nm srcdir
206de566360SJordan K. Hubbardand
207de566360SJordan K. Hubbard.Nm objs
208de566360SJordan K. Hubbardparameters must also be valid.  If they are not valid for a particular program, that
209de566360SJordan K. Hubbardprogram is skipped in the
210de566360SJordan K. Hubbard.Ar objs
211de566360SJordan K. Hubbardtarget.
212de566360SJordan K. Hubbard.Sh EXAMPLE
213de566360SJordan K. HubbardHere is an example
214de566360SJordan K. Hubbard.Nm crunchgen
215de566360SJordan K. Hubbardinput conf file, named
216de566360SJordan K. Hubbard.Dq Pa kcopy.conf :
217de566360SJordan K. Hubbard.Pp
218de566360SJordan K. Hubbard.nf
219de566360SJordan K. Hubbard	srcdirs /usr/src/bin /usr/src/sbin
220de566360SJordan K. Hubbard
221de566360SJordan K. Hubbard	progs test cp echo sh fsck halt init mount umount myinstall
222de566360SJordan K. Hubbard	ln test [       # test can be invoked via [
223de566360SJordan K. Hubbard	ln sh -sh       # init invokes the shell with "-sh" in argv[0]
224de566360SJordan K. Hubbard
225de566360SJordan K. Hubbard	special myprog objpaths /homes/leroy/src/myinstall.o # no sources
226de566360SJordan K. Hubbard
227de566360SJordan K. Hubbard	libs -lutil -lcrypt
228de566360SJordan K. Hubbard.fi
229de566360SJordan K. Hubbard.Pp
230de566360SJordan K. HubbardThis conf file specifies a small crunched binary consisting of some
231de566360SJordan K. Hubbardbasic system utilities plus a homegrown install program ``myinstall'',
232de566360SJordan K. Hubbardfor which no source directory is specified, but its object file is
233de566360SJordan K. Hubbardspecified directly with the
234de566360SJordan K. Hubbard.Nm special
235de566360SJordan K. Hubbardline.
236de566360SJordan K. Hubbard.Pp
237de566360SJordan K. HubbardThe crunched binary ``kcopy'' can be built as follows:
238de566360SJordan K. Hubbard.Pp
239de566360SJordan K. Hubbard.nf
240de566360SJordan K. Hubbard	% crunchgen -m Makefile kcopy.conf    # gen Makefile and kcopy.c
241de566360SJordan K. Hubbard	% make objs             # build the component progams' .o files
242de566360SJordan K. Hubbard	% make                  # build the crunched binary kcopy
243de566360SJordan K. Hubbard	% kcopy sh              # test that this invokes a sh shell
244de566360SJordan K. Hubbard	$			# it works!
245de566360SJordan K. Hubbard.fi
246de566360SJordan K. Hubbard.Pp
247de566360SJordan K. HubbardAt this point the binary ``kcopy'' can be copied onto an install floppy
248de566360SJordan K. Hubbardand hard-linked to the names of the component programs.
249de566360SJordan K. Hubbard.Sh SEE ALSO
250de566360SJordan K. Hubbard.Xr crunchide 1
251de566360SJordan K. Hubbard.Sh CAVEATS
252de566360SJordan K. HubbardWhile
253de566360SJordan K. Hubbard.Nm crunch
254de566360SJordan K. Hubbardtakes care to eliminate link conflicts between the component programs
255de566360SJordan K. Hubbardof a crunched binary, conflicts are still possible between the
256de566360SJordan K. Hubbardlibraries that are linked in.  Some shuffling in the order of
257de566360SJordan K. Hubbardlibraries may be required, and in some rare cases two libraries may
258de566360SJordan K. Hubbardhave an unresolveable conflict and thus cannot be crunched together.
259de566360SJordan K. Hubbard.Pp
260de566360SJordan K. HubbardSome versions of the BSD build environment do not by default build the
261de566360SJordan K. Hubbardintermediate object file for single-source file programs.  The ``make
262de566360SJordan K. Hubbardobjs'' target must then be used to get those object files built, or
263de566360SJordan K. Hubbardsome other arrangements made.
264de566360SJordan K. Hubbard.Sh AUTHOR
265de566360SJordan K. Hubbard.Nm Crunch
266de566360SJordan K. Hubbardwas written by James da Silva <jds@cs.umd.edu>.
267de566360SJordan K. Hubbard.sp 0
268de566360SJordan K. HubbardCopyright (c) 1994 University of Maryland.  All Rights Reserved.
269