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
|
.\" $OpenBSD: bsd.port.mk.5,v 1.45 2001/08/17 11:13:58 mpech Exp $
.\"
.\" Copyright (c) 2000 Marc Espie
.\"
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd June 10 2000
.Dt BSD.PORT.MK 5
.Os
.Sh NAME
.Nm bsd.port.mk
.Nd ports tree master Makefile fragment
.Sh SYNOPSIS
.Fd #include <bsd.port.mk>
.Sh DESCRIPTION
.Nm
holds all the standard routines used by the ports tree.
Some variables and targets are for its internal use only.
The rest is documented here.
.Pp
Other BSD variants, as well as older versions of
.Nm bsd.port.mk ,
include other targets and variables.
Conversion methods are outlined here.
.Pp
This is still incomplete; some variables and targets are not yet documented.
Mostly because undocumented stuff has fuzzy semantics, and it hasn't been
decided yet how to define it.
.Sh TARGETS
.Bl -tag -width do-configure
.It Ar addsum
Complete the ${CHECKSUM_FILE} record of checksums with files that have been
added since
.Ar makesum .
Complain if anything does not match.
.It Ar build , Ar all
Default target.
Build the port.
Essentially invoke
.Bd -literal
env -i ${MAKE_ENV} ${MAKE_PROGRAM} ${MAKE_FLAGS} \\
.Ed
.Bd -literal
-f ${MAKE_FILE} ${ALL_TARGET}
.Ed
.It Ar checkpatch
Debugging version of the
.Ar patch
target that simulates invoking
.Xr patch 1 .
.It Ar checksum
Check distribution archives and distribution patches control sum against
the results recorded in ${CHECKSUM_FILE},
using the cryptographic signature utilities listed in ${PREFERRED_CIPHERS}.
Normally ${ALLFILES}
are checksummed, unless
.Ev IGNOREFILES
is set to a list of files to ignore.
Invoking
.Ar checksum
with REFETCH=true
will try to fetch a version of with mismatched checksums off the
.Ox
main archive site.
.It Ar clean
Clean ports contents.
By default, it will clean the work directory.
It can be invoked as
make clean='[depends work fake flavors dist install sub package packages]'.
.Bl -tag -width packages
.It Va work
Clean work directory.
.It Va depends
Recurse into dependencies.
.It Va flavors
Clean all work directories.
.It Va dist
Clean distfiles.
.It Va install
Uninstall package.
.It Va package
Remove package file.
.It Va sub
With
.Va install
or
.Va package ,
clean subpackages as well.
.It Va packages
Short-hand for `sub package'.
.El
.It Ar configure
Configure the port.
Might be a void operation.
Unless overridden, configure creates the ${WRKBUILD}
directory (see SEPARATE_BUILD), runs ${SCRIPTDIR}/configure if it exists,
and runs whatever configuration methods are recorded in
.Ev CONFIGURE_STYLE .
.It Ar distpatch
Apply distribution patches only.
.It Ar do-patch
Override for the default behavior of
.Ar patch .
It is usually better to override
.Ar post-patch ,
as
.Ar patch
needs to invoke
.Ar distpatch
directly for historical reasons.
.It Ar extract
Extract the distfiles under
.Pa ${WRKDIST}
(but see
.Ev EXTRACT_ONLY ) .
Refer to
.Ev EXTRACT_CASES
for a complete description.
.It Ar fake
Do a fake port installation, that is, simulate the port installation under
${WRKINST}.
Described in a separate section below.
.It Ar fetch
Fetch the distfiles and patchfiles.
Each file of the
.Ev DISTFILES
and
.Ev PATCHFILES
lists is retrieved, if necessary, from the list of sites in
.Ev MASTER_SITES ,
with %SUBDIR% substituted with
.Ev MASTER_SITE_SUBDIR .
If a filename ends with a
.Sq :0
to
.Sq :9
extension, it will be retrieved from
.Ev MASTER_SITES0
to
.Ev MASTER_SITES9
instead.
The ports framework uses
.Pa ${DISTDIR}/${DIST_SUBDIR}
(aliased to
.Pa ${FULLDISTDIR} )
to cache the ports distribution files and patch files.
Note that this framework is also used by mirroring scripts,
which will also retrieve
.Ev SUPDISTFILES ,
to fill with supplementary distribution files which are not needed for
every configuration.
See
.Ev ALLFILES ,
.Ev CDROM_SITE ,
.Ev DISTDIR ,
.Ev DISTFILES ,
.Ev DIST_SUBDIR ,
.Ev FETCH_SYMLINK_DISTFILES ,
.Ev FULL_DISTDIR ,
.Ev MASTER_SITES ,
.Ev MASTER_SITES0 , ... ,
.Ev MASTER_SITES9 ,
.Ev PATCH_FILES ,
.Ev SUPDISTFILES ,
.Ev REFETCH .
.It Ar makesum
Create the ${CHECKSUM_FILE} list of recorded checksums by running the
cryptographic fingerprints sha1, md5 and rmd160 on ${ALLFILES} minus
${IGNOREFILES}.
.It Ar patch
Apply distribution and
.Ox
specific patches.
Because of historical accident,
.Ar patch
does not follow the exact same scheme other standard targets do.
Namely,
.Ar patch
invokes
.Ar pre-patch
(if defined),
.Ar do-patch ,
and
.Ar post-patch ,
but the default
.Ar do-patch
target recurses through
.Ar distpatch
So, if the
.Ar do-patch
target is overridden, it should still begin by calling
make distpatch, before applying
.Ox
specific patches.
See
.Ar distpatch
for the distribution patches-specific description.
If
.Pa ${PATCHDIR}
exists, the files described under
.Ev PATCH_LIST
will be applied under
.Ev WRKDIST .
.It Ar rebuild
Force rebuild of the port.
.It Ar show
Invoked as show=name, show the contents of ${name}.
Mostly used from recursive makes, or to know the contents of another
port's variables without guessing wrong.
.El
.Sh VARIABLES
.Bl -tag -width MASTER_SITES
.It Ev show
Invoked as make show=name, show the contents of variable name.
.It Ev ALLFILES
List of all files that need to be retrieved by
.Ar fetch ,
with master site selection extension removed. Read-only.
.It Ev ALL_TARGET
Target used to build software.
Default is
.Sq all .
Can be set to empty, to yield a package's default target.
.It Ev ARCH
Current machine architecture (read-only).
.It Ev AUTOCONF
Location of the autoconf binary if needed.
Defaults to autoconf (though make autoreconf might be more appropriate).
.It Ev AUTOCONF_DIR
Where to invoke autoconf if ${CONFIGURE_STYLE} includes autoconf.
Defaults to ${WRKSRC}.
.\" AUTOCONF_DIR should probably be a list, and be renamed to AUTOCONF_DIRS ?
.It Ev BSD_INSTALL_{PROGRAM,SCRIPT,DATA,MAN}[_DIR]
Macros passed to make and configure invocations.
Set based on corresponding INSTALL_* variables.
.It Ev BUILD_DEPENDS
List of other ports the current port needs to build correctly.
Each item has the form
.Sq file_to_test::directory[,-subpackage][,flavor ...][:target] .
The double :: is designed to allow wedging a package specification in the
near future.
.Sq target
defaults to
.Sq install
if it is not specified.
.Sq file_to_test
is checked against the current path for ports (see PORTPATH), or as an absolute
file name.
The special name /nonexistent can be used to force a build
dependency (see the ghostscript port for an example).
.Sq directory
is set relative to ${PORTSDIR}.
.Sq subpackage
is an optional subpackage name, to install instead of the default main
package name.
.Sq flavor ...
is a comma separated list of flavors.
By default, the dependency will build the default flavor.
Build dependencies are checked at the beginning of the extract stage.
.It Ev BZIP2
Name of the bzip2 binary.
.It Ev CATEGORIES
List of descriptive categories into which this port falls.
Mandatory.
See
.Ar link-categories ,
.Ar unlink-categories .
.It Ev CDROM_PACKAGES
Base location where packages suitable for a CDROM (see
PERMIT_PACKAGE_CDROM) will be placed
(default: ${PORTSDIR}/cdrom-packages/${ARCH})
.It Ev CDROM_SITE
Path to a local database that holds distribution files (usually a CD-Rom
or other similar media), used to retrieve distribution files before going
to the network.
Defaults to
.Pa /cdrom/distfiles
if this path exists.
Distribution files are still copied or linked (see
.Ev FETCH_SYMLINK_DISFILES )
into
.Ev DISTDIR
if they are found under CDROM_SITE.
.It Ev CFLAGS
Default flags passed to the compiler for building.
Many ports ignore it.
See also
.Ev COPTS .
.It Ev CHECKSUM_FILE
Location for this port checksums, used by
.Ar addsum ,
.Ar checksum ,
and
.Ar makesum .
Defaults to ${FILESDIR}/md5.
.It Ev CLEANDEPENDS
If set to
.Sq Yes
.Sq make clean
will also clean dependencies.
Note that distclean never recurses down to dependencies.
.It Ev COMMENT
Comment used for the package, and in the INDEX.
.It Ev COMMENT-foo
Comment used for sub package foo in a multi-package set up.
.It Ev COMMENT-vanilla
Comment used for a flavored package, if the non-flavored comment is
inappropriate.
.It Ev COMMENT-foo-vanilla
Comment used for a sub-, flavored package.
.It Ev CONFIGURE_ARGS
Arguments to pass to configure script.
Defaults are empty, except for
gnu-style configure, where prefix and sysconfdir are set.
.It Ev CONFIGURE_ENV
Basic environment passed to configure script (path and libtool setup).
gnu-style configure adds a lot more variables.
.It Ev CONFIGURE_SCRIPT
Set to name of script invoked by
.Ar configure
target, if appropriate.
Should be relative to ${WRKSRC}.
.It Ev CONFIGURE_SHARED
Set to --enable-shared or --disable-shared, depending whether the
architecture supports shared libraries.
Should be appended to CONFIGURE_ARGS, for ports that build dynamic libraries
and whose configure script supports these options.
.It Ev CONFIGURE_STYLE
Set to style of configuration that needs to happen.
If
.Sq perl ,
assume
.Xr perl 1
.Xr ExtUtils::MakeMaker 3p
style.
If
.Sq gnu ,
assume
gnu configure style.
Add
.Sq dest
if port does not handle DESTDIR correctly, and needs to be configured to
add DESTDIR to prefixes
.Po
see also
.Ev DESTDIRNAME
.Pc .
Add
.Sq old
if port is an older autoconf port, that does not recognize --sysconfdir.
Add
.Sq autoconf
if autoconf needs to be rerun first.
If
.Sq imake ,
assume port configures using X11 ports Imakefile framework.
Add
.Sq noman
if port has no man pages the Imakefile should try installing.
If
.Sq simple ,
there is a configure script, but it does not fit the normal gnu configure
conventions.
.It Ev COPTS
Supplementary options appended to ${CFLAGS} for building.
Since most ports ignore the COPTS convention, they are actually told to use
${CFLAGS} ${COPTS} as CFLAGS.
.It Ev CXXOPTS
Supplementary options appended to ${CXXFLAGS} for building.
.It Ev DEF_UMASK
Correct value of umask for the port to build and package correctly.
Tested against the actual umask at
.Ar fake
time.
Default is 022.
Don't override.
.It Ev DESTDIRNAME
Name of variable to set to ${WRKINST} while faking.
Usually DESTDIR.
To be used in the rare cases where a port heeds DESTDIR in a few
directories and needs to be configured with
.Sq gnu dest ,
so that those few directories do not get in the way.
.It Ev DISTDIR
Directory where all ports distfiles and patchfiles are stashed.
Defaults to
.Pa ${PORTSDIR}/distfiles.
Override if distfiles are stored elsewhere.
Always use
.Ev FULLDISTDIR
to refer to ports' distfiles location, as it takes an eventual
.Ev DIST_SUBDIR
into account.
.It Ev DISTFILES
The main port distribution files (the actual software source, except
for binary-only ports).
Will be retrieved from the MASTER_SITES (see
.Ar fetch ) ,
checksummed and extracted (see
.Ar checksum ,
.Ar extract ) .
normally holds a list of files, possibly with :0
.Ev DISTFILES
normally holds a list of files, possibly with
.Sq 0
to
.Sq 9
appended to select a different
.Ev MASTER_SITES .
See also
.Ev SUPDISTFILES .
.It Ev DISTNAME
Name used to identify the port.
See
.Ev DISTFILES
and
.Ev PKGNAME .
.It Ev DISTORIG
Suffix used by
.Ar distpatch
to rename original files.
Defaults to
.Pa .bak.orig .
Distinct from
.Pa .orig
to avoid confusing
.Ar update-patches .
.It Ev DIST_SUBDIR
Optional subdirectory of ${DISTDIR} where the current port's distfiles
and patchfiles will be located.
See target
.Ar fetch.
.It Ev ECHO_MSG
Used to display
.Sq ===> Configuring for foo
and similar informative messages.
Override to turn off, for instance.
.It Ev ERRORS
List of errors found while parsing the port's Makefile.
Display the errors before making any target, and if any error starts with
.Qq Fatal: ,
do not make anything.
For instance:
.Bd -literal -indent
\&.if !defined(COMMENT)
ERRORS+="Fatal: Missing comment"
\&.endif
.Ed
.It Ev EXTRACT_CASES
In the normal extraction stage (when
.Ev EXTRACT_ONLY
is not empty), this is the contents of a case statement, used to extract files.
Fragments are automatically appended to extract tar and zip
archives, so that the default case is equivalent to the following shell
fragment:
.Bd -literal -indent
set -e
cd ${WRKDIR}
for archive in ${EXTRACT_ONLY}
do
case $$archive in
*.zip)
unzip -q ${FULLDISTDIR}/$$archive -d ${WRKDIR};;
*.tar.bz2)
bzip2 -dc ${FULLDISTDIR}/$$archive| tar xf -;;
*.shar.gz|*.shar.Z|*.sh.Z|*.sh.gz)
gzcat ${FULLDISTDIR}/$$archive | /bin/sh;;
*.shar|*.sh)
/bin/sh ${FULLDISTDIR}/$$archive;;
*.tar)
tar xf ${FULLDISTDIR}/$$archive;;
*)
gzip -dc ${FULLDISTDIR}/$$archive | tar xf -;;
esac
done
.Ed
.It Ev EXTRACT_ONLY
Set if not all ${DISTFILES} should be extracted at do-extract stage.
Default value is ${DISTFILES}.
.It Ev EXTRACT_SUFX
Used to set DISTFILES default value to ${DISTNAME}${EXTRACT_SUFX}.
Default value is .tar.gz.
.It Ev FAKE
Automatically set to
.Sq Yes
for most ports (and all new ports).
Indicates that the port, using
.Ev FAKE_FLAGS
magic, will properly fake installation into ${WRKINST}, to be packaged
and properly installed from the package.
Set to
.Sq No
in very rare cases, and during port creation.
.It Ev FAKE_FLAGS
Flags passed to ${MAKE_PROGRAM} on fake invocation.
By default, ${DESTDIRNAME}=${WRKINST}.
.It Ev FETCH_CMD
Command used to fetch distfiles for this port.
Defaults to
.Pa /usr/bin/ftp .
No current port overrides the default.
.It Ev FETCH_DEPENDS
See BUILD_DEPENDS for specification.
Fetch dependencies are checked at the beginning of the extract stage.
No current port uses FETCH_DEPENDS.
.It Ev FETCH_SYMLINK_DISTFILES
Set to
.Sq Yes
to link distribution files off
.Ev CDROM_DISTSITE
instead of copying them.
.It Ev FILESDIR
Location of other files related to the current ports.
Holds at least the checksum file, sometimes other files
(default: files.${ARCH} or files).
.It Ev FLAVOR
The port current options.
Set by the user, and tested by the port to activate wanted functionalities.
.It Ev FLAVORS
List of all flavors keywords a port may match.
Used to sort FLAVOR into a canonical order to build the package name,
or to select the packing-list, and as a quick validity check.
.It Ev FLAVOR_EXT
Canonical list of flavors being set for the current build, dash-separated.
See
.Ev FULLPKGNAME .
.It Ev FTP_PACKAGES
Base location where packages suitable for ftp (see
PERMIT_PACKAGE_FTP) will be placed
(default: ${PORTSDIR}/ftp-packages/${ARCH})
.It Ev FULLPKGNAME
Full name of the main created package, taking flavors into account.
Defaults to ${PKGNAME}${FLAVOR_EXT}.
.It Ev FULLPKGNAME-foo
Full package name for sub-package foo, if the default value is not
appropriate.
.It Ev GMAKE
Location of the gnu make binary, if needed.
Defaults to gmake.
.It Ev IGNOREFILES
Set to the list of files that cannot be checksummed.
For use by ports which
fetch dynamically generated archives that can't be checksummed.
.It Ev LIB_DEPENDS
Libraries this port depends upon.
Similar to BUILD_DEPENDS, except that
.Sq file_to_test
is replaced by a
.Sq lib_spec
of the form:
.Sq libname.[version.[subversion]] .
See BUGS AND LIMITATIONS as well.
.Pp
On architectures that use dynamic libraries,
.Ev LIB_DEPENDS
is also used as a running time dependency, and recorded in the package as
such.
.It Ev FULLDISTDIR
Complete path to directory where ${DISTFILES} and ${PATCHFILES} will be
located, to be used in hand-crafted extraction targets (read-only).
.It Ev INSTALL_{PROGRAM,SCRIPT,DATA,MAN}[_DIR]
Macros to use to install a program, a script, a man page, or data (or the
corresponding directory, respectively).
.It Ev INSTALL_TARGET
Target invoked to install the software, during fake installation.
Default is
.Sq install .
.It Ev IS_INTERACTIVE
Set to
.Sq Yes
if port needs human interaction to build.
Usually implies NO_PACKAGE as well.
Porters should strive to minimize IS_INTERACTIVE ports, by using
FLAVORS for multiple choice ports, and by postponing human intervention
to package installation time.
.It Ev LIBTOOL
Location of the libtool binary for ports that set
.Ev USE_LIBTOOL
(default: ${LOCALBASE}/bin/libtool).
.It Ev LIBTOOL_FLAGS
Arguments to pass to libtool.
If USE_LIBTOOL is set, the environment variable LIBTOOL is set
to ${LIBTOOL} ${LIBTOOL_FLAGS}.
.It Ev LOCALBASE
where other ports have already been installed (default: /usr/local)
.It Ev MAINTAINER
E-mail address with full name of the port's maintainer.
Defaults to ports@openbsd.org.
.It Ev MAKE_ENV
Environment variables passed to make invocations.
Sets at least PATH, PREFIX, LOCALBASE, X11BASE, CFLAGS, TRUEPREFIX, DESTDIR,
and the BSD_INSTALL_* macros.
.It Ev MAKE_FLAGS
Flags used for all make invocations, except for the fake stage, which uses
FAKE_FLAGS.
.It Ev MAKE_FILE
Name of the Makefile used for ports building.
Defaults to Makefile.
Used after changing directory to ${WRKBUILD}.
.It Ev MAKE_PROGRAM
The make program that is used for building the port.
Set to ${MAKE} or ${GMAKE} depending on USE_GMAKE.
Read-only.
.It Ev MESSAGE
File recorded in the package and displayed during installation.
Defaults to ${PKGDIR}/MESSAGE if this file exists.
Leave empty if no message is needed.
.It Ev MTREE_FILE
.Xr mtree 8
specification to check when creating a PLIST with the
.Ar plist
target.
.Ev MTREE_FILE
can hold a list of file names, to which
.Pa ${PORTSDIR}/infrastructure/db/fake.mtree
is always appended.
These specifications are rooted at
.Pa ${WRKINST} ,
and are subject to
.Ev SUBST_VARS
substitution, to ease
.Pa ${PREFIX}
independence.
This feature is primarily intended for large, interconnected ports,
such as the kde suite, where a base package sets up a large, extra
directory hierarchy that would make the manual checking of packing lists
tedious.
.It Ev MULTI_PACKAGES
Set to a list of package extensions for ports that create multiple packages.
See
.Qq Flavors and multi-packages
below.
.Pp
.It Ev NEED_VERSION
Specific revision of
.Nm
needed by this ports tree.
Usually set to the current version of
.Nm
when port was built, and updated by port maintainers when needed.
.It Ev NOT_FOR_ARCHS
List of architectures on which this port does not build.
See also
.Ev ONLY_FOR_ARCHS .
.It Ev NO_BUILD
Port does not need any build stage.
.It Ev NO_DEPENDS
Don't verify build of dependencies.
Do not use in any ports Makefile.
This is only meant as a user convenience when, e.g., you just want to browse
through a given port's source and do not wish to trigger the build of
dependencies.
.It Ev NO_SHARED_ARCHS
Set to the list of platforms that do not support shared libraries.
Use with
.Ev NOT_FOR_ARCHS .
.It Ev NO_SHARED_LIBS
Set to
.Sq Yes
if platform does not support shared libraries.
To be tested after including
.Nm bsd.port.mk ,
if neither PFRAG.shared nor CONFIGURE_SHARED are enough.
.It Ev ONLY_FOR_ARCHS
List of architectures on which this port builds.
Can hold both processor-specific information (e.g., m68k), and more
specific model information (e.g., amiga).
.It Ev OPSYS
Always
.Ox
(read-only).
.It Ev OPSYS_VER
Revision number of
.Ox
(read-only).
.It Ev PACKAGES
Base location for packages built (default: ${PORTSDIR}/packages/${ARCH}).
.It Ev PATCH
Command to use to apply all patches.
Defaults to
.Pa /usr/bin/patch .
.It Ev PATCH_CASES
In the normal distpatch stage (when
.Ev PATCHFILES
is not empty), this is the contents of a case statement, used to apply
distribution patches.
Fragments are automatically appended to handle gzip'ed and bzip'ed
patches, so that the default case is equivalent to the following shell
fragment:
.Bd -literal -indent
set -e
cd ${FULLDISTDIR}
for patchfile in ${_PATCHFILES}
do
case $$patchfile in
*.bz2)
bzip2 -dc $$patchfile | ${PATCH} ${PATCH_DIST_ARGS};;
*.Z|*.gz)
gzcat $$patchfile | ${PATCH} ${PATCH_DIST_ARGS};;
*)
${PATCH} ${PATCH_DIST_ARGS} <$$patchfile;;
esac
done
.Ed
.It Ev PATCHDIR
Location for patches applied by patch target (default: patches.${ARCH} or
patches).
.It Ev PATCHFILES
Files to fetch from the master sites like
.Ev DISTFILES ,
but serving a different purpose, as they hold distribution patches that
will be applied at the
.Ar patch
stage.
See also
.Ev SUPDISTFILES .
.It Ev PATCH_ARGS
Full list of options used while applying port's patches.
.It Ev PATCH_CHECK_ONLY
Set to Yes by the
.Ar checkpatch
target.
Don't touch unless the default
.Ar checkpatch
target needs to be redefined.
Ideally, user-defined patch subtargets ought to test checkpatch.
In practice, they don't.
.It Ev PATCH_DEBUG
If set to
.Sq Yes ,
the
.Ar patch
stage will output extra debug information.
.It Ev PATCH_DIST_ARGS
Full list of options used while applying distribution patches.
.It Ev PATCH_DIST_STRIP
Patch option used to strip directory levels while applying distribution
patches.
Defaults to -p0 .
.It Ev PATCH_LIST
Wildcard pattern of patches to select under ${PATCHDIR} (default: patch-*).
Note that filenames ending in .orig, or ~ are never applied.
.It Ev PATCH_STRIP
Patch option used to strip directory levels while applying port's patches.
Defaults to -p0 .
.It Ev PORTPATH
Path used by most shell invocations.
Don't override unless really needed.
.It Ev PORTSDIR
Root of the ports tree (default: /usr/ports).
.It Ev PKGDIR
Location for packaging information (packing list, port description, port
short description).
Default: pkg.${ARCH} or pkg.
.It Ev PKGNAME
Name of the main created package.
Default is ${DISTNAME} for the main package,
and ${DISTNAME} for multi-packages ports.
This does not take flavors into account.
See
.Ev FULLPKGNAME
for that.
.It Ev PKGNAME-foo
Package name for sub-package foo, if the default value
of ${PKGNAME}${SUBPACKAGE} is not appropriate.
.It Ev PKGPATH
Path to the current port's directory, relative to ${PORTSDIR}.
Read-only.
.It Ev PREFERRED_CIPHERS
List of cryptographic ciphers to use, in order of preference.
Default is
.Sq sha1 rmd160 md5 .
The first cipher that matches in ${CHECKSUM_FILE} is verified.
.It Ev PREFIX
Base directory for the current port installation.
Usually ${LOCALBASE}, though some ports may elect a location under /var,
and some multi-package ports may install under several locations.
.It Ev REFETCH
If set to true,
.Ar checksum
will analyze ${CHECKSUM_FILE}, and try retrieving files with the correct
checksum off ftp.openbsd.org, in the directory
.Pa /pub/OpenBSD/distfiles/$cipher/$value/$file .
.It Ev RUN_DEPENDS
Specification of ports this port needs installed to be functional.
Same format as BUILD_DEPENDS.
The corresponding packages will be built at
.Ar install
stage, and
.Xr pkg_add 1
will take care of installing them.
.It Ev SED_PLIST
Pipeline of commands used to create the actual packing list from the
PLIST template (usually ${PKGDIR}/PLIST).
.Nm
appends to it substitution commands corresponding to the port's
FLAVOR and variables from SUBST_VARS.
${SED_PLIST} is invoked as a pipeline after inserting PFRAG.shared fragments.
.It Ev SCRIPTDIR
Location for scripts related to the current port (default: scripts.${ARCH}
or scripts).
.It Ev SEPARATE_BUILD
Many gnu configure ports can be built in a directory distinct from the
place they were unpacked.
For some specific ports, this is even mandatory.
Set to
.Sq simple
if this is the case.
The ports infrastructure will generate a separate ${WRKBUILD} directory
in which the port will be configured and built.
Wipe ${WRKBUILD} to start anew, but skipping the extract/patch stage.
Set to
.Sq concurrent
if the build process does not modify anything under ${WRKSRC}.
The build process can then be run concurrently on different architectures.
Set to
.Sq flavored
if distinct flavors of the port may share a common source tree.
.It Ev SUBPACKAGE
Set to the sub package suffix when building a package in a multi-package port.
Read-only.
Used to test for dependencies or to adjust the package name.
.It Ev SUBST_VARS
Make variables whole values get substituted to create the actual package
information.
Always holds
.Ev ARCH ,
.Ev HOMEPAGE ,
.Ev PREFIX ,
and
.Ev SYSCONFDIR .
The special construct
.Sq ${FLAVORS}
can be used in the packing-list to specify the current list of dash
separated flavors the port is compiled with (useful for cross-dependencies
in
.Ev MULTI_PACKAGES ) .
Add other
variables as needed.
.It Ev SUPDISTFILES
Supplementary files that need to be retrieved under some specific
circumstances. For instance, a port might need architecture-specific files.
.Ev SUPDISTFILES
should hold a list of all distfiles and patchfiles that are not always
needed, so that a mirror will be able to grab all files, or that
.Ar makesum
will work.
Having an overlap between
.Ev SUPDISTFILES
and
.Ev DISTFILES ,
.Ev PATCHFILES
is admissible, and in fact, expected, as it is much simpler to build
an error-free list of files to retrieve in that way.
See the xanim port for an example.
.It Ev SYSCONFDIR
Location for ports system configuration files.
Defaults to
.Pa /etc ,
should never be set to
.Pa /usr/local/etc .
.It Ev TAR
Name of the tar binary.
.It Ev TEMPLATES
Base location for the templates used in the
.Ar readme
target.
.It Ev UNZIP
Name of the unzip binary.
.It Ev WRKBUILD
Subdirectory of ${WRKDIR} where the actual build occurs.
Defaults to ${WRKSRC}, unless SEPARATE_BUILD is involved, in which case
it is set to an appropriate value.
.It Ev WRKDIR
Location where all port activity occurs.
Apart from the actual port, may
hold all kinds of cookies that checkpoint the port's build.
Read-only.
Ports that need to know the WRKDIR of another port must use
cd that_port_dir && make show VARNAME=WRKDIR for this.
Note that WRKDIR may be a symbolic link.
.It Ev WRKDIST
Subdirectory of ${WRKDIR} where the source normally unpacked.
Base for all patches (default: ${WRKDIR}/${DISTNAME}).
Note that WRKDIST may be a symbolic link, if set to ${WRKDIR}.
.It Ev WRKSRC
Subdirectory of ${WRKDIR} where the actual source is.
Base for configuration (default: ${WRKDIST})
Note that WRKSRC may be a symbolic link, if set to ${WRKDIR}.
.It Ev WRKPKG
Subdirectory of ${WRKBUILD} where package information gets generated.
Defaults to ${WKRBUILD}/pkg, do not override unless
.Sq pkg
conflicts with the port's conventions.
.It Ev WRKINST
Subdirectory of ${WRKDIR} where port normally installs (see
.Ar fake
target).
.It Ev WRKOBJDIR
If defined, used as a base for the actual port working directory.
The real working directory is created there, and the port ${WRKDIR} is
just a link.
.It Ev X11BASE
Where X11 has been installed (default: /usr/X11R6).
.It Ev USE_GMAKE
Set to
.Sq Yes
if gnu make (${GMAKE}) is needed for correct behavior of this port.
.It Ev USE_LIBTOOL
Set to
.Sq Yes
if libtool is required for correct behavior of this port.
Add correct dependencies, and passes LIBTOOL environment variable to
scripts invocations.
.It Ev USE_MOTIF
Set to
.Sq any
if port works with any version of motif;
.Sq lesstif
if port requires lesstif to work;
.Sq openmotif
if ports requires openmotif to work.
The
.Sq any
setting creates an extra flavor choice of
.Sq lesstif .
.It Ev XMKMF
Invocation of xmkmf for CONFIGURE_STYLE=imake port.
Defaults to xmkf -a -DPorts.
The -DPorts is specific to
.Ox
and is always appended.
.It Ev YACC
Name of yacc program to pass to gnu-configure, defaults to yacc.
(gnu-configure would always try to use bison otherwise, which leads to
unreproducible builds.)
Set to bison if needed.
.El
.Sh FILES
.Bl -tag -width files/md5
.It Pa ../Makefile.inc
Common Makefile fragment for a set of ports, included automatically.
.It Pa /cdrom/distfiles
Default path to a CD-Rom (or other media) full of distribution files.
.It Pa Makefile.${ARCH}
Arch-dependent Makefile fragment, included automatically.
.It Pa ${DISTDIR}
cache of all distribution files.
.It Pa ${FILESDIR}/md5
Checksum file.
Holds the output of
.Xr md5 1 ,
.Xr sha1 1 ,
and
.Xr rmd160 1
for the ports ${DISTFILES} and ${PATCHFILES}.
.It Pa ${FULLDISTDIR}/${ALLFILES}
cache of distribution files for a given port.
.It Pa ${PKGDIR}/DESCR
Description for the port.
Variables such as ${HOMEPAGE} will be expanded
(see SUBST_VARS).
Multi-package ports will use DESCR${SUBPACKAGE}.
.It Pa ${PKGDIR}/COMMENT
Short, one line description of the port, that is displayed by
.Xr pkg_info 1 ,
and appears in
.Pa ${PORTSDIR}/INDEX .
Name will be adjusted for flavored and multi-packages ports.
.It Pa ${PORTSDIR}/infrastructure/db/fake.mtree
Specification used for populating ${WRKINST} at the start of
.Ar fake .
Use
.Ar pre-fake
if this is incomplete.
.El
.Sh OBSOLETE TARGETS
.Bl -tag -width do-configure
.It Ar {pre,do}-extract
Don't override.
Set
.Ev EXTRACT_ONLY
to nothing and override
.Ar post-extract
instead.
.It Ar fetch-all , Ar fetch-list , Ar mirror-distfiles
See
.Xr mirroring-ports 7
for more efficient and flexible ways to build mirrors.
.El
.Sh OBSOLETE VARIABLES
.Bl -tag -width MASTER_SITES
.It Ev COMMENT
Used to be the name of the comment file for a package.
It now holds the comment itself.
Some magic has been put in to allow for a seamless transition.
.It Ev DESCR_SRC
From
.Nx .
This is DESCR.
.Ox
does not give a specific name to the generated file.
It is not recommended to try to access them directly.
.It Ev EXTRACT_AFTER_ARGS
Was used to cobble together the normal extraction command, as
${EXTRACT_CMD} ${EXTRACT_BEFORE_ARGS} ${EXTRACT_AFTER_ARGS}.
Use
.Ev EXTRACT_CASES
instead.
.It Ev EXTRACT_BEFORE_ARGS
Likewise, use
.Ev EXTRACT_CASES
instead.
.It Ev EXTRACT_CMD
Likewise, use
.Ev EXTRACT_CASES
instead.
.It Ev USE_BZIP2
Use
.Ev EXTRACT_SUFX
or
.Ev EXTRACT_CASES
instead.
.It Ev USE_ZIP
Use
.Ev EXTRACT_SUFX
or
.Ev EXTRACT_CASES
instead.
.It Ev GNU_CONFIGURE
Use
.Ev CONFIGURE_STYLE
instead.
.It Ev HAS_CONFIGURE
Use
.Ev CONFIGURE_STYLE
instead.
.It Ev MASTERDIR
From
.Fx .
Used to organize a collection of ports that share most files.
.Ox
uses a single port with flavors or multi-packages to produce
package variations instead.
.It Ev MD5_FILE
Use
.Ev CHECKSUM_FILE
instead.
.It Ev MIRROR_DISTFILE
Use
.Ev PERMIT_DISTFILES_FTP
and
.Ev PERMIT_DISTFILES_CDROM
to determine which files can be mirrored instead.
See
.Xr mirroring-ports 7 .
.It Ev NO_CONFIGURE
If ${FILESDIR}/configure does not exist, no automatic configuration will
be done anyway.
.It Ev NO_EXTRACT
Set EXTRACT_ONLY= instead.
.It Ev NO_INSTALL_MANPAGES
Use
.Ev CONFIGURE_STYLE
instead.
.It Ev NO_MTREE
Starting with
.Ox 2.7 ,
the operating system installation script runs the /usr/local specification
globally, instead of embedding it in each package.
So packages no longer record an
.Xr mtree 8
specification.
Use an explicit
.Sq @exec
command if needed.
.It Ev NO_PATCH
The absence of a patches directory does the same.
Use PATCHDIR and PATCH_LIST if patches need to be changed dynamically.
.It Ev NO_WRKDIR
All ports should have a working directory, as this is necessary to store
cookies and keep state.
.It Ev NO_WRKSUBDIR
The same functionality is obtained by setting WRKDIST=${WRKDIR} .
.It Ev NOCLEANDEPENDS
Use CLEANDEPENDS instead.
.It Ev NOMANCOMPRESS
.Fx
ships with compressed man pages, and uses this variable to control
that behavior.
.It Ev PATCH_SITES
.Ev PATCHFILES
used to be retrieved from a separate site list.
For greater flexibility, all files are now retrieved from
.Ev MASTER_SITES ,
.Ev MASTER_SITES0 , ...,
.Ev MASTER_SITES9 ,
using a
.Sq :0
to
.Sq :9
extension to the file name, e.g.,
.Bd -literal -offset indent
PATCH_FILES=foo.diff.gz
PATCH_SITES=ftp://ftp.zoinx.org/pub/
.Ed
.Pp
becomes
.Bd -literal -offset indent
PATCH_FILES=foo.diff.gz:0
MASTER_SITES0=ftp://ftp.zoinx.org/pub/
.Ed
.It Ev PLIST_SRC
From
.Nx .
This is PLIST.
.Ox
does not give a specific name to the generated file.
It is not recommended to try to access them directly.
.It Ev PKGNAME
Used to refer to the full package name, has been superseded by
.Ev FULLPKGNAME-foo ,
for
.Ev SUBPACKAGE
-foo .
.Ev PKGNAME
now holds the package name, not taking multi-packages nor flavors
into account.
Most ports are not concerned by this change.
.It Ev PLIST_SUBST
From
.Nx
and
.Fx .
Use SUBST_VARS instead.
.Ox
does not allow general substitutions of the form VAR=value, but uses
only a list of variables instead.
Most package files gets transformed, instead of only the packing list.
.It Ev USE_AUTOCONF
Use
.Ev CONFIGURE_STYLE
instead.
.It Ev USE_IMAKE
Use
.Ev CONFIGURE_STYLE
instead.
.El
.Sh OBSOLETE FILES
.Bl -tag -width files/md5
.It Pa ${SCRIPTDIR}/{pre,do,post}-*
Identical functionality can be obtained through a {pre,do,post}-* target,
invoking the script manually if necessary.
.It Pa ${PKGDIR}/PLIST.noshared
Use PFRAG.shared or PFRAG.no-shared instead.
PLIST.noshared was too easy to forget when updating ports.
.It Pa ${PKGDIR}/PLIST.sed
Use PLIST directly.
Until revision 1.295,
.Nm
did not substitute variables in the packing list unless this special form
was used.
.It Pa /usr/share/mk/bsd.port.mk
Original location of
.Nm bsd.port.mk .
The current file lives under ${PORTSDIR}/infrastructure/mk/bsd.port.mk,
whereas /usr/share/mk/bsd.port.mk is just a stub.
.It Pa {scripts,files,patches}.${OPSYS}
The
.Ox
ports tree focuses on robustness, not on being portable to other operating
systems.
In any case, portability should not need to depend on operating
system dependent patches.
.It Pa /usr/local/etc
Used by
.Fx
to marshall system configuration files.
All
.Ox
system configuration files are located in
.Pa /etc ,
or in a subdirectory of
.Pa /etc .
.El
.Sh THE FAKE FRAMEWORK
The
.Ar fake
target is used to install the port in a private directory first, package
that false installation, so that the real installation will use the
package.
.Pp
Essentially,
.Ar fake
invokes a real
.Ar install
process after tweaking a few variables.
.Pp
.Ar fake
first creates a skeleton tree under ${WRKINST}, using the
.Xr mtree 8
specification
.Pa ${PORTSDIR}/infrastructure/db/fake.mtree .
.Pp
A
.Ar pre-fake
target may be used to complete that skeleton tree.
For instance, a few ports may need supplementary stuff to be present (as
it would be installed if the ports' dependencies were present).
.Pp
If {pre,do,post}-install overrides are present, they are used with some
important changes: PREFIX is set to ${WRKINST}${PREFIX}, ${DESTDIRNAME}
is set to ${WRKINST}, and TRUEPREFIX is set to ${PREFIX}.
Essentially, old install targets work transparently, except for a need to
change PREFIX to TRUEPREFIX for symbolic links and similar path lookups.
Specific traditional post install work can be simply removed, as it will
be taken care of by the package itself (for instance, ldconfig, or
texinfo's install-info).
.Pp
If no do-install override is present, the port is installed using
.Bd -literal -indent offset
env -i ${MAKE_ENV}
PREFIX=${WRKINST}${PREFIX} ${DESTDIRNAME}=${WRKINST} TRUEPREFIX=${PREFIX}
${MAKE_PROGRAM} ${FAKE_FLAGS} -f ${MAKE_FILE} ${FAKE_TARGET}
.Ed
.Pp
Note that this does set both PREFIX and ${DESTDIRNAME}.
If a port's Makefile both heeds ${DESTDIRNAME},
and references PREFIX explicitly,
FAKE_FLAGS may rectify the problem by setting PREFIX=${PREFIX}
(which will do the right thing, since ${PREFIX} is a
.Xr make 1
construct which will not be seen by the shell).
.Pp
${FAKE_FLAGS} is used to set variables on
.Xr make 1
command line, which will override the port Makefile contents.
Thus, a port that mentions DESTDIR= does not need any patch to work with fake.
.Sh FLAVORS AND MULTI_PACKAGES
Starting with
.Ox 2.7 ,
each port can generate several packages through two orthogonal mechanisms:
FLAVORS and MULTI_PACKAGES.
.Pp
If a port can be compiled with several options, set FLAVORS to the list of
possible options in the Makefile.
When building the port, set
.Li "FLAVOR='option1 option2...'"
to build a specific flavor of the port.
The Makefile should test the value of FLAVOR as follows:
.Bd -literal
FLAVOR?=
.if ${FLAVOR:L:Moption1}
# what to do if option1
.endif
.if ${FLAVOR:L:Moption2}
# what to do if option2
.endif
.Ed
.Pp
.Pa bsd.port.mk
takes care of a few details, such as generating a distinct work directory for
each flavor, or adding a dash separated list of options to the package
name.
The order in which FLAVOR is specified does not matter: the generated list,
called the canonical package extension, matches the ordering of FLAVORS.
Also, it is an error to specify an option in FLAVOR that does not appear
in FLAVORS.
.Pp
In recursive package building, flavors can be specified as a comma
separated list after the package directory, e.g., SUBDIR+=vim,no_x11.
.Pp
Finally, packing information will use templates with the canonical package
extension if they are available: if FLAVOR='option1 option2' and both
COMMENT and COMMENT-option1-option2 are available, COMMENT-option1-option2 will
be used.
.Pp
If a port can generate several useful packages, set MULTI_PACKAGES
accordingly.
Each extension of a MULTI_PACKAGES name should start with a dash, so that
they cannot be confused with FLAVORS.
In dependency checking and recursive builds, a subpackage can be
specified after a comma, e.g., SUBDIR+=quake,-server.
MULTI_PACKAGES only affects the actual package building step (and the
describe step, since a MULTI_PACKAGES port will produce several
descriptions).
.Pp
If MULTI_PACKAGES is set, each element of MULTI_PACKAGES triggers a
recursive make package, with SUBPACKAGE set to the right value, and
PACKAGING defined.
For instance, if MULTI_PACKAGES=-lib -server,
make package will work as follows:
.Pp
.Bl -bullet -compact
.It
Run make package SUBPACKAGE= PACKAGING=,
.It
Run make package SUBPACKAGE=-lib PACKAGING=-lib,
.It
Run make package SUBPACKAGE=-server PACKAGING=-server,
.El
.Pp
The port's Makefile can test the value of SUBPACKAGE to specialize
processing for all sub packages.
Note that SUBPACKAGE can also be set for dependency checking, so be
careful to also test PACKAGING: the build stage is shared among all
subpackages, and tests often only make sense during the packaging stage.
All packing information is derived from
templates with SUBPACKAGE appended.
In the preceding example, the packing-list template for pkgname-foo
must be in PLIST-foo.
.Sh THE GENERATION OF PACKING INFORMATION
Starting after
.Ox 2.7
(around revision 1.300 of bsd.port.mk), all packing information is
generated from templates in ${PKGDIR}.
.Pp
.Bl -bullet -compact
.It
If not overridden by the user, determine which set of templates to use,
depending on the current SUBPACKAGE and FLAVOR information.
Set ${PLIST}, ${DESCR}, ${COMMENT}, ${MESSAGE} accordingly.
.It
Detect the existence of ${PKGDIR}/{REQ,INSTALL,DEINSTALL}${SUBPACKAGE}.
Modify PKG_ARGS accordingly, to use the generated files, and add
dependencies to regenerate the files if the templates change.
.It
Generate the actual DESCR, and if needed, MESSAGE, REQ, INSTALL, DEINSTALL
from the templates in ${DESCR}, ${MESSAGE}, ${PKGDIR}/REQ${SUBPACKAGE},
${PKGDIR}/INSTALL${SUBPACKAGE}, ${PKGDIR}/DEINSTALL${SUBPACKAGE}, by
substituting the variables in ${SUBST_VARS}, and by substituting
${FLAVORS} with the canonical flavor extension for this port,
e.g, if FLAVORS=no_map gfx qt2, if FLAVOR=gfx no_map, this is
.Sq -no_map-gfx .
.It
Generate the actual PLIST from the template ${PLIST},
by inserting shared/no-shared fragments, applying a possible user-supplied
pipeline, merging other fragments, applying the same variable
substitutions as other packing information, and finally handling
dynamic libraries macros.
.El
.Pp
Note that ${COMMENT} is currently not substituted, to speed up
.Ar describe
generation.
.Pp
To avoid substitution, variables can be escaped as follows:
.Li "$\e{PREFIX}"
.Pp
Constructs such as the line
.Li "%%SHARED%%"
or
.Li "!%%SHARED%%"
in the packing-list template trigger the inclusion of the
.Pa ${PKGDIR}/PFRAG.shared${SUBPACKAGE}
or
.Pa ${PKGDIR}/PFRAG.no-shared${SUBPACKAGE} .
.br
Similarly, if FLAVORS lists flav1, then the line
.Li "%%flav1%%"
(resp.
.Li "!%%flav1%%" )
will trigger the inclusion of
.Pa ${PKGDIR}/PFRAG.flav1${SUBPACKAGE}
(resp.
.Pa ${PKGDIR}/PFRAG.no-flav1${SUBPACKAGE} )
in the packing-list.
Fragments that cannot be handled by these simple rules
can always be specified in a custom SED_PLIST.
.Pp
The constructs
.Li "DYNLIBDIR(directory)"
and
.Li "NEWDYNLIBDIR(directory)"
should be used in
.Pa ${PKGDIR}/PFRAG.shared${SUBPACKAGE}
to register directories that hold dynamic libraries (see
.Xr ldconfig 8 ).
.Li "NEWDYNLIBDIR"
is meant for directories that will go away when the package is deleted.
If possible, it should not be used, because users also have to edit
.Pa rc.conf
to add the directory.
It is usually better to also let libraries be visible as a link
under ${LOCALBASE}.
Having a separate directory is enough to trick
.Xr ld 1
into grabbing the right version.
Note that libraries used only for
.Xr dlopen 3
do not need NEWDYNLIDIR.
.Pp
The special
.Ar plist
target does a fairly good job of automatically generating PLIST and
PFRAG.shared fragments.
.Pp
In MULTI_PACKAGES mode, there must be separate COMMENT, DESCR, and PLIST
templates for each SUBPACKAGE (and optional distinct MESSAGE, REQ, INSTALL,
DEINSTALL files in a similar way).
This contrasts with the FLAVORS
situation, where all these files will automatically default to the
non-flavor version if there is no flavor-specific file around.
.Sh BUGS AND LIMITATIONS
.Ev LOCALBASE ,
.Ev X11BASE
and
.Ev PREFIX
are not heeded consistently.
Most of the ports tree will probably fall
apart if one tries to build/use stuff elsewhere.
.Pp
.Ev LIB_DEPENDS
is automatically both a BUILD_DEPENDS and a RUN_DEPENDS, whereas some
smarter, more intricate mechanism could be designed to minimize dependencies.
.Sh HISTORY
The ports mechanism originally came from
.Fx .
A lot of additions were taken from
.Nx
over the years.
.Pp
When the file grew too large, it was cleaned up to restore some of
its speed and remove a lot of bugs.
.Pp
FLAVORS, MULTI_PACKAGES and FAKE are
.Ox
improvements.
.\" Voluntarily undocumented:
.\" AUTOCONF_ENV: probably not needed anyway, should be internal.
.\"
.\" Todo: OBJMACHINE
.Sh SEE ALSO
.Xr packages-specs 7
|