| blob | 7e92a7255269a19ded1f2df0a02dde7f25236265 |
1 .\" $NetBSD: crunchgen.1,v 1.27 2006/10/26 10:49:35 wiz Exp $
2 .\"
3 .\" Copyright (c) 1994 University of Maryland
4 .\" All Rights Reserved.
5 .\"
6 .\" Permission to use, copy, modify, distribute, and sell this software and its
7 .\" documentation for any purpose is hereby granted without fee, provided that
8 .\" the above copyright notice appear in all copies and that both that
9 .\" copyright notice and this permission notice appear in supporting
10 .\" documentation, and that the name of U.M. not be used in advertising or
11 .\" publicity pertaining to distribution of the software without specific,
12 .\" written prior permission. U.M. makes no representations about the
13 .\" suitability of this software for any purpose. It is provided "as is"
14 .\" without express or implied warranty.
15 .\"
16 .\" U.M. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL U.M.
18 .\" BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
19 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
20 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
21 .\" IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
22 .\"
23 .\" Author: James da Silva, Systems Design and Analysis Group
24 .\" Computer Science Department
25 .\" University of Maryland at College Park
26 .\"
27 .Dd October 18, 2006
28 .Dt CRUNCHGEN 1
29 .Os
30 .Sh NAME
31 .Nm crunchgen
32 .Nd generates build environment for a crunched binary
33 .Sh SYNOPSIS
34 .Nm
35 .Op Fl fOoq
36 .Bk -words
37 .Op Fl c Ar c-file-name
38 .Ek
39 .Bk -words
40 .Op Fl D Ar src-root
41 .Ek
42 .Bk -words
43 .Op Fl d Ar build-options
44 .Ek
45 .Bk -words
46 .Op Fl e Ar exec-file-name
47 .Ek
48 .Bk -words
49 .Op Fl L Ar lib-dir
50 .Ek
51 .Bk -words
52 .Op Fl m Ar makefile-name
53 .Ek
54 .Bk -words
55 .Op Fl v Ar var-spec
56 .Ek
57 .Ar conf-file
58 .Sh DESCRIPTION
59 A crunched binary is a program made up of many other programs linked
60 together into a single executable.
61 The crunched binary
62 .Fn main
63 function determines which component program to run by the contents of
64 argv[0].
65 The main reason to crunch programs together is for fitting as many
66 programs as possible onto an installation or system recovery floppy.
67 .Pp
68 .Nm
69 reads in the specifications in
70 .Ar conf-file
71 for a crunched binary, and generates a Makefile and accompanying
72 top-level C source file that when built create the crunched executable
73 file from the component programs.
74 For each component program,
75 .Nm
76 can optionally attempt to determine the object (.o) files that make up
77 the program from its source directory Makefile.
78 This information is cached between runs.
79 .Nm
80 uses the companion program
81 .Em crunchide
82 to eliminate link-time conflicts between the component programs by
83 hiding all unnecessary symbols.
84 .Pp
85 After
86 .Nm
87 is run, the crunched binary can be built by running
88 .Dq make -f Ao conf-name Ac Ns .mk .
89 The component programs' object files must already be built.
90 An
91 .Dq objs
92 target, included in the output makefile, will
93 run make in each component program's source dir to build the object
94 files for the user.
95 This is not done automatically since in release
96 engineering circumstances it is generally not desirable to be
97 modifying objects in other directories.
98 .Pp
99 The options are as follows:
100 .Bl -tag -width indent
101 .It Fl c Ar c-file-name
102 Set output C file name to
103 .Ar c-file-name .
104 The default name is
105 .Dq Ao confname Ac Ns .c .
106 .It Fl D Ar src-root
107 Assume that relative source directory specifications begin with
108 .Ar src-root .
109 .It Fl d Ar build-options
110 Set the DBG variable in the generated makefile to
111 .Ar build-options .
112 The default flags are -Os.
113 .It Fl e Ar exec-file-name
114 Set crunched binary executable file name to
115 .Ar exec-file-name .
116 The default name is
117 .Dq Aq conf-name .
118 .It Fl f
119 Flush cache.
120 Forces the recalculation of cached parameters.
121 .It Fl L Ar lib-dir
122 Try to obtain libraries from
123 .Ar lib-dir .
124 .It Fl m Ar makefile-name
125 Set output Makefile name to
126 .Ar makefile-name .
127 The default name is
128 .Dq Ao conf-name Ac Ns .mk .
129 .It Fl O
130 Force
131 .Nm
132 to parse the program's Makefile in determine the list of .o files.
133 Without this option
134 .Nm
135 expects the program's Makefile to have a program.ro target that links all
136 the program objects into a single relocatable.
137 .It Fl o
138 Use existing object files.
139 Rather than rebuilding object files via reach-over
140 makefiles, instead search for and use existing object files.
141 .It Fl q
142 Quiet operation.
143 Status messages are suppressed.
144 .It Fl v Ar varspec
145 Append a variable specification to the on-the fly generated Makefile.
146 .El
147 .Sh CRUNCHGEN CONFIGURATION FILE COMMANDS
148 .Nm
149 reads specifications from the
150 .Ar conf-file
151 that describe the components of the crunched binary.
152 In its simplest
153 use, the component program names are merely listed along with the
154 top-level source directories in which their sources can be found.
155 .Nm
156 then calculates (via the source makefiles) and caches the
157 list of object files and their locations.
158 For more specialized
159 situations, the user can specify by hand all the parameters that
160 .Nm
161 needs.
162 .Pp
163 The
164 .Ar conf-file
165 commands are as follows:
166 .Bl -tag -width indent
167 .It Nm srcdirs Ar dirname ...
168 A list of source trees in which the source directories of the
169 component programs can be found.
170 These dirs are searched using the
171 .Bx
172 .Dq Ao source-dir Ac Ns / Ns Ao progname Ac Ns /
173 convention.
174 Multiple
175 .Em srcdirs
176 lines can be specified.
177 The directories are searched in the order they are given.
178 .It Nm progs Ar progname ...
179 A list of programs that make up the crunched binary.
180 Multiple
181 .Em progs
182 lines can be specified.
183 .It Nm libs Ar libspec ...
184 A list of library specifications to be included in the crunched binary link.
185 Multiple
186 .Em libs
187 lines can be specified.
188 .It Nm ln Ar progname linkname
189 Causes the crunched binary to invoke
190 .Ar progname
191 whenever
192 .Ar linkname
193 appears in argv[0].
194 This allows programs that change their behavior when
195 run under different names to operate correctly.
196 .El
197 .Pp
198 To handle specialized situations, such as when the source is not
199 available or not built via a conventional Makefile, the following
200 .Em special
201 commands can be used to set
202 .Nm
203 parameters for a component program.
204 .Bl -tag -width indent
205 .It Nm special Ar progname Nm keepsymbols Ar symbols ...
206 Don't hide the specified symbols for
207 .Ar progname .
208 Normally all externally visible symbols for
209 a program is hidden to avoid interference.
210 Multiple
211 .Em keepsymbols
212 lines can be specified for given
213 .Ar progname .
214 .It Nm special Ar progname Nm srcdir Ar pathname
215 Set the source directory for
216 .Ar progname .
217 This is normally calculated by searching the specified
218 .Em srcdirs
219 for a directory named
220 .Ar progname .
221 .It Nm special Ar progname Nm objdir Ar pathname
222 Set the obj directory for
223 .Ar progname .
224 This is normally calculated by looking for a directory named
225 .Dq Pa obj
226 under the
227 .Ar srcdir ,
228 and if that is not found, the
229 .Ar srcdir
230 itself becomes the
231 .Ar objdir .
232 .Pp
233 .Nm Note :
234 This option only takes effect if the -o option to use existing object files is also
235 specified.
236 .It Nm special Ar progname Nm objs Ar object-file-name ...
237 Set the list of object files for program
238 .Ar progname .
239 This is normally calculated by constructing a temporary makefile that includes
240 .Dq Nm srcdir / Pa Makefile
241 and outputs the value of $(OBJS).
242 Multiple
243 .Em objs
244 lines can be specified for given
245 .Ar progname .
246 .It Nm special Ar progname Nm objpaths Ar full-pathname-to-object-file ...
247 Sets the pathnames of the object files for program
248 .Ar progname .
249 This is normally calculated by prepending the
250 .Em objdir
251 pathname to each file in the
252 .Nm objs
253 list.
254 Multiple
255 .Em objpaths
256 lines can be specified for given
257 .Ar progname .
258 .El
259 .Pp
260 Only the
261 .Em objpaths
262 parameter is actually needed by
263 .Nm
264 but it is calculated from
265 .Em objdir
266 and
267 .Em objs ,
268 which are in turn calculated from
269 .Em srcdir ,
270 so is sometimes convenient to specify the earlier parameters and let
271 .Nm
272 calculate forward from there if it can.
273 .Pp
274 The makefile produced by
275 .Nm
276 contains an optional
277 .Ar objs
278 target that will build the object files for each component program by
279 running make inside that program's source directory.
280 For this to work the
281 .Em srcdir
282 and
283 .Em objs
284 parameters must also be valid.
285 If they are not valid for a particular program, that
286 program is skipped in the
287 .Ar objs
288 target.
289 .Sh ENVIRONMENT
290 .Bl -tag -width MAKEOBJDIRPREFIX
291 .It Ev MAKEOBJDIRPREFIX
292 If the environment variable
293 .Ev MAKEOBJDIRPREFIX
294 is set, the object directory will be prefixed with the path contained in this
295 environment variable.
296 .Pp
297 .Nm Note :
298 This variable is only used if the -o option to use existing object files is also
299 specified.
300 .It Ev MACHINE
301 If the environment variable
302 .Ev MACHINE
303 is set, it is used as the name of the machine type, when accessing object
304 directories of the form obj.MACHINE.
305 If it is not set, it defaults to the machine type returned by
306 .Xr uname 3 .
307 .Pp
308 .Nm Note :
309 This option is only used if the -o option to use existing object files is also
310 specified.
311 .It Ev MAKE
312 If the environment variable
313 .Ev MAKE
314 is set, it is used as the name of the
315 .Xr make 1
316 executable to be called.
317 If this environment variable is not set,
318 .Nm
319 defaults to
320 .Dq make .
321 .El
322 .Sh EXAMPLES
323 Here is an example
324 .Em crunchgen
325 input conf file, named
326 .Dq Pa kcopy.conf :
327 .Pp
328 .Bd -literal -offset indent
329 srcdirs /usr/src/bin /usr/src/sbin
331 progs test cp echo sh fsck halt init mount umount myinstall
332 ln test [ # test can be invoked via [
333 ln sh -sh # init invokes the shell with "-sh" in argv[0]
335 special myprog objpaths /homes/leroy/src/myinstall.o # no sources
337 libs -lutil -lcrypt
338 .Ed
339 .Pp
340 This conf file specifies a small crunched binary consisting of some
341 basic system utilities plus a home-grown install program
342 .Dq myinstall ,
343 for which no source directory is specified, but its object file is
344 specified directly with the
345 .Em special
346 line.
347 .Pp
348 The crunched binary
349 .Dq kcopy
350 can be built as follows:
351 .Pp
352 .Bd -literal -offset indent
353 % crunchgen -m Makefile kcopy.conf # gen Makefile and kcopy.c
354 % make objs # build the component programs' .o files
355 % make # build the crunched binary kcopy
356 % kcopy sh # test that this invokes a sh shell
357 $ # it works!
358 .Ed
359 .Pp
360 At this point the binary
361 .Dq kcopy
362 can be copied onto an install floppy
363 and hard-linked to the names of the component programs.
364 .Sh SEE ALSO
365 .Xr crunchide 1 ,
366 .Xr make 1
367 .Sh AUTHORS
368 .Nm
369 was written by
370 .An James da Silva Aq jds@cs.umd.edu .
371 .Pp
372 Copyright (c) 1994 University of Maryland. All Rights Reserved.
373 .Sh BUGS
374 While
375 .Nm
376 takes care to eliminate link conflicts between the component programs
377 of a crunched binary, conflicts are still possible between the
378 libraries that are linked in.
379 Some shuffling in the order of
380 libraries may be required, and in some rare cases two libraries may
381 have an unresolvable conflict and thus cannot be crunched together.
382 .Pp
383 Some versions of the
384 .Bx
385 build environment do not by default build the
386 intermediate object file for single-source file programs.
387 The
388 .Dq make objs
389 target must then be used to get those object files built, or
390 some other arrangements made.
391 .Pp
392 If a program directory being searched for is found, but contains
393 no objects, other directories are not searched.
394 This causes the following directive to fail:
395 .Pp
396 .Bd -literal -offset indent
397 srcdirs /usr/src/usr.bin /usr/src/usr.bin/less
398 progs less gzip
399 .Ed
400 .Pp
401 as the
402 .Pa /usr/src/usr.bin/less
403 directory will be found with the
404 .Pa /usr/src/usr.bin
405 .Em srcdirs
406 entry, and as it does not contain the require objects,
407 .Nm
408 fails to find objects for the
409 .Em less
410 program.
411 To avoid this problem, list specific srcdirs first, and
412 the more general ones later, for e.g.:
413 .Pp
414 .Bd -literal -offset indent
415 srcdirs /usr/src/usr.bin/less /usr/src/usr.bin
416 progs less gzip
417 .Ed
418 .Pp
419 will not have the above problem.