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
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
|
<!-- $NetBSD: fixes.xml,v 1.50 2006/04/08 07:43:41 reed Exp $ -->
<chapter id="fixes"> <?dbhtml filename="fixes.html"?>
<title>Making your package work</title>
<sect1 id="general-operation">
<title>General operation</title>
<sect2 id="pulling-vars-from-etc-mk.conf">
<title>How to pull in variables from /etc/mk.conf</title>
<para>The problem with package-defined variables that can be
overridden via <varname>MAKECONF</varname> or
<filename>/etc/mk.conf</filename> is that &man.make.1; expands a
variable as it is used, but evaluates preprocessor-like
statements (.if, .ifdef and .ifndef) as they are read. So, to
use any variable (which may be set in
<filename>/etc/mk.conf</filename>) in one of the .if*
statements, the file <filename>/etc/mk.conf</filename> must be
included before that .if* statement.</para>
<para>Rather than having a number of ad-hoc ways of including
<filename>/etc/mk.conf</filename>, should it exist, or
<varname>MAKECONF</varname>, should it exist, include the
<filename>pkgsrc/mk/bsd.prefs.mk</filename> file in the package
Makefile before any preprocessor-like .if, .ifdef, or .ifndef
statements:</para>
<programlisting>
.include "../../mk/bsd.prefs.mk"
.if defined(USE_MENUS)
# ...
.endif
</programlisting>
<para>If you wish to set the <varname>CFLAGS</varname> variable
in <filename>/etc/mk.conf</filename>, please make sure to use:
<programlisting>
CFLAGS+= -your -flags
</programlisting>
Using <varname>CFLAGS=</varname> (i.e. without the
<quote>+</quote>) may lead to problems with packages that need
to add their own flags. Also, you may want to take a look at
the <filename role="pkg">devel/cpuflags</filename> package if
you're interested in optimization for the current CPU.</para>
</sect2>
<sect2 id="where-to-install-documentation">
<title>Where to install documentation</title>
<para>Documentation should be installed into
<filename>${PREFIX}/share/doc/${PKGBASE}</filename> or
<filename>${PREFIX}/share/doc/${PKGNAME}</filename> (the
latter includes the version number of the package).</para>
</sect2>
<sect2 id="restricted-packages">
<title>Restricted packages</title>
<para>Some licenses restrict how software may be re-distributed.
In order to satisfy these restrictions, the package system
defines five make variables that can be set to note these
restrictions:</para>
<itemizedlist>
<listitem>
<para><varname>RESTRICTED</varname></para>
<para>This variable should be set whenever a restriction
exists (regardless of its kind). Set this variable to a
string containing the reason for the restriction.</para>
</listitem>
<listitem>
<para><varname>NO_BIN_ON_CDROM</varname></para>
<para>Binaries may not be placed on CD-ROM. Set this
variable to <varname>${RESTRICTED}</varname> whenever a
binary package may not be included on a CD-ROM.</para>
</listitem>
<listitem>
<para><varname>NO_BIN_ON_FTP</varname></para>
<para>Binaries may not be placed on an FTP server. Set
this variable to <varname>${RESTRICTED}</varname>
whenever a binary package may not not be made available
on the Internet.</para>
</listitem>
<listitem>
<para><varname>NO_SRC_ON_CDROM</varname></para>
<para>Distfiles may not be placed on CD-ROM. Set this
variable to <varname>${RESTRICTED}</varname> if
re-distribution of the source code or other distfile(s) is
not allowed on CD-ROMs.</para>
</listitem>
<listitem>
<para><varname>NO_SRC_ON_FTP</varname></para>
<para>Distfiles may not be placed on FTP. Set this variable
to <varname>${RESTRICTED}</varname> if re-distribution of
the source code or other distfile(s) via the Internet is not
allowed.</para>
</listitem>
</itemizedlist>
<para>Please note that the use of <varname>NO_PACKAGE</varname>,
<varname>IGNORE</varname>, <varname>NO_CDROM</varname>, or other
generic make variables to denote restrictions is deprecated,
because they unconditionally prevent users from generating
binary packages!</para>
</sect2>
<sect2 id="dependencies">
<title>Handling dependencies</title>
<para>Your package may depend on some other package being present
- and there are various ways of expressing this
dependency. pkgsrc supports the <varname>BUILD_DEPENDS</varname>
and <varname>DEPENDS</varname> definitions, the
<varname>USE_TOOLS</varname> definition, as well as
dependencies via <filename>buildlink3.mk</filename>, which is
the preferred way to handle dependencies, and which uses the
variables named above. See <xref linkend="buildlink"/> for more
information.</para>
<para>The basic difference between the two variables is as
follows: The <varname>DEPENDS</varname> definition registers
that pre-requisite in the binary package so it will be pulled in
when the binary package is later installed, whilst the
<varname>BUILD_DEPENDS</varname> definition does not, marking a
dependency that is only needed for building the package.
</para>
<para>This means that if you only need a package present whilst
you are building, it should be noted as a
<varname>BUILD_DEPENDS</varname>.</para>
<para>The format for a <varname>BUILD_DEPENDS</varname> and a
<varname>DEPENDS</varname> definition is:</para>
<programlisting>
<pre-req-package-name>:../../<category>/<pre-req-package>
</programlisting>
<para>Please note that the <quote>pre-req-package-name</quote>
may include any of the wildcard version numbers recognized by
&man.pkg.info.1;.</para>
<orderedlist>
<listitem>
<para>If your package needs another package's binaries or
libraries to build or run, and if that package has a
<filename>buildlink3.mk</filename> file available, use it:
</para>
<programlisting>
.include "../../graphics/jpeg/buildlink3.mk"
</programlisting>
</listitem>
<listitem>
<para>If your package needs to use another package to build
itself and there is no <filename>buildlink3.mk</filename>
file available, use the <varname>BUILD_DEPENDS</varname>
definition:</para>
<programlisting>
BUILD_DEPENDS+= autoconf-2.13:../../devel/autoconf
</programlisting>
</listitem>
<listitem>
<para>If your package needs a library with which to link and
again there is no <filename>buildlink3.mk</filename> file
available, this is specified using the
<varname>DEPENDS</varname> definition. For example:</para>
<programlisting>
DEPENDS+= xpm-3.4j:../../graphics/xpm
</programlisting>
<para>You can also use wildcards in package dependences:</para>
<programlisting>
DEPENDS+= xpm-[0-9]*:../../graphics/xpm
</programlisting>
<para>Note that such wildcard dependencies are retained when
creating binary packages. The dependency is checked when
installing the binary package and any package which matches
the pattern will be used. Wildcard dependencies should be
used with care.</para>
<para>The <quote>-[0-9]*</quote> should be used instead of
<quote>-*</quote> to avoid potentially ambiguous matches
such as <quote>tk-postgresql</quote> matching a
<quote>tk-*</quote> <varname>DEPENDS</varname>.</para>
<para>Wildcards can also be used to specify that a package
will only build against a certain minimum version of a
pre-requisite:</para>
<programlisting>
DEPENDS+= tiff>=3.5.4:../../graphics/tiff
</programlisting>
<para>This means that the package will build against version
3.5.4 of the tiff library or newer. Such a dependency may
be warranted if, for example, the API of the library has
changed with version 3.5.4 and a package would not compile
against an earlier version of tiff.</para>
<para>Please note that such dependencies should only be
updated if a package requires a newer pre-requisite, but
not to denote recommendations such as
ABI changes that do not prevent a package from building
correctly. Such recommendations can be expressed using
<varname>ABI_DEPENDS</varname>:</para>
<programlisting>
ABI_DEPENDS+= tiff>=3.6.1:../../graphics/tiff
</programlisting>
<para>In addition to the above <varname>DEPENDS</varname>
line, this denotes that while a package will build against
tiff>=3.5.4, at least version 3.6.1 is recommended.
<varname>ABI_DEPENDS</varname> entries will be turned into
dependencies unless explicitly ignored (in which case a
warning will be printed).</para>
<para>To ignore these ABI dependency recommendations and just
use the required <varname>DEPENDS</varname>, set
<varname>USE_ABI_DEPENDS=NO</varname>. This may make
it easier and faster to update packages built using pkgsrc,
since older compatible dependencies can continue to be
used. This is useful for people who watch their rebuilds
very carefully; it is not very good as a general-purpose
hammer. If you use it, you need to be mindful of possible
ABI changes, including those from the underlying OS.
</para>
<para>Packages that are built with recommendations ignored
may not be uploaded to ftp.NetBSD.org by developers and
should not be used across different systems that may have
different versions of binary packages installed.</para>
<para>For security fixes, please update the package
vulnerabilities file. See <xref
linkend="security-handling"/> for more
information.</para>
</listitem>
<listitem>
<para>If your package needs some executable to be able to run
correctly and if there's no
<filename>buildlink3.mk</filename> file, this is specified
using the <varname>DEPENDS</varname> variable. The
<filename role="pkg">print/lyx</filename> package needs to
be able to execute the latex binary from the teTeX package
when it runs, and that is specified:</para>
<programlisting>
DEPENDS+= teTeX-[0-9]*:../../print/teTeX
</programlisting>
<para>The comment about wildcard dependencies from previous
paragraph applies here, too.</para>
</listitem>
</orderedlist>
<para>If your package needs files from another package to build,
add the relevant distribution files to
<varname>DISTFILES</varname>, so they will be extracted
automatically. See the <filename
role="pkg">print/ghostscript</filename> package for an example.
(It relies on the jpeg sources being present in source form
during the build.)</para>
<para>Please also note the <varname>BUILD_USES_MSGFMT</varname>
and <varname>BUILD_USES_GETTEXT_M4</varname> definitions, which
are provided as convenience definitions. The former works out
whether &man.msgfmt.1; is part of the base system, and, if it isn't,
installs the <filename role="pkg">devel/gettext</filename> package.
The latter adds a build dependency on either an installed
version of an older gettext package, or if it isn't, installs the
<filename role="pkg">devel/gettext-m4</filename> package.</para>
</sect2>
<sect2 id="conflicts">
<title>Handling conflicts with other packages</title>
<para>Your package may conflict with other packages a user might
already have installed on his system, e.g. if your package
installs the same set of files like another package in our
pkgsrc tree.</para>
<para>In this case you can set <varname>CONFLICTS</varname> to a
space-separated list of packages (including version string) your
package conflicts with.</para>
<para>For example, <filename role="pkg">x11/Xaw3d</filename>
and <filename role="pkg">x11/Xaw-Xpm</filename>
install the same shared library, thus you set in
<filename>pkgsrc/x11/Xaw3d/Makefile</filename>:</para>
<programlisting>
CONFLICTS= Xaw-Xpm-[0-9]*
</programlisting>
<para>and in <filename>pkgsrc/x11/Xaw-Xpm/Makefile</filename>:
</para>
<programlisting>
CONFLICTS= Xaw3d-[0-9]*
</programlisting>
<para>Packages will automatically conflict with other packages
with the name prefix and a different version
string. <quote>Xaw3d-1.5</quote> e.g. will automatically
conflict with the older version <quote>Xaw3d-1.3</quote>.
</para>
</sect2>
<sect2 id="not-building-packages">
<title>Packages that cannot or should not be built</title>
<para>There are several reasons why a package might be
instructed to not build under certain circumstances. If the
package builds and runs on most platforms, the exceptions
should be noted with <varname>NOT_FOR_PLATFORM</varname>. If
the package builds and runs on a small handful of platforms,
set <varname>ONLY_FOR_PLATFORM</varname> instead.
Both <varname>ONLY_FOR_PLATFORM</varname> and
<varname>NOT_FOR_PLATFORM</varname> are OS triples
(OS-version-platform) that can use glob-style
wildcards.</para>
<para>If the package should be skipped (for example, because it
provides functionality already provided by the system), set
<varname>PKG_SKIP_REASON</varname> to a descriptive message.
If the package should fail because some preconditions are not
met, set <varname>PKG_FAIL_REASON</varname> to a descriptive
message.</para>
</sect2>
<sect2 id="undeletable-packages">
<title>Packages which should not be deleted, once installed</title>
<para>To ensure that a package may not be deleted, once it has been
installed, the <varname>PKG_PRESERVE</varname> definition should
be set in the package Makefile. This will be carried into any
binary package that is made from this pkgsrc entry. A
<quote>preserved</quote> package will
not be deleted using &man.pkg.delete.1; unless the
<quote>-f</quote> option is used.</para>
</sect2>
<sect2 id="security-handling">
<title>Handling packages with security problems</title>
<para>When a vulnerability is found, this should be noted in
<filename>localsrc/security/advisories/pkg-vulnerabilities</filename>,
and after committing that file, use <command>make upload</command>
in the same directory to update the file on ftp.NetBSD.org.</para>
<para>After fixing the vulnerability by a patch, its
<varname>PKGREVISION</varname> should be increased (this
is of course not necessary if the problem is fixed by using
a newer release of the software).</para>
<para>Also, if the fix should be applied to the stable pkgsrc
branch, be sure to submit a pullup request!</para>
<para>Binary packages already on ftp.NetBSD.org will be handled
semi-automatically by a weekly cron job.</para>
</sect2>
<sect2 id="compiler-bugs">
<title>How to handle compiler bugs</title>
<para>Some source files trigger bugs in the compiler, based on
combinations of compiler version and architecture and almost
always relation to optimisation being enabled. Common symptoms
are gcc internal errors or never finishing compiling a file.
</para>
<para>Typically, a workaround involves testing the
<varname>MACHINE_ARCH</varname> and compiler version, disabling
optimisation for that
file/<varname>MACHINE_ARCH</varname>/compiler combination, and
documenting it in <filename>pkgsrc/doc/HACKS</filename>. See
that file for a number of examples!</para>
</sect2>
<sect2 id="bumping-pkgrevision">
<title>How to handle incrementing versions when fixing an existing package</title>
<para>When making fixes to an existing package it can be useful
to change the version number in <varname>PKGNAME</varname>. To
avoid conflicting with future versions by the original author, a
<quote>nb1</quote>, <quote>nb2</quote>, ... suffix can be used
on package versions by setting <varname>PKGREVISION=1</varname>
(2, ...). The <quote>nb</quote> is treated like a
<quote>.</quote> by the pkg tools. e.g.</para>
<programlisting>
DISTNAME= foo-17.42
PKGREVISION= 9
</programlisting>
<para>will result in a <varname>PKGNAME</varname> of
<quote>foo-17.42nb9</quote>.</para>
<para>When a new release of the package is released, the
<varname>PKGREVISION</varname> should be removed, e.g. on a new
minor release of the above package, things should be like:</para>
<programlisting>
DISTNAME= foo-17.43
</programlisting>
</sect2>
<sect2 id="portability-of-packages">
<title>Portability of packages</title>
<para>One appealing feature of pkgsrc is that it runs on many different
platforms. As a result, it is important to ensure, where possible,
that packages in pkgsrc are portable. There are some particular
details you should pay attention to while working on pkgsrc.</para>
<sect3 id="install-scripts">
<title>${INSTALL}, ${INSTALL_DATA_DIR}, ...</title>
<para>The BSD-compatible <command>install</command> supplied with some
operating systems will not perform more than one operation at a time.
As such, you should call <quote>${INSTALL}</quote>, etc. like this:</para>
<programlisting>
${INSTALL_DATA_DIR} ${PREFIX}/dir1
${INSTALL_DATA_DIR} ${PREFIX}/dir2
</programlisting>
</sect3>
</sect2>
</sect1>
<sect1 id="downloading-issues">
<title>Possible downloading issues</title>
<sect2 id="no-plain-download">
<title>Packages whose distfiles aren't available for plain downloading</title>
<para>If you need to download from a dynamic URL you can set
<varname>DYNAMIC_MASTER_SITES</varname> and a <command>make
fetch</command> will call <filename>files/getsite.sh</filename>
with the name of each file to download as an argument, expecting
it to output the URL of the directory from which to download
it. <filename role="pkg">graphics/ns-cult3d</filename> is an
example of this usage.
</para>
<para>If the download can't be automated, because the user must
submit personal information to apply for a password, or must pay
for the source, or whatever, you can set
<varname>_FETCH_MESSAGE</varname> to a macro which displays a
message explaining the situation.
<varname>_FETCH_MESSAGE</varname> must be executable shell
commands, not just a message. (Generally, it executes
<varname>${ECHO}</varname>). See one of the following packages
for an example:
<filename role="pkg">fonts/acroread-jpnfont</filename>,
<filename role="pkg">sysutils/storage-manager</filename>.</para>
</sect2>
<sect2 id="modified-distfiles-same-name">
<title>How to handle modified distfiles with the 'old' name</title>
<para>Sometimes authors of a software package make some
modifications after the software was released, and they put up a
new distfile without changing the package's version number. If a
package is already in pkgsrc at that time, the checksum will
no longer match. The contents of the new distfile should be
compared against the old one before changing anything, to make
sure the distfile was really updated on purpose, and that
no trojan horse or so crept in.
Then, the correct way to work around this is to
set <varname>DIST_SUBDIR</varname> to a unique directory name,
usually based on <varname>PKGNAME_NOREV</varname>. In case this
happens more often, <varname>PKGNAME</varname> can be used (thus
including the <filename>nbX</filename> suffix) or a date stamp
can be appended, like <varname>${PKGNAME_NOREV}-YYYYMMDD</varname>.
Do not forget regenerating the <filename>distinfo</filename> file
after that, since it contains the <varname>DIST_SUBDIR</varname>
path in the filenames.
Furthermore, a mail to the package's authors seems appropriate
telling them that changing distfiles after releases without
changing the file names is not good practice.</para>
</sect2>
</sect1>
<sect1 id="configuration-gotchas">
<title>Configuration gotchas</title>
<sect2 id="fixes.libtool">
<title>Shared libraries - libtool</title>
<para>pkgsrc supports many different machines, with different
object formats like a.out and ELF, and varying abilities to do
shared library and dynamic loading at all. To accompany this,
varying commands and options have to be passed to the
compiler, linker, etc. to get the Right Thing, which can be
pretty annoying especially if you don't have all the machines
at your hand to test things. The
<filename role="pkg">devel/libtool</filename> pkg
can help here, as it just <quote>knows</quote> how to build
both static and dynamic libraries from a set of source files,
thus being platform-independent.</para>
<para>Here's how to use libtool in a pkg in seven simple
steps:</para>
<orderedlist>
<listitem>
<para>Add <varname>USE_LIBTOOL=yes</varname> to the package
Makefile.</para>
</listitem>
<listitem>
<para>For library objects, use <quote>${LIBTOOL} --mode=compile
${CC}</quote> in place of <quote>${CC}</quote>. You could even
add it to the definition of <varname>CC</varname>, if only
libraries are being built in a given Makefile. This one command
will build both PIC and non-PIC library objects, so you need not
have separate shared and non-shared library rules.</para>
</listitem>
<listitem>
<para>For the linking of the library, remove any
<quote>ar</quote>, <quote>ranlib</quote>, and <quote>ld
-Bshareable</quote> commands, and instead use:</para>
<programlisting>
${LIBTOOL} --mode=link ${CC} -o ${.TARGET:.a=.la} ${OBJS:.o=.lo} \
-rpath ${PREFIX}/lib -version-info major:minor
</programlisting>
<para>Note that the library is changed to have a
<filename>.la</filename> extension, and the objects are
changed to have a <filename>.lo</filename>
extension. Change <varname>OBJS</varname> as
necessary. This automatically creates all of the
<filename>.a</filename>,
<filename>.so.major.minor</filename>, and ELF symlinks (if
necessary) in the build directory. Be sure to include
<quote>-version-info</quote>, especially when major and
minor are zero, as libtool will otherwise strip off the
shared library version.</para>
<para>From the libtool manual:</para>
<programlisting>
So, libtool library versions are described by three integers:
CURRENT
The most recent interface number that this library implements.
REVISION
The implementation number of the CURRENT interface.
AGE
The difference between the newest and oldest interfaces that
this library implements. In other words, the library implements
all the interface numbers in the range from number `CURRENT -
AGE' to `CURRENT'.
If two libraries have identical CURRENT and AGE numbers, then the
dynamic linker chooses the library with the greater REVISION number.
</programlisting>
<para>The <quote>-release</quote> option will produce
different results for a.out and ELF (excluding symlinks)
in only one case. An ELF library of the form
<quote>libfoo-release.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote>
will have a symlink of
<quote>libfoo.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote>
on an a.out platform. This is handled
automatically.</para>
<para>The <quote>-rpath argument</quote> is the install
directory of the library being built.</para>
<para>In the <filename>PLIST</filename>, include only the
<filename>.la</filename> file, the other files will be
added automatically.</para>
</listitem>
<listitem>
<para>When linking shared object (<filename>.so</filename>)
files, i.e. files that are loaded via &man.dlopen.3;, NOT
shared libraries, use <quote>-module
-avoid-version</quote> to prevent them getting version
tacked on.</para>
<para>The <filename>PLIST</filename> file gets the
<filename>foo.so</filename> entry.</para>
</listitem>
<listitem>
<para>When linking programs that depend on these libraries
<emphasis>before</emphasis> they are installed, preface
the &man.cc.1; or &man.ld.1; line with <quote>${LIBTOOL}
--mode=link</quote>, and it will find the correct
libraries (static or shared), but please be aware that
libtool will not allow you to specify a relative path in
-L (such as <quote>-L../somelib</quote>), because it
expects you to change that argument to be the
<filename>.la</filename> file. e.g.</para>
<programlisting>
${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib
</programlisting>
<para>should be changed to:</para>
<programlisting>
${LIBTOOL} --mode=link ${CC} -o <replaceable>someprog</replaceable> <replaceable>../somelib/somelib.la</replaceable>
</programlisting>
<para>and it will do the right thing with the libraries.</para>
</listitem>
<listitem>
<para>When installing libraries, preface the &man.install.1;
or &man.cp.1; command with <quote>${LIBTOOL}
--mode=install</quote>, and change the library name to
<filename>.la</filename>. e.g.</para>
<programlisting>
${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib
</programlisting>
<para>This will install the static <filename>.a</filename>,
shared library, any needed symlinks, and run
&man.ldconfig.8;.</para>
</listitem>
<listitem>
<para>In your <filename>PLIST</filename>, include only
the <filename>.la</filename>
file (this is a change from previous behaviour).</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="using-libtool">
<title>Using libtool on GNU packages that already support libtool</title>
<para>Add <varname>USE_LIBTOOL=yes</varname> to the
package Makefile. This will override the package's own libtool
in most cases. For older libtool using packages, libtool is
made by ltconfig script during the do-configure step; you can
check the libtool script location by doing <command>make
configure; find work*/ -name libtool</command>.</para>
<para><varname>LIBTOOL_OVERRIDE</varname> specifies which libtool
scripts, relative to <varname>WRKSRC</varname>, to override. By
default, it is set to <quote>libtool */libtool
*/*/libtool</quote>. If this does not match the location of the
package's libtool script(s), set it as appropriate.</para>
<para>If you do not need <filename>*.a</filename> static
libraries built and installed, then use
<varname>SHLIBTOOL_OVERRIDE</varname> instead.</para>
<para>If your package makes use of the platform-independent library
for loading dynamic shared objects, that comes with libtool
(libltdl), you should include devel/libltdl/buildlink3.mk.</para>
<para>Some packages use libtool incorrectly so that the package may not work or
build in some circumstances. Some of the more common errors are:</para>
<itemizedlist>
<listitem>
<para>The inclusion of a shared object (-module) as a dependent library in an
executable or library. This in itself isn't a problem if one of two things
has been done:</para>
<orderedlist>
<listitem>
<para>The shared object is named correctly, i.e.
<filename>libfoo.la</filename>, not
<filename>foo.la</filename></para>
</listitem>
<listitem>
<para>The -dlopen option is used when linking an executable.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>The use of libltdl without the correct calls to initialisation routines.
The function lt_dlinit() should be called and the macro
<varname>LTDL_SET_PRELOADED_SYMBOLS</varname> included in
executables.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="autoconf-automake">
<title>GNU Autoconf/Automake</title>
<para>If a package needs GNU autoconf or automake to be executed
to regenerate the configure script and Makefile.in makefile
templates, then they should be executed in a pre-configure
target.</para>
<para>For packages that need only autoconf:</para>
<programlisting>
AUTOCONF_REQD= 2.50 # if default version is not good enough
USE_TOOLS+= autoconf # use "autoconf213" for autoconf-2.13
...
pre-configure:
cd ${WRKSRC}; autoconf
...
</programlisting>
<para>and for packages that need automake and autoconf:</para>
<programlisting>
AUTOMAKE_REQD= 1.7.1 # if default version is not good enough
USE_TOOLS+= automake # use "automake14" for automake-1.4
...
pre-configure:
cd ${WRKSRC}; \
aclocal; autoheader; \
automake -a --foreign -i; autoconf
...
</programlisting>
<para>Packages which use GNU Automake will almost certainly
require GNU Make.</para>
<para>There are times when the configure process makes
additional changes to the generated files, which then causes
the build process to try to re-execute the automake sequence.
This is prevented by touching various files in the configure
stage. If this causes problems with your package you can set
<varname>AUTOMAKE_OVERRIDE=NO</varname> in the package
Makefile.</para>
</sect2>
</sect1>
<sect1 id="fixes-build">
<title>Building the package</title>
<sect2 id="cpp-defines">
<title>CPP defines</title>
<para>Sometimes you need to compile different code depending on
the target platform. The C preprocessor has a set of predefined
macros that can be queried by using <varname>#ifdef FOO</varname>
or <varname>#if defined(FOO)</varname>. Among these macros are
usually ones that describe the target CPU and operating system.
Depending of which of the macros are defined, you can write code
that uses features unique to a specific platform. Generally you
should rather use the GNU autotools (automake, autoconf, etc.) to
check for specific features (like the existence of a header file,
a function or a library), but sometimes this is not possible or
desired.</para>
<para>In that case you can use the predefined macros
below to configure your code to the platform it runs on. Almost
every operating system, hardware architecture and compiler has its
own macro. For example, if the macros <varname>__GNUC__</varname>,
<varname>__i386__</varname> and <varname>__NetBSD__</varname> are
all defined, you know that you are using NetBSD on an i386
compatible CPU, and your compiler is GCC.</para>
<sect3 id="fixes-build-cpp-opsys">
<title>CPP defines for operating systems</title>
<para>To distinguish between 4.4 BSD-derived systems and the
rest of the world, you should use the following code.</para>
<programlisting><![CDATA[
#include <sys/param.h>
#if (defined(BSD) && BSD >= 199306)
/* BSD-specific code goes here */
#else
/* non-BSD-specific code goes here */
#endif
]]></programlisting>
<para>If this distinction is not fine enough, you can also use
the following defines.</para>
<programlisting>
FreeBSD __FreeBSD__
DragonFly __DragonFly__
Interix __INTERIX
Linux linux, __linux, __linux__
NetBSD __NetBSD__
OpenBSD __OpenBSD__
Solaris sun, __sun
</programlisting>
</sect3><sect3 id="fixes-build-cpp-cpu">
<title>CPP defines for CPUs</title>
<programlisting>
i386 i386, __i386, __i386__
MIPS __mips
SPARC sparc, __sparc
</programlisting>
</sect3><sect3 id="fixes-build-cpp-compiler">
<title>CPP defines for compilers</title>
<programlisting>
GCC __GNUC__ (major version), __GNUC_MINOR__
SunPro __SUNPRO_C (0x570 for version 5.7)
</programlisting>
</sect3>
</sect2>
<sect2 id="cpp-list-examples">
<title>Examples of CPP defines for some platforms</title>
<para>The list of the CPP identification macros for hardware and
operating system may depend on the compiler that is used. The
following list contains some examples that may help you to choose
the right ones. For example, if you want to conditionally compile
code on Solaris, don't use <varname>__sun__</varname>, as the
SunPro compiler does not define it. Use <varname>__sun</varname>
instead.</para>
<variablelist>
<varlistentry><term>GCC 3.3.3 + SuSE Linux 9.1 + i386</term>
<listitem><para>__ELF__, __gnu_linux__, __i386, __i386__,
__linux, __linux__, __unix, __unix__, i386, linux,
unix.</para></listitem></varlistentry>
<varlistentry><term>GCC 2.95 + NetBSD 1.6.2 + i386</term>
<listitem><para>__ELF__, __NetBSD__, __i386, __i386__,
i386.</para></listitem></varlistentry>
<varlistentry><term>GCC 3.3.3 + NetBSD 2.0 + i386</term>
<listitem><para>__ELF__, __NetBSD__, __i386, __i386__,
i386.</para></listitem></varlistentry>
<varlistentry><term>GCC 4 + Solaris 8 + SPARC</term>
<listitem><para>__ELF__, __sparc, __sparc__, __sun, __sun__,
__SVR4, __svr4__, __unix, __unix__, sparc, sun,
unix.</para></listitem></varlistentry>
<varlistentry><term>SunPro 5.7 + Solaris 8 + SPARC</term>
<listitem><para>__SVR4, __sparc, __sun, __unix, sparc, sun,
unix.</para></listitem></varlistentry>
</variablelist>
</sect2>
<sect2 id="cpp-list">
<title>Getting a list of CPP defines</title>
<para>If your system uses the GNU C Compiler, you can get a list
of symbols that are defined by default, e.g. to identify the
platform, with the following command:</para>
<programlisting>
<![CDATA[gcc -E -dM - < /dev/null ]]>
</programlisting>
<para>On other systems you may get the list by using the system's
syscall trace utility (ktrace, truss, strace) to have a look which
arguments are passed to the actual compiler.</para>
</sect2>
</sect1>
<sect1 id="package-specific-actions">
<title>Package specific actions</title>
<sect2 id="user-interaction">
<title>User interaction</title>
<para>Occasionally, packages require interaction from the user, and this can be
in a number of ways:</para>
<itemizedlist>
<listitem>
<para>help in fetching the distfiles</para>
</listitem>
<listitem>
<para>help to configure the package before it is built</para>
</listitem>
<listitem>
<para>help during the build process</para>
</listitem>
<listitem>
<para>help during the installation of a package</para>
</listitem>
</itemizedlist>
<para>The <varname>INTERACTIVE_STAGE</varname> definition is provided to notify
the pkgsrc mechanism of an interactive stage which will be needed, and
this should be set in the package's <filename>Makefile</filename>, e.g.:</para>
<programlisting>
INTERACTIVE_STAGE= build
</programlisting>
<para>Multiple interactive stages can be specified:</para>
<programlisting>
INTERACTIVE_STAGE= configure install
</programlisting>
</sect2>
<sect2 id="handling-licenses">
<title>Handling licenses</title>
<para>A package may be covered by a license which the user has
or has not agreed to accept. For these cases, pkgsrc contains
a mechanism to note that a package is covered by a particular
license, and the package cannot be built unless the user has
accepted the license. (Installation of binary packages are
not currently subject to this mechanism.) Packages with
licenses that are either Open Source according to the Open
Source Initiative or Free according to the Free Software
Foundation will not be marked with a license tag. Packages
with licenses that have not been determined to meet either
definition will be marked with a license tag referring to the
license. This will prevent building unless pkgsrc is informed
that the license is acceptable, and enables displaying the
license.</para>
<para>The license tag mechanism is intended to address
copyright-related issues surrounding building, installing and
using a package, and not to address redistribution issues (see
<varname>RESTRICTED</varname> and
<varname>NO_SRC_ON_FTP</varname>, etc.). However, the above
definition of licenses for which tags are not needed implies
that packages with redistribution restrictions should have
tags.</para>
<para>
Denoting that a package is covered by a particular license is
done by placing the license in
<filename>pkgsrc/licenses</filename> and setting the
<varname>LICENSE</varname> variable to a string identifying
the license, e.g. in
<filename role="pkg">graphics/xv</filename>: </para>
<programlisting>
LICENSE= xv-license
</programlisting>
<para>
When trying to build, the user will get a notice that the
package is covered by a license which has not been
accepted:</para>
<programlisting>
&cprompt; <userinput>make</userinput>
===> xv-3.10anb9 has an unacceptable license: xv-license.
===> To view the license, enter "/usr/bin/make show-license".
===> To indicate acceptance, add this line to your /etc/mk.conf:
===> ACCEPTABLE_LICENSES+=xv-license
*** Error code 1
</programlisting>
<para>The license can be viewed with <command>make
show-license</command>, and if it is considered appropriate,
the line printed above can be added to
<filename>/etc/mk.conf</filename> to indicate acceptance of
the particular license:</para>
<programlisting>
ACCEPTABLE_LICENSES+=xv-license
</programlisting>
<para>When adding a package with a new license, the license
text should be added to <filename>pkgsrc/licenses</filename>
for displaying. A list of known licenses can be seen in this
directory as well as by looking at the list of (commented
out) <varname>ACCEPTABLE_LICENSES</varname> variable
settings in
<filename>pkgsrc/mk/defaults/mk.conf</filename>.</para>
<para>The use of <varname>LICENSE=shareware</varname>,
<varname>LICENSE=no-commercial-use</varname>, and similar
language is deprecated because it does not crisply refer to
a particular license text. Another problem with such usage
is that it does not enable a user to denote acceptance of
the license for a single package without accepting the same
license text for another package. In particular, this can
be inappropriate when e.g. one accepts a particular license to
indicate to pkgsrc that a fee has been paid.</para>
</sect2>
<sect2 id="installing-score-files">
<title>Installing score files</title>
<para>Certain packages, most of them in the games category, install
a score file that allows all users on the system to record their
highscores. In order for this to work, the binaries need to be
installed setgid and the score files owned by the appropriate
group and/or owner (traditionally the "games" user/group). The
following variables, documented in more detail in
<filename>mk/defaults/mk.conf</filename>, control this
behaviour: <varname>SETGIDGAME</varname>,
<varname>GAMEDATAMODE</varname>, <varname>GAMEGRP</varname>,
<varname>GAMEMODE</varname>, <varname>GAMEOWN</varname>.</para>
<para>Note that per default, setgid installation of games is
disabled; setting <varname>SETGIDGAME=YES</varname> will set all
the other variables accordingly.</para>
<para>A package should therefor never hard code file ownership or
access permissions but rely on <varname>INSTALL_GAME</varname> and
<varname>INSTALL_GAME_DATA</varname> to set these
correctly.</para>
</sect2>
<sect2 id="perl-scripts">
<title>Packages containing perl scripts</title>
<para>
If your package contains interpreted perl scripts, set
<varname>REPLACE_PERL</varname> to ensure that the proper
interpreter path is set. <varname>REPLACE_PERL</varname> should
contain a list of scripts, relative to
<varname>WRKSRC</varname>, that you want adjusted.</para>
</sect2>
<sect2 id="hardcoded-paths">
<title>Packages with hardcoded paths to other interpreters</title>
<para>
Your package may also contain scripts with hardcoded paths to
other interpreters besides (or as well as) perl. To correct the
full pathname to the script interpreter, you need to set the
following definitions in your <filename>Makefile</filename> (we
shall use <command>tclsh</command> in this example):</para>
<programlisting>
REPLACE_INTERPRETER+= tcl
REPLACE.tcl.old= .*/bin/tclsh
REPLACE.tcl.new= ${PREFIX}/bin/tclsh
REPLACE_FILES.tcl= # list of tcl scripts which need to be fixed,
# relative to ${WRKSRC}, just as in REPLACE_PERL
</programlisting>
<note><para>Before March 2006, these variables were called
<varname>_REPLACE.*</varname> and
<varname>_REPLACE_FILES.*</varname>.</para></note>
</sect2>
<sect2 id="perl-modules">
<title>Packages installing perl modules</title>
<para>Makefiles of packages providing perl5 modules should include
the Makefile fragment
<filename>../../lang/perl5/module.mk</filename>. It provides a
<command>do-configure</command> target for the standard perl
configuration for such modules as well as various hooks to tune
this configuration. See comments in this file for
details.</para>
<para>Perl5 modules will install into different places depending
on the version of perl used during the build process. To
address this, pkgsrc will append lines to the
<filename>PLIST</filename> corresponding to the files listed in
the installed <filename>.packlist</filename> file generated by
most perl5 modules. This is invoked by defining
<varname>PERL5_PACKLIST</varname> to a space-separated list of
paths to packlist files, e.g.:</para>
<programlisting>
PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist
</programlisting>
<para>The variables <varname>PERL5_SITELIB</varname>,
<varname>PERL5_SITEARCH</varname>, and
<varname>PERL5_ARCHLIB</varname> represent the three locations
in which perl5 modules may be installed, and may be used by
perl5 packages that don't have a packlist. These three
variables are also substituted for in the
<filename>PLIST</filename>.</para>
</sect2>
<sect2 id="faq.info-files">
<title>Packages installing info files</title>
<para>Some packages install info files or use the
<quote>makeinfo</quote> or <quote>install-info</quote>
commands. <varname>INFO_FILES</varname> should be defined in
the package Makefile so that <filename>INSTALL</filename> and
<filename>DEINSTALL</filename> scripts will be generated to
handle registration of the info files in the Info directory
file. The <quote>install-info</quote> command used for the info
files registration is either provided by the system, or by a
special purpose package automatically added as dependency if
needed.</para>
<para><varname>PKGINFODIR</varname> is the directory under
<filename>${PREFIX}</filename> where info files are primarily
located. <varname>PKGINFODIR</varname> defaults to
<quote>info</quote> and can be overridden by the user.</para>
<para>There are two mutually exclusive ways to specify the info
files for the package:</para>
<itemizedlist>
<listitem>
<para>list each of info files in the package
<filename>PLIST</filename>; however any split info files
need not be listed, or</para>
</listitem>
<listitem>
<para>list the filename of each info file in the
<varname>INFO_FILES</varname> variable; however any split
info file filenames need not be listed. In this case
each of the info files should be installed into the
directory <filename>${PREFIX}/${PKGINFODIR}</filename>.</para>
</listitem>
</itemizedlist>
<para>A package which needs the <quote>makeinfo</quote> command
at build time must add <quote>makeinfo</quote> to
<varname>USE_TOOLS</varname> in its Makefile. If a minimum
version of the <quote>makeinfo</quote> command is needed it
should be noted with the <varname>TEXINFO_REQD</varname>
variable in the package <filename>Makefile</filename>. By
default, a minimum version of 3.12 is required. If the system
does not provide a <command>makeinfo</command> command or if it
does not match the required minimum, a build dependency on the
<filename role="pkg">devel/gtexinfo</filename> package will
be added automatically.</para>
<para>The build and installation process of the software provided
by the package should not use the
<command>install-info</command> command as the registration of
info files is the task of the package
<filename>INSTALL</filename> script, and it must use the
appropriate <command>makeinfo</command> command.</para>
<para>To achieve this goal, the pkgsrc infrastructure creates
overriding scripts for the <command>install-info</command> and
<command>makeinfo</command> commands in a directory listed early
in <varname>PATH</varname>.</para>
<para>The script overriding <command>install-info</command> has
no effect except the logging of a message. The script overriding
<command>makeinfo</command> logs a message and according to the
value of <varname>TEXINFO_REQD</varname> either runs the appropriate
<command>makeinfo</command> command or exit on error.</para>
</sect2>
<sect2 id="manpages">
<title>Packages installing man pages</title>
<para>Many packages install manual pages. The man pages
are installed under <varname>${PREFIX}/${PKGMANDIR}</varname>
which is <filename>/usr/pkg/man</filename> by default.
<varname>PKGMANDIR</varname> defaults to <quote>man</quote>.
For example, you can set <varname>PKGMANDIR</varname> to
<quote>share/man</quote> to have man pages install under
<filename>/usr/pkg/share/man/</filename> by default.
</para>
<note><para>The support for a custom <varname>PKGMANDIR</varname>
is not complete.
</para></note>
<para>The <filename>PLIST</filename> files can just
use <filename>man/</filename> as the top level directory
for the man page file entries
and the pkgsrc framework will convert as needed.
</para>
<para> Packages that are
configured with <varname>GNU_CONFIGURE</varname> set as
<quote>yes</quote>, by default will use the
<filename>./configure</filename>
--mandir switch to set where the man pages should be installed.
The path is <varname>GNU_CONFIGURE_MANDIR</varname> which defaults
to <varname>${PREFIX}/${PKGMANDIR}</varname>.
</para>
<para>
Packages that use <varname>GNU_CONFIGURE</varname> but do not
use --mandir, can set <varname>CONFIGURE_HAS_MANDIR</varname>
to <quote>no</quote>.
Or if the <filename>./configure</filename> script uses
a non-standard use of --mandir, you can set
<varname>GNU_CONFIGURE_MANDIR</varname> as needed.
</para>
<para>See <xref linkend="manpage-compression"/> for
information on installation of compressed manual pages.
</para>
</sect2>
<sect2 id="gconf2-data-files">
<title>Packages installing GConf2 data files</title>
<para>
If a package installs <filename>.schemas</filename> or
<filename>.entries</filename> files, used by GConf2,
you need to take some extra steps to make sure they get registered
in the database:
</para>
<orderedlist>
<listitem>
<para>Include <filename>../../devel/GConf2/schemas.mk</filename>
instead of its <filename>buildlink3.mk</filename> file. This
takes care of rebuilding the GConf2 database at installation and
deinstallation time, and tells the package where to install
GConf2 data files using some standard configure arguments. It
also disallows any access to the database directly from the
package.</para>
</listitem>
<listitem>
<para>Ensure that the package installs its
<filename>.schemas</filename> files under
<filename>${PREFIX}/share/gconf/schemas</filename>. If they get
installed under <filename>${PREFIX}/etc</filename>, you will
need to manually patch the package.</para>
</listitem>
<listitem>
<para>Check the PLIST and remove any entries under the etc/gconf
directory, as they will be handled automatically. See
<xref linkend="faq.conf"/> for more information.</para>
</listitem>
<listitem>
<para>Define the <varname>GCONF2_SCHEMAS</varname> variable in
your <filename>Makefile</filename> with a list of all
<filename>.schemas</filename> files installed by the package, if
any. Names must not contain any directories in them.</para>
</listitem>
<listitem>
<para>Define the <varname>GCONF2_ENTRIES</varname> variable in
your <filename>Makefile</filename> with a
list of all <filename>.entries</filename> files installed by the
package, if any. Names must not contain any directories in
them.</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="scrollkeeper-data-files">
<title>Packages installing scrollkeeper data files</title>
<para>
If a package installs <filename>.omf</filename> files, used by
scrollkeeper, you need to take some extra steps to make sure they
get registered in the database:
</para>
<orderedlist>
<listitem>
<para>Include
<filename>../../textproc/scrollkeeper/omf.mk</filename>
instead of its <filename>buildlink3.mk</filename> file. This
takes care of rebuilding the scrollkeeper database at
installation and deinstallation time, and disallows any access
to it directly from the package.
</para>
</listitem>
<listitem>
<para>Check the PLIST and remove any entries under the
<filename>libdata/scrollkeeper</filename> directory, as they
will be handled automatically.</para>
</listitem>
<listitem>
<para>Remove the <filename>share/omf</filename> directory from
the PLIST. It will be handled by scrollkeeper.</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="x11-fonts">
<title>Packages installing X11 fonts</title>
<para>If a package installs font files, you will need to rebuild
the fonts database in the directory where they get installed at
installation and deinstallation time. This can be automatically
done by using the pkginstall framework.</para>
<para>You can list the directories where fonts are installed in the
<varname>FONTS_DIRS.<replaceable>type</replaceable></varname>
variables, where <replaceable>type</replaceable> can be one of
<quote>ttf</quote>, <quote>type1</quote> or <quote>x11</quote>.
Also make sure that the database file
<filename>fonts.dir</filename> is not listed in the PLIST.</para>
<para>Note that you should not create new directories for fonts;
instead use the standard ones to avoid that the user needs to
manually configure his X server to find them.</para>
</sect2>
<sect2 id="gtk2-modules">
<title>Packages installing GTK2 modules</title>
<para>If a package installs GTK2 immodules or loaders, you need to
take some extra steps to get them registered in the GTK2 database
properly:</para>
<orderedlist>
<listitem> <para>Include
<filename>../../x11/gtk2/modules.mk</filename> instead of its
<filename>buildlink3.mk</filename> file. This takes care of
rebuilding the database at installation and deinstallation time.
</para>
</listitem>
<listitem> <para>
Set <varname>GTK2_IMMODULES=YES</varname> if
your package installs GTK2 immodules.</para>
</listitem>
<listitem> <para>
Set <varname>GTK2_LOADERS=YES</varname> if your package installs
GTK2 loaders.</para>
</listitem>
<listitem> <para>
Patch the package to not touch any of the GTK2 databases directly.
These are:
<itemizedlist>
<listitem><para><filename>libdata/gtk-2.0/gdk-pixbuf.loaders</filename></para></listitem>
<listitem><para><filename>libdata/gtk-2.0/gtk.immodules</filename></para></listitem>
</itemizedlist>
</para>
</listitem>
<listitem> <para>
Check the PLIST and remove any entries under the
<filename>libdata/gtk-2.0</filename> directory, as they will be
handled automatically.</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="sgml-xml-data">
<title>Packages installing SGML or XML data</title>
<para>If a package installs SGML or XML data files that need to be
registered in system-wide catalogs (like DTDs, sub-catalogs,
etc.), you need to take some extra steps:
</para>
<orderedlist>
<listitem>
<para>Include
<filename>../../textproc/xmlcatmgr/catalogs.mk</filename> in
your <filename>Makefile</filename>, which takes care of
registering those files in system-wide catalogs at
installation and deinstallation time.</para>
</listitem>
<listitem>
<para>Set <varname>SGML_CATALOGS</varname> to the full path of
any SGML catalogs installed by the package.</para>
</listitem>
<listitem>
<para>Set <varname>XML_CATALOGS</varname> to the full path of
any XML catalogs installed by the package.</para>
</listitem>
<listitem>
<para>Set <varname>SGML_ENTRIES</varname> to individual entries
to be added to the SGML catalog. These come in groups of
three strings; see xmlcatmgr(1) for more information
(specifically, arguments recognized by the 'add' action).
Note that you will normally not use this variable.</para>
</listitem>
<listitem>
<para>Set <varname>XML_ENTRIES</varname> to individual entries
to be added to the XML catalog. These come in groups of three
strings; see xmlcatmgr(1) for more information (specifically,
arguments recognized by the 'add' action). Note that you will
normally not use this variable.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="mime-database">
<title>Packages installing extensions to the MIME database</title>
<para>If a package provides extensions to the MIME database by
installing <filename>.xml</filename> files inside
<filename>${PREFIX}/share/mime/packages</filename>, you
need to take some extra steps to ensure that the database is kept
consistent with respect to these new files:
</para>
<orderedlist>
<listitem>
<para>Include
<filename>../../databases/shared-mime-info/mimedb.mk</filename>
(avoid using the <filename>buildlink3.mk</filename> file from
this same directory, which is reserved for inclusion from
other <filename>buildlink3.mk</filename> files). It takes
care of rebuilding the MIME database at installation and
deinstallation time, and disallows any access to it directly
from the package.</para>
</listitem>
<listitem>
<para>Check the PLIST and remove any entries under the
<filename>share/mime</filename> directory,
<emphasis>except</emphasis> for files saved under
<filename>share/mime/packages</filename>. The former are
handled automatically by
the update-mime-database program, but the latter are
package-dependent and must be removed by the package that
installed them in the first place.</para>
</listitem>
<listitem>
<para>Remove any <filename>share/mime/*</filename> directories
from the PLIST. They will be handled by the shared-mime-info
package.</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="intltool">
<title>Packages using intltool</title>
<para>If a package uses intltool during its build, include the
<filename>../../textproc/intltool/buildlink3.mk</filename> file,
which forces it to use the intltool package provided by pkgsrc,
instead of the one bundled with the distribution file.
</para>
<para>This tracks intltool's build-time dependencies and uses the
latest available version; this way, the package benefits of any
bug fixes that may have appeared since it was released.
</para>
</sect2>
<sect2 id="startup-scripts">
<title>Packages installing startup scripts</title>
<para>If a package contains a rc.d script, it won't be copied into
the startup directory by default, but you can enable it, by adding
the option <varname>PKG_RCD_SCRIPTS=YES</varname> in
<filename>/etc/mk.conf</filename>. This option will copy the scripts
into <filename>/etc/rc.d</filename> when a package is installed, and
it will automatically remove the scripts when the package is
deinstalled.</para>
</sect2>
<sect2 id="tex-packages">
<title>Packages installing TeX modules</title>
<para>If a package installs TeX packages into the texmf tree,
the <filename>ls-R</filename> database of the tree needs to be
updated.</para>
<note><para>Except the main TeX packages such as teTeX-texmf,
packages should install files
into <varname>PKG_LOCALTEXMFPREFIX</varname>,
not <varname>PKG_TEXMFPREFIX</varname>.</para></note>
<orderedlist>
<listitem><para>Include
<filename>../../print/teTeX/module.mk</filename> instead
of <filename>../../mk/tex.buildlink3.mk</filename>. This
takes care of rebuilding the <filename>ls-R</filename>
database at installation and deinstallation time.</para>
</listitem>
<listitem><para>If your package installs files into a texmf
tree other than the one
at <varname>PKG_LOCALTEXMFPREFIX</varname>,
set <varname>TEXMFDIRS</varname> to the list of all texmf
trees that need database update.</para>
<para>If your package also installs font map files that need
to be registered using <command>updmap</command>,
set <varname>TEX_FONTMAPS</varname> to the list of all
such font map files. Then <command>updmap</command> will
be run automatically at installation/deinstallation to
enable/disable font map files for TeX output
drivers.</para>
</listitem>
<listitem><para>Make sure that none of <filename>ls-R</filename>
databases are included in <filename>PLIST</filename>, as
they will be removed only by the teTeX-bin package.</para>
</listitem>
</orderedlist>
</sect2>
</sect1>
<sect1 id="feedback-to-author">
<title>Feedback to the author</title>
<para>If you have found any bugs in the package you make available,
if you had to do special steps to make it run under NetBSD or
if you enhanced the software in various other ways, be sure
to report these changes back to the original author of the
program! With that kind of support, the next release of the
program can incorporate these fixes, and people not using the
NetBSD packages system can win from your efforts.</para>
<para>Support the idea of free software!</para>
</sect1>
</chapter>
|