1.\" $OpenBSD: bsd.port.mk.5,v 1.574 2023/01/21 09:01:55 kn Exp $ 2.\" 3.\" Copyright (c) 2000-2008 Marc Espie 4.\" 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd $Mdocdate: January 21 2023 $ 28.Dt BSD.PORT.MK 5 29.Os 30.Sh NAME 31.Nm bsd.port.mk 32.Nd ports tree master Makefile fragment 33.Sh SYNOPSIS 34.Fd .include <bsd.port.mk> 35.Sh DESCRIPTION 36.Nm 37contains the 38.Xr ports 7 39tree 40.Xr make 1 41framework, in the form of documented public targets, 42variables and paths. 43.Pp 44Identifiers beginning with an underscore 45are internal-use only and likely to change without 46notice. 47.Pp 48This documentation contains sections covering targets, variables, 49diagnostics, and filenames, ordered in alphabetic order, followed 50by a section covering the fake framework, a section 51explaining flavors and multi-packages, and a section covering 52the generation of package information. 53.Pp 54It ends with sections covering some obsolete targets, variables and files, 55outlining conversion 56methods from older incarnations of the ports tree or from other 57.Bx 58variants. 59.Pp 60.Nm 61also uses quite a few helper scripts which live under 62.Pa ${PORTSDIR}/infrastructure/bin . 63.Pp 64Binary package details are mostly covered in 65.Xr pkg_create 1 66for the packing-list details, 67and in 68.Xr pkg_add 1 69for the installation semantics. 70.Pp 71Common usage such as building every package in 72the system is covered by 73.Xr ports 7 74and 75.Xr bulk 8 76instead, with 77.Xr packages 7 78providing an overview of the result. 79.Sh TARGETS 80.Bl -tag -width Ds 81.It Cm {build,run,all,test}-dir-depends 82Print all dependencies for a port in order to build it, run it, build and 83run it, or to run regression tests. 84The output is formatted as package specification pairs, in a form suitable 85for 86.Xr tsort 1 . 87.It Cm full-{build,run,all,test}-depends 88Print all dependencies a package depends upon for building, running, 89or both, as a list of package names, sorted by dependency order with 90.Xr tsort 1 , 91most dependent port first. 92.It Cm {build,lib,test,run}-depends-list 93Print a list of first level package specifications a port depends as 94build dependencies, library dependencies, test dependencies or 95run dependencies. 96.It Cm print-{build,run}-depends 97User convenience target that displays the result of 98.Cm full-{build,run}-depends 99in a more readable way. 100.It Cm {pre,do,post}-* 101Most standard targets can be specialized according to a given port's needs. 102If defined, 103the 104.Cm pre-* 105hook will be invoked before running the normal action; 106the 107.Cm do-* 108hook will be invoked instead of the normal action; 109the 110.Cm post-* 111hook will be invoked after the normal action. 112Specialization hooks exist for 113.Cm build , 114.Cm configure , 115.Cm distpatch , 116.Cm extract , 117.Cm fake , 118.Cm gen , 119.Cm install , 120.Cm patch , 121.Cm test . 122See individual targets for exceptions. 123.It Cm all-lib-depends-args 124Process the full 125.Ev LIB_DEPENDS 126list into a form suitable for 127.Xr pkg_create 1 , 128see 129.Cm print-package-args . 130.It Cm build , Cm all 131Default target. 132Build the port. 133Essentially invoke 134.Bd -literal 135env -i ${MAKE_ENV} ${MAKE_PROGRAM} ${MAKE_FLAGS} \e 136 -f ${MAKE_FILE} ${ALL_TARGET} 137.Ed 138.It Cm check-register 139Introspection target. 140Verify from the ports tree, without building anything, that the current 141subpackage will register okay 142.Po 143see 144.Ev PLIST_REPOSITORY 145.Pc . 146.It Cm check-register-all 147Apply 148.Cm check-register 149to all subpackages of the current port. 150.It Cm checkpatch 151Check that patches would apply cleanly, but do not modify anything. 152.It Cm checksum 153Compute a 154.Xr sha256 1 155digest 156of ${CHECKSUM_FILES} (files listed in DISTFILES and PATCHFILES) and 157check it against ${CHECKSUM_FILE}, normally 158.Pa distinfo . 159In case of a mismatch, running 160.Cm checksum 161with 162.Ev REFETCH Ns = Ns Cm true 163will fetch alternative versions of files keyed on their checksum 164from the 165.Ox 166main archive site. 167.It Cm clean 168Clean ports contents. 169By default, it will clean the work directory. 170It can be invoked as 171make clean='[depends build bulk work fake flavors dist install sub package 172packages plist test]'. 173.Bl -tag -width packages 174.It Va work 175Clean work directory. 176.It Va bulk 177Clean bulk cookie. 178.It Va build 179Clean the 180.Ev WRKBUILD 181directory (only useful if 182.Ev SEPARATE_BUILD 183is set). 184.It Va depends 185Recurse into dependencies. 186.It Va dist 187Clean distribution files. 188.It Va fake 189Clean fake installation directory. 190.It Va flavors 191Clean all work directories. 192.It Va install 193Uninstall package. 194.It Va package 195Remove all copies of package file. 196.It Va plist 197Remove registered packing-lists of all subpackages. 198.It Va test 199Clean test cookie. 200.It Va sub 201With 202.Va install 203or 204.Va package , 205clean subpackages as well. 206.It Va packages 207Shorthand for 208.Sq sub package . 209.It Va all 210Shorthand for 211.Sq work flavors packages plist . 212.El 213.It Cm clean-depends 214Shorthand for 215.Ql make clean=depends . 216.It Cm configure 217Configure the port. 218By default, 219.Cm configure 220creates the ${WRKBUILD} directory (see 221.Ev SEPARATE_BUILD ) , 222and runs whatever configuration methods are recorded in 223.Ev CONFIGURE_STYLE . 224.It Cm distclean 225Shorthand for 226.Ql make clean=dist . 227.It Cm distpatch 228Apply distribution patches only. 229See 230.Cm patch , 231.Ev PATCH_CASES 232and 233.Ev FIX_CRLF_FILES 234for details. 235.It Cm dump-vars 236Dump the values of all relevant variables in a port, prepended with the 237port's FULLPKGPATH. 238.It Cm extract 239Extract the distribution files under 240.Pa ${WRKDIR} 241(but see 242.Ev EXTRACT_ONLY , 243.Ev FIX_EXTRACT_PERMISSIONS 244and 245.Ev NO_DEPENDS ) . 246Refer to 247.Ev EXTRACT_CASES 248for a complete description. 249Do not use 250.Cm pre-extract 251and 252.Cm do-extract 253hooks. 254.It Cm fake 255Do a fake port installation, that is, simulate the port installation under 256${WRKINST}. 257There is no 258.Cm do-fake 259and 260.Cm post-fake 261hooks. 262.Cm fake 263actually uses 264.Cm pre-fake , 265.Cm pre-install , 266.Cm do-install 267and 268.Cm post-install . 269Override 270.Cm pre-install , 271.Cm do-install , 272or 273.Cm post-install 274to change behavior. 275Do not touch 276.Cm pre-fake 277unless you really know what you are doing. 278See 279.Sx THE FAKE FRAMEWORK 280section below. 281.It Cm fake-wantlib-args 282Check 283.Ev WANTLIB 284against the list of installed packages and libraries in the ports tree. 285See 286.Cm print-package-args . 287.It Cm fetch 288Fetch the list of files in 289.Ev DISTFILES 290and 291.Ev PATCHFILES 292using ${FETCH_CMD}. 293Files are normally retrieved from the list of sites in 294.Ev MASTER_SITES . 295.Pp 296Appending 297.Sq :0 298to 299.Sq :9 300to an entry will let 301${FETCH_CMD} retrieve from 302.Ev MASTER_SITES0 303to 304.Ev MASTER_SITES9 305instead. 306If the rest of the entry parses as 307.Sq Ar filename Ns { Ns Ar url Ns } Ns Ar sufx 308${FETCH_CMD} will fetch 309.Ar url Ns Ar sufx 310instead, but store the result as 311.Ar filename Ns Ar sufx . 312.Pp 313Transfers in progress are stored as 314.Ar filenamesufx.part 315and moved after completion. 316.Pp 317The ports framework uses 318.Pa ${DISTDIR}/${DIST_SUBDIR} 319(aliased to 320.Pa ${FULLDISTDIR} ) 321to save the ports distribution files and patch files. 322.Pp 323If you want to fetch a significant number of distfiles quickly, say 324all files relevant to a port, 325.Cm dpb Fl F 326is more efficient. 327.Pp 328Use of 329.Cm {pre,do,post}-fetch 330hooks is forbidden, as this would make mirroring of distfiles very complicated. 331.Pp 332See 333.Ev CHECKSUMFILES , 334.Ev DISTDIR , 335.Ev DISTFILES , 336.Ev DIST_SUBDIR , 337.Ev FETCH_CMD , 338.Ev FETCH_MANUALLY , 339.Ev FETCH_SYMLINK_DISTFILES , 340.Ev FULLDISTDIR , 341.Ev MAKESUMFILES , 342.Ev MASTER_SITES , 343.Ev MASTER_SITES0 , ... , 344.Ev MASTER_SITES9 , 345.Ev PATCHFILES , 346.Ev SUPDISTFILES , 347.Ev REFETCH . 348.It Cm fetch-all 349Like 350.Cm fetch , 351but also fetches 352.Ev SUPDISTFILES , 353for use with e.g., 354.Cm makesum . 355.It Cm fix-permissions 356Ensure permissions are correct when using 357.Ev PORTS_PRIVSEP 358and/or 359.Xr dpb 1 . 360.Pp 361If necessary, creates directory 362.Ev DISTDIR 363owned by 364.Ev FETCH_USER , 365and creates directories 366.Ev LOCKDIR , 367.Ev PACKAGE_REPOSITORY , 368.Ev PLIST_REPOSITORY 369and 370.Ev WRKOBJDIR 371owned by 372.Ev BUILD_USER . 373.Pp 374If these directories already exist, 375ownership of their contents is modified to conform to 376.Ev PORTS_PRIVSEP 377and 378.Xr dpb 1 379requirements. 380.It Cm gen 381Generate configure script when needed, either after patching 382input files, or from scratch for some ports, 383generally using automake, autoconf, autoreconf and similar GNU tools. 384This target only has modules 385.Po Ev MODxxx_gen Pc 386and a 387.Ar do-gen 388hooks. 389Then adjust timestamps to avoid regeneration during build 390.Po 391see 392.Ev REORDER_DEPENDENCIES 393.Pc . 394.It Cm generate-readmes 395Generate READMEs, rc scripts and login.conf.d files from 396.Pa ${PKGDIR} 397into 398.Pa ${WRKINST} . 399Run after 400.Cm fake 401and before 402.Cm package 403or 404.Cm update-plist . 405Always rerun, as it is cheap enough. 406.It Cm index 407Top-level target, see 408.Xr ports 7 . 409.It Cm install-depends 410Before package installation, install and verify dependencies constructed from 411.Ev RUN_DEPENDS , LIB_DEPENDS , 412and 413.Ev WANTLIB . 414.It Cm install 415Install the package after building. 416See the description of 417.Sx THE FAKE FRAMEWORK 418for the non-intuitive details of the way 419.Cm {pre,do,post}-install 420hooks are actually used by the ports tree. 421.It Cm install-all 422Install all packages in a multi-packages port. 423.It Cm lib-depends-args 424Filter 425.Ev LIB_DEPENDS 426to keep only entries required by 427.Ev WANTLIB , 428and output a list of dependencies suitable for 429.Xr pkg_create 1 , 430see 431.Cm print-package-args . 432.It Cm lib-depends-check 433Verify that the 434.Ev LIB_DEPENDS 435and 436.Ev WANTLIB 437are accurate for the port. 438See 439.Cm port-lib-depends-check , 440which is quicker. 441.It Cm license-check 442Check that 443.Ev PERMIT_PACKAGE 444settings match: 445if any dependency has a more restrictive setting, warn about it. 446This warning is advisory, because the automated license checking cannot 447figure out which ports were used only for building and did not taint 448the current port. 449.It Cm lock 450Manually obtain a lock on a given directory. 451Output must be used to update environment variables. 452The lock can be released with 453.Cm unlock . 454Seldom used, see 455.Xr ports 7 456for details. 457.It Cm makesum 458Run 459.Xr sha256 1 460on ${MAKESUMFILES} 461that is, files listed in ${DISTFILES}, ${SUPDISTFILES} and ${PATCHFILES}, 462and store the result in ${CHECKSUM_FILE}, normally 463.Pa distinfo . 464Also store the lengths of all files for a quick check during 465.Cm fetch . 466.It Cm no-lib-depends-args 467Degenerate form of 468.Cm lib-depends-args 469that does not do anything. 470See 471.Cm print-package-args . 472.It Cm no-wantlib-args 473Degenerate form of 474.Cm wantlib-args 475that does not do anything. 476See 477.Cm print-package-args . 478.It Cm package 479Build a port package (or packages in a 480.Ev MULTI_PACKAGES 481case) from the fake installation. 482Involves creating packaging information from templates 483(see 484.Ev COMMENT , 485.Ev SUBST_VARS 486among others) and invoking 487.Xr pkg_create 1 488for each package in the 489.Ev MULTI_PACKAGES 490list. 491If the repository already contains up-to-date packages, they are not rebuilt. 492If PLIST_REPOSITORY is set, the resulting packaging information is compared 493with existing stuff, and saved if new, with loud complaints if it changed 494without a REVISION bump. 495.Pp 496Also note that 497.Pa ${PLIST_REPOSITORY}/${MACHINE_ARCH}/history 498contains LRU caches for all files 499.Po 500see 501.Xr package 5 502.Pc . 503Arch-independent packages are created in ${PACKAGE_REPOSITORY}/no-arch, 504and copied into ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/all as needed. 505If ${PERMIT_PACKAGE} is set to 506.Sq Yes , 507copies built packages into ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/ftp, using 508hard links if possible. 509.It Cm patch 510Apply distribution and 511.Ox 512specific patches. 513Because of historical accident, 514.Cm patch 515does not follow the exact same scheme other standard targets do. 516Namely, 517.Cm patch 518invokes 519.Cm pre-patch 520(if defined), 521.Cm do-patch , 522and 523.Cm post-patch , 524but the default 525.Cm do-patch 526target invokes 527.Cm distpatch 528directly. 529So, if the 530.Cm do-patch 531target is overridden, it should still begin by calling 532.Ql make distpatch , 533before applying 534.Ox 535specific patches. 536Accordingly, the exact sequence of hooks is: 537.Cm pre-patch , 538.Cm do-distpatch , 539.Cm post-distpatch , 540.Cm do-patch , 541.Cm post-patch . 542If 543.Pa ${PATCHDIR} 544exists, the files described under 545.Ev PATCH_LIST 546will be applied under 547.Ev WRKDIST . 548.It Cm peek-ftp 549Connect to the first site in 550.Ev MASTER_SITES , 551in the right directory, and leaves user at 552.Xr ftp 1 Ns 's 553prompt. 554.It Cm pkglocatedb 555Top-level target, see 556.Xr ports 7 . 557.It Cm port-lib-depends-check 558Verify that the 559.Ev LIB_DEPENDS 560and 561.Ev WANTLIB 562hold all shared libraries used for every package in the port. 563See 564.Xr library-specs 7 . 565This makes use of 566.Cm print-plist-with-depends 567to avoid actually building the packages, it only needs the 568completion of the 569.Cm fake 570stage, and thus is quicker than 571.Cm lib-depends-check , 572unless you already have all binary packages. 573.It Cm port-wantlib-args 574Resolve 575.Ev WANTLIB 576against the ports tree itself and system libraries, without looking at built 577or installed packages, and writes a list of options suitable for 578.Xr pkg_create 1 . 579See 580.Cm print-package-args . 581.It Cm prepare 582Before port building, install and verify dependencies constructed from 583.Ev BUILD_DEPENDS , 584.Ev LIB_DEPENDS 585and 586.Ev WANTLIB . 587In 588.Ev MULTI_PACKAGES 589setups, 590see 591.Sx FLAVORS AND MULTI_PACKAGES . 592.It Cm print-package-args 593Print all dependency-related information that will be passed as parameters 594to 595.Xr pkg_create 1 , 596e.g., 597.Fl W Ar wantlib 598and 599.Fl P Ar depends 600lines. 601.Pp 602Those parameters are generated by 603.Cm run-depends-args 604for 605.Ev RUN_DEPENDENCIES 606handling, a form of 607.Cm lib-depends-args 608for 609.Ev LIB_DEPENDS 610and 611.Ev WANTLIB 612interaction, 613and a form of 614.Cm wantlib-args 615for 616.Ev WANTLIB 617resolution. 618.Pp 619Variables 620.Ev lib_depends_args 621and 622.Ev wantlib_args 623control the exact behavior: 624.Ev lib_depends_args 625is normally set to 626.Cm lib-depends-args , 627but will be set to 628.Cm all-lib-depends-args 629by 630.Cm port-lib-depends-check , 631in order to have access to the full list of LIB_DEPENDS for figuring 632out missing WANTLIB. 633.Ev wantlib_args 634is normally set to 635.Cm wantlib-args 636but it may be set to 637.Cm port-wantlib-args 638for introspection purposes, 639to 640.Cm fake-wantlib-args 641to avoid some checks, or to 642.Cm no-wantlib-args 643to avoid expensive WANTLIB checks entirely. 644.It Cm print-update-signature 645Print the update signature, as computed using information from the ports tree, 646in the same format used for 647.Xr pkg_info 1 648.Fl S . 649.It Cm print-plist 650Generate and print a package packing-list from the static information 651present in the port. 652.It Cm print-plist-all 653Iterate over 654.Cm print-plist 655for all subpackages in a given port. 656.It Cm print-plist-all-with-depends 657Iterate over 658.Cm print-plist-with-depends 659for all subpackages in a given port. 660.It Cm print-plist-contents 661Generate and print package contents from the static information 662present in the port. 663In contrast with 664.Cm print-plist , 665the package contents only consists of files, all tagged with category 666markers such as @file. 667See 668.Xr pkg_create 1 . 669.It Cm print-plist-libs 670Generate and print the list of static and dynamic libraries present in the port. 671See 672.Xr pkg_create 1 . 673.It Cm print-plist-libs-with-depends 674Like 675.Cm print-plist-libs , 676but slower. 677It also handles 678.Ev LIB_DEPENDS , 679.Ev RUN_DEPENDS , 680and 681.Ev WANTLIB , 682so that the packing-list has complete dependency information. 683.It Cm print-plist-with-depends 684Like 685.Cm print-plist , 686but slower. 687It also handles 688.Ev LIB_DEPENDS , 689.Ev RUN_DEPENDS , 690and 691.Ev WANTLIB , 692so that the packing-list is complete. 693.It Cm rebuild 694Force rebuild of the port. 695.It Cm regen 696Force rebuilding configure scripts using 697.Ar gen 698steps. 699.It Cm reinstall 700Force reinstallation of a port, by first cleaning the old installation. 701This will obviously not work for software used as dependencies of other 702installed software. 703In that case, 704.Cm update 705might do the right thing. 706.It Cm repackage 707Rebuild the packages of a port after removing existing packages. 708.It Cm run-depends-args 709Process 710.Ev RUN_DEPENDS 711and outputs a list of dependencies suitable for 712.Xr pkg_create 1 , 713see 714.Cm print-package-args . 715.It Cm reprepare 716Force running the 717.Ar prepare 718target again. 719.It Cm retest 720Force running the 721.Ar test 722target again. 723.It Cm show 724Invoked as make show=name, show the contents of ${name}. 725Invoked as make show="name1 name2 ...", 726show the contents of ${name1} ${name2} ..., 727one variable value per line. 728Mostly used from recursive makes, or to know the contents of another 729port's variables without guessing wrongly. 730.It Cm show-debug-info 731Displays the information that was generated by 732.Xr build-debug-info 1 . 733.It Cm show-fake-size 734Print the size of ${WRKINST}, in kilobytes. 735Used by some options of 736.Xr dpb 1 , 737suitable for 738.Ev BULK_TARGETS . 739.It Cm show-indexed 740Similar to 741.Cm show . 742Invoked as make show-indexed=name, show the contents of ${name${SUBPACKAGE}}, 743or ${name} if the variable 744.Ev name 745is not 746.Ev SUBPACKAGE 747dependent. 748.It Cm show-list 749Similar to 750.Cm show . 751Shows "list-like" variables, one entry per line. 752Mostly useful as a debugging target, since some internal variables may now 753exceed 754.Dv ARG_MAX . 755.It Cm show-prepare-results 756Print the list of actual installed packages found out by 757.Cm prepare . 758.It Cm show-prepare-test-results 759Print the list of actual installed packages found out by 760.Cm prepare 761and 762.Cm test-depends . 763.It Cm show-required-by 764Print the list of 765.Xr pkgpath 7 766for all ports that will be affected by the 767current port changing. 768Works by walking the list of dependencies, in reverse. 769.It Cm show-run-depends 770Print all running dependencies for a port, one per-line, without duplicates. 771.It Cm subpackage 772Build a port package. 773Exactly like 774.Cm package , 775but affects only one single subpackage in multi-packages ports. 776.It Cm show-size 777Print the size of the work directory, in kilobytes. 778Used by some options of 779.Xr dpb 1 , 780suitable for 781.Ev BULK_TARGETS . 782.It Cm subupdate 783Update an existing installation to a newer package, exactly 784like 785.Cm update , 786but affects only one single subpackage in multi-packages ports. 787.It Cm test 788Run regression tests for the port. 789Essentially depend on a correct build and invoke 790.Bd -literal 791env -i ${ALL_TEST_ENV} ${MAKE_PROGRAM} ${ALL_TEST_FLAGS} \e 792 -f ${MAKE_FILE} ${TEST_TARGET} ${TEST_LOG} 793.Ed 794.Pp 795If a port needs some other ports installed to run regression tests, 796use 797.Ev TEST_DEPENDS . 798If a port needs special configuration or build options to enable regression 799testing, define a 800.Sq test 801.Ev FLAVOR . 802.It Cm test-depends 803Before running regression tests, Install and verify dependencies 804constructed from 805.Ev TEST_DEPENDS . 806.It Cm unlock 807Manually release a lock on a given directory. 808See 809.Cm lock . 810.It Cm update-patches 811Create or update patches for a port, using 812.Xr update-patches 1 . 813See 814.Ev EDIT_PATCHES . 815.It Cm update 816Update an existing installation to a newer package: 817scan the installation for a package with the same 818.Ev FULLPKGPATH , 819and update it using 820.Sq pkg_add -r 821if a newer package is available. 822In multi-packages ports, all relevant packages are updated. 823See 824.Ev UPDATE_COOKIES_DIR 825and 826.Ev FORCE_UPDATE 827as well. 828.Pp 829However, see 830.Sx CAVEATS 831in 832.Xr ports 7 : 833.Cm update 834is always 835.Sq best-effort 836and will often not work correctly when 837updating to a significantly different newer version. 838.It Cm update-or-install 839Update an installed package or perform a fresh installation, 840by using 841.Sq pkg_add -r . 842Handles one single package in multi-packages ports. 843See 844.Ev UPDATE_COOKIES_DIR 845and 846.Ev FORCE_UPDATE 847as well. 848.It Cm update-or-install-all 849Update installed packages or perform a fresh installation, 850by using 851.Sq pkg_add -r . 852Handles all packages in multi-packages ports. 853See 854.Ev UPDATE_COOKIES_DIR 855and 856.Ev FORCE_UPDATE 857as well. 858.It Cm update-plist 859Update the packing-lists for a port, using the fake installation and the 860existing packing lists, by invoking 861.Xr update-plist 1 862with the correct parameters, along with 863port-specific options 864.Po 865.Ev UPDATE_PLIST_ARGS 866.Pc 867and user settings 868.Po 869.Ev UPDATE_PLIST_OPTS 870.Pc . 871Also see 872.Ev SUBST_VARS 873for details about the default handling of variable substitution. 874.It Cm verbose-show 875Similar to 876.Cm show , 877except that it prefixes each value with the variable name, e.g., 878.Li VAR=value . 879Also note that it does not show undefined variables, contrary to 880.Cm show 881which outputs blank lines for these. 882.It Cm wantlib-args 883Call 884.Cm port-wantlib-args 885and 886.Cm fake-wantlib-args 887and compare the results, errors out in case of discrepancies. 888See 889.Cm print-package-args . 890.El 891.Sh VARIABLES 892Note that some variables are marked as 893.Sq User settings , 894which means that individual ports should not modify them, 895and that some variables are marked as 896.Sq read-only , 897which means that they shouldn't ever be changed. 898In a 899.Ev MULTI_PACKAGES 900setup, some variables have settings specific to a given subpackage. 901See 902.Sx FLAVORS AND MULTI_PACKAGES . 903.Bl -tag -width Ds 904.It Ev show 905Invoked as make show=name, show the contents of ${name}. 906Invoked as make show="name1 name2 ...", show the contents of 907${name1} ${name2} ..., 908one variable value per line. 909.It Ev ALL_FAKE_FLAGS 910Flags passed to ${MAKE} invocations during the fake process. 911Equals 912.Li ${MAKE_FLAGS} ${DESTDIRNAME}=${WRKINST} ${FAKE_FLAGS} . 913Read-only. 914.It Ev ALL_TEST_ENV 915Environment passed to test. 916Equals 917.Li ${MAKE_ENV} ${TEST_ENV} . 918Read-only. 919.It Ev ALL_TEST_FLAGS 920Flags passed to ${MAKE} invocations during test. 921Equals 922.Li ${MAKE_FLAGS} ${TEST_FLAGS} . 923Read-only. 924.It Ev ALL_TARGET 925Target used to build software. 926Default is 927.Sq all . 928Can be set to empty, to yield a package's default target. 929.It Ev APM_ARCHS 930Set to the list of 931.Xr apm 4 932architectures. 933Read-only. 934Use with 935.Ev ONLY_FOR_ARCHS . 936.It Ev ARCH 937Current machine architecture. 938Read-only. 939.It Ev AUTOCONF 940Location of the autoconf binary if needed. 941Defaults to autoconf. 942.It Ev AUTOCONF_DIR 943Where to invoke autoconf or autoreconf if ${CONFIGURE_STYLE} includes 944.Sq autoconf 945or 946.Sq autoreconf , 947respectively. 948Defaults to ${WRKSRC}. 949.\" AUTOCONF_DIR should probably be a list, and be renamed to AUTOCONF_DIRS ? 950.It Ev AUTOCONF_ENV 951Environment values that should be passed to all runs of autoconf, automake 952and related tools. 953Specifically, version numbers and PATH. 954Automatically set as soon as 955.Ev CONFIGURE_STYLE 956is gnu or higher. 957.It Ev AUTOCONF_VERSION 958Starting with 959.Ox 3.3 , 960several versions of autoconf may coexist peacefully. 961The main autoconf script is a shell wrapper in the 962.Pa devel/metaauto 963package, and similarly for automake. 964Setting 965.Ev AUTOCONF_VERSION 966along with 967.Ev CONFIGURE_STYLE 968set to autoconf is the correct way to specify which one to use. 969.Ev AUTOCONF_VERSION 970defaults to 2.13. 971If autoconf must be run manually, 972.Ev MODGNU_AUTOCONF_DEPENDS 973can be used to specify what packages to depend upon. 974.It Ev AUTOHEADER 975Location of the autoheader binary. 976Defaults to autoheader. 977.It Ev AUTOMAKE_VERSION 978Several versions of automake may coexist peacefully. 979.Ev AUTOMAKE_VERSION 980must be set before trying to run automake. 981Defaults to 1.4. 982.It Ev AUTORECONF 983Location of the autoreconf binary and the arguments it is invoked with. 984Can be set to 985.Sq autogen.sh 986if such a script is available. 987Defaults to autoreconf --force --install. 988.It Ev BASE_PKGPATH 989Full 990.Xr pkgpath 7 991to the current port, taking flavors into account. 992See also 993.Ev BUILD_PKGPATH , 994which also includes pseudo-flavors. 995Read-only. 996.It Ev BASELOCALSTATEDIR 997User settings. 998Base location for system-wide state directory. 999Defaults to 1000.Pa ${VARBASE} . 1001See 1002.Ev LOCALSTATEDIR . 1003.It Ev BASESYSCONFDIR 1004User settings. 1005Base location for system-wide configuration files. 1006Defaults to 1007.Pa /etc . 1008See 1009.Ev SYSCONFDIR . 1010.It Ev BATCH 1011User settings. 1012Set to 1013.Sq Yes 1014to avoid ports that require user-interaction. 1015Use in conjunction with 1016.Ev INTERACTIVE 1017to simplify bulk-package builds. 1018.Pq See IGNORE . 1019.It Ev BE_ARCHS 1020Set to the list of big-endian architectures. 1021Read-only. 1022Use with 1023.Ev NOT_FOR_ARCHS 1024and 1025.Ev ONLY_FOR_ARCHS . 1026.It Ev BUILD_DEPENDS 1027List of other ports the current port needs to build correctly. 1028Each item has the form 1029.Sq [pkgspec:]pkgpath[:target] . 1030.Sq target 1031defaults to 1032.Sq install . 1033The package installed must conform to the 1034.Sq pkgspec , 1035which is by default obtained from the dependent 1036.Sq pkgpath 1037.Po 1038see 1039.Ev PKGSPEC 1040.Pc . 1041If no installation is involved, the infrastructure will still check 1042that the directory would provide a package conforming to the 1043.Sq pkgspec . 1044.Sq pkgpath 1045is set relative to ${PORTSDIR}, 1046see 1047.Xr pkgpath 7 1048for details. 1049Build dependencies are checked before the 1050.Cm extract 1051stage during 1052.Cm prepare . 1053.Pp 1054Build dependencies with a 1055.Cm patch , 1056.Cm configure 1057or 1058.Cm build 1059target will be processed in a subdirectory of the working directory, 1060specifically, in ${WRKDIR}/some/directory, 1061with 1062.Pa some/directory 1063the directory part of the 1064.Sq pkgpath . 1065.It Ev BUILD_ONCE 1066User settings. 1067Defaults to 1068.Sq \&No . 1069Set to 1070.Sq Yes 1071during bulk builds. 1072.Pp 1073When 1074.Ev BUILD_ONCE 1075is set to 1076.Sq Yes , 1077all 1078.Ev PSEUDO_FLAVORS 1079matching 1080.Sq no_* 1081will be disabled, unless the special pseudo-flavor 1082.Sq bootstrap 1083is also set. 1084.Pp 1085This is a bulk build optimisation, automatically set by 1086.Xr dpb 1 : 1087to avoid rebuilding the same package several times, a full bulk build will 1088strip most ports of pseudo-packages variations that remove subpackages. 1089.Pp 1090For instance, an individual package may depend on 1091.Pa databases/db/v4,no_java,no_tcl , 1092to avoid bringing a jdk in during a quick build. 1093Nevertheless, during a full bulk build, 1094.Pa databases/db/v4 1095will only be built once, as the pseudo-flavor will be automatically removed. 1096.Pp 1097However, the extra 1098.Sq bootstrap 1099rule is needed to take build cycles into account. 1100For instance, the 1101.Pa x11/gnome/gvfs,-goa 1102subpackage depends on gnome-online-accounts, which in turn requires 1103.Pa x11/gnome/gvfs,-main 1104to build (through its dependencies). 1105So 1106.Pa x11/gnome/gvfs 1107has 1108.Li PSEUDO_FLAVORS = no_smb no_goa bootstrap 1109and the GNOME build first builds 1110.Pa x11/gnome/gvfs,no_smb,no_goa,bootstrap,-main 1111which is later used to rebuild 1112.Pa x11/gnome/gvfs . 1113.It Ev BUILD_PKGPATH 1114Full 1115.Xr pkgpath 7 1116to the current port, taking flavors and pseudo-flavors 1117into account. 1118See also 1119.Ev BASE_PKGPATH , 1120which doesn't include pseudo-flavors. 1121Mostly useful to write dependencies for subpackages like this: 1122.Li "LIB_DEPENDS-foo=${BUILD_PKGPATH}" 1123and avoid starting to build a package with some other flavor combination. 1124See 1125.Xr pkgpath 7 1126on the subject of 1127.Sq pkgpath normalisation . 1128Read-only. 1129.It Ev BUILD_PACKAGES 1130The actual list of packages that will be built, once architecture problems 1131and pseudo-flavors have been taken into account. 1132See 1133.Sx FLAVORS AND MULTI_PACKAGES . 1134.It Ev BROKEN 1135Define only for broken ports, set to reason the port is broken. 1136See also 1137.Ev NO_IGNORE , 1138.Ev TRY_BROKEN . 1139.It Ev BUILD_USER 1140User to switch to when using 1141.Ev PORTS_PRIVSEP , 1142defaults to 1143.Sq _pbuild . 1144.It Ev BROKEN-<arch> 1145Define only for ports broken on a given architecture. 1146Distinct from 1147.Ev ONLY_FOR_ARCHS 1148and 1149.Ev NOT_FOR_ARCHS , 1150which are used to mark ports for which support for some architectures 1151does not exist at all, or is completely obsolete. 1152.It Ev BSD_INSTALL_{PROGRAM,SCRIPT,DATA,MAN}[_DIR] 1153Macros passed to make and configure invocations. 1154Set based on corresponding INSTALL_* variables. 1155.It Ev BULK 1156User settings. 1157If set to 1158.Sq Yes , 1159all successful package builds and installations will clean 1160their working directories, after invoking 1161any targets mentioned in BULK_TARGETS, 1162and commands mentioned in BULK_DO. 1163Can be set on a per-${PKGPATH} basis. 1164For instance, setting BULK_misc/screen=No 1165will override any BULK=Yes passed on the command line. 1166If set to 1167.Sq Auto , 1168it will apply to dependencies, but not to the current port itself. 1169See 1170.Ev BULK_COOKIES_DIR . 1171Defaults to 1172.Sq Auto . 1173.It Ev BULK_COOKIES_DIR 1174User settings. 1175Used to store cookies for successful bulk-package builds, defaults to 1176.Pa ${PORTSDIR}/bulk/${MACHINE_ARCH} . 1177.It Ev BULK_DO 1178Commands to run after each bulk package build before cleaning up the 1179working directory. 1180Empty defaults. 1181Can be set on a per-${PKGPATH} basis, e.g., 1182BULK_DO_${PKGPATH}=... 1183.It Ev BULK_FLAGS 1184Flags to pass to build each target in 1185.Ev BULK_TARGETS . 1186.It Ev BULK_TARGETS 1187Targets to run after each bulk package build before cleaning up the 1188working directory. 1189Empty defaults. 1190Can be set on a per-${PKGPATH} basis, e.g., 1191BULK_TARGETS_${PKGPATH}=... 1192.It Ev BZIP2 1193Name of the bzip2 binary. 1194.It Ev CATEGORIES 1195List of descriptive categories into which this port falls. 1196Mandatory. 1197One entry must match the current pkgpath: 1198.Pa devel/gmake 1199must belong to the 1200.Sq devel 1201category. 1202See 1203.Cm link-categories , 1204.Cm unlink-categories . 1205.It Ev CCACHE_DIR 1206Sets the cache directory used when 1207.Ev USE_CCACHE 1208is set to yes. 1209Defaults to ${WRKOBJDIR}/.ccache. 1210.It Ev CCACHE_ENV 1211Sets additional environment variables when 1212.Ev USE_CCACHE 1213is set to yes. 1214For instance, to enable verbose logging, set 1215CCACHE_ENV="CCACHE_LOGFILE=/tmp/ccache.log" 1216.It Ev CDIAGFLAGS 1217Flags appended to 1218.Ev CFLAGS 1219if 1220.Ev WARNINGS 1221is set. 1222.It Ev CFLAGS 1223Default flags passed to the compiler for building. 1224Many ports ignore it. 1225See also 1226.Ev COPTS , 1227.Ev CDIAGFLAGS . 1228.It Ev CHECK_LIB_DEPENDS 1229User settings. 1230If set to 1231.Sq Yes , 1232every package build will verify that shared libraries are correctly 1233registered. 1234This is essentially the same as running 1235.Ql make lib-depends-check 1236after each package build. 1237Defaults to 1238.Sq \&No , 1239as this can be a big performance hit. 1240.It Ev CHECKSUMFILES 1241List of all files that need to be retrieved by 1242.Cm fetch , 1243with 1244.Ev DIST_SUBDIR 1245prepended and with the master site selection extension removed. 1246Read-only. 1247See also 1248.Ev MAKESUMFILES . 1249.It Ev CHECKSUM_FILE 1250Location for this port's checksums, used by 1251.Cm checksum , 1252and 1253.Cm makesum . 1254Defaults to 1255.Pa distinfo . 1256.It Ev CHECKSUM_PACKAGES 1257User settings. 1258Choose whether or not to checksum packages while building. 1259Deposits result in 1260.Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cksums/${FULLPKGNAME}.sha256 . 1261Can be set to 1262.Sq Yes 1263to compute a checksum for all packages, 1264or to 1265.Sq ftp 1266to compute it only for 1267.Ev PERMIT_PACKAGE 1268packages. 1269Defaults to 1270.Sq no , 1271which does not compute a checksum at all. 1272.It Ev CHOSEN_COMPILER 1273Read-only. 1274Compiler suite chosen by the 1275.Ev COMPILER 1276mechanism. 1277Set to 1278.Sq irrelevant 1279to disable 1280.Ev COMPILER . 1281.It Ev CLEANDEPENDS 1282If set to 1283.Sq Yes , 1284the 1285.Cm clean 1286target will also clean dependencies. 1287Can be overridden on a per-${PKGPATH} basis, 1288by setting CLEANDEPENDS_${PKGPATH}. 1289.It Ev COMMENT 1290Short (no more than 60 characters) description of the port, used for 1291the package and the INDEX. 1292It should not start with an uppercase letter unless semantically 1293significant. 1294.It Ev COMMENT-foo 1295Same as COMMENT but used for sub package -foo in a multi-package setup. 1296.It Ev COMMENT-vanilla 1297Same as COMMENT but used for a flavored package, if the non-flavored comment 1298is inappropriate. 1299.It Ev COMMENT-foo-vanilla 1300Same as COMMENT but used for a sub-, flavored package. 1301.It Ev COMES_WITH 1302The first release where the port was made part of the standard 1303distribution. 1304If the current 1305.Ox 1306version is >= this version then a notice 1307will be displayed instead of the port being built. 1308.It Ev COMPILER 1309Select preferred compiler. 1310First element in the list that matches will be chosen. 1311.Bl -tag -width ports-gccxx 1312.It base-gcc 1313gcc 4.2 compiler from base 1314.It base-clang 1315clang compiler from base 1316.It gcc3 1317gcc 3 compiler from base 1318.It ports-gcc 1319gcc 8 compiler from ports 1320(heeds 1321.Ev MODGCC4_ARCHS 1322from the module) 1323.It ports-clang 1324clang compiler from ports 1325(heeds 1326.Ev MODCLANG_ARCHS 1327from the module) 1328.El 1329.Pp 1330The first compiler that matches criteria will be chosen. 1331On clang-based architectures, even though gcc is still compiled in base, 1332.Sq base-gcc 1333never matches. 1334.Pp 1335Defaults to base compilers, e.g., 1336.Sq base-clang base-gcc gcc3 . 1337.Pp 1338Common reasons for explicitly setting 1339.Ev COMPILER 1340will most often be C++11 support, thread-local-storage support (emulated), 1341atomic operations on some arches, sometimes assembler support, ABI 1342compatibility with dependent/depending ports, or plain old internal compiler 1343errors. 1344.Pp 1345With 1346.Ev COMPILER 1347in effect, 1348.Ev MODGCC4_ARCHS 1349and 1350.Ev MODCLANG_ARCHS 1351default to 1352.Sq ${GCC49_ARCHS} 1353and 1354.Sq ${LLVM_ARCHS} 1355respectively. 1356.Pp 1357.Ev ONLY_FOR_ARCHS 1358will also be set if applicable. 1359.It Ev COMPILER_LANGS 1360The value of 1361.Ev COMPILER_LANGS 1362will be added to the respective module's supported langs. 1363Defaults to 1364.Sq c c++ . 1365Only 1366.Sq c 1367and 1368.Sq c++ 1369are supported by this mechanism. 1370.Sq fortran 1371or 1372.Sq java 1373still need old modules annotations, so that it's possible 1374to select, e.g., 1375.Sq gfortran 1376from gcc 8 while having clang from base. 1377See also 1378.Ev CHOSEN_COMPILER . 1379.It Ev COMPILER_LINKS 1380Used by 1381.Nm 1382and compiler 1383.Ev MODULES 1384to build scripts in 1385.Pa ${WRKDIR}/bin 1386to force setting compiler flags 1387.Po 1388.Fl B 1389is required for clang to find 1390.Pa ${WRKDIR}/bin/ld 1391as used by 1392.Ev USE_WXNEEDED 1393.Pc 1394and call 1395.Ev COMPILER_WRAPPER 1396if used. 1397.It Ev COMPILER_WRAPPER 1398External program used to "wrap" compilers. 1399Populated automatically by 1400.Ev USE_CCACHE 1401or can be set explicitly for other purposes (e.g. distcc). 1402.It Ev CONFIG_SITE_LIST 1403Used when 1404.Li CONFIGURE_STYLE=gnu , 1405or with 1406.Li MODULES += gnu . 1407List of 1408.Pa config.site 1409fragments that will speed up gnu-configure, and prevent it from 1410preferring various gnu programs, unless 1411.Ev BUILD_DEPENDS 1412explicitly ask for them. 1413Read-only, available for debugging purposes. 1414.It Ev CLANG_ARCHS, GCC3_ARCHS , GCC4_ARCHS 1415List of architectures using Clang, GCC 3.3.6 or GCC 4.2.1 as the base compiler. 1416Read-only. 1417Use with 1418.Ev NOT_FOR_ARCHS 1419or 1420.Ev ONLY_FOR_ARCHS 1421to limit ports to architectures where they compile. 1422.It Ev CONFIGURE_ARGS 1423Arguments to pass to configure script. 1424Defaults are empty, except for 1425GNU-style configure, where prefix and sysconfdir are set. 1426.It Ev CONFIGURE_ENV 1427Basic environment passed to configure script (path and libtool setup). 1428GNU-style configure adds a lot more variables. 1429.It Ev CONFIGURE_SCRIPT 1430Set to name of script invoked by the 1431.Cm configure 1432target, if appropriate. 1433Should be either an absolute path, or relative to ${WRKSRC}. 1434.It Ev CONFIGURE_STYLE 1435Set to style of configuration that needs to happen. 1436.Pp 1437If 1438.Sq perl , 1439assume 1440.Xr perl 1 Ns 's 1441.Xr ExtUtils::MakeMaker 3p 1442style. 1443Add 1444.Sq modbuild 1445to enable 1446.Xr Module::Build 3p , 1447.Sq modbuild tiny 1448to enable 1449.Xr Module::Build::Tiny 3p , 1450or 1451.Sq modinst 1452for 1453.Xr Module::Install 3p 1454style. 1455.Pp 1456If 1457.Sq gnu , 1458assume 1459GNU configure style. 1460Add 1461.Sq dest 1462if port does not handle DESTDIR correctly, and needs to be configured to 1463add DESTDIR to prefixes 1464.Po 1465see also 1466.Ev DESTDIRNAME 1467.Pc . 1468Add 1469.Sq old 1470if port is an older autoconf port that does not recognize --sysconfdir. 1471Add 1472.Sq autoconf 1473if autoconf needs to be rerun first, 1474but set 1475.Sq no-autoheader 1476to prevent autoheader from running. 1477Alternatively, add 1478.Sq autoreconf 1479to rerun autoconf, automake, and related tools to completely regenerate 1480the GNU build framework. 1481.Pp 1482If 1483.Sq imake , 1484assume port configures using X11 ports Imakefile framework. 1485Add 1486.Sq noman 1487if port has no man pages the Imakefile should try installing. 1488.Pp 1489If 1490.Sq simple , 1491there is a configure script, but it does not fit the normal GNU configure 1492conventions. 1493.Pp 1494Extensions may be defined by specific MODULES. 1495See 1496.Xr port-modules 5 1497for details. 1498.It Ev COPTS 1499User settings. 1500Supplementary options appended to ${CFLAGS} for building. 1501Since most ports ignore the COPTS convention, they are actually told to use 1502${CFLAGS} ${COPTS} as CFLAGS. 1503.It Ev CXXDIAGFLAGS 1504Flags appended to 1505.Ev CXXFLAGS 1506if 1507.Ev WARNINGS 1508is set. 1509.It Ev CXXFLAGS 1510Default flags passed to the C++ compiler for building. 1511Many ports ignore it. 1512.It Ev CXXOPTS 1513User settings. 1514Supplementary options appended to ${CXXFLAGS} for building. 1515.It Ev DEBUG_CONFIGURE_ARGS 1516Supplementary ${CONFIGURE_ARGS} 1517for enabling the generation of debugging information. 1518.It Ev DEBUG_PACKAGES 1519List of ${SUBPACKAGES} for which debug packages should be built "on the side". 1520Usually set as 1521.Li DEBUG_PACKAGES=${BUILD_PACKAGES} 1522for packages where debug information is desirable. 1523Note the subpackages with 1524.Li PKG_ARCH=* 1525will automatically be stripped from that list. 1526See 1527.Sx THE DEBUG_PACKAGES INFRASTRUCTURE 1528below for details. 1529.It Ev DEBUGINFO_ARCHS 1530List of archs for which debug information may be provided as extra packages. 1531Normally only amd64 for performance reasons. 1532.It Ev DESTDIR 1533See 1534.Ev DESTDIRNAME . 1535.It Ev DESTDIRNAME 1536Name of variable to set to ${WRKINST} while faking. 1537Usually DESTDIR. 1538To be used in the rare cases where a port heeds DESTDIR in a few 1539directories and needs to be configured with 1540.Sq gnu dest , 1541so that those few directories do not get in the way. 1542.It Ev DISTDIR 1543User settings. 1544Directory where all ports distribution files and patchfiles are stashed. 1545Defaults to 1546.Pa ${PORTSDIR}/distfiles . 1547Override if distribution files are stored elsewhere. 1548Always use 1549.Ev FULLDISTDIR 1550to refer to ports' distribution files location, as it takes an eventual 1551.Ev DIST_SUBDIR 1552into account. 1553.It Ev DISTFILES 1554The main port's distribution files (the actual software source, except 1555for binary-only ports). 1556Will be retrieved from the MASTER_SITES (see 1557.Cm fetch ) , 1558checksummed and extracted (see 1559.Cm checksum , 1560.Cm extract ) . 1561.Ev DISTFILES 1562normally holds a list of files, possibly with 1563.Sq :0 1564to 1565.Sq :9 1566appended to select a different 1567.Ev MASTER_SITES . 1568.Pp 1569Each entry may optionally be of the form 1570.Sq Ar filename Ns { Ns Ar url Ns } Ns Ar sufx 1571to deal with sites that only offer archives as weird urls, doing the transfer 1572of 1573.Ar url Ns Ar sufx 1574into result file 1575.Ar filename Ns Ar sufx . 1576For instance, if 1577.Bd -literal 1578DISTFILES = minetest-{minetest/archive/}${V}${EXTRACT_SUFX} 1579.Ed 1580.Pp 1581then 1582.Cm fetch 1583will retrieve from url 1584.Sq minetest/archive/${V}${EXTRACT_SUFX} 1585into 1586.Sq minetest-${V}${EXTRACT_SUFX} . 1587.Pp 1588If ${DISTFILES} varies depending on 1589.Ev FLAVORS 1590or architecture, use 1591.Ev SUPDISTFILES 1592to ensure distfiles mirroring and 1593.Cm makesum 1594proper operation. 1595.It Ev DISTNAME 1596Name used to identify the port. 1597See 1598.Ev DISTFILES 1599and 1600.Ev PKGNAME . 1601.It Ev DISTORIG 1602Suffix used by 1603.Cm distpatch 1604to rename original files. 1605Defaults to 1606.Pa .bak.orig . 1607Distinct from 1608.Pa .orig 1609to avoid confusing 1610.Cm update-patches . 1611.It Ev DIST_SUBDIR 1612Optional subdirectory of ${DISTDIR} where the current port's distribution 1613files and patchfiles will be located. 1614See target 1615.Cm fetch . 1616.It Ev DPB 1617Set by the Distributed Ports Builder to only get the information it needs 1618from 1619.Cm dump-vars . 1620.It Ev DPB_LOCKNAME 1621If set, 1622.Xr dpb 1 1623will use this instead of the default 1624.Ev PKGPATH Ns - Ns 1625derived name. 1626This feature comes with large restrictions and shouldn't be used unless 1627absolutely necessary. 1628Specifically, it can allow 1629.Nm dpb 1630to build several flavors of the same port at the same time, 1631but beware: under 1632.Ev MULTI_PACKAGES 1633and 1634.Ev PSEUDO_FLAVORS 1635conditions, if some of these packages are identical across flavors, 1636this will not work. 1637This also makes it harder to interact with locks if the names are not obvious. 1638.It Ev DPB_PROPERTIES 1639Annotations for the Distributed Ports Builder. 1640See 1641.Xr dpb 1 1642for semantics. 1643.It Ev DUMMY_PACKAGE 1644If defined, 1645.Nm 1646will provide dummy values for variables mandatory for a minimally functional 1647port. 1648Used by various pieces of the ports tree to perform introspection and get to 1649.Nm Ns 's 1650variables. 1651.It Ev ECHO_MSG 1652User settings. 1653Used to display 1654.Sq ===> Configuring for foo 1655and similar informative messages. 1656Override to turn off, for instance. 1657.It Ev ECHO_REORDER 1658User settings. 1659Set it to 1660.Sq echo 1661to see 1662.Ev REORDER_DEPENDENCIES 1663actions. 1664Silent by default. 1665.It Ev EDIT_PATCHES 1666User settings. 1667If set to 1668.Sq \&No , 1669.Cm update-patches 1670will not open changed files in an editor. 1671.It Ev EPOCH 1672Epoch number of the current package. 1673Used when the port version is changed but the new version is not regarded by 1674.Xr packages-specs 7 1675as being newer. 1676Once added, it cannot be removed or go backwards. 1677Defaults to empty (no need for numbering changes), then 1678numbering starts at 0. 1679Gets automatically incorporated into 1680.Ev FULLPKGNAME 1681as 1682.Sq v${EPOCH} 1683to form a full package-name conforming to 1684.Xr packages-specs 7 . 1685.It Ev ERRORS 1686List of errors found while parsing the port's Makefile. 1687Display the errors before making any target, and if any error starts with 1688.Qq Fatal : , 1689do not make anything. 1690For instance: 1691.Bd -literal -offset indent 1692\&.if !defined(COMMENT) 1693ERRORS+="Fatal: Missing comment" 1694\&.endif 1695.Ed 1696Porter can add to 1697.Ev ERRORS , 1698for instance to flag erroneous combinations of 1699.Ev FLAVORS 1700(but see 1701.Ev ONLY_FOR_ARCHS 1702.Ev NOT_FOR_ARCHS 1703and 1704.Ev BROKEN 1705for other common issues). 1706.It Ev EXTRACT_CASES 1707In the normal extraction stage (when 1708.Ev EXTRACT_ONLY 1709is not empty), this is the contents of a 1710.Xr sh 1 1711.Em case conditional , 1712used to extract files. 1713Fragments are automatically appended to extract the following archives and 1714add the relevant compression tool to 1715.Ev BUILD_DEPENDS : 1716.Pp 1717.Bl -tag -width archivers/lzip/lunzip -offset indent -compact 1718.It gzip 1719tar.gz, tgz 1720.It tar 1721tar 1722.It archivers/bzip2 1723tar.bz2, tbz2, tbz 1724.It archivers/xz 1725tar.xz, tar.lzma, tar.lz 1726.It archivers/unzip 1727zip 1728.It archivers/zstd 1729tar.zst, tar.zstd 1730.It converters/rpm2cpio 1731rpm 1732.El 1733.Pp 1734Other cases not supported directly in 1735.Nm 1736can be added, and existing cases can be overridden. 1737For example the following example sets extra conversion flags to unzip, 1738and adds support for rar: 1739.Bd -literal 1740 *.zip) ${UNZIP} -Laq ${FULLDISTDIR}/$$archive -d ${WRKDIR};; \\ 1741 *.rar) ${LOCALBASE}/bin/unrar x -idq ${DISTDIR}/$$archive;; 1742.Ed 1743.It Ev EXTRACT_ONLY 1744Set to the list of distfiles to actually extract if some distfiles 1745should not be extracted during the 1746.Cm do-extract 1747stage. 1748Defaults to all distfiles, can even be set to empty. 1749.It Ev EXTRACT_SUFX 1750Used to set DISTFILES default value to ${DISTNAME}${EXTRACT_SUFX}. 1751The decompression tool needed will be automatically added as 1752.Ev BUILD_DEPENDS . 1753Default value is .tar.gz. 1754.It Ev EXTRACT_FILES 1755Set to the list of files to actually extract from distfiles. 1756Its content is subject to shell evaluation as part of 1757.Ev EXTRACT_CASES 1758and passed as 1759.Ar file ... 1760argument to 1761.Xr tar 1 1762or 1763.Xr unzip 1 , 1764e.g., 1765.Xr glob 7 1766patterns and shell brace expansion may be used. 1767Empty by default to extract all files. 1768.It Ev FAKE_FLAGS 1769Extra flags passed to ${MAKE_PROGRAM} during the 1770fake invocation. 1771Empty by default. 1772Also see 1773.Ev ALL_FAKE_FLAGS . 1774.It Ev FAKE_SETUP 1775List of environment values normally set during fake invocations. 1776Exposed so that modules may provide their own 1777.Cm do-install . 1778Read-only, 1779see 1780.Sx THE FAKE FRAMEWORK 1781section for details. 1782.It Ev FAKE_TARGET 1783Target built by ${MAKE_PROGRAM} on fake invocation. 1784Defaults to ${INSTALL_TARGET}. 1785.It Ev FAKEOBJDIR 1786User settings. 1787If non empty, used as a base for the fake area. 1788The real fake directory ${WRKINST} is created there. 1789Can be set on a per-${PKGPATH} basis. 1790For instance, setting FAKEOBJDIR_www/mozilla-firefox=/tmp/obj 1791will affect only the mozilla-firefox port. 1792.It Ev FETCH_CMD 1793User settings. 1794Command used to fetch distribution files for this port. 1795Defaults to 1796.Xr ftp 1 . 1797Can be used to go through excessively paranoid firewalls. 1798Note that 1799.Ev FETCH_CMD 1800should support a few ftp options, chief among them 1801being 1802.Fl C 1803and 1804.Fl o Ar dest , 1805but also 1806.Fl m , 1807.Fl S , 1808.Fl v , 1809.Fl V . 1810Most of these can be no-ops in a FETCH_CMD script, 1811See 1812.Pa ${PORTSDIR}/infrastructure/template/fetch_cmd.template 1813for a skeleton script. 1814.It Ev FETCH_MANUALLY 1815Some ports' distfiles cannot be fetched automatically for licensing reasons. 1816In this case, set 1817.Ev FETCH_MANUALLY 1818to a list of strings that will be displayed, one per line, e.g., 1819.Bd -literal 1820FETCH_MANUALLY= "You must fetch foo-1.0.tgz" 1821FETCH_MANUALLY+="from http://www.fubar.com/ manually," 1822FETCH_MANUALLY+="after reading and agreeing to the license." 1823.Ed 1824Behaves like 1825.Ev IS_INTERACTIVE 1826if some distribution files are missing. 1827.It Ev FETCH_PACKAGES 1828User settings, defaults to 1829.Sq \&No . 1830Set to 1831.Xr pkg_add 1 1832options. 1833Instruct the 1834.Cm package 1835target to download packages missing from the repository from locations in 1836${PKG_PATH} and place them into 1837.Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cache/ , 1838only building them if no suitable packages are found. 1839For instance, 1840.Bd -literal -offset indent 1841make FETCH_PACKAGES= 1842.Ed 1843.Pp 1844to use without any options, or 1845.Bd -literal -offset indent 1846make FETCH_PACKAGES=-Dsnap 1847.Ed 1848.Pp 1849to use close to release. 1850.It Ev FILESDIR 1851Location of other files related to the current port. 1852Default: files. 1853.It Ev FETCH_USER 1854User to use to fetch distfiles when using 1855.Ev PORTS_PRIVSEP , 1856defaults to 1857.Sq _pfetch . 1858.It Ev FIX_CLEANUP_PERMISSIONS 1859If 1860.Sq Yes , 1861restore read, write and directory search permissions for the build user on 1862.Pa ${WRKDIR} 1863before running 1864.Cm clean . 1865Used for build systems which set paranoid permissions at build time. 1866Defaults to 1867.Sq \&No . 1868.It Ev FIX_CRLF_FILES 1869Name(s) of files with line endings to correct at the end of 1870.Cm distpatch . 1871Sometimes a port will include files with MS-DOS line endings (CR LF). 1872To avoid problems with patches (especially when sent by email) 1873these should be converted to LF. 1874.Nm 1875changes to WRKDIST before converting files - shell wildcards may be used. 1876.It Ev FIX_EXTRACT_PERMISSIONS 1877If 1878.Sq Yes , 1879restore contents of 1880.Pa ${WRKDIR} 1881to world-readable at the end of 1882.Cm extract . 1883Used for some distfile contents which have paranoid permissions for no reason. 1884Defaults to 1885.Sq \&No . 1886.It Ev FLAVOR 1887The port's current options. 1888Set by the user, and tested by the port to activate wanted functionalities. 1889.It Ev FLAVORS 1890List of all flavors keywords a port may match. 1891Used to sort 1892.Ev FLAVOR 1893into a canonical order to build the package name, 1894or to select the packing-list, and as a quick validity check. 1895See also 1896.Ev PSEUDO_FLAVORS . 1897.It Ev FLAVOR_EXT 1898Canonical list of flavors being set for the current build, dash-separated. 1899See 1900.Ev FULLPKGNAME . 1901.It Ev FORCE_UPDATE 1902User settings. 1903If set to 1904.Sq Yes , 1905the 1906.Cm update 1907target will always update an installed package, 1908as soon as its signature differs, 1909and all dependencies that install packages will 1910also force an update. 1911If set to 1912.Sq hard , 1913the 1914.Cm update 1915target will also update installed packages even when the signature 1916did not change. 1917.It Ev FULLDISTDIR 1918Complete path to directory where ${DISTFILES} and ${PATCHFILES} will be 1919located, to be used in hand-crafted extraction targets. 1920Read-only. 1921.It Ev FULLPKGNAME 1922Full name of the created package, taking flavors into account. 1923Defaults to ${PKGNAME}${FLAVOR_EXT}. 1924See also 1925.Ev EPOCH 1926and 1927.Ev REVISION . 1928.It Ev FULLPKGPATH 1929Path to the current port's directory, relative to ${PORTSDIR}, 1930including flavors and subpackages. 1931See 1932.Xr pkgpath 7 . 1933.It Ev GH_* 1934Support for GitHub-hosted projects. 1935Leave empty for non hosted projects. 1936Yields a suitable default for 1937.Ev MASTER_SITES_GITHUB 1938and 1939.Ev DISTNAME . 1940.It Ev GH_ACCOUNT 1941Account name of the GitHub user hosting the project. 1942.It Ev GH_COMMIT 1943SHA1 commit id to fetch. 1944It is an error to specify ${GH_COMMIT} when ${GH_TAGNAME} is specified. 1945.It Ev GH_DISTFILE 1946Set by 1947.Nm 1948to the generated name of the distribution file. 1949This can be useful for ports listing multiple 1950.Ev DISTFILES . 1951.It Ev GH_PROJECT 1952Name of the project on GitHub. 1953.It Ev GH_TAGNAME 1954Name of the tag to download. 1955Setting ${GH_TAGNAME} to master is invalid 1956and will throw an error. 1957${WRKDIST} is auto-generated based on the 1958${GH_TAGNAME} if specified, otherwise ${GH_COMMIT} will be used to generate 1959${WRKDIST}. 1960.It Ev GMAKE 1961Location of the GNU make binary, if needed. 1962Defaults to gmake. 1963.It Ev HOMEPAGE 1964URL to the homepage of the software, if applicable. 1965.It Ev IGNORE 1966For ignored ports, set to the reasons for which the port is ignored. 1967If non-empty, most common targets that do something (e.g., 1968.Cm fetch , 1969.Cm build , 1970.Cm install No ... ) 1971will be ignored. 1972See also 1973.Ev BATCH , 1974.Ev BROKEN , 1975.Ev FETCH_MANUALLY , 1976.Ev IGNORE_IS_FATAL , 1977.Ev IGNORE_SILENT , 1978.Ev INTERACTIVE , 1979.Ev IS_INTERACTIVE , 1980.Ev NOT_FOR_ARCHS , 1981.Ev NO_IGNORE , 1982.Ev ONLY_FOR_ARCHS . 1983.It Ev IGNORE_IS_FATAL 1984User settings. 1985If set to 1986.Sq Yes , 1987ignored ports will become fatal errors. 1988.It Ev IGNORE_SILENT 1989User settings. 1990If set to 1991.Sq Yes , 1992do not print anything when ignoring a port. 1993.It Ev INSTALL_DEBUG_PACKAGES 1994User settings. 1995Defaults to 1996.Sq \&No . 1997If 1998.Sq Yes , 1999install available debug packages during all install/update targets. 2000.It Ev INSTALL_{PROGRAM,SCRIPT,DATA,MAN}[_DIR] 2001Macros to use to install a program, a script, data, or a man page (or the 2002corresponding directory), respectively. 2003.It Ev INSTALL_TARGET 2004Target invoked to install the software, during fake installation. 2005Default is 2006.Sq install . 2007.It Ev INTERACTIVE 2008User settings. 2009Set to 2010.Sq Yes 2011to skip all non-interactive ports. 2012Used in conjunction with 2013.Ev BATCH 2014to simplify bulk-package builds. 2015.It Ev IS_INTERACTIVE 2016Set to 2017.Sq Yes 2018if port needs human interaction to build. 2019Porters should strive to minimize 2020.Ev IS_INTERACTIVE 2021ports, by using 2022.Ev FLAVORS 2023for multiple choice ports, and by postponing human intervention 2024to package installation time. 2025.It Ev LE_ARCHS 2026Set to the list of little-endian architectures. 2027Read-only. 2028Use with 2029.Ev NOT_FOR_ARCHS 2030and 2031.Ev ONLY_FOR_ARCHS . 2032.It Ev LIB_DEPENDS 2033List of packages used by a port for its library dependencies. 2034Each item has the form 2035.Sq [pkgspec:]pkgpath . 2036Similar to 2037.Ev BUILD_DEPENDS 2038and 2039.Ev RUN_DEPENDS , 2040but with specific rules: 2041.Ev LIB_DEPENDS 2042always turn into 2043.Ev BUILD_DEPENDS 2044.Po 2045but see 2046.Sx FLAVORS AND MULTI PACKAGES 2047.Pc . 2048.Pp 2049.Ev LIB_DEPENDS 2050is also used as a run-time dependency, and recorded in the package as 2051such, if any of the libraries mentioned in 2052.Ev WANTLIB 2053is a shared library that originates within the dependent port. 2054.Pp 2055See 2056.Xr library-specs 7 2057for more details. 2058.It Ev lib_depends_args 2059Controls the behavior of 2060.Xr pkg_create 1 2061related targets, see 2062.Cm print-package-args 2063for details. 2064.It Ev LIBCXX 2065List of standard C++ libraries for the base compiler. 2066Read-only. 2067Use in 2068.Ev WANTLIB . 2069.It Ev LIBTOOL 2070Location of the libtool binary. 2071Default: 2072.Pa /usr/bin/libtool . 2073.It Ev LIBTOOL_FLAGS 2074Arguments to pass to libtool. 2075If USE_LIBTOOL is set, the environment variable LIBTOOL is set 2076to ${LIBTOOL} ${LIBTOOL_FLAGS}. 2077.It Ev LLD_EMUL 2078As 2079.Xr ld.lld 1 2080does not have a default emulation mode, 2081if it is the linker in-use, 2082.Ev LLD_EMUL 2083defaults to the correct option to set the emulation mode; 2084Otherwise, it stays empty. 2085Read-only. 2086Seldom used, as it is only needed to link binary data without using the 2087compiler. 2088.It Ev LLVM_ARCHS 2089Set to the list of architectures where LLVM/Clang could be used, 2090e.g., via lang/clang port module, see 2091.Xr port-modules 5 . 2092Read-only. 2093Use with 2094.Ev NOT_FOR_ARCHS 2095or 2096.Ev ONLY_FOR_ARCHS . 2097.It Ev LOCALBASE 2098where other ports have already been installed. 2099Default: 2100.Pa /usr/local . 2101.It Ev LOCALSTATEDIR 2102Location for this port's state directory, should always be derived 2103from 2104.Ev BASELOCALSTATEDIR , 2105which defaults to 2106.Pa /var . 2107Passed to gnu configure scripts. 2108.It Ev LOCKDIR 2109User settings. 2110Defaults to 2111.Pa ${WRKOBJDIR}/locks . 2112If set, points to a local directory common for all instances of 2113concurrent ports builds. 2114.It Ev LOCK_CMD 2115Expands to a command that will acquire a lock, namely 2116.Xr portlock 1 . 2117See also 2118.Xr ports 7 . 2119.It Ev LOCK_VERBOSE 2120User settings. 2121Defaults to 2122.Sq \&No . 2123Set to 2124.Sq Yes 2125to show every acquire/release lock operation. 2126.It Ev LP64_ARCHS 2127Set to the list of 64-bit architectures. 2128Read-only. 2129Use with 2130.Ev NOT_FOR_ARCHS . 2131.It Ev MAINTAINER 2132Email address with full name of the port's maintainer. 2133Defaults to 2134.Mt ports@openbsd.org . 2135.It Ev MAKE_ENV 2136Environment variables passed to make invocations and tests. 2137Sets at least PATH, PREFIX, LOCALBASE, X11BASE, CFLAGS, TRUEPREFIX, DESTDIR, 2138and the BSD_INSTALL_* macros. 2139.It Ev MAKE_FLAGS 2140Flags used for all make invocations, except for the 2141.Cm fake 2142stage, which adds 2143.Ev FAKE_FLAGS 2144(see 2145.Ev ALL_FAKE_FLAGS ) 2146and for the 2147.Cm test 2148stage, which adds 2149.Ev TEST_FLAGS 2150(see 2151.Ev ALL_TEST_FLAGS ) . 2152.It Ev MAKE_FILE 2153Name of the Makefile used for ports building. 2154Defaults to Makefile. 2155Used after changing directory to ${WRKBUILD}. 2156.It Ev MAKE_JOBS 2157Number of jobs to use when building the port, normally passed to 2158.Ev MAKE_PROGRAM 2159through 2160.Ev PARALLEL_MAKE_FLAGS . 2161Mostly set automatically when 2162.Ev DPB_PROPERTIES 2163contains 2164.Sq parallel . 2165.Pp 2166Note that 2167.Xr make 1 2168still has bugs that may prevent parallel build from working correctly! 2169.It Ev MAKE_PROGRAM 2170The make program that is used for building the port. 2171Set to ${MAKE} or ${GMAKE} depending on USE_GMAKE. 2172Read-only. 2173.It Ev MAKEFILE_LIST 2174Introspection variable, see 2175.Xr make 1 . 2176.It Ev MAKESUMFILES 2177List of all files that need to be retrieved by 2178.Cm fetch-all , 2179with 2180.Ev DIST_SUBDIR 2181prepended and with master site selection extension removed. 2182Read-only. 2183See also 2184.Ev CHECKSUMFILES . 2185.It Ev MASTER_SITE_BACKUP 2186User settings. 2187List of sites to try after normal master sites. 2188Normally includes ${MASTER_SITE_OPENBSD} and ${MASTER_SITE_FREEBSD}. 2189.It Ev MASTER_SITE_* 2190Lists of standard sites to retrieve files from, refer to 2191.Pa ${PORTSDIR}/infrastructure/db/network.conf 2192for a complete list. 2193.Pp 2194Generally used with the standard 2195.Xr make 1 Ns 's 2196.Li ${VARIABLE:=subdir/} 2197construct to append the relevant subdir at the end of each entry, e.g., 2198.Dl MASTER_SITES = ${MASTER_SITE_GNU:=cgicc/} 2199.It Ev MASTER_SITES 2200List of primary locations from which distribution files and patchfiles are 2201retrieved. 2202See the 2203.Cm fetch 2204target for details. 2205Defaults to ${MASTER_SITES_GITHUB} for GitHub-hosted projects, 2206see 2207.Ev GH_* . 2208See 2209.Xr ports 7 2210for user configuration. 2211.It Ev MASTER_SITES0 , ... , MASTER_SITES9 2212Supplementary locations from which distribution files and patchfiles are 2213retrieved. 2214.It Ev MESSAGE 2215File recorded in the package and displayed during installation. 2216Defaults to ${PKGDIR}/MESSAGE if this file exists. 2217Leave empty if no message is needed. 2218.It Ev MISSING_FILES 2219When 2220.Ev FETCH_MANUALLY 2221is set, 2222.Ev MISSING_FILES 2223will contain the list of missing distfiles or patchfiles that need to 2224be fetched manually. 2225Read-only. 2226.It Ev MTREE_FILE 2227.Xr mtree 8 2228specification used during 2229.Ar fake . 2230Replaced by direct use of 2231.Xr mkdir 1 2232now that 2233.Ar fake 2234no longer happens as root. 2235.It Ev MODGNU_CONFIG_GUESS_DIRS 2236If a port uses config.guess outside WRKSRC, the directories 2237containing the other copies must be set here. 2238.It Ev MODPERL_ADJ_FILES 2239If any files have a Perl shebang line, which needs to be replaced 2240with 2241.Dq #!/usr/bin/perl , 2242list them in 2243.Ev MODPERL_ADJ_FILES . 2244File paths here should be relative to 2245.Ev WRKSRC . 2246These files are patched automatically at the end of 2247.Cm pre-configure . 2248.It Ev MODPERL_BIN_ADJ 2249Shell fragment to patch the Perl interpreter path in executable scripts. 2250Used by 2251.Ev MODPERL_ADJ_FILES . 2252.It Ev MODPERL_BUILD_TARGET 2253Normal content of 2254.Cm do-build 2255when 2256.Ev CONFIGURE_STYLE 2257uses perl. 2258Provided as a separate variable if a port wants to override 2259.Cm do-build 2260for its own reasons. 2261.It Ev MODPERL_INSTALL_TARGET 2262Likewise for 2263.Cm do-install . 2264.It Ev MODPERL_TEST_TARGET 2265Likewise for 2266.Cm do-test . 2267.It Ev MODPERL_REGEN_PPPORT 2268Normally, if ppport.h is present, 2269it will be regenerated using a current version of 2270.Xr Devel::PPPort 3p . 2271Set to the filename under 2272.Pa ${WRKSRC} , 2273or 2274.Sq \&No 2275to disable. 2276Defaults to 2277.Sq ppport.h . 2278.It Ev MODULES 2279External modules mechanism, documented separately. 2280Modules such as 2281.Sq imake 2282and 2283.Sq gnu 2284are normally included automatically with the right 2285.Ev CONFIGURE_STYLE . 2286Note that it is possible to 2287.Li CONFIGURE_STYLE = simple , 2288.Li MODULES += gnu 2289to just get the effects of 2290.Ev CONFIG_SITE 2291and 2292.Ev MODGNU_CONFIG_GUESS_DIRS 2293along with the default 2294.Ev TEST_TARGET , 2295in case the normal GNU configure script was wrapped in a separate script that 2296takes different arguments. 2297See 2298.Xr port-modules 5 . 2299.It Ev MULTI_PACKAGES 2300Set to a list of subpackage extensions for ports that create multiple packages. 2301See 2302.Sx FLAVORS AND MULTI_PACKAGES 2303below. 2304Especially read the part about 2305.Ev ONLY_FOR_ARCHS 2306when some of the packages only exist for some architectures. 2307.It NO_ARCH 2308Location for arch-independent packages. 2309Defaults to 2310.Sq no-arch . 2311Normally, packages are generated under ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}, 2312except for packages where PKG_ARCH=*, which end up under 2313${PACKAGE_REPOSITORY}/${NO_ARCH}. 2314.It Ev NOT_FOR_ARCHS 2315List of architectures on which this port does not build. 2316See also 2317.Ev ONLY_FOR_ARCHS . 2318.It Ev NO_BUILD 2319Set to 2320.Sq Yes 2321if port does not need any build stage. 2322.It Ev NO_CCACHE 2323Set to 2324.Sq Yes 2325to prevent ccache from being used when building a certain port, 2326even when 2327.Ev USE_CCACHE 2328is set. 2329.It Ev NO_CHECKSUM 2330Set to 2331.Sq Yes 2332by 2333.Xr dpb 1 2334to avoid 2335.Cm checksum 2336entirely, 2337as 2338.Xr dpb 1 2339already deals with checksums internally. 2340.It Ev NO_DEPENDS 2341User settings. 2342Don't verify build of dependencies. 2343Do not use in any ports Makefile. 2344This is only meant as a user convenience when, e.g., you just want to browse 2345through a given port's source and do not wish to trigger the build of 2346dependencies. 2347.It Ev NO_IGNORE 2348User settings. 2349If set to 2350.Sq Yes , 2351avoid ignoring a port for the usual reasons. 2352Use, for instance, for fetching all distribution files, or for fixing a 2353broken port. 2354See also 2355.Ev IGNORE 2356and 2357.Ev TRY_BROKEN . 2358.It Ev NO_TEST 2359Port does not have any regression tests. 2360Only set to 2361.Sq Yes 2362for ports with no regression test. 2363It should be left alone for ports with empty regression tests, and for 2364ports with failing tests. 2365That way, if a subsequent update of a port acquires actual regression tests, 2366they will be picked up automatically. 2367.It Ev ONLY_FOR_ARCHS 2368List of architectures on which this port builds. 2369Can hold both processor-specific information (e.g., powerpc), and more 2370specific model information (e.g., macppc). 2371This is subpackage dependent. 2372Read the corresponding part of 2373.Sx FLAVORS AND MULTI_PACKAGES 2374if some subpackages should only be built on some architectures. 2375.It Ev OSREV 2376Revision number of 2377.Ox . 2378Read-only. 2379.It Ev PACKAGE_REPOSITORY 2380User settings. 2381Location for built packages. 2382Defaults to 2383.Pa ${PORTSDIR}/packages . 2384See 2385.Cm package 2386for details. 2387.It Ev PARALLEL_MAKE_FLAGS 2388Used when 2389.Ev DPB_PROPERTIES 2390contains 2391.Sq parallel . 2392Flags to pass to 2393.Ev MAKE_PROGRAM 2394to yield a parallel build. 2395Defaults to 2396.Li -j${MAKE_JOBS} . 2397Mostly set to empty by ports that use other mechanisms for setting the number 2398of jobs. 2399.It Ev PARALLEL_MAKE_JOBS 2400User settings. 2401Value of 2402.Ev MAKE_JOBS 2403to use when building manually a port with 2404.Ev DPB_PROPERTIES 2405containing 2406.Sq parallel . 2407Defaults to the number of online cpus. 2408.It Ev PATCH 2409Command to use to apply all patches. 2410Defaults to 2411.Pa /usr/bin/patch . 2412.It Ev PATCHORIG 2413Suffix used by 2414.Cm patch 2415to rename original files, and 2416.Cm update-patches 2417to re-generate 2418.Pa ${PATCHDIR}/${PATCH_LIST} 2419by looking for files using this suffix. 2420Defaults to 2421.Pa .orig . 2422For a port that already contains 2423.Pa .orig 2424files in the ${DISTFILES}, 2425set this to something else, such as 2426.Pa .pat.orig . 2427See also 2428.Cm distpatch , 2429.Ev DISTORIG . 2430.It Ev PATCH_CASES 2431In the normal 2432.Cm distpatch 2433stage (when 2434.Ev PATCHFILES 2435is not empty), this is the contents of a case statement, used to apply 2436distribution patches. 2437Fragments are automatically appended to handle gzip'ed, bzip'ed and lzip'ed 2438patches, so that the default case is more or less equivalent to the following 2439shell fragment: 2440.Bd -literal 2441set -e 2442cd ${FULLDISTDIR} 2443for patchfile in ${_LIST_PATCHFILES} 2444do 2445 case $$patchfile in 2446 *.bz2) 2447 ${BZIP2} -d <$$patchfile | ${PATCH} ${PATCH_DIST_ARGS};; 2448 *.zst|*.zstd) 2449 zstdcat -c <$$patchfile | ${PATCH} ${PATCH_DIST_ARGS};; 2450 *.Z|*.gz) 2451 ${GZIP_CMD} -d <$$patchfile | ${PATCH} ${PATCH_DIST_ARGS};; 2452 *) 2453 ${PATCH} ${PATCH_DIST_ARGS} <$$patchfile;; 2454 esac 2455done 2456.Ed 2457.It Ev PATCHDIR 2458Location for patches applied by the 2459.Cm patch 2460target. 2461Default: 2462.Pa patches . 2463.It Ev PATCHFILES 2464Files to fetch from the master sites like 2465.Ev DISTFILES , 2466but serving a different purpose, as they hold distribution patches that 2467will be applied at the 2468.Cm patch 2469stage. 2470See also 2471.Ev SUPDISTFILES . 2472.It Ev PATCH_ARGS 2473Full list of options used while applying port's patches. 2474.It Ev PATCH_CHECK_ONLY 2475Set to 2476.Sq Yes 2477by the 2478.Cm checkpatch 2479target. 2480Don't touch unless the default 2481.Cm checkpatch 2482target needs to be redefined. 2483Ideally, user-defined patch subtargets ought to test checkpatch. 2484In practice, they don't. 2485.It Ev PATCH_DEBUG 2486If set to 2487.Sq Yes , 2488the 2489.Cm patch 2490stage will output extra debug information. 2491This is the default. 2492.It Ev PATCH_DIST_ARGS 2493Full list of options used while applying distribution patches. 2494.It Ev PATCH_DIST_STRIP 2495Patch option used to strip directory levels while applying distribution 2496patches. 2497Defaults to -p0. 2498.It Ev PATCH_LIST 2499Wildcard pattern of patches to select under ${PATCHDIR}. 2500Defaults to patch-*. 2501Note that filenames ending in .orig, or ~ are never applied. 2502Note that 2503.Ev PATCH_LIST 2504can hold absolute pathnames, for instance to share patches among similar 2505ports: 2506.Bd -literal 2507PATCH_LIST=${PORTSDIR}/x11/kde/libs2/patches/p-* patch-* 2508.Ed 2509.It Ev PATCH_STRIP 2510Patch option used to strip directory levels while applying port's patches. 2511Defaults to -p0. 2512.It Ev PERMIT_DISTFILES , PERMIT_PACKAGE 2513Set to 2514.Sq Yes 2515if the distribution files or the package can be allowed on FTP sites without 2516legal issues. 2517Set to reason not to otherwise. 2518PERMIT_* lines in the Makefile should be preceded with a comment explaining 2519details about licensing and patents issues the port may have. 2520Porters must be very thorough in their checks. 2521In case of doubt, ask. 2522.Pp 2523If 2524.Ev PERMIT_PACKAGE 2525is set to 2526.Sq Yes , 2527.Ev PERMIT_DISTFILES 2528will default to 2529.Sq Yes . 2530.It Ev PKG_ADD 2531User settings. 2532Path to 2533.Xr pkg_add 1 2534command, with possible options. 2535.It Ev PKG_ARCH 2536Comma-separated list of architectures on which this package may install. 2537Defaults to ${MACHINE_ARCH},${ARCH}. 2538.Pp 2539For instance: 2540.Ev MACHINE_ARCH Ns = Ns Ar powerpc , 2541.Ev ARCH Ns = Ns Ar macppc . 2542.Pp 2543Most (if not all packages) will install correctly according to 2544.Ev MACHINE_ARCH . 2545.Pp 2546Use * for arch-independent packages 2547.Po 2548see also 2549.Sx THE DEBUG_PACKAGES INFRASTRUCTURE 2550.Pc . 2551.It Ev PKG_ARGS 2552Special arguments to pass to 2553.Xr pkg_create 1 , 2554in addition to the default ones. 2555For mips64 and pic libraries, see 2556.Sx THE GENERATION OF PACKAGE INFORMATION . 2557.It Ev PKG_CREATE 2558User settings. 2559Path to 2560.Xr pkg_create 1 2561command, with possible options. 2562.It Ev PKG_CREATE_NO_CHECKS 2563Porters switch. 2564Set to 2565.Sq Yes 2566to avoid checking the ports tree when solving 2567.Ev WANTLIB 2568.Po 2569see 2570.Cm wantlib-args 2571.Pc . 2572May result in bogus packages that mix 2573.Cm @depends 2574lines obtained from 2575the ports tree with 2576.Cm @wantlib 2577lines that come from the installed system. 2578Set to 2579.Sq Warn 2580to have the differences printed as a warning instead of an error 2581.Po 2582the default 2583.Pc . 2584.It Ev PKG_DBDIR 2585User settings. 2586Path to package installation records. 2587Defaults to 2588.Pa /var/db/pkg . 2589.It Ev PKG_DELETE 2590User settings. 2591Path to 2592.Xr pkg_delete 1 2593command, with possible options. 2594.It Ev PKG_INFO 2595User settings. 2596Path to 2597.Xr pkg_info 1 2598command, with possible options. 2599.It Ev PKG_TMPDIR 2600See 2601.Xr pkg_add 1 . 2602Normally points to 2603.Pa /var/tmp , 2604as per default. 2605.It Ev PORTHOME 2606Setting of env variable 2607.Ev HOME 2608for most shell invocations. 2609Default will trip ports that try to write into $HOME while building. 2610.It Ev PORTPATH 2611Path used by most shell invocations. 2612Don't override unless really needed. 2613.It Ev PORTSDIR 2614Root of the ports tree (default: 2615.Pa /usr/ports ) . 2616.It Ev PORTSDIR_PATH 2617Path used by dependencies and 2618.Pa bsd.port.subdir.mk 2619to look up package specifications. 2620Defaults to 2621.Pa ${PORTSDIR}:${PORTSDIR}/mystuff . 2622.It Ev PORTS_PRIVSEP 2623If set to 2624.Sq Yes , 2625will build ports as 2626.Ev BUILD_USER 2627and fetch distfiles 2628as 2629.Ev FETCH_USER . 2630.Pp 2631To work fully, this does require the ports tree 2632to be world-readable, and 2633.Pa ${WRKDIR} 2634to be world-readable as well 2635.Po 2636.Cm update-patches 2637and friends won't work otherwise 2638.Pc . 2639.Pp 2640Meant to use in concert with 2641.Xr dpb 1 , 2642which uses the same permissions 2643.Po 2644see 2645.Sq THE SECURITY MODEL OF DPB 2646in 2647.Xr dpb 1 2648.Pc . 2649.Pp 2650Basically, 2651.Ev BUILD_USER 2652must be able to write into 2653.Pa ${WRKOBJDIR} , ${PACKAGE_REPOSITORY} , ${PLIST_REPOSITORY} 2654and 2655.Ev FETCH_USER 2656must be able to write into 2657.Pa ${DISTDIR} . 2658The directories and permissions can be set correctly using 2659.Cm fix-permissions . 2660.Pp 2661The regular user must be allowed to execute commands as 2662.Ev BUILD_USER 2663and 2664.Ev FETCH_USER . 2665Running commands as another user can be achieved with 2666.Xr doas 1 2667by setting 2668.Ev SUDO=doas 2669in 2670.Xr mk.conf 5 2671and using the following minimal 2672.Xr doas.conf 5 : 2673.Bd -literal -offset indent 2674permit keepenv nopass solene as _pbuild 2675permit keepenv nopass solene as _pfetch 2676.Ed 2677.Pp 2678It is reasonably safe to allow your user id to run commands as the 2679.Ev BUILD_USER 2680or 2681.Ev FETCH_USER 2682and using 2683.Ic nopass 2684for these can save a lot of password entry, however it is inadvisable 2685to allow commands like 2686.Xr pkg_add 1 2687to run as root without a password. 2688.Pp 2689Note that this also means that 2690.Xr doas 1 2691must be configured to work within the chroot 2692created by 2693.Xr proot 1 . 2694.Pp 2695As 2696.Xr dpb 1 2697does its own privilege dropping when run as root, 2698it will automatically override 2699.Ev PORTS_PRIVSEP . 2700.Pp 2701User settings, defaults to 2702.Sq \&No . 2703.It Ev PKGDIR 2704Location for packaging information (packing-list, port description, messages). 2705.Cm update-plist 2706may create it. 2707Must be a valid directory. 2708Default: pkg. 2709.It Ev PKGFILE 2710Full path to the created package for the given subpackage. 2711Read-only. 2712.It Ev PKGFILES 2713Full path to all created packages. 2714Read-only. 2715.It Ev PKGNAME 2716Name of the created package. 2717Default is ${DISTNAME}. 2718This does not take flavors into account. 2719See 2720.Ev FULLPKGNAME 2721for that. 2722Specific revisions and epoch changes should be 2723handled by 2724.Ev REVISION 2725and 2726.Ev EPOCH 2727instead. 2728.It Ev PKGNAMES 2729Read-only. 2730List of all package names generated by the port, with 2731.Ev FLAVORS 2732and 2733.Ev BUILD_PACKAGES 2734taken into account. 2735Mostly used as 2736.Ql make show=PKGNAMES 2737to verify that bumped package names are correct. 2738.It Ev PKGNAME-foo 2739Package name for sub-package foo, if the default value 2740of ${PKGNAME}${SUBPACKAGE} is not appropriate. 2741.It Ev PKGPATH 2742Path to the current port's directory, relative to ${PORTSDIR}. 2743Read-only. 2744.It Ev PKGPATHS 2745Read-only. 2746List of all package paths generated by the port, with 2747.Ev FLAVORS 2748and 2749.Ev MULTI_PACKAGES 2750taken into account. 2751Order matches 2752.Ev PKGNAMES 2753exactly. 2754.It Ev PKGSPEC 2755Default package spec for using this port as a dependency. 2756Defaults to 2757.Sq stem-* , 2758derived from the 2759.Ev FULLPKGNAME . 2760Do not override without very good reasons, 2761namely software that coexist as different incompatible versions with the 2762same stem, e.g., already a mess. 2763.It Ev PKGSTEM 2764Base for the package name without any version number. 2765Used in 2766.Pa READMEs 2767file names and actual contents, can be overridden for ports 2768with branches, like php, e.g., 2769.Li PKGSTEM-main = php-5.6 2770.It Ev PLIST_DB 2771Deprecated, see 2772.Ev PLIST_REPOSITORY . 2773.It Ev PLIST_REPOSITORY 2774User settings. 2775Base directory used to save generated packing-lists, as persistent information. 2776Packing-lists are processed by a script, 2777.Xr register-plist 1 , 2778which complains when packing-lists change without a 2779.Ev REVISION 2780bump. 2781It also knows enough about package version numbers when something in the 2782package or its dependencies goes backward, thus catching 2783.Ev EPOCH 2784issues. 2785This directory is never cleaned during normal operation. 2786.Ql make clean=plist 2787should only ever be used during debugging by port maintainers. 2788Defaults to 2789.Pa ${PORTSDIR}/plist 2790.Po 2791plists actually get saved into 2792.Pa ${PLIST_REPOSITORY}/${MACHINE_ARCH} 2793.Pc . 2794If set to empty, will not register anything: very much unsafe. 2795.It Ev PORTS_BUILD_XENOCARA_TOO 2796EXPERIMENTAL. 2797Set to 2798.Sq Yes 2799to build xenocara through ports. 2800This is highly experimental and not recommended. 2801.It Ev PORTROACH 2802Controls the behavior of 2803.Pa misc/portroach 2804as documented in detail at 2805.Lk http://jasperla.github.io/portroach/docs/portroach-portconfig.txt . 2806.It Ev PREFIX 2807Base directory for the current port installation. 2808Usually ${LOCALBASE}, though some ports may elect a location under 2809.Pa ${VARBASE} , 2810and some multi-package ports may install under several locations. 2811Additionally, firmware files generally install under 2812.Pa ${BASESYSCONFDIR} . 2813.It Ev PREPARE_CHECK_ONLY 2814Build settings. 2815Prevent the 2816.Cm prepare 2817stage from installing anything, let it just check dependencies, and 2818handle [:target] dependencies. 2819Mostly used by 2820.Xr dpb 1 , 2821which already installs everything before running 2822.Cm prepare . 2823.It Ev PROGRESS_METER 2824User settings. 2825Defaults to 2826.Sq Yes . 2827Forces commands like 2828.Xr ftp 1 2829and 2830.Xr pkg_create 1 2831to use their progress-meter even in the absence of a terminal. 2832.It Ev PROPERTIES 2833List of properties specific to a given machine architecture. 2834Most often obtained through 2835.Xr bsd.port.arch.mk 5 . 2836These can be checked like this 2837.Bd -literal -offset indent 2838\&.include <bsd.port.arch.mk> 2839\&.if ${PROPERTIES:Mapm} 2840# then add build options specific to apm arches 2841\&... 2842\&.if !${PROPERTIES:Mlp64} 2843# build options specific to lp32 arches 2844\&... 2845.Ed 2846For 2847.Ev MULTI_PACKAGES 2848setup, use of 2849.Ev ONLY_FOR_ARCHS-sub 2850and 2851.Ev BUILD_PACKAGES 2852is generally preferred (and simpler). 2853Possible properties include 2854.Bl -tag -width mono 2855.It apm 2856architecture possesses suspend (apm) support. 2857.It be 2858architecture is big-endian. 2859.It gccN 2860gccN architecture. 2861.It le 2862architecture is little-endian. 2863.It lp64 2864lp64 architecture. 2865.It llvm 2866there is 2867.Pa lang/llvm 2868support on this architecture. 2869.It mono 2870there is 2871.Pa lang/mono 2872support on this architecture. 2873.El 2874.It Ev PSEUDO_FLAVOR 2875List of flavors in 2876.Ev FLAVOR 2877that are actually pseudo-flavors. 2878Only for introspection purposes. 2879Read-only. 2880.It Ev PSEUDO_FLAVORS 2881Extra list of flavors that do not register in package names, but are still 2882used to control build logic, and work directory names. 2883Its only use should be for disabling part of a multi-packages build, 2884for instance: 2885.Bd -literal 2886FLAVOR=no_gnome make package 2887.Ed 2888.Pp 2889Pseudo-flavors should be named as 2890.Sq no_something 2891to disable the build of subpackage 2892.Sq -something 2893.Po 2894and possibly some others, by restricting 2895.Ev BUILD_PACKAGES 2896.Pc . 2897Pseudo-flavors should always be handled through 2898.Xr bsd.port.arch.mk 5 . 2899A pseudo-flavor can remove several subpackages through the following 2900construct. 2901.Bd -literal -offset indent 2902# pseudo-flavor no_gui will also remove gtk and gtk3 2903MULTI_PACKAGES = -main -gtk -gtk3 -gui 2904# ... 2905\&.include <bsd.port.arch.mk> 2906 2907# remove extra build components 2908\&.if !${BUILD_PACKAGES:M-gui} 2909BUILD_PACKAGES := ${BUILD_PACKAGES:N-gtk:N-gtk3} 2910\&.endif 2911 2912# normal configure setup, e.g., 2913\&.if ${BUILD_PACKAGES:M-gtk} 2914# ... 2915.Ed 2916.Pp 2917Caveat: creation of a separate working directory is mandatory for a 2918pseudo-flavor. 2919If, at a later time, a full build with all subpackages is required, 2920all the work will need to be done again. 2921.Pp 2922See also 2923.Ev BUILD_ONCE . 2924.It Ev RCDIR 2925Location for daemon startup scripts. 2926Defaults to 2927.Pa /etc/rc.d . 2928Do not change. 2929.It Ev REFETCH 2930User settings. 2931If set to true, 2932.Cm checksum 2933will analyze ${CHECKSUM_FILE}, and try retrieving files with the correct 2934checksum off 2935.Lk https://ftp.openbsd.org , 2936in the directory 2937.Pa /pub/OpenBSD/distfiles/$cipher/$value/$file . 2938.It Ev REGISTER_PLIST_OPTS 2939User settings. 2940User options added to 2941.Xr register-plist 1 . 2942.It Ev REORDER_DEPENDENCIES 2943Points to a list of files that specify inter-dependencies for 2944.Xr make 1 . 2945If defined, each line of the file is either a comment (starting with #) 2946or a pair of two files: most_recent older. 2947At the end of 2948.Cm post-patch , 2949.Xr touch 1 2950will be used to ensure those files are put in the proper order. 2951The files are assumed to be under 2952.Pa ${WRKSRC} . 2953The notation /file can be used to ask for a recursive search, e.g., 2954to make sure that all Makefile.in are up to date. 2955See 2956.Pa ${PORTSDIR}/infrastructure/mk/automake.dep 2957for an example. 2958.It Ev REPORT_PROBLEM 2959See 2960.Xr ports 7 . 2961.It Ev REPORT_PROBLEM_LOGFILE 2962See 2963.Xr ports 7 . 2964.It Ev REVISION 2965Revision number of the current package. 2966Defaults to empty (very first package), then 2967numbering starts at 0. 2968Gets automatically incorporated into 2969.Ev FULLPKGNAME 2970as 2971.Sq p${REVISION} 2972to form a full package-name conforming to 2973.Xr packages-specs 7 . 2974.It Ev RUN_DEPENDS 2975Specification of ports this port needs installed to be functional. 2976Same format as 2977.Ev LIB_DEPENDS . 2978The corresponding packages will be built right before the 2979.Cm install 2980stage, and 2981.Xr pkg_add 1 2982will take care of installing them. 2983.It Ev SEPARATE_BUILD 2984Many GNU configure ports can be built in a directory distinct from the 2985place they were unpacked. 2986For some specific ports, this is even mandatory. 2987Set to 2988.Sq yes 2989if this is the case. 2990The ports infrastructure will generate a separate ${WRKBUILD} directory 2991in which the port will be configured and built. 2992Wipe ${WRKBUILD} to start anew, but skipping the extract/patch stage. 2993.It Ev SETENV 2994Normally set to 2995.Li /usr/bin/env -i . 2996Prepended to every command invocation that requires a clean environment. 2997Do not override. 2998.It Ev SHARED_LIBS 2999List of shared libraries that the port may build, as a list of the form 3000.Sq libname 3001.Sq libversion . 3002Used to set variables of the form 3003.Ev LIBlibname_VERSION 3004that are then used for substitution by 3005.Xr pkg_create 1 . 3006The porter is responsible for making sure the port uses those version numbers 3007when shared libraries are built. 3008.Pp 3009The intent is that the 3010.Ox 3011ports system must have control over shared library versions because of global 3012changes that may require bumping the major version of every shared library in 3013the system, or simply because the third party programmers do not understand 3014the rules for shared library versions, thus breaking the update mechanism. 3015For that reason it is advised to set libversion to 0.0 when first importing a 3016port. 3017.Pp 3018Porters of software using libtool should make sure 3019.Ev MAKE_FLAGS 3020get propagated to the libtool invocations. 3021This should be enough in most cases. 3022.It Ev SKIPDIR 3023See 3024.Xr ports 7 . 3025.It Ev STATIC_PLIST 3026Normally set to 3027.Sq yes . 3028Can be set to no for ports that do not have a static plist. 3029Do not change without a very good reason. 3030Note that the only good reason to not have a static plist is for ports such 3031as 3032.Pa databases/ports-readmes 3033which actually build a bunch of files depending on the current ports tree. 3034This breaks all introspection mechanisms within the ports tree, including 3035.Pa databases/pkglocatedb 3036which will not include that port. 3037.It Ev STARTAFTER 3038See 3039.Xr ports 7 . 3040.It Ev STARTDIR 3041See 3042.Xr ports 7 . 3043.It Ev SUBPACKAGE 3044Set to the subpackage suffix when building a package in a multi-package port. 3045Read-only. 3046Used to test for dependencies or to adjust the package name. 3047.It Ev SUBST_CMD 3048A command that can be used to perform 3049.Ev SUBST_VARS 3050substitution on arbitrary files. 3051In normal mode, 3052.Pp 3053.Dl ${SUBST_CMD} file1 file2 ... 3054.Pp 3055will substitute files in place, creating backup copies of them. 3056In copy mode, 3057.Pp 3058.Dl ${SUBST_CMD} -c src1 dest1 src2 dest2 3059.Pp 3060will copy files over while performing the substitution, as suitable for 3061copying template files over from 3062.Pa ${FILESDIR} 3063to 3064.Pa ${PREFIX} , 3065for instance. 3066This uses 3067.Xr pkg_subst 1 3068with suitable parameters. 3069Read-only. 3070.Pp 3071${SUBST_CMD} 3072can be used like 3073.Xr install 1 : 3074.Dl ${SUBST_CMD} Oo Fl g Ar group Oc Oo Fl o Ar owner Oc Oo Fl m Ar mode Oc file... 3075to set file 3076.Ar owner , 3077.Ar group 3078and/or 3079.Ar mode . 3080.Pp 3081Note that 3082.Ev SUBST_CMD 3083is not really appropriate when variables have subpackage variations, like 3084.Ev PREFIX 3085or 3086.Ev FULLPKGNAME . 3087Use the appropriate 3088.Ev SUBST_CMD-sub 3089instead. 3090.It Ev SUBST_CMD-sub 3091.Ev SUBST_CMD 3092with subpackage-dependent semantics, like packing-list substitution. 3093It will substitute the right variable depending on the desired subpackage, 3094e.g., 3095.Ev SUBST_CMD-foo 3096will substitute the value of 3097.Ev FULLPKGNAME-foo 3098for 3099.Li ${FULLPKGNAME} . 3100.It Ev SUBST_DATA , SUBST_MAN , SUBST_PROGRAM 3101Specialized versions of 3102.Ev SUBST_CMD 3103that use 3104.Fl c 3105and appropriate owner/group/mode for data, manpages and programs respectively. 3106.It Ev SUBST_VARS 3107Make variables whose values get substituted to create the actual package 3108information. 3109Always holds 3110.Ev ARCH , 3111.Ev BASE_PKGPATH , 3112.Ev FLAVOR_EXT , 3113.Ev FULLPKGNAME , 3114.Ev HOMEPAGE , 3115.Ev LOCALBASE , 3116.Ev MACHINE_ARCH , 3117.Ev MAINTAINER , 3118.Ev PREFIX , 3119.Ev PKGSTEM , 3120.Ev RCDIR , 3121.Ev SYSCONFDIR , 3122.Ev TRUEPREFIX , 3123and 3124.Ev X11BASE . 3125The special construct 3126.Sq ${FLAVORS} 3127can be used in the packing-list to specify the current list of dash 3128separated flavors the port is compiled with (useful for cross-dependencies 3129in 3130.Ev MULTI_PACKAGES ) . 3131Add other 3132variables as needed. 3133.Pp 3134.Ev TRUEPREFIX 3135is never passed to 3136.Xr pkg_create 1 3137as it is identical to 3138.Ev PREFIX . 3139.Pp 3140By default, 3141.Xr update-plist 1 3142is run with the following options: 3143.Bd -literal -offset indent 3144update-plist -i ARCH -i BASE_PKGPATH -i FULLPKGNAME 3145-i FULLPKGPATH -i LOCALSTATEDIR -i MACHINE_ARCH 3146-s BASE_PKGPATH -s LOCALBASE -s LOCALSTATEDIR -s PREFIX 3147-s RCDIR -s SYSCONFDIR -s X11BASE 3148.Ed 3149.It Ev SUDO 3150User settings. 3151If set to 3152.Xr doas 1 3153in 3154.Xr mk.conf 5 , 3155the ports tree will only invoke root's privileges for the parts that 3156really require it. 3157.It Ev SUPDISTFILES 3158Supplementary files that need to be retrieved under some specific 3159circumstances. 3160For instance, a port might need architecture-specific files. 3161.Ev SUPDISTFILES 3162should hold a list of all distribution files and patchfiles that are not 3163always needed, so that a mirror will be able to grab all files, or that 3164.Cm makesum 3165will work. 3166Having an overlap between 3167.Ev SUPDISTFILES 3168and 3169.Ev DISTFILES , 3170.Ev PATCHFILES 3171is admissible, and in fact, expected, as it is much simpler to build 3172an error-free list of files to retrieve in that way. 3173See the xanim port for an example. 3174.It Ev SYSCONFDIR 3175Location for this port's configuration files, should always be derived 3176from 3177.Ev BASESYSCONFDIR , 3178which defaults to 3179.Pa /etc . 3180Passed to gnu configure scripts and substituted in packing-lists. 3181.It Ev TAR 3182Name of the tar binary. 3183.It Ev TARGETS 3184Read-only. 3185Set to the list of special targets for a port 3186.Po 3187.Cm {pre,do,post}-* 3188and module hooks 3189.Pc . 3190Used by introspection tools such as the sqlports package. 3191.It Ev TEMPLATES 3192Base location for the templates used in the 3193.Cm readmes 3194target. 3195User settings. 3196Defaults to 3197.Pa ${PORTSDIR}/infrastructure/templates . 3198.It Ev TEST_DEPENDS 3199See 3200.Ev BUILD_DEPENDS 3201for specification. 3202Test dependencies are only checked if the 3203.Cm test 3204stage is invoked. 3205.It Ev TEST_ENV 3206Additional environment variables passed to tests. 3207Empty by default. 3208.It Ev TEST_FLAGS 3209Extra flags passed to ${MAKE_PROGRAM} to run the regression tests. 3210Empty by default. 3211.It Ev TEST_IS_INTERACTIVE 3212Set to 3213.Sq Yes 3214if port needs human interaction to run its tests, or set to 3215.Sq X11 3216if the tests need an active X11 display to work. 3217.It Ev TEST_LOG 3218Command used to log the results of regression tests to TEST_LOGFILE. 3219Read-only. 3220.It Ev TEST_LOGFILE 3221Log file containing the results of regression tests. 3222.It Ev TEST_TARGET 3223Target to run regression tests. 3224Defaults to 3225.Sq test , 3226except for 3227.Sq perl 3228and 3229.Sq gnu 3230.Ev CONFIGURE_STYLE , 3231which default to 3232.Sq test 3233and 3234.Sq check , 3235respectively. 3236.It Ev TRUEPREFIX 3237Read-only. 3238Mostly the same as ${PREFIX}, except it never gets ${DESTDIR} prepended 3239during 3240.Cm fake . 3241Refer to 3242.Sx THE FAKE FRAMEWORK 3243section for details. 3244.It Ev TRY_BROKEN 3245User settings. 3246If set to 3247.Sq Yes , 3248don't set 3249.Ev IGNORE 3250for 3251.Ev BROKEN 3252ports, so that we will attempt to build them. 3253.It Ev UNLOCK_CMD 3254User settings. 3255If set, expands to a command that will release a lock. 3256This lock will reside in 3257.Pa ${LOCKDIR} . 3258.It Ev UNMESSAGE 3259File recorded in the package and displayed during deinstallation. 3260Defaults to ${PKGDIR}/UNMESSAGE if this file exists. 3261Leave empty if no message is needed. 3262.It Ev UNZIP 3263Name of the unzip binary. 3264.It Ev UPDATE_COOKIES_DIR 3265User settings. 3266Used to store cookies for package updates and defaults to 3267.Pa ${PORTSDIR}/update/${MACHINE_ARCH} . 3268If set to empty, will revert to a file under 3269.Pa ${WRKDIR} . 3270.It Ev UPDATE_PLIST_ARGS 3271Tweaks to 3272.Xr update-plist 1 3273behavior for some specific ports, such as variable handling. 3274.It Ev UPDATE_PLIST_OPTS 3275User settings. 3276User options added to 3277.Xr update-plist 1 , 3278mostly 3279.Fl v 3280for now. 3281.It Ev USE_CCACHE 3282User settings. 3283Set to 3284.Sq Yes 3285to use ccache when building ports. 3286Sets up the build environment so that it is used. 3287.It Ev USE_GMAKE 3288Set to 3289.Sq Yes 3290if GNU make (${GMAKE}) is needed for correct behavior of this port. 3291.It Ev USE_GROFF 3292Set to 3293.Sq Yes 3294to use groff to build manpages. 3295This sets groff as a build dependency, and also tells 3296.Xr pkg_create 1 3297to format manpages behind the scene using groff while building packages. 3298.It Ev USE_LIBTOOL 3299Defaults to 3300.Sq Yes . 3301Set to 3302.Sq gnu 3303if the base 3304.Xr libtool 1 3305is insufficient and GNU libtool is required. 3306Set to 3307.Sq \&No 3308to disable the use of 3309.Xr libtool 1 3310entirely; this should not be set under normal circumstances. 3311Adds dependencies if necessary, and passes LIBTOOL environment variable to 3312scripts invocations. 3313.Pp 3314Many ports using GNU autoconf need an m4 file from the GNU libtool package 3315but otherwise work with base 3316.Xr libtool 1 . 3317In those cases do not set 3318.Ev USE_LIBTOOL , 3319instead just set 3320.Li BUILD_DEPENDS = devel/libtool . 3321.It Ev USE_LLD 3322Set to 3323.Sq Yes 3324or 3325.Sq \&No 3326to force the use of 3327.Xr ld.lld 1 3328.Po 3329as opposed to 3330bfd's 3331.Xr ld 1 3332.Pc . 3333Defaults to the appropriate value for the current architecture 3334.Po 3335see 3336.Ev LLD_ARCHS 3337in 3338.Xr bsd.port.arch.mk 5 3339.Pc . 3340.It Ev USE_MFS 3341Set to 3342.Sq Yes 3343to build ports under an MFS filesystem 3344(see 3345.Xr mount_mfs 8 ) . 3346Mostly for use by 3347.Xr dpb 1 3348and not intended to be a user setting. 3349See 3350.Ev WRKOBJDIR_MFS 3351for configuration. 3352.It Ev USE_NOEXECONLY 3353If set to 3354.Sq Yes , 3355writes a wrapper script to ${WRKDIR}/bin/ld in 3356.Cm patch 3357adding 3358.Fl -no-execute-only . 3359Use when a port does not work with execute-only (unreadable) code sections 3360which are used by default by the linker on some architectures. 3361.It Ev USE_WXNEEDED 3362If set to 3363.Sq Yes , 3364writes a wrapper script to ${WRKDIR}/bin/ld in 3365.Cm patch 3366to request that the linker adds an 3367.Dv PT_OPENBSD_WXNEEDED 3368ELF section. 3369Use when a port requires memory mappings that are both executable 3370and writable and cannot be modified to avoid this. 3371.It Ev USE_X11 3372Normally, presence of ${X11BASE} is enforced by default for building ports. 3373But there is an experimental way to hook the xenocara build into 3374.Xr dpb 1 , 3375which requires knowing whether a port requires X11 to already 3376be there. 3377.Pp 3378The infrastructure mostly sets 3379.Ev USE_X11 3380automatically based on 3381.Ev WANTLIB 3382values, there are a few ports (about 20) that require X11 components without 3383any library telltale. 3384.It Ev VARBASE 3385User settings. 3386Base location for ports that install stuff outside of 3387.Pa ${LOCALBASE} . 3388Defaults to 3389.Pa /var . 3390.It Ev WANTLIB 3391List of library specifications that a package will need. 3392May include system and X11 libraries. 3393See 3394.Xr library-specs 7 3395for more details. 3396.Pp 3397As a special extension, 3398.Ev WANTLIB 3399may include absolute paths, e.g., 3400.Pa ${LOCALBASE}/lib/expat=4 3401to distinguish between base libraries and port libraries. 3402Use with caution, this is very seldom needed. 3403.It Ev wantlib_args 3404Controls the behavior of 3405.Xr pkg_create 1 3406related targets, see 3407.Cm print-package-args 3408for details. 3409.It Ev WARNINGS 3410User settings. 3411If set to 3412.Sq Yes , 3413add 3414.Ev CDIAGFLAGS 3415to 3416.Ev CFLAGS 3417and 3418.Ev CXXDIAGFLAGS 3419to 3420.Ev CXXFLAGS . 3421.It Ev WRKBUILD 3422Subdirectory of ${WRKDIR} where the actual build occurs. 3423Defaults to ${WRKSRC}, unless 3424.Ev SEPARATE_BUILD 3425is involved, in which case it is set to an appropriate value. 3426.It Ev WRKCONF 3427Subdirectory of ${WRKDIR} where the actual configure set occurs. 3428Defaults to ${WRKBUILD}. 3429.It Ev WRKDIR 3430Location where all port activity occurs. 3431Apart from the actual port, may 3432hold all kinds of cookies that checkpoint the port's build. 3433Read-only. 3434Note that WRKDIR may be a symbolic link. 3435During ports building, 3436.Pa ${WRKDIR}/bin 3437is put at the front of the 3438.Ev PATH . 3439.It Ev WRKDIR_LINKNAME 3440Name of a symbolic link to create within the port directory which will 3441point to the port's ${WRKDIR}. 3442Deprecated. 3443.It Ev WRKDIST 3444Subdirectory of ${WRKDIR} in which the distribution files normally unpack. 3445Base for all patches. 3446Defaults to 3447.Pa ${WRKDIR}/${DISTNAME} . 3448Note that WRKDIST may be a symbolic link, if set to ${WRKDIR}. 3449.It Ev WRKSRC 3450Subdirectory of ${WRKDIR} where the actual source is. 3451Base for configuration (default: ${WRKDIST}). 3452Note that WRKSRC may be a symbolic link, if set to ${WRKDIR}. 3453.It Ev WRKINST 3454Subdirectory of ${WRKDIR} where port normally installs (see the 3455.Cm fake 3456target). 3457.It Ev WRKOBJDIR 3458Used as a base for the actual port working directory. 3459Defaults to 3460.Pa ${PORTSDIR}/pobj . 3461The real working directory ${WRKDIR} is created there. 3462Can be set on a per-${PKGPATH} basis. 3463For instance, setting WRKOBJDIR_www/mozilla=/tmp/obj 3464will affect only the mozilla port. 3465If explicitly unset (WRKOBJDIR=), the working directory is 3466created within the port directory. 3467.It Ev WRKOBJDIR_MFS 3468Alternate location for the port working directory. 3469The intent is to use an MFS based filesystem for small ports with 3470.Xr dpb 1 . 3471Active when 3472.Ev USE_MFS 3473is 3474.Sq Yes . 3475Defaults to 3476.Pa /tmp/pobj . 3477.It Ev X11BASE 3478Where X11 has been installed. 3479Default: 3480.Pa /usr/X11R6 . 3481.It Ev XAUTHORITY 3482Points to a suitable authority file for X11 interactive regression tests. 3483Defaults to 3484.Pa ${HOME}/.Xauthority . 3485.It Ev XMKMF 3486Invocation of xmkmf for a 3487.Li CONFIGURE_STYLE=imake 3488port. 3489Defaults to xmkmf -a -DPorts. 3490The -DPorts is specific to 3491.Ox 3492and is always appended. 3493.It Ev YACC 3494Name of yacc program to pass to GNU-configure, defaults to yacc. 3495GNU-configure would always try to use bison otherwise, which leads to 3496unreproducible builds. 3497Set to bison if needed. 3498.El 3499.Sh THE FAKE FRAMEWORK 3500The 3501.Cm fake 3502target is used to install the port in a private directory first, ready for 3503packaging by the 3504.Cm package 3505target, so that the actual installation will use the package. 3506.Pp 3507Essentially, 3508.Cm fake 3509invokes a real install process after tweaking a few variables. 3510.Pp 3511.Cm fake 3512first creates a skeleton tree under ${WRKINST}, using 3513.Xr mkdir 1 3514.Fl p . 3515.Pp 3516A 3517.Cm pre-fake 3518target may be used to complete that skeleton tree. 3519For instance, a few ports may need supplementary stuff to be present (as 3520it would be installed if the port's dependencies were present). 3521.Pp 3522If 3523.Cm {pre,do,post}-install 3524overrides are present, they are used with some 3525important changes, listed in 3526.Ev FAKE_SETUP : 3527.Bd -literal -offset indent 3528TRUEPREFIX=${PREFIX} 3529PREFIX=${WRKINST}${PREFIX} 3530${DESTDIRNAME}=${WRKINST} 3531.Ed 3532.Pp 3533Essentially, old install targets work transparently, except for a need to 3534change 3535.Ev PREFIX 3536to 3537.Ev TRUEPREFIX 3538for symbolic links and similar path lookups. 3539Specific traditional post install work can be simply removed, as it will 3540be taken care of by the package itself (for instance, ldconfig, or 3541texinfo's install-info). 3542.Pp 3543If no 3544.Cm do-install 3545override is present, the port is installed using 3546.Bd -literal -offset 2n 3547env -i ${MAKE_ENV} ${FAKE_SETUP} ${MAKE_PROGRAM} ${ALL_FAKE_FLAGS} -f ${MAKE_FILE} ${FAKE_TARGET} 3548.Ed 3549.Pp 3550Note that this does set both PREFIX and ${DESTDIRNAME}. 3551If a port's Makefile both heeds ${DESTDIRNAME}, 3552and references PREFIX explicitly, 3553FAKE_FLAGS may rectify the problem by setting PREFIX=${PREFIX} 3554(which will do the right thing, since ${PREFIX} is a 3555.Xr make 1 3556construct which will not be seen by the shell). 3557.Pp 3558${FAKE_FLAGS} is used to set variables on 3559.Xr make 1 3560command line, which will override the port Makefile contents. 3561Thus, a port that mentions DESTDIR= does not need any patch to work with fake. 3562.Pp 3563Files such as 3564.Pa ${PKGDIR}/README* 3565or 3566.Pa ${PKGDIR}/*.rc 3567get copied to 3568.Pa ${WRKINST} 3569right after the end of 3570.Cm fake , 3571during 3572.Cm generate-readmes 3573(see the 3574.Sx FILES 3575section above for details). 3576.Sh THE DEBUG_PACKAGES INFRASTRUCTURE 3577If 3578.Ev DEBUG_PACKAGES 3579is not empty, debug packages will be built "on the side". 3580Since debug information is usually large, this is controlled on a per-arch 3581basis with 3582.Ev DEBUGINFO_ARCHS 3583controlling the behavior (set to amd64 by default). 3584.Pp 3585During the normal 3586.Cm package 3587target , 3588.Xr build-debug-info 1 3589will be invoked to deduce debug packing-lists from the normal packing-lists, 3590and some extra makefile rules will be invoked to set aside the debug 3591information. 3592.Pp 3593Then each normal package will have a "shadow" debug-* package built alongside 3594it, with the exact same package signature, except it will also be tied closely 3595with the normal package. 3596.Pp 3597Figuring out what files contain debug information is entirely achieved through 3598.Cm @bin , 3599.Cm @lib , 3600.Cm @so 3601and 3602.Cm @static-lib 3603annotations in the base packing-lists. 3604.Pp 3605Debug packages will be produced for all subpackages in 3606.Ev DEBUG_PACKAGES . 3607Usually, the heuristics of trimming arch-independent packages 3608from 3609.Ev BUILD_PACKAGES 3610is enough. 3611In case this still produces empty debug packages, the 3612.Ev DEBUG_PACKAGES 3613list should be produced manually. 3614.Pp 3615The actual debug packages are not registered through 3616.Xr register-plist 1 3617since the information was automatically generated. 3618.Pp 3619debug package names and debug package filenames are added to 3620.Ev PKGNAMES 3621and 3622.Ev PKGFILES 3623respectively for introspection purpose. 3624.Pp 3625.Xr egdb 1 3626from ports can read debug information from a separate file, as long as 3627the original ELF file was annotated with a debuginfo link. 3628.Pp 3629That feature is used to set debug information on the side, in 3630.Pa .debug/ 3631subdirectories alongside the normal binaries, shared objects and shared 3632libraries. 3633.Pp 3634For static libraries, the information can't be separated, instead the full 3635static library with debug information is provided in the 3636.Pa .debug/ 3637subdirectory, while the normal static library gets stripped. 3638.Sh FLAVORS AND MULTI_PACKAGES 3639Starting with 3640.Ox 2.7 , 3641each port can generate distinct packages through two orthogonal mechanisms: 3642.Ev FLAVORS 3643and 3644.Ev MULTI_PACKAGES . 3645.Pp 3646The current 3647.Ev MULTI_PACKAGES 3648mechanism was introduced after 3649.Ox 4.0 . 3650.Pp 3651The arch-dependent part was refined after 3652.Ox 5.0 . 3653.Pp 3654If a port can be compiled with several options, these options 3655should be turned into 3656.Ev FLAVORS . 3657The port maintainer will set 3658.Ev FLAVORS 3659to be the list of possible options in the Makefile. 3660When building the port, the package builder will set 3661.Li "FLAVOR='option1 option2...'" 3662to build a specific flavor of the port. 3663The Makefile should test the value of FLAVOR as follows: 3664.Bd -literal -offset indent 3665FLAVOR?= 3666\&.if ${FLAVOR:Moption1} 3667# what to do if option1 3668\&.endif 3669\&.if ${FLAVOR:Moption2} 3670# what to do if option2 3671\&.endif 3672.Ed 3673.Pp 3674.Nm 3675takes care of a few details, such as generating a distinct work directory for 3676each flavor, or creating a FULLPKGNAME by adding a dash separated list of 3677flavors to the base package name. 3678The order in which 3679.Ev FLAVOR 3680is specified does not matter: this dash separated list will be 3681reordered to match the ordering of 3682.Ev FLAVORS . 3683.Pp 3684It is an error to specify an option in 3685.Ev FLAVOR 3686that does not appear in 3687.Ev FLAVORS , 3688to prevent misspellings. 3689.Pp 3690In bulk package building, flavors can be specified as a comma 3691separated list after the package directory, e.g., SUBDIR+=vim,no_x11 3692.Po 3693see 3694.Xr pkgpath 7 3695.Pc 3696.Pp 3697Finally, package information will use templates with the canonical package 3698extension if they are available: if FLAVOR='option1 option2' and both 3699COMMENT and COMMENT-option1-option2 are available, COMMENT-option1-option2 will 3700be used. 3701.Pp 3702If one build of a port can generate several distinct packages, set 3703.Ev MULTI_PACKAGES 3704accordingly. 3705Each extension of a 3706.Ev MULTI_PACKAGES 3707name should start with a dash, so that they cannot be confused with 3708.Ev FLAVORS . 3709In dependency checking and bulk builds, a subpackage can be 3710specified after a comma, e.g., 3711.Li SUBDIR+=quake,-server . 3712.Ev MULTI_PACKAGES 3713only affects the actual package building step. 3714.Pp 3715If 3716.Ev MULTI_PACKAGES 3717is set, the packaging stage happens once for every 3718subpackage, using subpackage-specific variables. 3719For instance, if 3720.Li MULTI_PACKAGES=-main -lib -server , 3721.Ev PKG_ARCH-main , 3722.Ev PKG_ARCH-lib 3723and 3724.Ev PKG_ARCH-server 3725will be used for the subpackages respectively called 3726.Ev FULLPKGNAME-main , 3727.Ev FULLPKGNAME-lib 3728and 3729.Ev FULLPKGNAME-server . 3730.Pp 3731All package information is also derived from 3732templates with SUBPACKAGE appended. 3733In the preceding example, the packing-list template for FULLPKGNAME-lib 3734must be in PLIST-lib. 3735.Pp 3736The following variables are subpackage dependent: 3737.Ev COMMENT , 3738.Ev PKG_ARCH , 3739.Ev PERMIT_PACKAGE , 3740.Ev PKGFILE , 3741.Ev PKGNAME , 3742.Ev PKGSTEM , 3743.Ev FULLPKGNAME , 3744.Ev REVISION , 3745.Ev EPOCH , 3746.Ev FULLPKGPATH , 3747.Ev RUN_DEPENDS , 3748.Ev WANTLIB , 3749.Ev LIB_DEPENDS , 3750.Ev IGNORE , 3751.Ev ONLY_FOR_ARCHS , 3752.Ev NOT_FOR_ARCHS , 3753.Ev PKG_ARGS , 3754.Ev PREFIX , 3755.Ev CATEGORIES , 3756.Ev MESSAGE , 3757.Ev UNMESSAGE , 3758.Ev DESCR , 3759.Ev PLIST , 3760.Ev STATIC_PLIST , 3761.Ev PKGSPEC . 3762.Pp 3763The usual non-MULTI_PACKAGES variables are simply used as default values 3764for all subpackages. 3765So, if you set 3766.Li "PKG_ARCH=*" 3767.Li "PKG_ARCH-main=i386" 3768then 3769.Ev PKG_ARCH-lib 3770and 3771.Ev PKG_ARCH-server 3772will both be 3773.Sq * . 3774.Pp 3775.Ev WANTLIB 3776and 3777.Ev LIB_DEPENDS 3778are special. 3779At the beginning of the build, during 3780.Cm prepare , 3781all build dependencies will be checked, 3782which includes 3783.Ev LIB_DEPENDS , 3784.Ev WANTLIB 3785for every subpackage. 3786As an exception, any 3787.Ev LIB_DEPENDS-sub 3788that references the current port will be ignored as a build dependency, 3789in order to avoid recursion. 3790.Pp 3791.Ev FULLPKGPATH 3792and 3793.Ev FULLPKGNAME 3794are special as well. 3795If 3796.Ev PKGNAME 3797is <stem>-<version>, 3798then 3799.Ev PKGNAME-sub 3800will be set to 3801<stem>-sub-<version> 3802by default, except for 3803.Ev PKGNAME-main 3804which has 3805.Ev PKGNAME 3806as a default. 3807Normally, 3808.Ev FULLPKGPATH-sub 3809is automatically set to the right value, 3810but in very rare cases, one may need to override the default: 3811for instance, if one specific subpackage is not affected by flavor 3812settings that affect other subpackages, e.g., for include files packs, 3813then the flavoring part of the fullpkgpath may need to be dropped. 3814.Pp 3815In terms of using the port, quite a few targets will have a subpackage 3816specific subtarget: 3817invoking 3818.Cm package 3819is the same as invoking 3820.Cm subpackage 3821for all subpackages, 3822invoking 3823.Cm install-all 3824is the same as invoking 3825.Cm install 3826for all subpackages, 3827and invoking 3828.Cm update 3829is the same as invoking 3830.Cm subupdate 3831for all subpackages. 3832.Pp 3833.Ev ONLY_FOR_ARCHS 3834and 3835.Ev NOT_FOR_ARCHS 3836interact with 3837.Ev MULTI_PACKAGES 3838and 3839.Ev IGNORE . 3840The infrastructure will automatically filter subpackages 3841that are not suitable for the current architecture. 3842Thus, 3843.Ev MULTI_PACKAGES 3844should always list all subpackages, 3845even things not buildable on the current architecture, 3846for indexing purposes. 3847.Pp 3848Starting with 3849.Ox 5.1 , 3850.Xr bsd.port.arch.mk 5 3851should be used to simplify the handling of 3852.Ev MULTI_PACKAGES 3853in arch-dependent setups: 3854.Pp 3855Make sure 3856.Ev MULTI_PACKAGES , 3857.Ev ONLY_FOR_ARCHS* , 3858and 3859.Ev PSEUDO_FLAVORS 3860are defined correctly, then 3861.Bd -literal -offset indent 3862\&.include <bsd.port.arch.mk> 3863.Ed 3864.Pp 3865This will compute 3866.Ev BUILD_PACKAGES , 3867the list of actual subpackages to build with the current setup, 3868by taking arch constraints and pseudo-flavors into account. 3869Then test 3870.Ev BUILD_PACKAGES 3871to set up the right configuration, e.g., to check if 3872.Ev SUBPACKAGE 3873.Ar -mono 3874should be built: 3875.Bd -literal -offset indent 3876\&.if ${BUILD_PACKAGES:M-mono} 3877.Ed 3878.Pp 3879The 3880.Pa lang/gcc/8 3881or 3882.Pa print/poppler 3883ports should provide examples of proper use. 3884.Pp 3885Note that 3886.Xr dpb 1 3887will break if all subpackages are not properly listed. 3888.Sh THE GENERATION OF PACKAGE INFORMATION 3889Starting after 3890.Ox 4.1 3891all package information is processed directly by 3892.Xr pkg_create 1 3893from templates in ${PKG_DIR}. 3894.Pp 3895.Bl -bullet -compact 3896.It 3897If not overridden by the user, determine which set of templates to use, 3898depending on the current SUBPACKAGE and FLAVOR information. 3899Set PLIST${SUBPACKAGE}, DESCR${SUBPACKAGE}, COMMENT${SUBPACKAGE}, 3900MESSAGE${SUBPACKAGE}, UNMESSAGE${SUBPACKAGE} accordingly. 3901.It 3902Generate the actual DESCR, and if needed, MESSAGE, UNMESSAGE, 3903from the templates in ${DESCR}, ${MESSAGE}, ${UNMESSAGE}, by 3904substituting the variables in ${SUBST_VARS}, and by substituting 3905${FLAVORS} with the canonical flavor extension for this port, 3906e.g., if 3907.Li FLAVORS=no_map gfx qt2 , 3908if 3909.Li FLAVOR=gfx no_map , 3910this is 3911.Sq -no_map-gfx . 3912.It 3913Generate the actual packing-list from the template ${PLIST}, 3914by inserting fragments 3915and applying the same variable substitutions as other package information. 3916.El 3917.Pp 3918Note that ${COMMENT} is currently not substituted. 3919.Pp 3920To avoid substitution, variables can be escaped as follows: 3921.Li "$\e{PREFIX}" 3922.Pp 3923If 3924.Ev FLAVORS 3925lists flv, then constructs such as the line 3926.Li "%%flv%%" 3927or 3928.Li "!%%flv%%" 3929in the packing-list template trigger the inclusion of 3930.Pa ${PKGDIR}/PFRAG.flv${SUBPACKAGE} 3931or 3932.Pa ${PKGDIR}/PFRAG.no-flv${SUBPACKAGE} . 3933Other fragments can be defined by simply adding 3934.Li "-Dfrag=1" 3935or 3936.Li "-Dfrag=0" 3937to 3938.Ev PKG_ARGS . 3939.Pp 3940If libraries are built using 3941.Pa bsd.lib.mk , 3942special care should be taken for mips64* architectures, 3943which do not ever build 3944.Pa *pic.a 3945files (all mips code is pic already). 3946.Nm 3947automatically adds 3948.Li "-Dno_mips64=1" 3949or 3950.Li "-Dno_mips64=0" 3951to 3952.Ev PKG_ARGS , 3953and the porter only needs to provide the appropriate fragment. 3954.Pp 3955.Xr pkg_add 1 3956now calls 3957.Xr ldconfig 8 3958directly, provided dynamic libraries have been annotated with 3959.Li "@lib libthingy.so.5.0" . 3960Adding new directories to the dynamic loader cache has been 3961deprecated. 3962It is often better to let libraries be visible as a link 3963under ${LOCALBASE}. 3964Having a separate directory is enough to trick 3965.Xr ld 1 3966into grabbing the right version. 3967Libraries used only for 3968.Xr dlopen 3 3969do not need to be visible. 3970Some programs will prefer to use rpath to find their own libraries. 3971.Pp 3972The special 3973.Cm update-plist 3974target does a fairly good job of automatically generating the packing-list 3975information. 3976.Pp 3977If 3978.Ev PLIST_REPOSITORY 3979points to a directory, all packing-lists from packages generated by 3980.Xr pkg_create 1 3981during the 3982.Cm package 3983stage are saved in 3984.Pa ${PLIST_REPOSITORY}/${MACHINE_ARCH} 3985by a script: 3986.Pa ${PORTSDIR}/infrastructure/bin/register-plist . 3987This script strips some irrelevant information and normalizes the 3988packing-list somehow, and compares it to existing information, looking 3989for relevant changes. 3990Since a package name must always be changed when the packing-list changes, 3991any attempt to replace a packing-list of a given name with a different 3992packing-list will be flagged as an error. 3993.Pp 3994In 3995.Ev MULTI_PACKAGES 3996mode, there must be separate COMMENT, DESCR, and PLIST 3997templates for each SUBPACKAGE (and optional distinct MESSAGE, UNMESSAGE 3998files in a similar way). 3999This contrasts with the 4000.Ev FLAVORS 4001situation, where all these files will automatically default to the 4002non-flavor version if there is no flavor-specific file around. 4003.Sh OBSOLETE TARGETS 4004.Bl -tag -width Ds 4005.It Cm {build,run,lib}-depends 4006The dependency mechanism now meshes 4007.Ev BUILD_DEPENDS , LIB_DEPENDS , RUN_DEPENDS, WANTLIB 4008and 4009.Ev MULTI_PACKAGES . 4010Refer to 4011.Cm prepare , install-depends , test-depends . 4012.El 4013.Sh OBSOLETE VARIABLES 4014.Bl -tag -width Ds 4015.It Ev FETCH_BEFORE_ARGS , FETCH_AFTER_ARGS 4016Set 4017.Ev FETCH_CMD 4018to point to a script that does any required special treatment instead. 4019.It Ev FETCH_DEPENDS 4020Used to specify dependencies that were needed to fetch files. 4021It is much easier to mirror locally weird distribution files. 4022.It Ev NO_EXTRACT 4023Set EXTRACT_ONLY= instead. 4024.It Ev NO_WRKDIR 4025All ports should have a working directory, as this is necessary to store 4026cookies and keep state. 4027.It Ev NO_WRKSUBDIR 4028The same functionality is obtained by setting WRKDIST=${WRKDIR}. 4029.It Ev OPSYS_VER 4030Use 4031.Ev OSREV 4032instead. 4033.It Ev PKGNAME 4034Used to refer to the full package name, has been superseded by 4035.Ev FULLPKGNAME-foo , 4036for 4037.Ev SUBPACKAGE 4038-foo. 4039.Ev PKGNAME 4040now holds the package name, not taking multi-packages or flavors 4041into account. 4042Most ports are not concerned by this change. 4043.It Ev PLIST_SUBST 4044From 4045.Nx 4046and 4047.Fx . 4048Use SUBST_VARS instead. 4049.Ox 4050does not allow general substitutions of the form VAR=value, but uses 4051only a list of variables instead. 4052Most package files gets transformed, instead of only the packing-list. 4053.It Ev SCRIPTDIR 4054Old location for scripts related to the current port. 4055There is no reason for the semantic distinction, use 4056.Ev FILESDIR 4057for those. 4058.It Ev USE_BZIP2 4059The framework will automatically detect the presence of 4060.Pa .tar.bz2 4061files to extract. 4062See also 4063.Ev BZIP2 , EXTRACT_CASES , 4064and 4065.Ev EXTRACT_SUFX . 4066.It Ev USE_ZIP 4067The framework will automatically detect the presence of 4068.Pa .zip 4069files to extract. 4070See also 4071.Ev ZIP , EXTRACT_CASES , 4072and 4073.Ev EXTRACT_SUFX . 4074.El 4075.Sh FILES 4076.Bl -tag -width Ds 4077.It Pa ../Makefile.inc 4078Common Makefile fragment for a set of ports, included automatically. 4079.It Pa /cdrom/distfiles 4080Default path to a CD-ROM (or other media) full of distribution files. 4081.It Pa ${PORTSDIR}/distfiles 4082Default setup of ${DISTDIR}. 4083.It Pa ${DISTDIR} 4084Cache of all distribution files. 4085.It Pa distinfo 4086Checksum file. 4087Holds the output of 4088.Xr cksum 1 , 4089using 4090.Xr sha256 1 4091for the port's ${DISTFILES} and ${PATCHFILES}, 4092as well as the sizes of these files. 4093.It Pa ${DISTDIR}/${CHECKSUMFILES} 4094Cache of normal distribution files for a given port. 4095.It Pa ${DISTDIR}/${MAKESUMFILES} 4096Cache of all distribution files for a given port. 4097.It Pa ${PORTSDIR}/infrastructure/mk/*.mk 4098Actual location of the 4099.Xr make 1 4100glue for the ports tree. 4101.Xr make 1 4102looks for 4103.Pa bsd.port.mk 4104.Po 4105and 4106.Pa bsd.port.subdir.mk 4107.Pc 4108under 4109.Pa /usr/share/mk/bsd.port.mk , 4110but that file is just a stub that redirects to the real location. 4111.It Pa ${PKGDIR}/DESCR 4112Description for the port. 4113Variables such as ${HOMEPAGE} and ${MAINTAINER} will be expanded 4114(see SUBST_VARS). 4115Multi-package ports will use DESCR${SUBPACKAGE}. 4116.It Pa ${PKGDIR}/README 4117.Ox 4118specific documentation for a port, that will be installed as 4119.Pa ${LOCALBASE}/share/doc/pkg-readmes/${PKGSTEM} 4120at the end of 4121.Cm fake . 4122Variables from 4123.Ev SUBST_VARS 4124will be expanded. 4125Multi-package ports will use 4126.Pa README${SUBPACKAGE} . 4127.It Pa ${PKGDIR}/<foo>.login 4128login.conf.d file for class <foo>. 4129Will be installed as 4130.Ar ${PREFIX}/share/examples/login.conf.d/foo 4131at the end of 4132.Cm fake . 4133When a port provides a daemon started by 4134.Xr rc.d 8 4135requiring non-default 4136.Xr login.conf 5 4137attributes, a sample file should be provided 4138and used as a template by adding 4139.Cm @sample /etc/login.conf.d/${ Ns Va class Ns } 4140to the packing list. 4141.It Pa ${PKGDIR}/<foo>.rc 4142Startup script for <foo>. 4143Will be installed as 4144.Ar ${RCDIR}/<foo> 4145at the end of 4146.Cm fake . 4147Variables from 4148.Ev SUBST_VARS 4149will be expanded. 4150.It Pa ${PORTSDIR}/plist 4151Default setup of ${PLIST_REPOSITORY}. 4152.It Pa ${PORTSDIR}/packages 4153Default setup of ${PACKAGE_REPOSITORY}. 4154.It Pa ${PACKAGE_REPOSITORY}/no-arch 4155Location of arch-independent packages. 4156.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/all 4157Location of all built packages. 4158.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cache 4159Location of packages retrieved through the network. 4160.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cksums 4161Location of checksums, see 4162.Ev CHECKSUM_PACKAGES . 4163.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cdrom 4164Location of packages suitable for the CD. 4165.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/ftp 4166Location of packages suitable for FTP. 4167.It Pa ${PORTSDIR}/bulk/${MACHINE_ARCH} 4168Default setup of ${BULK_COOKIES_DIR}. 4169.It Pa ${PORTSDIR}/update/${MACHINE_ARCH} 4170Default setup of ${UPDATE_COOKIES_DIR}. 4171.It Pa ${PORTSDIR}/mystuff 4172Extra directory used to store local ports before committing them. 4173All depend targets will normally look there after the normal lookup fails. 4174See 4175.Ev PORTSDIR_PATH . 4176.El 4177.Sh DIAGNOSTICS 4178Note that some of these messages are actually emitted by some other external 4179commands, but grouped here for convenience: easier to look for in 4180.Xr dpb 1 Ns 's 4181logs. 4182.Bl -diag 4183.It "/bin/sh: cd .../pkg - No such file or directory" 4184Emitted during 4185.Cm generate-readmes . 4186.Pa ${PKGDIR} 4187must point to an existing directory, so that 4188.Nm 4189can be certain there are no 4190.Pa MESSAGEs 4191or 4192other files pertinent to the package. 4193.It "Discovered old directory in ..." 4194This message comes from 4195.Xr update-plist 1 . 4196A directory was found in the packing-list file mentioned in the diagnostic. 4197That directory line used to be needed but is no longer, 4198because it's now accounted for through dependencies. 4199Indicates the old directory has been removed. 4200.It "Error: change in plist between ..." 4201Error message comes from 4202.Xr register-plist 1 . 4203.It "Error: duplicate item in packing-list" 4204Error message comes from 4205.Xr pkg_create 1 , 4206and will result from incorrect packing-lists, such as including several 4207fragments with the same file, or having incorrect 4208.Ev PKG_ARGS-sub . 4209.It "Error: Libraries in packing-lists...and libraries from installed packages don't match" 4210The ports tree and the installed packages are out-of-sync. 4211Mixing library information from both sources might produce packages that can't 4212be installed elsewhere. 4213Cleanest fix is to update the out-of-date source (e.g., update the ports tree, 4214or build and install new packages). 4215Developers may use 4216.Ev PKG_CREATE_NO_CHECKS 4217instead, assuming they understand the implications. 4218See 4219.Cm print-package-args Pq Cm wantlib-args 4220for details. 4221.It "Fatal: can't flavor a SUBDIR" 4222A dependency mentions top_subdir,flavor. 4223Flavor would then be ignored, as it is only applied to individual ports. 4224.It "Fatal: can't subpackage a SUBDIR" 4225A dependency mentions top_subdir,-sub. 4226Subpackage would then be ignored, as it is only applied to individual ports. 4227.It "Fatal: flavor should never start with a digit" 4228This would utterly confuse 4229.Xr pkg_add 1 . 4230See 4231.Xr packages-specs 7 . 4232.It "Fatal: inclusion of <file> from <file>" 4233.Pa bsd.port.mk 4234or 4235.Pa bsd.port.subdir.mk 4236has been included from a 4237.Ev MODULE 4238or from 4239.Pa Makefile.inc , 4240resulting in a double inclusion. 4241This would lead to weird results, such as 4242.Ev PKG_ARGS 4243being defined twice. 4244.It "Fatal: SUBPACKAGES should always begin with -: <offending list>" 4245That is the only way to differentiate between 4246.Ev FLAVOR 4247and 4248.Ev SUBPACKAGE 4249in 4250.Xr pkgpath 7 4251specifications. 4252.It "Fatal: building ports requires correctly installed X11" 4253All file sets of the base OS, including xenocara, must be installed 4254before building ports. 4255.It "Fatal: /usr/local/lib/X11/app-defaults should exist and be a symlink" 4256/usr/local/lib/X11/app-defaults is distributed as a symlink in the 4257xshare*.tgz file set. 4258If xenocara was not fully installed before packages were added, it may 4259have been created as a directory instead. 4260.It "Fatal: the licensing info for <pkgname> is incomplete..." 4261Every port must have explicit defines of all 4262.Ev PERMIT_* 4263values. 4264.It "Fatal: Use 'env FLAVOR=flavor make' instead" 4265Arguments specified after 4266.Xr make 1 4267are hardcoded for all recursive sub-makes, and very difficult to override. 4268Thus, 4269.Ev FLAVOR 4270must be specified in the environment instead. 4271.It "Fatal: Use 'env SUBPACKAGE=-sub make' instead" 4272Arguments specified after 4273.Xr make 1 4274are hardcoded for all recursive sub-makes, and very difficult to override. 4275Thus, 4276.Ev SUBPACKAGE 4277must be specified in the environment instead. 4278.It "ldconfig: <dir>: No such file or directory" 4279Usually produced by 4280.Xr pkg_add 1 4281running 4282.Xr ldconfig 8 . 4283Some tools such as GNU libtool will add directories living under 4284.Pa ${WRKINST} 4285to the shared library path during the 4286.Cm fake 4287stage. 4288Of course, 4289.Xr ldconfig 8 4290will later complain after the directory no longer exists. 4291The bogus tool should be fixed to conform to 4292.Ox 4293usage. 4294.It LIB_DEPENDS <spec> not needed for <FULLPKGPATH> 4295There doesn't seem to be any WANTLIB to match the given LIB_DEPENDS. 4296Thus, the LIB_DEPENDS won't turn into a @depends line in the created package. 4297This is often because of confusion between LIB_DEPENDS and RUN_DEPENDS: 4298RUN_DEPENDS is needed for dlopen'd libraries. 4299.Pp 4300Might be intentional sometimes, if some compile flavors create static binaries, 4301for instance. 4302Also, will happen for multi-packages, where one sets LIB_DEPENDS to have 4303a given build dependency (and corresponding WANTLIB for a given SUBPACKAGE). 4304.Pp 4305See 4306.Cm print-package-args Pq Cm lib-depends-args 4307for details. 4308.It "Warning: FULLPKGNAME-sub defined but not FULLPKGPATH-sub" 4309.Ev FULLPKGNAME-sub 4310has been explicitly defined by the port, instead of relying on the default, 4311but no value of 4312.Ev FULLPKGPATH-sub 4313has been given. 4314This is often an error. 4315.It "Warning: no debug-info in ..." 4316Port uses 4317.Ev DEBUG_PACKAGES 4318so the 4319.Xr build-debug-info 1 4320script expects debug information on all binaries and libraries. 4321Most probably, the build machinery for that specific port omitted -g 4322somewhere, or it runs strips during fake anyway. 4323It can also occur if 4324.Ev DEBUG_PACKAGES 4325includes subpackages with no files holding debug info. 4326.It "Warning: symlink(s) point to non existent file." 4327Warning message comes from 4328.Xr pkg_create 1 . 4329The symlink resides in the fake area, under 4330.Pa ${WRKINST} . 4331This is only a warning because the symlink may point to a run-time dependency, 4332which obviously won't exist under 4333.Pa ${WRKINST} 4334at the time 4335.Ql make package 4336is run. 4337.It "Warning: @option no-default-conflict with no @conflict" 4338Warning message comes from 4339.Xr pkg_create 1 . 4340Most packages that waive "default-conflict" will have explicit conflict markers 4341instead. 4342Otherwise, the package will only conflict with the exact same version, with 4343some possible 4344.Ev REVISION 4345bumps. 4346Any other version or 4347.Ev FLAVOR 4348won't conflict. 4349This is generally an error, apart from very few ports like 4350.Pa devel/autoconf/* . 4351.It "groff produced empty result for <manpage>..." 4352Warning message comes from 4353.Xr pkg_create 1 . 4354Manpages are automatically formatted with 4355.Xr groff 1 4356if 4357.Ev USE_GROFF 4358is set. 4359The above message denotes an actual problem while formatting the page, 4360which should be addressed. 4361In the meantime, 4362.Xr pkg_create 1 4363still produces a package, but leaves the manpage unformatted, in the hope 4364that something will be able to make sense of it. 4365.El 4366.Sh SEE ALSO 4367.Xr clean-old-distfiles 1 , 4368.Xr ftp 1 , 4369.Xr pkg_add 1 , 4370.Xr pkg_create 1 , 4371.Xr OpenBSD::Intro 3p , 4372.Xr bsd.port.arch.mk 5 , 4373.Xr mk.conf 5 , 4374.Xr port-modules 5 , 4375.Xr library-specs 7 , 4376.Xr mirroring-ports 7 , 4377.Xr packages-specs 7 , 4378.Xr pkgpath 7 , 4379.Xr ports 7 4380.Sh HISTORY 4381The ports mechanism originally came from 4382.Fx . 4383A lot of additions were taken from 4384.Nx 4385over the seminal years. 4386.Pp 4387Since 1998, the framework has been systematically cleaned-up and reorganized 4388to remove bugs. 4389New features have been carefully introduced, trying hard to avoid 4390inconsistencies. 4391.Pp 4392.Ev FLAVORS , 4393.Ev MULTI_PACKAGES , 4394.Ev SEPARATE_BUILD 4395and FAKE are 4396.Ox 4397improvements. 4398Most recent additions do not come from another 4399.Bx . 4400.\" Voluntarily undocumented: 4401.\" AUTOCONF_ENV: probably not needed anyway, should be internal. 4402.Sh BUGS 4403.Ev LOCALBASE , 4404.Ev X11BASE , 4405.Ev BASESYSCONFDIR , 4406.Ev VARBASE 4407and 4408.Ev PREFIX 4409are not heeded consistently. 4410Using anything but the default values has not been heavily tested. 4411Some ports may not build if you change them. 4412