1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
|
<!-- $NetBSD: components.xml,v 1.32 2006/12/15 13:22:14 martti Exp $ -->
<chapter id="components"> <?dbhtml filename="components.html"?>
<title>Package components - files, directories and contents</title>
<para>Whenever you're preparing a package, there are a number of
files involved which are described in the following
sections.</para>
<sect1 id="components.Makefile">
<title><filename>Makefile</filename></title>
<para>Building, installation and creation of a binary package are all
controlled by the package's <filename>Makefile</filename>.
The <filename>Makefile</filename> describes various things about
a package, for example from where to get it, how to configure,
build, and install it.</para>
<para>A package <filename>Makefile</filename> contains several
sections that describe the package.</para>
<para>In the first section there are the following variables, which
should appear exactly in the order given here. The order and
grouping of the variables is mostly historical and has no further
meaning.</para>
<itemizedlist>
<listitem><para><varname>DISTNAME</varname> is the basename of the
distribution file to be downloaded from the package's
website.</para></listitem>
<listitem><para><varname>PKGNAME</varname> is the name of the
package, as used by pkgsrc. You only need to provide it if
<varname>DISTNAME</varname> (which is the default) is not a good
name for the package in pkgsrc. Usually it is the pkgsrc
directory name together with the version number. It must match the
regular expression
<varname>^[A-Za-z0-9][A-Za-z0-9-_.+]*$</varname>, that is, it
starts with a letter or digit, and contains only letters, digits,
dashes, underscores, dots and plus signs.</para></listitem>
<listitem><para><varname>SVR4_PKGNAME</varname> is the name of
the package file to create if the <varname>PKGNAME</varname>
isn't unique on a SVR4 system. The default is
<varname>PKGNAME</varname>, which may be shortened when you use
<filename role="pkg">pkgtools/gensolpkg</filename>. Only add
<varname>SVR4_PKGNAME</varname> if <varname>PKGNAME</varname>
does not produce an unique package name on a SVR4 system.
The length of <varname>SVR4_PKGNAME</varname> is limited to 5
characters.</para></listitem>
<listitem><para><varname>CATEGORIES</varname> is a list of categories
which the package fits in. You can choose any of the top-level
directories of pkgsrc for it.</para>
<para>Currently the following values are available for
<varname>CATEGORIES</varname>. If more than
one is used, they need to be separated by spaces:</para>
<programlisting>
archivers cross geography meta-pkgs security
audio databases graphics misc shells
benchmarks devel ham multimedia sysutils
biology editors inputmethod net textproc
cad emulators lang news time
chat finance mail parallel wm
comms fonts math pkgtools www
converters games mbone print x11
</programlisting>
</listitem>
<listitem><para><varname>MASTER_SITES</varname>,
<varname>DYNAMIC_MASTER_SITES</varname>,
<varname>DIST_SUBDIR</varname>, <varname>EXTRACT_SUFX</varname>
and <varname>DISTFILES</varname> are discussed in detail in
<xref linkend="build.fetch"/>.</para></listitem>
</itemizedlist>
<para>The second section contains information about separately
downloaded patches, if any.
<itemizedlist>
<listitem><para><varname>PATCHFILES:</varname>
Name(s) of additional files that contain distribution patches.
There is no default. pkgsrc will look for them at
<varname>PATCH_SITES</varname>.
They will automatically be uncompressed before patching if
the names end with <filename>.gz</filename> or
<filename>.Z</filename>.</para>
</listitem>
<listitem><para><varname>PATCH_SITES</varname>:
Primary location(s) for distribution patch files (see
<varname>PATCHFILES</varname> below) if not found locally.</para>
</listitem>
</itemizedlist></para>
<para>The third section contains the following variables.
<itemizedlist>
<listitem><para><varname>MAINTAINER</varname> is the email address
of the person who feels responsible for this package, and who is
most likely to look at problems or questions regarding this
package which have been reported with &man.send-pr.1;. Other
developers should contact the <varname>MAINTAINER</varname> before
making major changes to the package. When packaging a new program,
set <varname>MAINTAINER</varname> to yourself. If you really can't
maintain the package for future updates, set it to
<email>pkgsrc-users@NetBSD.org</email>.</para></listitem>
<listitem><para><varname>HOMEPAGE</varname> is a URL where users can
find more information about the package.</para></listitem>
<listitem><para><varname>COMMENT</varname> is a one-line
description of the package (should not include the package
name).</para></listitem>
</itemizedlist></para>
<para>Other variables that affect the build:
<itemizedlist>
<listitem>
<para><varname>WRKSRC</varname>: The directory where the
interesting distribution files of the package are found. The
default is <filename>${WRKDIR}/${DISTNAME}</filename>, which
works for most packages.</para>
<para>If a package doesn't create a subdirectory for itself
(most GNU software does, for instance), but extracts itself in
the current directory, you should set
<varname>WRKSRC=${WRKDIR}</varname>.</para>
<para>If a package doesn't create a subdirectory with the
name of <varname>DISTNAME</varname> but some different name,
set <varname>WRKSRC</varname> to point to the proper name in
<filename>${WRKDIR}</filename>, for example
<varname>WRKSRC=${WRKDIR}/${DISTNAME}/unix</varname>. See
<filename role="pkg">lang/tcl</filename> and <filename
role="pkg">x11/tk</filename> for other examples.</para>
<para>The name of the working directory created by pkgsrc is
taken from the <varname>WRKDIR_BASENAME</varname>
variable. By default, its value is
<filename>work</filename>. If you want to use the same
pkgsrc tree for building different kinds of binary packages,
you can change the variable according to your needs. Two
other variables handle common cases of setting
<varname>WRKDIR_BASENAME</varname> individually. If
<varname>OBJHOSTNAME</varname> is defined in
<filename>/etc/mk.conf</filename>, the first component of
the host's name is attached to the directory name. If
<varname>OBJMACHINE</varname> is defined, the platform name
is attached, which might look like
<filename>work.i386</filename> or
<filename>work.sparc</filename>.</para>
</listitem>
</itemizedlist></para>
<para>Please pay attention to the following gotchas:</para>
<itemizedlist>
<listitem>
<para>Add <varname>MANCOMPRESSED</varname> if man pages are
installed in compressed form by the package. For packages using
BSD-style makefiles which honor MANZ, there is
<varname>MANCOMPRESSED_IF_MANZ</varname>.</para>
</listitem>
<listitem>
<para>Replace <filename>/usr/local</filename> with
<quote>${PREFIX}</quote> in all files (see patches,
below).</para>
</listitem>
<listitem>
<para>If the package installs any info files, see <xref
linkend="faq.info-files"/>.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="components.distinfo">
<title><filename>distinfo</filename></title>
<para>The <filename>distinfo</filename> file contains the message
digest, or checksum, of each distfile needed for the package. This
ensures that the distfiles retrieved from the Internet have not been
corrupted during transfer or altered by a malign force to introduce
a security hole. Due to recent rumor about weaknesses of digest
algorithms, all distfiles are protected using both SHA1 and RMD160
message digests, as well as the file size.</para>
<para>The <filename>distinfo</filename> file also contains the
checksums for all the patches found in the
<filename>patches</filename> directory (see <xref
linkend="components.patches"/>).</para>
<para>To regenerate the <filename>distinfo</filename> file, use the
<command>make makedistinfo</command> or <command>make mdi</command>
command.</para>
<para>Some packages have different sets of distfiles depending on
the platform, for example <filename
role="pkg">www/navigator</filename>). These are kept in the same
<filename>distinfo</filename> file and care should be taken when
upgrading such a package to ensure distfile information is not
lost.</para>
</sect1>
<sect1 id="components.patches">
<title>patches/*</title>
<para>This directory contains files that are used by the
&man.patch.1; command to
modify the sources as distributed in the distribution file into a form
that will compile and run perfectly on &os;. The files are applied
successively in alphabetic order (as returned by a shell
<quote>patches/patch-*</quote> glob expansion), so
<filename>patch-aa</filename> is applied before
<filename>patch-ab</filename>, etc.</para>
<para>The <filename>patch-*</filename> files should be in
<command>diff -bu</command> format, and apply without a fuzz to avoid
problems. (To force patches to apply
with fuzz you can set <varname>PATCH_FUZZ_FACTOR=-F2</varname>).
Furthermore, do not put changes for more than one file into a single
patch file, as this will make future modifications more difficult.</para>
<para>Similar, a file should be patched at most once, not several times by
several different patches. If a file needs several patches, they should
be combined into one file.</para>
<para>One important thing to mention is to pay attention that no RCS IDs
get stored in the patch files, as these will cause problems when
later checked into the &os; CVS tree. Use the
<command>pkgdiff</command> from the
<filename role="pkg">pkgtools/pkgdiff</filename> package to avoid
these problems.</para>
<para>For even more automation, we recommend using
<command>mkpatches</command> from the same package to make a
whole set of patches. You just have to backup files before you
edit them to <filename>filename.orig</filename>, e.g. with
<command>cp -p filename filename.orig</command> or, easier, by
using <command>pkgvi</command> again from the same package. If
you upgrade a package this way, you can easily compare the new
set of patches with the previously existing one with
<command>patchdiff</command>. Copy the patches you want to use
or update from the <filename>work/.newpatches</filename>
directory to <filename>patches/</filename>.</para>
<para>When you have finished a package, remember to generate
the checksums for the patch files by using the <command>make
makepatchsum</command> command, see <xref
linkend="components.distinfo"/>.</para>
<para>When adding a patch that corrects a problem in the
distfile (rather than e.g. enforcing pkgsrc's view of where
man pages should go), send the patch as a bug report to the
maintainer. This benefits non-pkgsrc users of the package,
and usually makes it possible to remove the patch in future
version.</para>
<para>If you want to share patches between multiple packages
in pkgsrc, e.g. because they use the same distfiles, set
<varname>PATCHDIR</varname> to the path where the patch files
can be found, e.g.:</para>
<programlisting>
PATCHDIR= ${.CURDIR}/../xemacs/patches
</programlisting>
<para>Patch files that are distributed by the author or other
maintainers can be listed in
<varname>PATCHFILES</varname>.</para>
<para>If it is desired to store any patches that should not be
committed into pkgsrc, they can be kept outside the pkgsrc
tree in the <filename>$LOCALPATCHES</filename> directory. The
directory tree there is expected to have the same
<quote>category/package</quote> structure as pkgsrc, and
patches are expected to be stored inside these dirs (also
known as <filename>$LOCALPATCHES/$PKGPATH</filename>). For
example, if you want to keep a private patch for
<filename>pkgsrc/graphics/png</filename>, keep it in
<filename>$LOCALPATCHES/graphics/png/mypatch</filename>. All
files in the named directory are expected to be patch files,
and <emphasis>they are applied after pkgsrc patches are
applied</emphasis>.</para>
<sect2 id="components.patches.guidelines">
<title>Patching guidelines</title>
<para>When fixing a portability issue in the code do not use
preprocessor magic to check for the current operating system nor
platform. Doing so hurts portability to other platforms because
the OS-specific details are not abstracted appropriately.</para>
<para>The general rule to follow is: instead of checking for the
operating system the application is being built on, check for the
specific <emphasis>features</emphasis> you need. For example,
instead of assuming that kqueue is available under NetBSD and
using the <varname>__NetBSD__</varname> macro to conditionalize
kqueue support, add a check that detects kqueue itself —
yes, this generally involves patching the
<command>configure</command> script. There is absolutely nothing
that prevents some OSes from adopting interfaces from other OSes
(e.g. Linux implementing kqueue), something that the above checks
cannot take into account.</para>
<para>Of course, checking for features generally involves more
work on the developer's side, but the resulting changes are
cleaner and there are chances they will work on many other
platforms. Not to mention that there are higher chances of being
later integrated into the mainstream sources. Remember:
<emphasis>It doesn't work unless it is right!</emphasis></para>
<para>Some typical examples:</para>
<table id="patch-examples">
<title>Patching examples</title>
<tgroup cols="3">
<thead>
<row>
<entry>Where</entry>
<entry>Incorrect</entry>
<entry>Correct</entry>
</row>
</thead>
<tbody>
<row>
<entry>configure script</entry>
<entry>
<programlisting>case ${target_os} in
netbsd*) have_kvm=yes ;;
*) have_kvm=no ;;
esac</programlisting>
</entry>
<entry>
<programlisting>AC_CHECK_LIB(kvm, kvm_open, have_kvm=yes, have_kvm=no)</programlisting>
</entry>
</row>
<row>
<entry>C source file</entry>
<entry>
<programlisting>#if defined(__NetBSD__)
# include <sys/event.h>
#endif</programlisting>
</entry>
<entry>
<programlisting>#if defined(HAVE_SYS_EVENT_H)
# include <sys/event.h>
#endif</programlisting>
</entry>
</row>
<row>
<entry>C source file</entry>
<entry><programlisting>int
monitor_file(...)
{
#if defined(__NetBSD__)
int fd = kqueue();
...
#else
...
#endif
}</programlisting>
</entry>
<entry>
<programlisting>int
monitor_file(...)
{
#if defined(HAVE_KQUEUE)
int fd = kqueue();
...
#else
...
#endif
}</programlisting>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>For more information, please read the <emphasis>Making
packager-friendly software</emphasis> article (<ulink
url="http://www.onlamp.com/pub/a/onlamp/2005/03/31/packaging.html">part
1</ulink>, <ulink
url="http://www.oreillynet.com/pub/a/onlamp/2005/04/28/packaging2.html">part
2</ulink>). It summarizes multiple details on how to make
software easier to package; all the suggestions in it were
collected from our experience in pkgsrc work, so they are possibly
helpful when creating patches too.</para>
</sect2>
<sect2 id="components.patches.feedback">
<title>Feedback to the author</title>
<para>Always, always, <emphasis role="strong">always</emphasis>
feed back any <emphasis>portability fixes</emphasis> or
improvements you do to a package to the mainstream developers.
This is the only way to get their attention on portability issues
and to ensure that future versions can be built out-of-the box on
NetBSD. Furthermore, any user that gets newer distfiles will get
the fixes straight from the packaged code.</para>
<para>This generally involves cleaning up the patches as described
in the following section (because sometimes the patches that are
added to pkgsrc are quick hacks), filling bug reports in the
appropriate trackers for the projects and working with the
mainstream authors to accept your changes. It is
<emphasis>extremely important</emphasis> that you do it so that
the packages in pkgsrc are kept simple and thus further changes
can be done without much hassle.</para>
<para>Support the idea of free software!</para>
</sect2>
</sect1>
<sect1 id="other-mandatory-files">
<title>Other mandatory files</title>
<variablelist>
<varlistentry>
<term><filename>DESCR</filename></term>
<listitem>
<para>A multi-line description of the piece of software. This should include
any credits where they are due. Please bear in mind that others do not
share your sense of humour (or spelling idiosyncrasies), and that others
will read everything that you write here.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>PLIST</filename></term>
<listitem>
<para>This file governs the files that are installed on your
system: all the binaries, manual pages, etc. There are other
directives which may be entered in this file, to control the
creation and deletion of directories, and the location of
inserted files. See <xref linkend="plist"/> for more
information.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="components.optional">
<title>Optional files</title>
<sect2 id="components.optional.bin">
<title>Files affecting the binary package</title>
<variablelist>
<varlistentry>
<term><filename>INSTALL</filename></term>
<listitem>
<para>This shell script is invoked twice by &man.pkg.add.1;.
First time after package extraction and before files are
moved in place, the second time after the files to install
are moved in place. This can be used to do any custom
procedures not possible with @exec commands in
<filename>PLIST</filename>. See &man.pkg.add.1; and
&man.pkg.create.1; for more information. See also <xref
linkend="files-and-dirs-outside-prefix" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>DEINSTALL</filename></term>
<listitem>
<para>This script is executed before and after any files are removed. It is
this script's responsibility to clean up any additional messy details
around the package's installation, since all pkg_delete knows is how to
delete the files created in the original distribution.
See &man.pkg.delete.1;
and &man.pkg.create.1; for more information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>MESSAGE</filename></term>
<listitem>
<para>This file is displayed after installation of the package.
Useful for things like legal notices on almost-free
software and hints for updating config files after
installing modules for apache, PHP etc.
Please note that you can modify variables in it easily by using
<varname>MESSAGE_SUBST</varname> in the package's
<filename>Makefile</filename>:</para>
<programlisting>
MESSAGE_SUBST+= SOMEVAR="somevalue"
</programlisting>
<para>replaces "${SOMEVAR}" with <quote>somevalue</quote> in
<filename>MESSAGE</filename>. By default, substitution is
performed for <varname>PKGNAME</varname>,
<varname>PKGBASE</varname>, <varname>PREFIX</varname>,
<varname>LOCALBASE</varname>, <varname>X11PREFIX</varname>,
<varname>X11BASE</varname>,
<varname>PKG_SYSCONFDIR</varname>,
<varname>ROOT_GROUP</varname>, and
<varname>ROOT_GROUP</varname>.</para>
<para>You can display a different or additional files by
setting the <varname>MESSAGE_SRC</varname> variable. Its
default is <filename>MESSAGE</filename>, if the file
exists.</para>
</listitem>
</varlistentry>
<varlistentry><term><filename>ALTERNATIVES</filename></term>
<listitem><para>FIXME: There is no documentation on the
alternatives framework.</para></listitem></varlistentry>
</variablelist>
</sect2>
<sect2 id="components.optional.build">
<title>Files affecting the build process</title>
<variablelist>
<varlistentry><term><filename>Makefile.common</filename></term>
<listitem><para>This file contains arbitrary things that could
also go into a <filename>Makefile</filename>, but its purpose is
to be used by more than one package. This file should only be
used when the packages that will use the file are known in
advance. For other purposes it is often better to write a
<filename>*.mk</filename> file and give it a good name that
describes what it does.</para></listitem></varlistentry>
<varlistentry><term><filename>buildlink3.mk</filename></term>
<listitem><para>This file contains the dependency information
for the buildlink3 framework (see <xref
linkend="buildlink"/>).</para></listitem></varlistentry>
<varlistentry><term><filename>hacks.mk</filename></term>
<listitem><para>This file contains workarounds for compiler bugs
and similar things. It is included automatically by the pkgsrc
infrastructure, so you don't need an extra
<literal>.include</literal> line for
it.</para></listitem></varlistentry>
<varlistentry><term><filename>options.mk</filename></term>
<listitem><para>This file contains the code for the
package-specific options (see <xref linkend="options"/>) that can be
selected by the user. If a package has only one or two options,
it is equally acceptable to put the code directly into the
<filename>Makefile</filename>.</para></listitem></varlistentry>
</variablelist>
</sect2>
<sect2 id="components.optional.none">
<title>Files affecting nothing at all</title>
<variablelist>
<varlistentry><term><filename>README*</filename></term>
<listitem><para>These files do not take place in the creation of
a package and thus are purely informative to the package
developer.</para></listitem></varlistentry>
<varlistentry><term><filename>TODO</filename></term>
<listitem><para>This file contains things that need to be done
to make the package even
better.</para></listitem></varlistentry>
</variablelist>
</sect2>
</sect1>
<sect1 id="work-dir">
<title><filename>work*</filename></title>
<para>When you type <command>make</command>, the distribution files are
unpacked into the directory denoted by
<varname>WRKDIR</varname>. It can be removed by running
<command>make clean</command>. Besides the sources, this
directory is also used to keep various timestamp files.
The directory gets <emphasis>removed completely</emphasis> on clean.
The default is <filename>${.CURDIR}/work</filename>
or <filename>${.CURDIR}/work.${MACHINE_ARCH}</filename>
if <varname>OBJMACHINE</varname> is set.</para>
</sect1>
<sect1 id="files-dir">
<title><filename>files/*</filename></title>
<para>If you have any files that you wish to be placed in the package prior
to configuration or building, you could place these files here and use
a <command>${CP}</command> command in the
<quote>pre-configure</quote> target to achieve
this. Alternatively, you could simply diff the file against
<filename>/dev/null</filename> and use the patch mechanism to manage
the creation of this file.</para>
<para>If you want to share files in this way with other
packages, set the <varname>FILESDIR</varname> variable to point
to the other package's <filename>files</filename> directory,
e.g.:</para>
<programlisting>
FILESDIR=${.CURDIR}/../xemacs/files
</programlisting>
</sect1>
</chapter>
|