1.\" $OpenBSD: bsd.port.mk.5,v 1.577 2023/04/05 09:46:27 edd 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: April 5 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 ${CHECKSUMFILES} (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. 1202.It Ev CCACHE_DIR 1203Sets the cache directory used when 1204.Ev USE_CCACHE 1205is set to yes. 1206Defaults to ${WRKOBJDIR}/.ccache. 1207.It Ev CCACHE_ENV 1208Sets additional environment variables when 1209.Ev USE_CCACHE 1210is set to yes. 1211For instance, to enable verbose logging, set 1212CCACHE_ENV="CCACHE_LOGFILE=/tmp/ccache.log" 1213.It Ev CDIAGFLAGS 1214Flags appended to 1215.Ev CFLAGS 1216if 1217.Ev WARNINGS 1218is set. 1219.It Ev CFLAGS 1220Default flags passed to the compiler for building. 1221Many ports ignore it. 1222See also 1223.Ev COPTS , 1224.Ev CDIAGFLAGS . 1225.It Ev CHECK_LIB_DEPENDS 1226User settings. 1227If set to 1228.Sq Yes , 1229every package build will verify that shared libraries are correctly 1230registered. 1231This is essentially the same as running 1232.Ql make lib-depends-check 1233after each package build. 1234Defaults to 1235.Sq \&No , 1236as this can be a big performance hit. 1237.It Ev CHECKSUMFILES 1238List of all files that need to be retrieved by 1239.Cm fetch , 1240with 1241.Ev DIST_SUBDIR 1242prepended and with the master site selection extension removed. 1243Read-only. 1244See also 1245.Ev MAKESUMFILES . 1246.It Ev CHECKSUM_FILE 1247Location for this port's checksums, used by 1248.Cm checksum , 1249and 1250.Cm makesum . 1251Defaults to 1252.Pa distinfo . 1253.It Ev CHECKSUM_PACKAGES 1254User settings. 1255Choose whether or not to checksum packages while building. 1256Deposits result in 1257.Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cksums/${FULLPKGNAME}.sha256 . 1258Can be set to 1259.Sq Yes 1260to compute a checksum for all packages, 1261or to 1262.Sq ftp 1263to compute it only for 1264.Ev PERMIT_PACKAGE 1265packages. 1266Defaults to 1267.Sq no , 1268which does not compute a checksum at all. 1269.It Ev CHOSEN_COMPILER 1270Read-only. 1271Compiler suite chosen by the 1272.Ev COMPILER 1273mechanism. 1274Set to 1275.Sq irrelevant 1276to disable 1277.Ev COMPILER . 1278.It Ev CLEANDEPENDS 1279If set to 1280.Sq Yes , 1281the 1282.Cm clean 1283target will also clean dependencies. 1284Can be overridden on a per-${PKGPATH} basis, 1285by setting CLEANDEPENDS_${PKGPATH}. 1286.It Ev COMMENT 1287Short (no more than 60 characters) description of the port, used for 1288the package and the INDEX. 1289It should not start with an uppercase letter unless semantically 1290significant. 1291.It Ev COMMENT-foo 1292Same as COMMENT but used for sub package -foo in a multi-package setup. 1293.It Ev COMMENT-vanilla 1294Same as COMMENT but used for a flavored package, if the non-flavored comment 1295is inappropriate. 1296.It Ev COMMENT-foo-vanilla 1297Same as COMMENT but used for a sub-, flavored package. 1298.It Ev COMES_WITH 1299The first release where the port was made part of the standard 1300distribution. 1301If the current 1302.Ox 1303version is >= this version then a notice 1304will be displayed instead of the port being built. 1305.It Ev COMPILER 1306Select preferred compiler. 1307First element in the list that matches will be chosen. 1308.Bl -tag -width ports-gccxx 1309.It base-gcc 1310gcc 4.2 compiler from base 1311.It base-clang 1312clang compiler from base 1313.It gcc3 1314gcc 3 compiler from base 1315.It ports-gcc 1316gcc 8 compiler from ports 1317(heeds 1318.Ev MODGCC4_ARCHS 1319from the module) 1320.It ports-clang 1321clang compiler from ports 1322(heeds 1323.Ev MODCLANG_ARCHS 1324from the module) 1325.El 1326.Pp 1327The first compiler that matches criteria will be chosen. 1328On clang-based architectures, even though gcc is still compiled in base, 1329.Sq base-gcc 1330never matches. 1331.Pp 1332Defaults to base compilers, e.g., 1333.Sq base-clang base-gcc gcc3 . 1334.Pp 1335Common reasons for explicitly setting 1336.Ev COMPILER 1337will most often be C++11 support, thread-local-storage support (emulated), 1338atomic operations on some arches, sometimes assembler support, ABI 1339compatibility with dependent/depending ports, or plain old internal compiler 1340errors. 1341.Pp 1342With 1343.Ev COMPILER 1344in effect, 1345.Ev MODGCC4_ARCHS 1346and 1347.Ev MODCLANG_ARCHS 1348default to 1349.Sq ${GCC49_ARCHS} 1350and 1351.Sq ${LLVM_ARCHS} 1352respectively. 1353.Pp 1354.Ev ONLY_FOR_ARCHS 1355will also be set if applicable. 1356.It Ev COMPILER_LANGS 1357The value of 1358.Ev COMPILER_LANGS 1359will be added to the respective module's supported langs. 1360Defaults to 1361.Sq c c++ . 1362Only 1363.Sq c 1364and 1365.Sq c++ 1366are supported by this mechanism. 1367.Sq fortran 1368or 1369.Sq java 1370still need old modules annotations, so that it's possible 1371to select, e.g., 1372.Sq gfortran 1373from gcc 8 while having clang from base. 1374See also 1375.Ev CHOSEN_COMPILER . 1376.It Ev COMPILER_LINKS 1377Used by 1378.Nm 1379and compiler 1380.Ev MODULES 1381to build scripts in 1382.Pa ${WRKDIR}/bin 1383to force setting compiler flags 1384.Po 1385.Fl B 1386is required for clang to find 1387.Pa ${WRKDIR}/bin/ld 1388as used by 1389.Ev USE_WXNEEDED 1390.Pc 1391and call 1392.Ev COMPILER_WRAPPER 1393if used. 1394.It Ev COMPILER_WRAPPER 1395External program used to "wrap" compilers. 1396Populated automatically by 1397.Ev USE_CCACHE 1398or can be set explicitly for other purposes (e.g. distcc). 1399.It Ev CONFIG_SITE_LIST 1400Used when 1401.Li CONFIGURE_STYLE=gnu , 1402or with 1403.Li MODULES += gnu . 1404List of 1405.Pa config.site 1406fragments that will speed up gnu-configure, and prevent it from 1407preferring various gnu programs, unless 1408.Ev BUILD_DEPENDS 1409explicitly ask for them. 1410Read-only, available for debugging purposes. 1411.It Ev CLANG_ARCHS, GCC3_ARCHS , GCC4_ARCHS 1412List of architectures using Clang, GCC 3.3.6 or GCC 4.2.1 as the base compiler. 1413Read-only. 1414Use with 1415.Ev NOT_FOR_ARCHS 1416or 1417.Ev ONLY_FOR_ARCHS 1418to limit ports to architectures where they compile. 1419.It Ev CONFIGURE_ARGS 1420Arguments to pass to configure script. 1421Defaults are empty, except for 1422GNU-style configure, where prefix and sysconfdir are set. 1423.It Ev CONFIGURE_ENV 1424Basic environment passed to configure script (path and libtool setup). 1425GNU-style configure adds a lot more variables. 1426.It Ev CONFIGURE_SCRIPT 1427Set to name of script invoked by the 1428.Cm configure 1429target, if appropriate. 1430Should be either an absolute path, or relative to ${WRKSRC}. 1431.It Ev CONFIGURE_STYLE 1432Set to style of configuration that needs to happen. 1433.Pp 1434If 1435.Sq perl , 1436assume 1437.Xr perl 1 Ns 's 1438.Xr ExtUtils::MakeMaker 3p 1439style. 1440Add 1441.Sq modbuild 1442to enable 1443.Xr Module::Build 3p , 1444.Sq modbuild tiny 1445to enable 1446.Xr Module::Build::Tiny 3p , 1447or 1448.Sq modinst 1449for 1450.Xr Module::Install 3p 1451style. 1452.Pp 1453If 1454.Sq gnu , 1455assume 1456GNU configure style. 1457Add 1458.Sq dest 1459if port does not handle DESTDIR correctly, and needs to be configured to 1460add DESTDIR to prefixes 1461.Po 1462see also 1463.Ev DESTDIRNAME 1464.Pc . 1465Add 1466.Sq old 1467if port is an older autoconf port that does not recognize --sysconfdir. 1468Add 1469.Sq autoconf 1470if autoconf needs to be rerun first, 1471but set 1472.Sq no-autoheader 1473to prevent autoheader from running. 1474Alternatively, add 1475.Sq autoreconf 1476to rerun autoconf, automake, and related tools to completely regenerate 1477the GNU build framework. 1478.Pp 1479If 1480.Sq imake , 1481assume port configures using X11 ports Imakefile framework. 1482Add 1483.Sq noman 1484if port has no man pages the Imakefile should try installing. 1485.Pp 1486If 1487.Sq simple , 1488there is a configure script, but it does not fit the normal GNU configure 1489conventions. 1490.Pp 1491Extensions may be defined by specific MODULES. 1492See 1493.Xr port-modules 5 1494for details. 1495.It Ev COPTS 1496User settings. 1497Supplementary options appended to ${CFLAGS} for building. 1498Since most ports ignore the COPTS convention, they are actually told to use 1499${CFLAGS} ${COPTS} as CFLAGS. 1500.It Ev CXXDIAGFLAGS 1501Flags appended to 1502.Ev CXXFLAGS 1503if 1504.Ev WARNINGS 1505is set. 1506.It Ev CXXFLAGS 1507Default flags passed to the C++ compiler for building. 1508Many ports ignore it. 1509.It Ev CXXOPTS 1510User settings. 1511Supplementary options appended to ${CXXFLAGS} for building. 1512.It Ev DEBUG_CONFIGURE_ARGS 1513Supplementary ${CONFIGURE_ARGS} 1514for enabling the generation of debugging information. 1515.It Ev DEBUG_PACKAGES 1516List of ${SUBPACKAGES} for which debug packages should be built "on the side". 1517Usually set as 1518.Li DEBUG_PACKAGES=${BUILD_PACKAGES} 1519for packages where debug information is desirable. 1520Note the subpackages with 1521.Li PKG_ARCH=* 1522will automatically be stripped from that list. 1523See 1524.Sx THE DEBUG_PACKAGES INFRASTRUCTURE 1525below for details. 1526.It Ev DEBUGINFO_ARCHS 1527List of archs for which debug information may be provided as extra packages. 1528Normally only amd64 for performance reasons. 1529.It Ev DESTDIR 1530See 1531.Ev DESTDIRNAME . 1532.It Ev DESTDIRNAME 1533Name of variable to set to ${WRKINST} while faking. 1534Usually DESTDIR. 1535To be used in the rare cases where a port heeds DESTDIR in a few 1536directories and needs to be configured with 1537.Sq gnu dest , 1538so that those few directories do not get in the way. 1539.It Ev DISTDIR 1540User settings. 1541Directory where all ports distribution files and patchfiles are stashed. 1542Defaults to 1543.Pa ${PORTSDIR}/distfiles . 1544Override if distribution files are stored elsewhere. 1545Always use 1546.Ev FULLDISTDIR 1547to refer to ports' distribution files location, as it takes an eventual 1548.Ev DIST_SUBDIR 1549into account. 1550.It Ev DISTFILES 1551The main port's distribution files (the actual software source, except 1552for binary-only ports). 1553Will be retrieved from the MASTER_SITES (see 1554.Cm fetch ) , 1555checksummed and extracted (see 1556.Cm checksum , 1557.Cm extract ) . 1558.Ev DISTFILES 1559normally holds a list of files, possibly with 1560.Sq :0 1561to 1562.Sq :9 1563appended to select a different 1564.Ev MASTER_SITES . 1565.Pp 1566Each entry may optionally be of the form 1567.Sq Ar filename Ns { Ns Ar url Ns } Ns Ar sufx 1568to deal with sites that only offer archives as weird urls, doing the transfer 1569of 1570.Ar url Ns Ar sufx 1571into result file 1572.Ar filename Ns Ar sufx . 1573For instance, if 1574.Bd -literal 1575DISTFILES = minetest-{minetest/archive/}${V}${EXTRACT_SUFX} 1576.Ed 1577.Pp 1578then 1579.Cm fetch 1580will retrieve from url 1581.Sq minetest/archive/${V}${EXTRACT_SUFX} 1582into 1583.Sq minetest-${V}${EXTRACT_SUFX} . 1584.Pp 1585If ${DISTFILES} varies depending on 1586.Ev FLAVORS 1587or architecture, use 1588.Ev SUPDISTFILES 1589to ensure distfiles mirroring and 1590.Cm makesum 1591proper operation. 1592.It Ev DISTNAME 1593Name used to identify the port. 1594See 1595.Ev DISTFILES 1596and 1597.Ev PKGNAME . 1598.It Ev DISTORIG 1599Suffix used by 1600.Cm distpatch 1601to rename original files. 1602Defaults to 1603.Pa .bak.orig . 1604Distinct from 1605.Ev PATCHORIG 1606to avoid confusing 1607.Cm update-patches . 1608.It Ev DIST_SUBDIR 1609Optional subdirectory of ${DISTDIR} where the current port's distribution 1610files and patchfiles will be located. 1611See target 1612.Cm fetch . 1613.It Ev DPB 1614Set by the Distributed Ports Builder to only get the information it needs 1615from 1616.Cm dump-vars . 1617.It Ev DPB_LOCKNAME 1618If set, 1619.Xr dpb 1 1620will use this instead of the default 1621.Ev PKGPATH Ns - Ns 1622derived name. 1623This feature comes with large restrictions and shouldn't be used unless 1624absolutely necessary. 1625Specifically, it can allow 1626.Nm dpb 1627to build several flavors of the same port at the same time, 1628but beware: under 1629.Ev MULTI_PACKAGES 1630and 1631.Ev PSEUDO_FLAVORS 1632conditions, if some of these packages are identical across flavors, 1633this will not work. 1634This also makes it harder to interact with locks if the names are not obvious. 1635.It Ev DPB_PROPERTIES 1636Annotations for the Distributed Ports Builder. 1637See 1638.Xr dpb 1 1639for semantics. 1640.It Ev DUMMY_PACKAGE 1641If defined, 1642.Nm 1643will provide dummy values for variables mandatory for a minimally functional 1644port. 1645Used by various pieces of the ports tree to perform introspection and get to 1646.Nm Ns 's 1647variables. 1648.It Ev ECHO_MSG 1649User settings. 1650Used to display 1651.Sq ===> Configuring for foo 1652and similar informative messages. 1653Override to turn off, for instance. 1654.It Ev ECHO_REORDER 1655User settings. 1656Set it to 1657.Sq echo 1658to see 1659.Ev REORDER_DEPENDENCIES 1660actions. 1661Silent by default. 1662.It Ev EDIT_PATCHES 1663User settings. 1664If set to 1665.Sq \&No , 1666.Cm update-patches 1667will not open changed files in an editor. 1668.It Ev EPOCH 1669Epoch number of the current package. 1670Used when the port version is changed but the new version is not regarded by 1671.Xr packages-specs 7 1672as being newer. 1673Once added, it cannot be removed or go backwards. 1674Defaults to empty (no need for numbering changes), then 1675numbering starts at 0. 1676Gets automatically incorporated into 1677.Ev FULLPKGNAME 1678as 1679.Sq v${EPOCH} 1680to form a full package-name conforming to 1681.Xr packages-specs 7 . 1682.It Ev ERRORS 1683List of errors found while parsing the port's Makefile. 1684Display the errors before making any target, and if any error starts with 1685.Qq Fatal : , 1686do not make anything. 1687For instance: 1688.Bd -literal -offset indent 1689\&.if !defined(COMMENT) 1690ERRORS+="Fatal: Missing comment" 1691\&.endif 1692.Ed 1693Porter can add to 1694.Ev ERRORS , 1695for instance to flag erroneous combinations of 1696.Ev FLAVORS 1697(but see 1698.Ev ONLY_FOR_ARCHS 1699.Ev NOT_FOR_ARCHS 1700and 1701.Ev BROKEN 1702for other common issues). 1703.It Ev EXTRACT_CASES 1704In the normal extraction stage (when 1705.Ev EXTRACT_ONLY 1706is not empty), this is the contents of a 1707.Xr sh 1 1708.Em case conditional , 1709used to extract files. 1710Fragments are automatically appended to extract the following archives and 1711add the relevant compression tool to 1712.Ev BUILD_DEPENDS : 1713.Pp 1714.Bl -tag -width archivers/lzip/lunzip -offset indent -compact 1715.It gzip 1716tar.gz, tgz 1717.It tar 1718tar 1719.It archivers/bzip2 1720tar.bz2, tbz2, tbz 1721.It archivers/xz 1722tar.xz, tar.lzma, tar.lz 1723.It archivers/unzip 1724zip 1725.It archivers/zstd 1726tar.zst, tar.zstd 1727.It converters/rpm2cpio 1728rpm 1729.El 1730.Pp 1731Other cases not supported directly in 1732.Nm 1733can be added, and existing cases can be overridden. 1734For example the following example sets extra conversion flags to unzip, 1735and adds support for rar: 1736.Bd -literal 1737 *.zip) ${UNZIP} -Laq ${FULLDISTDIR}/$$archive -d ${WRKDIR};; \\ 1738 *.rar) ${LOCALBASE}/bin/unrar x -idq ${DISTDIR}/$$archive;; 1739.Ed 1740.It Ev EXTRACT_ONLY 1741Set to the list of distfiles to actually extract if some distfiles 1742should not be extracted during the 1743.Cm do-extract 1744stage. 1745Defaults to all distfiles, can even be set to empty. 1746.It Ev EXTRACT_SUFX 1747Used to set DISTFILES default value to ${DISTNAME}${EXTRACT_SUFX}. 1748The decompression tool needed will be automatically added as 1749.Ev BUILD_DEPENDS . 1750Default value is .tar.gz. 1751.It Ev EXTRACT_FILES 1752Set to the list of files to actually extract from distfiles. 1753Its content is subject to shell evaluation as part of 1754.Ev EXTRACT_CASES 1755and passed as 1756.Ar file ... 1757argument to 1758.Xr tar 1 1759or 1760.Xr unzip 1 , 1761e.g., 1762.Xr glob 7 1763patterns and shell brace expansion may be used. 1764Empty by default to extract all files. 1765.It Ev FAKE_FLAGS 1766Extra flags passed to ${MAKE_PROGRAM} during the 1767fake invocation. 1768Empty by default. 1769Also see 1770.Ev ALL_FAKE_FLAGS . 1771.It Ev FAKE_SETUP 1772List of environment values normally set during fake invocations. 1773Exposed so that modules may provide their own 1774.Cm do-install . 1775Read-only, 1776see 1777.Sx THE FAKE FRAMEWORK 1778section for details. 1779.It Ev FAKE_TARGET 1780Target built by ${MAKE_PROGRAM} on fake invocation. 1781Defaults to ${INSTALL_TARGET}. 1782.It Ev FAKEOBJDIR 1783User settings. 1784If non empty, used as a base for the fake area. 1785The real fake directory ${WRKINST} is created there. 1786Can be set on a per-${PKGPATH} basis. 1787For instance, setting FAKEOBJDIR_www/mozilla-firefox=/tmp/obj 1788will affect only the mozilla-firefox port. 1789.It Ev FETCH_CMD 1790User settings. 1791Command used to fetch distribution files for this port. 1792Defaults to 1793.Xr ftp 1 . 1794Can be used to go through excessively paranoid firewalls. 1795Note that 1796.Ev FETCH_CMD 1797should support a few ftp options, chief among them 1798being 1799.Fl C 1800and 1801.Fl o Ar dest , 1802but also 1803.Fl m , 1804.Fl S , 1805.Fl v , 1806.Fl V . 1807Most of these can be no-ops in a FETCH_CMD script, 1808See 1809.Pa ${PORTSDIR}/infrastructure/template/fetch_cmd.template 1810for a skeleton script. 1811.It Ev FETCH_MANUALLY 1812Some ports' distfiles cannot be fetched automatically for licensing reasons. 1813In this case, set 1814.Ev FETCH_MANUALLY 1815to a list of strings that will be displayed, one per line, e.g., 1816.Bd -literal 1817FETCH_MANUALLY= "You must fetch foo-1.0.tgz" 1818FETCH_MANUALLY+="from http://www.fubar.com/ manually," 1819FETCH_MANUALLY+="after reading and agreeing to the license." 1820.Ed 1821Behaves like 1822.Ev IS_INTERACTIVE 1823if some distribution files are missing. 1824.It Ev FETCH_PACKAGES 1825User settings, defaults to 1826.Sq \&No . 1827Set to 1828.Xr pkg_add 1 1829options. 1830Instruct the 1831.Cm package 1832target to download packages missing from the repository from locations in 1833${PKG_PATH} and place them into 1834.Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cache/ , 1835only building them if no suitable packages are found. 1836For instance, 1837.Bd -literal -offset indent 1838make FETCH_PACKAGES= 1839.Ed 1840.Pp 1841to use without any options, or 1842.Bd -literal -offset indent 1843make FETCH_PACKAGES=-Dsnap 1844.Ed 1845.Pp 1846to use close to release. 1847.It Ev FILESDIR 1848Location of other files related to the current port. 1849Default: files. 1850.It Ev FETCH_USER 1851User to use to fetch distfiles when using 1852.Ev PORTS_PRIVSEP , 1853defaults to 1854.Sq _pfetch . 1855.It Ev FIX_CLEANUP_PERMISSIONS 1856If 1857.Sq Yes , 1858restore read, write and directory search permissions for the build user on 1859.Pa ${WRKDIR} 1860before running 1861.Cm clean . 1862Used for build systems which set paranoid permissions at build time. 1863Defaults to 1864.Sq \&No . 1865.It Ev FIX_CRLF_FILES 1866Name(s) of files with line endings to correct at the end of 1867.Cm distpatch . 1868Sometimes a port will include files with MS-DOS line endings (CR LF). 1869To avoid problems with patches (especially when sent by email) 1870these should be converted to LF. 1871.Nm 1872changes to WRKDIST before converting files - shell wildcards may be used. 1873.It Ev FIX_EXTRACT_PERMISSIONS 1874If 1875.Sq Yes , 1876restore contents of 1877.Pa ${WRKDIR} 1878to world-readable at the end of 1879.Cm extract . 1880Used for some distfile contents which have paranoid permissions for no reason. 1881Defaults to 1882.Sq \&No . 1883.It Ev FLAVOR 1884The port's current options. 1885Set by the user, and tested by the port to activate wanted functionalities. 1886.It Ev FLAVORS 1887List of all flavors keywords a port may match. 1888Used to sort 1889.Ev FLAVOR 1890into a canonical order to build the package name, 1891or to select the packing-list, and as a quick validity check. 1892See also 1893.Ev PSEUDO_FLAVORS . 1894.It Ev FLAVOR_EXT 1895Canonical list of flavors being set for the current build, dash-separated. 1896See 1897.Ev FULLPKGNAME . 1898.It Ev FORCE_UPDATE 1899User settings. 1900If set to 1901.Sq Yes , 1902the 1903.Cm update 1904target will always update an installed package, 1905as soon as its signature differs, 1906and all dependencies that install packages will 1907also force an update. 1908If set to 1909.Sq hard , 1910the 1911.Cm update 1912target will also update installed packages even when the signature 1913did not change. 1914.It Ev FULLDISTDIR 1915Complete path to directory where ${DISTFILES} and ${PATCHFILES} will be 1916located, to be used in hand-crafted extraction targets. 1917Read-only. 1918.It Ev FULLPKGNAME 1919Full name of the created package, taking flavors into account. 1920Defaults to ${PKGNAME}${FLAVOR_EXT}. 1921See also 1922.Ev EPOCH 1923and 1924.Ev REVISION . 1925.It Ev FULLPKGPATH 1926Path to the current port's directory, relative to ${PORTSDIR}, 1927including flavors and subpackages. 1928See 1929.Xr pkgpath 7 . 1930.It Ev GH_* 1931Support for GitHub-hosted projects. 1932Leave empty for non hosted projects. 1933Yields a suitable default for 1934.Ev MASTER_SITES_GITHUB 1935and 1936.Ev DISTNAME . 1937.It Ev GH_ACCOUNT 1938Account name of the GitHub user hosting the project. 1939.It Ev GH_COMMIT 1940SHA1 commit id to fetch. 1941It is an error to specify ${GH_COMMIT} when ${GH_TAGNAME} is specified. 1942.It Ev GH_DISTFILE 1943Set by 1944.Nm 1945to the generated name of the distribution file. 1946This can be useful for ports listing multiple 1947.Ev DISTFILES . 1948.It Ev GH_PROJECT 1949Name of the project on GitHub. 1950.It Ev GH_TAGNAME 1951Name of the tag to download. 1952Setting ${GH_TAGNAME} to master is invalid 1953and will throw an error. 1954${WRKDIST} is auto-generated based on the 1955${GH_TAGNAME} if specified, otherwise ${GH_COMMIT} will be used to generate 1956${WRKDIST}. 1957.It Ev GMAKE 1958Location of the GNU make binary, if needed. 1959Defaults to gmake. 1960.It Ev HOMEPAGE 1961URL to the homepage of the software, if applicable. 1962.It Ev IGNORE 1963For ignored ports, set to the reasons for which the port is ignored. 1964If non-empty, most common targets that do something (e.g., 1965.Cm fetch , 1966.Cm build , 1967.Cm install No ... ) 1968will be ignored. 1969See also 1970.Ev BATCH , 1971.Ev BROKEN , 1972.Ev FETCH_MANUALLY , 1973.Ev IGNORE_IS_FATAL , 1974.Ev IGNORE_SILENT , 1975.Ev INTERACTIVE , 1976.Ev IS_INTERACTIVE , 1977.Ev NOT_FOR_ARCHS , 1978.Ev NO_IGNORE , 1979.Ev ONLY_FOR_ARCHS . 1980.It Ev IGNORE_IS_FATAL 1981User settings. 1982If set to 1983.Sq Yes , 1984ignored ports will become fatal errors. 1985.It Ev IGNORE_SILENT 1986User settings. 1987If set to 1988.Sq Yes , 1989do not print anything when ignoring a port. 1990.It Ev INSTALL_DEBUG_PACKAGES 1991User settings. 1992Defaults to 1993.Sq \&No . 1994If 1995.Sq Yes , 1996install available debug packages during all install/update targets. 1997.It Ev INSTALL_{PROGRAM,SCRIPT,DATA,MAN}[_DIR] 1998Macros to use to install a program, a script, data, or a man page (or the 1999corresponding directory), respectively. 2000.It Ev INSTALL_TARGET 2001Target invoked to install the software, during fake installation. 2002Default is 2003.Sq install . 2004.It Ev INTERACTIVE 2005User settings. 2006Set to 2007.Sq Yes 2008to skip all non-interactive ports. 2009Used in conjunction with 2010.Ev BATCH 2011to simplify bulk-package builds. 2012.It Ev IS_INTERACTIVE 2013Set to 2014.Sq Yes 2015if port needs human interaction to build. 2016Porters should strive to minimize 2017.Ev IS_INTERACTIVE 2018ports, by using 2019.Ev FLAVORS 2020for multiple choice ports, and by postponing human intervention 2021to package installation time. 2022.It Ev LE_ARCHS 2023Set to the list of little-endian architectures. 2024Read-only. 2025Use with 2026.Ev NOT_FOR_ARCHS 2027and 2028.Ev ONLY_FOR_ARCHS . 2029.It Ev LIB_DEPENDS 2030List of packages used by a port for its library dependencies. 2031Each item has the form 2032.Sq [pkgspec:]pkgpath . 2033Similar to 2034.Ev BUILD_DEPENDS 2035and 2036.Ev RUN_DEPENDS , 2037but with specific rules: 2038.Ev LIB_DEPENDS 2039always turn into 2040.Ev BUILD_DEPENDS 2041.Po 2042but see 2043.Sx FLAVORS AND MULTI PACKAGES 2044.Pc . 2045.Pp 2046.Ev LIB_DEPENDS 2047is also used as a run-time dependency, and recorded in the package as 2048such, if any of the libraries mentioned in 2049.Ev WANTLIB 2050is a shared library that originates within the dependent port. 2051.Pp 2052See 2053.Xr library-specs 7 2054for more details. 2055.It Ev lib_depends_args 2056Controls the behavior of 2057.Xr pkg_create 1 2058related targets, see 2059.Cm print-package-args 2060for details. 2061.It Ev LIBCXX 2062List of standard C++ libraries for the base compiler. 2063Read-only. 2064Use in 2065.Ev WANTLIB . 2066.It Ev LIBTOOL 2067Location of the libtool binary. 2068Default: 2069.Pa /usr/bin/libtool . 2070.It Ev LIBTOOL_FLAGS 2071Arguments to pass to libtool. 2072If USE_LIBTOOL is set, the environment variable LIBTOOL is set 2073to ${LIBTOOL} ${LIBTOOL_FLAGS}. 2074.It Ev LLD_EMUL 2075As 2076.Xr ld.lld 1 2077does not have a default emulation mode, 2078if it is the linker in-use, 2079.Ev LLD_EMUL 2080defaults to the correct option to set the emulation mode; 2081Otherwise, it stays empty. 2082Read-only. 2083Seldom used, as it is only needed to link binary data without using the 2084compiler. 2085.It Ev LLVM_ARCHS 2086Set to the list of architectures where LLVM/Clang could be used, 2087e.g., via lang/clang port module, see 2088.Xr port-modules 5 . 2089Read-only. 2090Use with 2091.Ev NOT_FOR_ARCHS 2092or 2093.Ev ONLY_FOR_ARCHS . 2094.It Ev LOCALBASE 2095where other ports have already been installed. 2096Default: 2097.Pa /usr/local . 2098.It Ev LOCALSTATEDIR 2099Location for this port's state directory, should always be derived 2100from 2101.Ev BASELOCALSTATEDIR , 2102which defaults to 2103.Pa /var . 2104Passed to gnu configure scripts. 2105.It Ev LOCKDIR 2106User settings. 2107Defaults to 2108.Pa ${WRKOBJDIR}/locks . 2109If set, points to a local directory common for all instances of 2110concurrent ports builds. 2111.It Ev LOCK_CMD 2112Expands to a command that will acquire a lock, namely 2113.Xr portlock 1 . 2114See also 2115.Xr ports 7 . 2116.It Ev LOCK_VERBOSE 2117User settings. 2118Defaults to 2119.Sq \&No . 2120Set to 2121.Sq Yes 2122to show every acquire/release lock operation. 2123.It Ev LP64_ARCHS 2124Set to the list of 64-bit architectures. 2125Read-only. 2126Use with 2127.Ev NOT_FOR_ARCHS . 2128.It Ev MAINTAINER 2129Email address with full name of the port's maintainer. 2130Defaults to 2131.Mt ports@openbsd.org . 2132.It Ev MAKE_ENV 2133Environment variables passed to make invocations and tests. 2134Sets at least PATH, PREFIX, LOCALBASE, X11BASE, CFLAGS, TRUEPREFIX, DESTDIR, 2135and the BSD_INSTALL_* macros. 2136.It Ev MAKE_FLAGS 2137Flags used for all make invocations, except for the 2138.Cm fake 2139stage, which adds 2140.Ev FAKE_FLAGS 2141(see 2142.Ev ALL_FAKE_FLAGS ) 2143and for the 2144.Cm test 2145stage, which adds 2146.Ev TEST_FLAGS 2147(see 2148.Ev ALL_TEST_FLAGS ) . 2149.It Ev MAKE_FILE 2150Name of the Makefile used for ports building. 2151Defaults to Makefile. 2152Used after changing directory to ${WRKBUILD}. 2153.It Ev MAKE_JOBS 2154Number of jobs to use when building the port, normally passed to 2155.Ev MAKE_PROGRAM 2156through 2157.Ev PARALLEL_MAKE_FLAGS . 2158Mostly set automatically when 2159.Ev DPB_PROPERTIES 2160contains 2161.Sq parallel . 2162.Pp 2163Note that 2164.Xr make 1 2165still has bugs that may prevent parallel build from working correctly! 2166.It Ev MAKE_PROGRAM 2167The make program that is used for building the port. 2168Set to ${MAKE} or ${GMAKE} depending on USE_GMAKE. 2169Read-only. 2170.It Ev MAKEFILE_LIST 2171Introspection variable, see 2172.Xr make 1 . 2173.It Ev MAKESUMFILES 2174List of all files that need to be retrieved by 2175.Cm fetch-all , 2176with 2177.Ev DIST_SUBDIR 2178prepended and with master site selection extension removed. 2179Read-only. 2180See also 2181.Ev CHECKSUMFILES . 2182.It Ev MASTER_SITE_BACKUP 2183User settings. 2184List of sites to try after normal master sites. 2185Normally includes ${MASTER_SITE_OPENBSD} and ${MASTER_SITE_FREEBSD}. 2186.It Ev MASTER_SITE_* 2187Lists of standard sites to retrieve files from, refer to 2188.Pa ${PORTSDIR}/infrastructure/db/network.conf 2189for a complete list. 2190.Pp 2191Generally used with the standard 2192.Xr make 1 Ns 's 2193.Li ${VARIABLE:=subdir/} 2194construct to append the relevant subdir at the end of each entry, e.g., 2195.Dl MASTER_SITES = ${MASTER_SITE_GNU:=cgicc/} 2196.It Ev MASTER_SITES 2197List of primary locations from which distribution files and patchfiles are 2198retrieved. 2199See the 2200.Cm fetch 2201target for details. 2202Defaults to ${MASTER_SITES_GITHUB} for GitHub-hosted projects, 2203see 2204.Ev GH_* . 2205See 2206.Xr ports 7 2207for user configuration. 2208.It Ev MASTER_SITES0 , ... , MASTER_SITES9 2209Supplementary locations from which distribution files and patchfiles are 2210retrieved. 2211.It Ev MESSAGE 2212File recorded in the package and displayed during installation. 2213Defaults to ${PKGDIR}/MESSAGE if this file exists. 2214Leave empty if no message is needed. 2215.It Ev MISSING_FILES 2216When 2217.Ev FETCH_MANUALLY 2218is set, 2219.Ev MISSING_FILES 2220will contain the list of missing distfiles or patchfiles that need to 2221be fetched manually. 2222Read-only. 2223.It Ev MTREE_FILE 2224.Xr mtree 8 2225specification used during 2226.Ar fake . 2227Replaced by direct use of 2228.Xr mkdir 1 2229now that 2230.Ar fake 2231no longer happens as root. 2232.It Ev MODGNU_CONFIG_GUESS_DIRS 2233If a port uses config.guess outside WRKSRC, the directories 2234containing the other copies must be set here. 2235.It Ev MODPERL_ADJ_FILES 2236If any files have a Perl shebang line, which needs to be replaced 2237with 2238.Dq #!/usr/bin/perl , 2239list them in 2240.Ev MODPERL_ADJ_FILES . 2241File paths here should be relative to 2242.Ev WRKSRC . 2243These files are patched automatically at the end of 2244.Cm pre-configure . 2245.It Ev MODPERL_BIN_ADJ 2246Shell fragment to patch the Perl interpreter path in executable scripts. 2247Used by 2248.Ev MODPERL_ADJ_FILES . 2249.It Ev MODPERL_BUILD_TARGET 2250Normal content of 2251.Cm do-build 2252when 2253.Ev CONFIGURE_STYLE 2254uses perl. 2255Provided as a separate variable if a port wants to override 2256.Cm do-build 2257for its own reasons. 2258.It Ev MODPERL_INSTALL_TARGET 2259Likewise for 2260.Cm do-install . 2261.It Ev MODPERL_TEST_TARGET 2262Likewise for 2263.Cm do-test . 2264.It Ev MODPERL_REGEN_PPPORT 2265Normally, if ppport.h is present, 2266it will be regenerated using a current version of 2267.Xr Devel::PPPort 3p . 2268Set to the filename under 2269.Pa ${WRKSRC} , 2270or 2271.Sq \&No 2272to disable. 2273Defaults to 2274.Sq ppport.h . 2275.It Ev MODULES 2276External modules mechanism, documented separately. 2277Modules such as 2278.Sq imake 2279and 2280.Sq gnu 2281are normally included automatically with the right 2282.Ev CONFIGURE_STYLE . 2283Note that it is possible to 2284.Li CONFIGURE_STYLE = simple , 2285.Li MODULES += gnu 2286to just get the effects of 2287.Ev CONFIG_SITE 2288and 2289.Ev MODGNU_CONFIG_GUESS_DIRS 2290along with the default 2291.Ev TEST_TARGET , 2292in case the normal GNU configure script was wrapped in a separate script that 2293takes different arguments. 2294See 2295.Xr port-modules 5 . 2296.It Ev MULTI_PACKAGES 2297Set to a list of subpackage extensions for ports that create multiple packages. 2298See 2299.Sx FLAVORS AND MULTI_PACKAGES 2300below. 2301Especially read the part about 2302.Ev ONLY_FOR_ARCHS 2303when some of the packages only exist for some architectures. 2304.It NO_ARCH 2305Location for arch-independent packages. 2306Defaults to 2307.Sq no-arch . 2308Normally, packages are generated under ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}, 2309except for packages where PKG_ARCH=*, which end up under 2310${PACKAGE_REPOSITORY}/${NO_ARCH}. 2311.It Ev NOT_FOR_ARCHS 2312List of architectures on which this port does not build. 2313See also 2314.Ev ONLY_FOR_ARCHS . 2315.It Ev NO_BUILD 2316Set to 2317.Sq Yes 2318if port does not need any build stage. 2319.It Ev NO_CCACHE 2320Set to 2321.Sq Yes 2322to prevent ccache from being used when building a certain port, 2323even when 2324.Ev USE_CCACHE 2325is set. 2326.It Ev NO_CHECKSUM 2327Set to 2328.Sq Yes 2329by 2330.Xr dpb 1 2331to avoid 2332.Cm checksum 2333entirely, 2334as 2335.Xr dpb 1 2336already deals with checksums internally. 2337.It Ev NO_DEPENDS 2338User settings. 2339Don't verify build of dependencies. 2340Do not use in any ports Makefile. 2341This is only meant as a user convenience when, e.g., you just want to browse 2342through a given port's source and do not wish to trigger the build of 2343dependencies. 2344.It Ev NO_IGNORE 2345User settings. 2346If set to 2347.Sq Yes , 2348avoid ignoring a port for the usual reasons. 2349Use, for instance, for fetching all distribution files, or for fixing a 2350broken port. 2351See also 2352.Ev IGNORE 2353and 2354.Ev TRY_BROKEN . 2355.It Ev NO_TEST 2356Port does not have any regression tests. 2357Only set to 2358.Sq Yes 2359for ports with no regression test. 2360It should be left alone for ports with empty regression tests, and for 2361ports with failing tests. 2362That way, if a subsequent update of a port acquires actual regression tests, 2363they will be picked up automatically. 2364.It Ev ONLY_FOR_ARCHS 2365List of architectures on which this port builds. 2366Can hold both processor-specific information (e.g., powerpc), and more 2367specific model information (e.g., macppc). 2368This is subpackage dependent. 2369Read the corresponding part of 2370.Sx FLAVORS AND MULTI_PACKAGES 2371if some subpackages should only be built on some architectures. 2372.It Ev OSREV 2373Revision number of 2374.Ox . 2375Read-only. 2376.It Ev PACKAGE_REPOSITORY 2377User settings. 2378Location for built packages. 2379Defaults to 2380.Pa ${PORTSDIR}/packages . 2381See 2382.Cm package 2383for details. 2384.It Ev PARALLEL_MAKE_FLAGS 2385Used when 2386.Ev DPB_PROPERTIES 2387contains 2388.Sq parallel . 2389Flags to pass to 2390.Ev MAKE_PROGRAM 2391to yield a parallel build. 2392Defaults to 2393.Li -j${MAKE_JOBS} . 2394Mostly set to empty by ports that use other mechanisms for setting the number 2395of jobs. 2396.It Ev PARALLEL_MAKE_JOBS 2397User settings. 2398Value of 2399.Ev MAKE_JOBS 2400to use when building manually a port with 2401.Ev DPB_PROPERTIES 2402containing 2403.Sq parallel . 2404Defaults to the number of online cpus. 2405.It Ev PATCH 2406Command to use to apply all patches. 2407Defaults to 2408.Pa /usr/bin/patch . 2409.It Ev PATCHORIG 2410Suffix used by 2411.Cm patch 2412to rename original files, and 2413.Cm update-patches 2414to re-generate 2415.Pa ${PATCHDIR}/${PATCH_LIST} 2416by looking for files using this suffix. 2417Defaults to 2418.Pa .orig.port . 2419In the unlikely event that one of the ${DISTFILES} already contains 2420.Pa .orig.port 2421files, set this to something else, such as 2422.Pa .orig.obsdport . 2423See also 2424.Cm distpatch , 2425.Ev DISTORIG . 2426.It Ev PATCH_CASES 2427In the normal 2428.Cm distpatch 2429stage (when 2430.Ev PATCHFILES 2431is not empty), this is the contents of a case statement, used to apply 2432distribution patches. 2433Fragments are automatically appended to handle gzip'ed, bzip'ed and lzip'ed 2434patches, so that the default case is more or less equivalent to the following 2435shell fragment: 2436.Bd -literal 2437set -e 2438cd ${FULLDISTDIR} 2439for patchfile in ${_LIST_PATCHFILES} 2440do 2441 case $$patchfile in 2442 *.bz2) 2443 ${BZIP2} -d <$$patchfile | ${PATCH} ${PATCH_DIST_ARGS};; 2444 *.zst|*.zstd) 2445 zstdcat -c <$$patchfile | ${PATCH} ${PATCH_DIST_ARGS};; 2446 *.Z|*.gz) 2447 ${GZIP_CMD} -d <$$patchfile | ${PATCH} ${PATCH_DIST_ARGS};; 2448 *) 2449 ${PATCH} ${PATCH_DIST_ARGS} <$$patchfile;; 2450 esac 2451done 2452.Ed 2453.It Ev PATCHDIR 2454Location for patches applied by the 2455.Cm patch 2456target. 2457Default: 2458.Pa patches . 2459.It Ev PATCHFILES 2460Files to fetch from the master sites like 2461.Ev DISTFILES , 2462but serving a different purpose, as they hold distribution patches that 2463will be applied at the 2464.Cm patch 2465stage. 2466See also 2467.Ev SUPDISTFILES . 2468.It Ev PATCH_ARGS 2469Full list of options used while applying port's patches. 2470.It Ev PATCH_CHECK_ONLY 2471Set to 2472.Sq Yes 2473by the 2474.Cm checkpatch 2475target. 2476Don't touch unless the default 2477.Cm checkpatch 2478target needs to be redefined. 2479Ideally, user-defined patch subtargets ought to test checkpatch. 2480In practice, they don't. 2481.It Ev PATCH_DEBUG 2482If set to 2483.Sq Yes , 2484the 2485.Cm patch 2486stage will output extra debug information. 2487This is the default. 2488.It Ev PATCH_DIST_ARGS 2489Full list of options used while applying distribution patches. 2490.It Ev PATCH_DIST_STRIP 2491Patch option used to strip directory levels while applying distribution 2492patches. 2493Defaults to -p0. 2494.It Ev PATCH_LIST 2495Wildcard pattern of patches to select under ${PATCHDIR}. 2496Defaults to patch-*. 2497Note that filenames ending in .orig, or ~ are never applied. 2498Note that 2499.Ev PATCH_LIST 2500can hold absolute pathnames, for instance to share patches among similar 2501ports: 2502.Bd -literal 2503PATCH_LIST=${PORTSDIR}/x11/kde/libs2/patches/p-* patch-* 2504.Ed 2505.It Ev PATCH_STRIP 2506Patch option used to strip directory levels while applying port's patches. 2507Defaults to -p0. 2508.It Ev PERMIT_DISTFILES , PERMIT_PACKAGE 2509Set to 2510.Sq Yes 2511if the distribution files or the package can be allowed on FTP sites without 2512legal issues. 2513Set to reason not to otherwise. 2514PERMIT_* lines in the Makefile should be preceded with a comment explaining 2515details about licensing and patents issues the port may have. 2516Porters must be very thorough in their checks. 2517In case of doubt, ask. 2518.Pp 2519If 2520.Ev PERMIT_PACKAGE 2521is set to 2522.Sq Yes , 2523.Ev PERMIT_DISTFILES 2524will default to 2525.Sq Yes . 2526.It Ev PKG_ADD 2527User settings. 2528Path to 2529.Xr pkg_add 1 2530command, with possible options. 2531.It Ev PKG_ARCH 2532Comma-separated list of architectures on which this package may install. 2533Defaults to ${MACHINE_ARCH},${ARCH}. 2534.Pp 2535For instance: 2536.Ev MACHINE_ARCH Ns = Ns Ar powerpc , 2537.Ev ARCH Ns = Ns Ar macppc . 2538.Pp 2539Most (if not all packages) will install correctly according to 2540.Ev MACHINE_ARCH . 2541.Pp 2542Use * for arch-independent packages 2543.Po 2544see also 2545.Sx THE DEBUG_PACKAGES INFRASTRUCTURE 2546.Pc . 2547.It Ev PKG_ARGS 2548Special arguments to pass to 2549.Xr pkg_create 1 , 2550in addition to the default ones. 2551For mips64 and pic libraries, see 2552.Sx THE GENERATION OF PACKAGE INFORMATION . 2553.It Ev PKG_CREATE 2554User settings. 2555Path to 2556.Xr pkg_create 1 2557command, with possible options. 2558.It Ev PKG_CREATE_NO_CHECKS 2559Porters switch. 2560Set to 2561.Sq Yes 2562to avoid checking the ports tree when solving 2563.Ev WANTLIB 2564.Po 2565see 2566.Cm wantlib-args 2567.Pc . 2568May result in bogus packages that mix 2569.Cm @depends 2570lines obtained from 2571the ports tree with 2572.Cm @wantlib 2573lines that come from the installed system. 2574Set to 2575.Sq Warn 2576to have the differences printed as a warning instead of an error 2577.Po 2578the default 2579.Pc . 2580.It Ev PKG_DBDIR 2581User settings. 2582Path to package installation records. 2583Defaults to 2584.Pa /var/db/pkg . 2585.It Ev PKG_DELETE 2586User settings. 2587Path to 2588.Xr pkg_delete 1 2589command, with possible options. 2590.It Ev PKG_INFO 2591User settings. 2592Path to 2593.Xr pkg_info 1 2594command, with possible options. 2595.It Ev PKG_TMPDIR 2596See 2597.Xr pkg_add 1 . 2598Normally points to 2599.Pa /var/tmp , 2600as per default. 2601.It Ev PORTHOME 2602Setting of env variable 2603.Ev HOME 2604for most shell invocations. 2605Default will trip ports that try to write into $HOME while building. 2606.It Ev PORTPATH 2607Path used by most shell invocations. 2608Don't override unless really needed. 2609.It Ev PORTSDIR 2610Root of the ports tree (default: 2611.Pa /usr/ports ) . 2612.It Ev PORTSDIR_PATH 2613Path used by dependencies and 2614.Pa bsd.port.subdir.mk 2615to look up package specifications. 2616Defaults to 2617.Pa ${PORTSDIR}:${PORTSDIR}/mystuff . 2618.It Ev PORTS_PRIVSEP 2619If set to 2620.Sq Yes , 2621will build ports as 2622.Ev BUILD_USER 2623and fetch distfiles 2624as 2625.Ev FETCH_USER . 2626.Pp 2627To work fully, this does require the ports tree 2628to be world-readable, and 2629.Pa ${WRKDIR} 2630to be world-readable as well 2631.Po 2632.Cm update-patches 2633and friends won't work otherwise 2634.Pc . 2635.Pp 2636Meant to use in concert with 2637.Xr dpb 1 , 2638which uses the same permissions 2639.Po 2640see 2641.Sq THE SECURITY MODEL OF DPB 2642in 2643.Xr dpb 1 2644.Pc . 2645.Pp 2646Basically, 2647.Ev BUILD_USER 2648must be able to write into 2649.Pa ${WRKOBJDIR} , ${PACKAGE_REPOSITORY} , ${PLIST_REPOSITORY} 2650and 2651.Ev FETCH_USER 2652must be able to write into 2653.Pa ${DISTDIR} . 2654The directories and permissions can be set correctly using 2655.Cm fix-permissions . 2656.Pp 2657The regular user must be allowed to execute commands as 2658.Ev BUILD_USER 2659and 2660.Ev FETCH_USER . 2661Running commands as another user can be achieved with 2662.Xr doas 1 2663by setting 2664.Ev SUDO=doas 2665in 2666.Xr mk.conf 5 2667and using the following minimal 2668.Xr doas.conf 5 : 2669.Bd -literal -offset indent 2670permit keepenv nopass solene as _pbuild 2671permit keepenv nopass solene as _pfetch 2672.Ed 2673.Pp 2674It is reasonably safe to allow your user id to run commands as the 2675.Ev BUILD_USER 2676or 2677.Ev FETCH_USER 2678and using 2679.Ic nopass 2680for these can save a lot of password entry, however it is inadvisable 2681to allow commands like 2682.Xr pkg_add 1 2683to run as root without a password. 2684.Pp 2685Note that this also means that 2686.Xr doas 1 2687must be configured to work within the chroot 2688created by 2689.Xr proot 1 . 2690.Pp 2691As 2692.Xr dpb 1 2693does its own privilege dropping when run as root, 2694it will automatically override 2695.Ev PORTS_PRIVSEP . 2696.Pp 2697User settings, defaults to 2698.Sq \&No . 2699.It Ev PKGDIR 2700Location for packaging information (packing-list, port description, messages). 2701.Cm update-plist 2702may create it. 2703Must be a valid directory. 2704Default: pkg. 2705.It Ev PKGFILE 2706Full path to the created package for the given subpackage. 2707Read-only. 2708.It Ev PKGFILES 2709Full path to all created packages. 2710Read-only. 2711.It Ev PKGNAME 2712Name of the created package. 2713Default is ${DISTNAME}. 2714This does not take flavors into account. 2715See 2716.Ev FULLPKGNAME 2717for that. 2718Specific revisions and epoch changes should be 2719handled by 2720.Ev REVISION 2721and 2722.Ev EPOCH 2723instead. 2724.It Ev PKGNAMES 2725Read-only. 2726List of all package names generated by the port, with 2727.Ev FLAVORS 2728and 2729.Ev BUILD_PACKAGES 2730taken into account. 2731Mostly used as 2732.Ql make show=PKGNAMES 2733to verify that bumped package names are correct. 2734.It Ev PKGNAME-foo 2735Package name for sub-package foo, if the default value 2736of ${PKGNAME}${SUBPACKAGE} is not appropriate. 2737.It Ev PKGPATH 2738Path to the current port's directory, relative to ${PORTSDIR}. 2739Read-only. 2740.It Ev PKGPATHS 2741Read-only. 2742List of all package paths generated by the port, with 2743.Ev FLAVORS 2744and 2745.Ev MULTI_PACKAGES 2746taken into account. 2747Order matches 2748.Ev PKGNAMES 2749exactly. 2750.It Ev PKGSPEC 2751Default package spec for using this port as a dependency. 2752Defaults to 2753.Sq stem-* , 2754derived from the 2755.Ev FULLPKGNAME . 2756Do not override without very good reasons, 2757namely software that coexist as different incompatible versions with the 2758same stem, e.g., already a mess. 2759.It Ev PKGSTEM 2760Base for the package name without any version number. 2761Used in 2762.Pa READMEs 2763file names and actual contents, can be overridden for ports 2764with branches, like php, e.g., 2765.Li PKGSTEM-main = php-5.6 2766.It Ev PLIST_DB 2767Deprecated, see 2768.Ev PLIST_REPOSITORY . 2769.It Ev PLIST_REPOSITORY 2770User settings. 2771Base directory used to save generated packing-lists, as persistent information. 2772Packing-lists are processed by a script, 2773.Xr register-plist 1 , 2774which complains when packing-lists change without a 2775.Ev REVISION 2776bump. 2777It also knows enough about package version numbers when something in the 2778package or its dependencies goes backward, thus catching 2779.Ev EPOCH 2780issues. 2781This directory is never cleaned during normal operation. 2782.Ql make clean=plist 2783should only ever be used during debugging by port maintainers. 2784Defaults to 2785.Pa ${PORTSDIR}/plist 2786.Po 2787plists actually get saved into 2788.Pa ${PLIST_REPOSITORY}/${MACHINE_ARCH} 2789.Pc . 2790If set to empty, will not register anything: very much unsafe. 2791.It Ev PORTS_BUILD_XENOCARA_TOO 2792EXPERIMENTAL. 2793Set to 2794.Sq Yes 2795to build xenocara through ports. 2796This is highly experimental and not recommended. 2797.It Ev PORTROACH 2798Controls the behavior of 2799.Pa misc/portroach 2800as documented in detail at 2801.Lk http://jasperla.github.io/portroach/docs/portroach-portconfig.txt . 2802.It Ev PREFIX 2803Base directory for the current port installation. 2804Usually ${LOCALBASE}, though some ports may elect a location under 2805.Pa ${VARBASE} , 2806and some multi-package ports may install under several locations. 2807Additionally, firmware files generally install under 2808.Pa ${BASESYSCONFDIR} . 2809.It Ev PREPARE_CHECK_ONLY 2810Build settings. 2811Prevent the 2812.Cm prepare 2813stage from installing anything, let it just check dependencies, and 2814handle [:target] dependencies. 2815Mostly used by 2816.Xr dpb 1 , 2817which already installs everything before running 2818.Cm prepare . 2819.It Ev PROGRESS_METER 2820User settings. 2821Defaults to 2822.Sq Yes . 2823Forces commands like 2824.Xr ftp 1 2825and 2826.Xr pkg_create 1 2827to use their progress-meter even in the absence of a terminal. 2828.It Ev PROPERTIES 2829List of properties specific to a given machine architecture. 2830Most often obtained through 2831.Xr bsd.port.arch.mk 5 . 2832These can be checked like this 2833.Bd -literal -offset indent 2834\&.include <bsd.port.arch.mk> 2835\&.if ${PROPERTIES:Mapm} 2836# then add build options specific to apm arches 2837\&... 2838\&.if !${PROPERTIES:Mlp64} 2839# build options specific to lp32 arches 2840\&... 2841.Ed 2842For 2843.Ev MULTI_PACKAGES 2844setup, use of 2845.Ev ONLY_FOR_ARCHS-sub 2846and 2847.Ev BUILD_PACKAGES 2848is generally preferred (and simpler). 2849Possible properties include 2850.Bl -tag -width mono 2851.It apm 2852architecture possesses suspend (apm) support. 2853.It be 2854architecture is big-endian. 2855.It gccN 2856gccN architecture. 2857.It le 2858architecture is little-endian. 2859.It lp64 2860lp64 architecture. 2861.It llvm 2862there is 2863.Pa lang/llvm 2864support on this architecture. 2865.It mono 2866there is 2867.Pa lang/mono 2868support on this architecture. 2869.El 2870.It Ev PSEUDO_FLAVOR 2871List of flavors in 2872.Ev FLAVOR 2873that are actually pseudo-flavors. 2874Only for introspection purposes. 2875Read-only. 2876.It Ev PSEUDO_FLAVORS 2877Extra list of flavors that do not register in package names, but are still 2878used to control build logic, and work directory names. 2879Its only use should be for disabling part of a multi-packages build, 2880for instance: 2881.Bd -literal 2882FLAVOR=no_gnome make package 2883.Ed 2884.Pp 2885Pseudo-flavors should be named as 2886.Sq no_something 2887to disable the build of subpackage 2888.Sq -something 2889.Po 2890and possibly some others, by restricting 2891.Ev BUILD_PACKAGES 2892.Pc . 2893Pseudo-flavors should always be handled through 2894.Xr bsd.port.arch.mk 5 . 2895A pseudo-flavor can remove several subpackages through the following 2896construct. 2897.Bd -literal -offset indent 2898# pseudo-flavor no_gui will also remove gtk and gtk3 2899MULTI_PACKAGES = -main -gtk -gtk3 -gui 2900# ... 2901\&.include <bsd.port.arch.mk> 2902 2903# remove extra build components 2904\&.if !${BUILD_PACKAGES:M-gui} 2905BUILD_PACKAGES := ${BUILD_PACKAGES:N-gtk:N-gtk3} 2906\&.endif 2907 2908# normal configure setup, e.g., 2909\&.if ${BUILD_PACKAGES:M-gtk} 2910# ... 2911.Ed 2912.Pp 2913Caveat: creation of a separate working directory is mandatory for a 2914pseudo-flavor. 2915If, at a later time, a full build with all subpackages is required, 2916all the work will need to be done again. 2917.Pp 2918See also 2919.Ev BUILD_ONCE . 2920.It Ev RCDIR 2921Location for daemon startup scripts. 2922Defaults to 2923.Pa /etc/rc.d . 2924Do not change. 2925.It Ev REFETCH 2926User settings. 2927If set to true, 2928.Cm checksum 2929will analyze ${CHECKSUM_FILE}, and try retrieving files with the correct 2930checksum off 2931.Lk https://ftp.openbsd.org , 2932in the directory 2933.Pa /pub/OpenBSD/distfiles/$cipher/$value/$file . 2934.It Ev REGISTER_PLIST_OPTS 2935User settings. 2936User options added to 2937.Xr register-plist 1 . 2938.It Ev REORDER_DEPENDENCIES 2939Points to a list of files that specify inter-dependencies for 2940.Xr make 1 . 2941If defined, each line of the file is either a comment (starting with #) 2942or a pair of two files: most_recent older. 2943At the end of 2944.Cm post-patch , 2945.Xr touch 1 2946will be used to ensure those files are put in the proper order. 2947The files are assumed to be under 2948.Pa ${WRKSRC} . 2949The notation /file can be used to ask for a recursive search, e.g., 2950to make sure that all Makefile.in are up to date. 2951See 2952.Pa ${PORTSDIR}/infrastructure/mk/automake.dep 2953for an example. 2954.It Ev REPORT_PROBLEM 2955See 2956.Xr ports 7 . 2957.It Ev REPORT_PROBLEM_LOGFILE 2958See 2959.Xr ports 7 . 2960.It Ev REVISION 2961Revision number of the current package. 2962Defaults to empty (very first package), then 2963numbering starts at 0. 2964Gets automatically incorporated into 2965.Ev FULLPKGNAME 2966as 2967.Sq p${REVISION} 2968to form a full package-name conforming to 2969.Xr packages-specs 7 . 2970.It Ev RUN_DEPENDS 2971Specification of ports this port needs installed to be functional. 2972Same format as 2973.Ev LIB_DEPENDS . 2974The corresponding packages will be built right before the 2975.Cm install 2976stage, and 2977.Xr pkg_add 1 2978will take care of installing them. 2979.It Ev SEPARATE_BUILD 2980Many GNU configure ports can be built in a directory distinct from the 2981place they were unpacked. 2982For some specific ports, this is even mandatory. 2983Set to 2984.Sq yes 2985if this is the case. 2986The ports infrastructure will generate a separate ${WRKBUILD} directory 2987in which the port will be configured and built. 2988Wipe ${WRKBUILD} to start anew, but skipping the extract/patch stage. 2989.It Ev SETENV 2990Normally set to 2991.Li /usr/bin/env -i . 2992Prepended to every command invocation that requires a clean environment. 2993Do not override. 2994.It Ev SHARED_LIBS 2995List of shared libraries that the port may build, as a list of the form 2996.Sq libname 2997.Sq libversion . 2998Used to set variables of the form 2999.Ev LIBlibname_VERSION 3000that are then used for substitution by 3001.Xr pkg_create 1 . 3002The porter is responsible for making sure the port uses those version numbers 3003when shared libraries are built. 3004.Pp 3005The intent is that the 3006.Ox 3007ports system must have control over shared library versions because of global 3008changes that may require bumping the major version of every shared library in 3009the system, or simply because the third party programmers do not understand 3010the rules for shared library versions, thus breaking the update mechanism. 3011For that reason it is advised to set libversion to 0.0 when first importing a 3012port. 3013.Pp 3014Porters of software using libtool should make sure 3015.Ev MAKE_FLAGS 3016get propagated to the libtool invocations. 3017This should be enough in most cases. 3018.It Ev SKIPDIR 3019See 3020.Xr ports 7 . 3021.It Ev STATIC_PLIST 3022Normally set to 3023.Sq yes . 3024Can be set to no for ports that do not have a static plist. 3025Do not change without a very good reason. 3026Note that the only good reason to not have a static plist is for ports such 3027as 3028.Pa databases/ports-readmes 3029which actually build a bunch of files depending on the current ports tree. 3030This breaks all introspection mechanisms within the ports tree, including 3031.Pa databases/pkglocatedb 3032which will not include that port. 3033.It Ev STARTAFTER 3034See 3035.Xr ports 7 . 3036.It Ev STARTDIR 3037See 3038.Xr ports 7 . 3039.It Ev SUBPACKAGE 3040Set to the subpackage suffix when building a package in a multi-package port. 3041Read-only. 3042Used to test for dependencies or to adjust the package name. 3043.It Ev SUBST_CMD 3044A command that can be used to perform 3045.Ev SUBST_VARS 3046substitution on arbitrary files. 3047In normal mode, 3048.Pp 3049.Dl ${SUBST_CMD} file1 file2 ... 3050.Pp 3051will substitute files in place, creating backup copies of them. 3052In copy mode, 3053.Pp 3054.Dl ${SUBST_CMD} -c src1 dest1 src2 dest2 3055.Pp 3056will copy files over while performing the substitution, as suitable for 3057copying template files over from 3058.Pa ${FILESDIR} 3059to 3060.Pa ${PREFIX} , 3061for instance. 3062This uses 3063.Xr pkg_subst 1 3064with suitable parameters. 3065Read-only. 3066.Pp 3067${SUBST_CMD} 3068can be used like 3069.Xr install 1 : 3070.Dl ${SUBST_CMD} Oo Fl g Ar group Oc Oo Fl o Ar owner Oc Oo Fl m Ar mode Oc file... 3071to set file 3072.Ar owner , 3073.Ar group 3074and/or 3075.Ar mode . 3076.Pp 3077Note that 3078.Ev SUBST_CMD 3079is not really appropriate when variables have subpackage variations, like 3080.Ev PREFIX 3081or 3082.Ev FULLPKGNAME . 3083Use the appropriate 3084.Ev SUBST_CMD-sub 3085instead. 3086.It Ev SUBST_CMD-sub 3087.Ev SUBST_CMD 3088with subpackage-dependent semantics, like packing-list substitution. 3089It will substitute the right variable depending on the desired subpackage, 3090e.g., 3091.Ev SUBST_CMD-foo 3092will substitute the value of 3093.Ev FULLPKGNAME-foo 3094for 3095.Li ${FULLPKGNAME} . 3096.It Ev SUBST_DATA , SUBST_MAN , SUBST_PROGRAM 3097Specialized versions of 3098.Ev SUBST_CMD 3099that use 3100.Fl c 3101and appropriate owner/group/mode for data, manpages and programs respectively. 3102.It Ev SUBST_VARS 3103Make variables whose values get substituted to create the actual package 3104information. 3105Always holds 3106.Ev ARCH , 3107.Ev BASE_PKGPATH , 3108.Ev FLAVOR_EXT , 3109.Ev FULLPKGNAME , 3110.Ev HOMEPAGE , 3111.Ev LOCALBASE , 3112.Ev MACHINE_ARCH , 3113.Ev MAINTAINER , 3114.Ev PREFIX , 3115.Ev PKGSTEM , 3116.Ev RCDIR , 3117.Ev SYSCONFDIR , 3118.Ev TRUEPREFIX , 3119and 3120.Ev X11BASE . 3121The special construct 3122.Sq ${FLAVORS} 3123can be used in the packing-list to specify the current list of dash 3124separated flavors the port is compiled with (useful for cross-dependencies 3125in 3126.Ev MULTI_PACKAGES ) . 3127Add other 3128variables as needed. 3129.Pp 3130.Ev TRUEPREFIX 3131is never passed to 3132.Xr pkg_create 1 3133as it is identical to 3134.Ev PREFIX . 3135.Pp 3136By default, 3137.Xr update-plist 1 3138is run with the following options: 3139.Bd -literal -offset indent 3140update-plist -i ARCH -i BASE_PKGPATH -i FULLPKGNAME 3141-i FULLPKGPATH -i LOCALSTATEDIR -i MACHINE_ARCH 3142-s BASE_PKGPATH -s LOCALBASE -s LOCALSTATEDIR -s PREFIX 3143-s RCDIR -s SYSCONFDIR -s X11BASE 3144.Ed 3145.It Ev SUDO 3146User settings. 3147If set to 3148.Xr doas 1 3149in 3150.Xr mk.conf 5 , 3151the ports tree will only invoke root's privileges for the parts that 3152really require it. 3153.It Ev SUPDISTFILES 3154Supplementary files that need to be retrieved under some specific 3155circumstances. 3156For instance, a port might need architecture-specific files. 3157.Ev SUPDISTFILES 3158should hold a list of all distribution files and patchfiles that are not 3159always needed, so that a mirror will be able to grab all files, or that 3160.Cm makesum 3161will work. 3162Having an overlap between 3163.Ev SUPDISTFILES 3164and 3165.Ev DISTFILES , 3166.Ev PATCHFILES 3167is admissible, and in fact, expected, as it is much simpler to build 3168an error-free list of files to retrieve in that way. 3169See the xanim port for an example. 3170.It Ev SYSCONFDIR 3171Location for this port's configuration files, should always be derived 3172from 3173.Ev BASESYSCONFDIR , 3174which defaults to 3175.Pa /etc . 3176Passed to gnu configure scripts and substituted in packing-lists. 3177.It Ev TAR 3178Name of the tar binary. 3179.It Ev TARGETS 3180Read-only. 3181Set to the list of special targets for a port 3182.Po 3183.Cm {pre,do,post}-* 3184and module hooks 3185.Pc . 3186Used by introspection tools such as the sqlports package. 3187.It Ev TEMPLATES 3188Base location for the templates used in the 3189.Cm readmes 3190target. 3191User settings. 3192Defaults to 3193.Pa ${PORTSDIR}/infrastructure/templates . 3194.It Ev TEST_DEPENDS 3195See 3196.Ev BUILD_DEPENDS 3197for specification. 3198Test dependencies are only checked if the 3199.Cm test 3200stage is invoked. 3201.It Ev TEST_ENV 3202Additional environment variables passed to tests. 3203Empty by default. 3204.It Ev TEST_FLAGS 3205Extra flags passed to ${MAKE_PROGRAM} to run the regression tests. 3206Empty by default. 3207.It Ev TEST_IS_INTERACTIVE 3208Set to 3209.Sq Yes 3210if port needs human interaction to run its tests, or set to 3211.Sq X11 3212if the tests need an active X11 display to work. 3213.It Ev TEST_LOG 3214Command used to log the results of regression tests to TEST_LOGFILE. 3215Read-only. 3216.It Ev TEST_LOGFILE 3217Log file containing the results of regression tests. 3218.It Ev TEST_TARGET 3219Target to run regression tests. 3220Defaults to 3221.Sq test , 3222except for 3223.Sq perl 3224and 3225.Sq gnu 3226.Ev CONFIGURE_STYLE , 3227which default to 3228.Sq test 3229and 3230.Sq check , 3231respectively. 3232.It Ev TRUEPREFIX 3233Read-only. 3234Mostly the same as ${PREFIX}, except it never gets ${DESTDIR} prepended 3235during 3236.Cm fake . 3237Refer to 3238.Sx THE FAKE FRAMEWORK 3239section for details. 3240.It Ev TRY_BROKEN 3241User settings. 3242If set to 3243.Sq Yes , 3244don't set 3245.Ev IGNORE 3246for 3247.Ev BROKEN 3248ports, so that we will attempt to build them. 3249.It Ev UNLOCK_CMD 3250User settings. 3251If set, expands to a command that will release a lock. 3252This lock will reside in 3253.Pa ${LOCKDIR} . 3254.It Ev UNMESSAGE 3255File recorded in the package and displayed during deinstallation. 3256Defaults to ${PKGDIR}/UNMESSAGE if this file exists. 3257Leave empty if no message is needed. 3258.It Ev UNZIP 3259Name of the unzip binary. 3260.It Ev UPDATE_COOKIES_DIR 3261User settings. 3262Used to store cookies for package updates and defaults to 3263.Pa ${PORTSDIR}/update/${MACHINE_ARCH} . 3264If set to empty, will revert to a file under 3265.Pa ${WRKDIR} . 3266.It Ev UPDATE_PLIST_ARGS 3267Tweaks to 3268.Xr update-plist 1 3269behavior for some specific ports, such as variable handling. 3270.It Ev UPDATE_PLIST_OPTS 3271User settings. 3272User options added to 3273.Xr update-plist 1 , 3274mostly 3275.Fl v 3276for now. 3277.It Ev USE_CCACHE 3278User settings. 3279Set to 3280.Sq Yes 3281to use ccache when building ports. 3282Sets up the build environment so that it is used. 3283.It Ev USE_GMAKE 3284Set to 3285.Sq Yes 3286if GNU make (${GMAKE}) is needed for correct behavior of this port. 3287.It Ev USE_GROFF 3288Set to 3289.Sq Yes 3290to use groff to build manpages. 3291This sets groff as a build dependency, and also tells 3292.Xr pkg_create 1 3293to format manpages behind the scene using groff while building packages. 3294.It Ev USE_LIBTOOL 3295Defaults to 3296.Sq Yes . 3297Set to 3298.Sq gnu 3299if the base 3300.Xr libtool 1 3301is insufficient and GNU libtool is required. 3302Set to 3303.Sq \&No 3304to disable the use of 3305.Xr libtool 1 3306entirely; this should not be set under normal circumstances. 3307Adds dependencies if necessary, and passes LIBTOOL environment variable to 3308scripts invocations. 3309.Pp 3310Many ports using GNU autoconf need an m4 file from the GNU libtool package 3311but otherwise work with base 3312.Xr libtool 1 . 3313In those cases do not set 3314.Ev USE_LIBTOOL , 3315instead just set 3316.Li BUILD_DEPENDS = devel/libtool . 3317.It Ev USE_LLD 3318Set to 3319.Sq Yes 3320or 3321.Sq \&No 3322to force the use of 3323.Xr ld.lld 1 3324.Po 3325as opposed to 3326bfd's 3327.Xr ld 1 3328.Pc . 3329Defaults to the appropriate value for the current architecture 3330.Po 3331see 3332.Ev LLD_ARCHS 3333in 3334.Xr bsd.port.arch.mk 5 3335.Pc . 3336.It Ev USE_MFS 3337Set to 3338.Sq Yes 3339to build ports under an MFS filesystem 3340(see 3341.Xr mount_mfs 8 ) . 3342Mostly for use by 3343.Xr dpb 1 3344and not intended to be a user setting. 3345See 3346.Ev WRKOBJDIR_MFS 3347for configuration. 3348.It Ev USE_NOEXECONLY 3349If set to 3350.Sq Yes , 3351writes a wrapper script to ${WRKDIR}/bin/ld in 3352.Cm patch 3353adding 3354.Fl -no-execute-only . 3355Use when a port does not work with execute-only (unreadable) code sections 3356which are used by default by the linker on some architectures. 3357.It Ev USE_WXNEEDED 3358If set to 3359.Sq Yes , 3360writes a wrapper script to ${WRKDIR}/bin/ld in 3361.Cm patch 3362to request that the linker adds an 3363.Dv PT_OPENBSD_WXNEEDED 3364ELF section. 3365Use when a port requires memory mappings that are both executable 3366and writable and cannot be modified to avoid this. 3367.It Ev USE_X11 3368Normally, presence of ${X11BASE} is enforced by default for building ports. 3369But there is an experimental way to hook the xenocara build into 3370.Xr dpb 1 , 3371which requires knowing whether a port requires X11 to already 3372be there. 3373.Pp 3374The infrastructure mostly sets 3375.Ev USE_X11 3376automatically based on 3377.Ev WANTLIB 3378values, there are a few ports (about 20) that require X11 components without 3379any library telltale. 3380.It Ev VARBASE 3381User settings. 3382Base location for ports that install stuff outside of 3383.Pa ${LOCALBASE} . 3384Defaults to 3385.Pa /var . 3386.It Ev WANTLIB 3387List of library specifications that a package will need. 3388May include system and X11 libraries. 3389See 3390.Xr library-specs 7 3391for more details. 3392.Pp 3393As a special extension, 3394.Ev WANTLIB 3395may include absolute paths, e.g., 3396.Pa ${LOCALBASE}/lib/expat=4 3397to distinguish between base libraries and port libraries. 3398Use with caution, this is very seldom needed. 3399.It Ev wantlib_args 3400Controls the behavior of 3401.Xr pkg_create 1 3402related targets, see 3403.Cm print-package-args 3404for details. 3405.It Ev WARNINGS 3406User settings. 3407If set to 3408.Sq Yes , 3409add 3410.Ev CDIAGFLAGS 3411to 3412.Ev CFLAGS 3413and 3414.Ev CXXDIAGFLAGS 3415to 3416.Ev CXXFLAGS . 3417.It Ev WRKBUILD 3418Subdirectory of ${WRKDIR} where the actual build occurs. 3419Defaults to ${WRKSRC}, unless 3420.Ev SEPARATE_BUILD 3421is involved, in which case it is set to an appropriate value. 3422.It Ev WRKCONF 3423Subdirectory of ${WRKDIR} where the actual configure set occurs. 3424Defaults to ${WRKBUILD}. 3425.It Ev WRKDIR 3426Location where all port activity occurs. 3427Apart from the actual port, may 3428hold all kinds of cookies that checkpoint the port's build. 3429Read-only. 3430Note that WRKDIR may be a symbolic link. 3431During ports building, 3432.Pa ${WRKDIR}/bin 3433is put at the front of the 3434.Ev PATH . 3435.It Ev WRKDIR_LINKNAME 3436Name of a symbolic link to create within the port directory which will 3437point to the port's ${WRKDIR}. 3438Deprecated. 3439.It Ev WRKDIST 3440Subdirectory of ${WRKDIR} in which the distribution files normally unpack. 3441Base for all patches. 3442Defaults to 3443.Pa ${WRKDIR}/${DISTNAME} . 3444Note that WRKDIST may be a symbolic link, if set to ${WRKDIR}. 3445.It Ev WRKSRC 3446Subdirectory of ${WRKDIR} where the actual source is. 3447Base for configuration (default: ${WRKDIST}). 3448Note that WRKSRC may be a symbolic link, if set to ${WRKDIR}. 3449.It Ev WRKINST 3450Subdirectory of ${WRKDIR} where port normally installs (see the 3451.Cm fake 3452target). 3453.It Ev WRKOBJDIR 3454Used as a base for the actual port working directory. 3455Defaults to 3456.Pa ${PORTSDIR}/pobj . 3457The real working directory ${WRKDIR} is created there. 3458Can be set on a per-${PKGPATH} basis. 3459For instance, setting WRKOBJDIR_www/mozilla=/tmp/obj 3460will affect only the mozilla port. 3461If explicitly unset (WRKOBJDIR=), the working directory is 3462created within the port directory. 3463.It Ev WRKOBJDIR_MFS 3464Alternate location for the port working directory. 3465The intent is to use an MFS based filesystem for small ports with 3466.Xr dpb 1 . 3467Active when 3468.Ev USE_MFS 3469is 3470.Sq Yes . 3471Defaults to 3472.Pa /tmp/pobj . 3473.It Ev X11BASE 3474Where X11 has been installed. 3475Default: 3476.Pa /usr/X11R6 . 3477.It Ev XAUTHORITY 3478Points to a suitable authority file for X11 interactive regression tests. 3479Defaults to 3480.Pa ${HOME}/.Xauthority . 3481.It Ev XMKMF 3482Invocation of xmkmf for a 3483.Li CONFIGURE_STYLE=imake 3484port. 3485Defaults to xmkmf -a -DPorts. 3486The -DPorts is specific to 3487.Ox 3488and is always appended. 3489.It Ev YACC 3490Name of yacc program to pass to GNU-configure, defaults to yacc. 3491GNU-configure would always try to use bison otherwise, which leads to 3492unreproducible builds. 3493Set to bison if needed. 3494.El 3495.Sh THE FAKE FRAMEWORK 3496The 3497.Cm fake 3498target is used to install the port in a private directory first, ready for 3499packaging by the 3500.Cm package 3501target, so that the actual installation will use the package. 3502.Pp 3503Essentially, 3504.Cm fake 3505invokes a real install process after tweaking a few variables. 3506.Pp 3507.Cm fake 3508first creates a skeleton tree under ${WRKINST}, using 3509.Xr mkdir 1 3510.Fl p . 3511.Pp 3512A 3513.Cm pre-fake 3514target may be used to complete that skeleton tree. 3515For instance, a few ports may need supplementary stuff to be present (as 3516it would be installed if the port's dependencies were present). 3517.Pp 3518If 3519.Cm {pre,do,post}-install 3520overrides are present, they are used with some 3521important changes, listed in 3522.Ev FAKE_SETUP : 3523.Bd -literal -offset indent 3524TRUEPREFIX=${PREFIX} 3525PREFIX=${WRKINST}${PREFIX} 3526${DESTDIRNAME}=${WRKINST} 3527.Ed 3528.Pp 3529Essentially, old install targets work transparently, except for a need to 3530change 3531.Ev PREFIX 3532to 3533.Ev TRUEPREFIX 3534for symbolic links and similar path lookups. 3535Specific traditional post install work can be simply removed, as it will 3536be taken care of by the package itself (for instance, ldconfig, or 3537texinfo's install-info). 3538.Pp 3539If no 3540.Cm do-install 3541override is present, the port is installed using 3542.Bd -literal -offset 2n 3543env -i ${MAKE_ENV} ${FAKE_SETUP} ${MAKE_PROGRAM} ${ALL_FAKE_FLAGS} -f ${MAKE_FILE} ${FAKE_TARGET} 3544.Ed 3545.Pp 3546Note that this does set both PREFIX and ${DESTDIRNAME}. 3547If a port's Makefile both heeds ${DESTDIRNAME}, 3548and references PREFIX explicitly, 3549FAKE_FLAGS may rectify the problem by setting PREFIX=${PREFIX} 3550(which will do the right thing, since ${PREFIX} is a 3551.Xr make 1 3552construct which will not be seen by the shell). 3553.Pp 3554${FAKE_FLAGS} is used to set variables on 3555.Xr make 1 3556command line, which will override the port Makefile contents. 3557Thus, a port that mentions DESTDIR= does not need any patch to work with fake. 3558.Pp 3559Files such as 3560.Pa ${PKGDIR}/README* 3561or 3562.Pa ${PKGDIR}/*.rc 3563get copied to 3564.Pa ${WRKINST} 3565right after the end of 3566.Cm fake , 3567during 3568.Cm generate-readmes 3569(see the 3570.Sx FILES 3571section above for details). 3572.Sh THE DEBUG_PACKAGES INFRASTRUCTURE 3573If 3574.Ev DEBUG_PACKAGES 3575is not empty, debug packages will be built "on the side". 3576Since debug information is usually large, this is controlled on a per-arch 3577basis with 3578.Ev DEBUGINFO_ARCHS 3579controlling the behavior (set to amd64 by default). 3580.Pp 3581During the normal 3582.Cm package 3583target , 3584.Xr build-debug-info 1 3585will be invoked to deduce debug packing-lists from the normal packing-lists, 3586and some extra makefile rules will be invoked to set aside the debug 3587information. 3588.Pp 3589Then each normal package will have a "shadow" debug-* package built alongside 3590it, with the exact same package signature, except it will also be tied closely 3591with the normal package. 3592.Pp 3593Figuring out what files contain debug information is entirely achieved through 3594.Cm @bin , 3595.Cm @lib , 3596.Cm @so 3597and 3598.Cm @static-lib 3599annotations in the base packing-lists. 3600.Pp 3601Debug packages will be produced for all subpackages in 3602.Ev DEBUG_PACKAGES . 3603Usually, the heuristics of trimming arch-independent packages 3604from 3605.Ev BUILD_PACKAGES 3606is enough. 3607In case this still produces empty debug packages, the 3608.Ev DEBUG_PACKAGES 3609list should be produced manually. 3610.Pp 3611The actual debug packages are not registered through 3612.Xr register-plist 1 3613since the information was automatically generated. 3614.Pp 3615debug package names and debug package filenames are added to 3616.Ev PKGNAMES 3617and 3618.Ev PKGFILES 3619respectively for introspection purpose. 3620.Pp 3621.Xr egdb 1 3622from ports can read debug information from a separate file, as long as 3623the original ELF file was annotated with a debuginfo link. 3624.Pp 3625That feature is used to set debug information on the side, in 3626.Pa .debug/ 3627subdirectories alongside the normal binaries, shared objects and shared 3628libraries. 3629.Pp 3630For static libraries, the information can't be separated, instead the full 3631static library with debug information is provided in the 3632.Pa .debug/ 3633subdirectory, while the normal static library gets stripped. 3634.Sh FLAVORS AND MULTI_PACKAGES 3635Starting with 3636.Ox 2.7 , 3637each port can generate distinct packages through two orthogonal mechanisms: 3638.Ev FLAVORS 3639and 3640.Ev MULTI_PACKAGES . 3641.Pp 3642The current 3643.Ev MULTI_PACKAGES 3644mechanism was introduced after 3645.Ox 4.0 . 3646.Pp 3647The arch-dependent part was refined after 3648.Ox 5.0 . 3649.Pp 3650If a port can be compiled with several options, these options 3651should be turned into 3652.Ev FLAVORS . 3653The port maintainer will set 3654.Ev FLAVORS 3655to be the list of possible options in the Makefile. 3656When building the port, the package builder will set 3657.Li "FLAVOR='option1 option2...'" 3658to build a specific flavor of the port. 3659The Makefile should test the value of FLAVOR as follows: 3660.Bd -literal -offset indent 3661FLAVOR?= 3662\&.if ${FLAVOR:Moption1} 3663# what to do if option1 3664\&.endif 3665\&.if ${FLAVOR:Moption2} 3666# what to do if option2 3667\&.endif 3668.Ed 3669.Pp 3670.Nm 3671takes care of a few details, such as generating a distinct work directory for 3672each flavor, or creating a FULLPKGNAME by adding a dash separated list of 3673flavors to the base package name. 3674The order in which 3675.Ev FLAVOR 3676is specified does not matter: this dash separated list will be 3677reordered to match the ordering of 3678.Ev FLAVORS . 3679.Pp 3680It is an error to specify an option in 3681.Ev FLAVOR 3682that does not appear in 3683.Ev FLAVORS , 3684to prevent misspellings. 3685.Pp 3686In bulk package building, flavors can be specified as a comma 3687separated list after the package directory, e.g., SUBDIR+=vim,no_x11 3688.Po 3689see 3690.Xr pkgpath 7 3691.Pc 3692.Pp 3693Finally, package information will use templates with the canonical package 3694extension if they are available: if FLAVOR='option1 option2' and both 3695COMMENT and COMMENT-option1-option2 are available, COMMENT-option1-option2 will 3696be used. 3697.Pp 3698If one build of a port can generate several distinct packages, set 3699.Ev MULTI_PACKAGES 3700accordingly. 3701Each extension of a 3702.Ev MULTI_PACKAGES 3703name should start with a dash, so that they cannot be confused with 3704.Ev FLAVORS . 3705In dependency checking and bulk builds, a subpackage can be 3706specified after a comma, e.g., 3707.Li SUBDIR+=quake,-server . 3708.Ev MULTI_PACKAGES 3709only affects the actual package building step. 3710.Pp 3711If 3712.Ev MULTI_PACKAGES 3713is set, the packaging stage happens once for every 3714subpackage, using subpackage-specific variables. 3715For instance, if 3716.Li MULTI_PACKAGES=-main -lib -server , 3717.Ev PKG_ARCH-main , 3718.Ev PKG_ARCH-lib 3719and 3720.Ev PKG_ARCH-server 3721will be used for the subpackages respectively called 3722.Ev FULLPKGNAME-main , 3723.Ev FULLPKGNAME-lib 3724and 3725.Ev FULLPKGNAME-server . 3726.Pp 3727All package information is also derived from 3728templates with SUBPACKAGE appended. 3729In the preceding example, the packing-list template for FULLPKGNAME-lib 3730must be in PLIST-lib. 3731.Pp 3732The following variables are subpackage dependent: 3733.Ev COMMENT , 3734.Ev PKG_ARCH , 3735.Ev PERMIT_PACKAGE , 3736.Ev PKGFILE , 3737.Ev PKGNAME , 3738.Ev PKGSTEM , 3739.Ev FULLPKGNAME , 3740.Ev REVISION , 3741.Ev EPOCH , 3742.Ev FULLPKGPATH , 3743.Ev RUN_DEPENDS , 3744.Ev WANTLIB , 3745.Ev LIB_DEPENDS , 3746.Ev IGNORE , 3747.Ev ONLY_FOR_ARCHS , 3748.Ev NOT_FOR_ARCHS , 3749.Ev PKG_ARGS , 3750.Ev PREFIX , 3751.Ev CATEGORIES , 3752.Ev MESSAGE , 3753.Ev UNMESSAGE , 3754.Ev DESCR , 3755.Ev PLIST , 3756.Ev STATIC_PLIST , 3757.Ev PKGSPEC . 3758.Pp 3759The usual non-MULTI_PACKAGES variables are simply used as default values 3760for all subpackages. 3761So, if you set 3762.Li "PKG_ARCH=*" 3763.Li "PKG_ARCH-main=i386" 3764then 3765.Ev PKG_ARCH-lib 3766and 3767.Ev PKG_ARCH-server 3768will both be 3769.Sq * . 3770.Pp 3771.Ev WANTLIB 3772and 3773.Ev LIB_DEPENDS 3774are special. 3775At the beginning of the build, during 3776.Cm prepare , 3777all build dependencies will be checked, 3778which includes 3779.Ev LIB_DEPENDS , 3780.Ev WANTLIB 3781for every subpackage. 3782As an exception, any 3783.Ev LIB_DEPENDS-sub 3784that references the current port will be ignored as a build dependency, 3785in order to avoid recursion. 3786.Pp 3787.Ev FULLPKGPATH 3788and 3789.Ev FULLPKGNAME 3790are special as well. 3791If 3792.Ev PKGNAME 3793is <stem>-<version>, 3794then 3795.Ev PKGNAME-sub 3796will be set to 3797<stem>-sub-<version> 3798by default, except for 3799.Ev PKGNAME-main 3800which has 3801.Ev PKGNAME 3802as a default. 3803Normally, 3804.Ev FULLPKGPATH-sub 3805is automatically set to the right value, 3806but in very rare cases, one may need to override the default: 3807for instance, if one specific subpackage is not affected by flavor 3808settings that affect other subpackages, e.g., for include files packs, 3809then the flavoring part of the fullpkgpath may need to be dropped. 3810.Pp 3811In terms of using the port, quite a few targets will have a subpackage 3812specific subtarget: 3813invoking 3814.Cm package 3815is the same as invoking 3816.Cm subpackage 3817for all subpackages, 3818invoking 3819.Cm install-all 3820is the same as invoking 3821.Cm install 3822for all subpackages, 3823and invoking 3824.Cm update 3825is the same as invoking 3826.Cm subupdate 3827for all subpackages. 3828.Pp 3829.Ev ONLY_FOR_ARCHS 3830and 3831.Ev NOT_FOR_ARCHS 3832interact with 3833.Ev MULTI_PACKAGES 3834and 3835.Ev IGNORE . 3836The infrastructure will automatically filter subpackages 3837that are not suitable for the current architecture. 3838Thus, 3839.Ev MULTI_PACKAGES 3840should always list all subpackages, 3841even things not buildable on the current architecture, 3842for indexing purposes. 3843.Pp 3844Starting with 3845.Ox 5.1 , 3846.Xr bsd.port.arch.mk 5 3847should be used to simplify the handling of 3848.Ev MULTI_PACKAGES 3849in arch-dependent setups: 3850.Pp 3851Make sure 3852.Ev MULTI_PACKAGES , 3853.Ev ONLY_FOR_ARCHS* , 3854and 3855.Ev PSEUDO_FLAVORS 3856are defined correctly, then 3857.Bd -literal -offset indent 3858\&.include <bsd.port.arch.mk> 3859.Ed 3860.Pp 3861This will compute 3862.Ev BUILD_PACKAGES , 3863the list of actual subpackages to build with the current setup, 3864by taking arch constraints and pseudo-flavors into account. 3865Then test 3866.Ev BUILD_PACKAGES 3867to set up the right configuration, e.g., to check if 3868.Ev SUBPACKAGE 3869.Ar -mono 3870should be built: 3871.Bd -literal -offset indent 3872\&.if ${BUILD_PACKAGES:M-mono} 3873.Ed 3874.Pp 3875The 3876.Pa lang/gcc/8 3877or 3878.Pa print/poppler 3879ports should provide examples of proper use. 3880.Pp 3881Note that 3882.Xr dpb 1 3883will break if all subpackages are not properly listed. 3884.Sh THE GENERATION OF PACKAGE INFORMATION 3885Starting after 3886.Ox 4.1 3887all package information is processed directly by 3888.Xr pkg_create 1 3889from templates in ${PKG_DIR}. 3890.Pp 3891.Bl -bullet -compact 3892.It 3893If not overridden by the user, determine which set of templates to use, 3894depending on the current SUBPACKAGE and FLAVOR information. 3895Set PLIST${SUBPACKAGE}, DESCR${SUBPACKAGE}, COMMENT${SUBPACKAGE}, 3896MESSAGE${SUBPACKAGE}, UNMESSAGE${SUBPACKAGE} accordingly. 3897.It 3898Generate the actual DESCR, and if needed, MESSAGE, UNMESSAGE, 3899from the templates in ${DESCR}, ${MESSAGE}, ${UNMESSAGE}, by 3900substituting the variables in ${SUBST_VARS}, and by substituting 3901${FLAVORS} with the canonical flavor extension for this port, 3902e.g., if 3903.Li FLAVORS=no_map gfx qt2 , 3904if 3905.Li FLAVOR=gfx no_map , 3906this is 3907.Sq -no_map-gfx . 3908.It 3909Generate the actual packing-list from the template ${PLIST}, 3910by inserting fragments 3911and applying the same variable substitutions as other package information. 3912.El 3913.Pp 3914Note that ${COMMENT} is currently not substituted. 3915.Pp 3916To avoid substitution, variables can be escaped as follows: 3917.Li "$\e{PREFIX}" 3918.Pp 3919If 3920.Ev FLAVORS 3921lists flv, then constructs such as the line 3922.Li "%%flv%%" 3923or 3924.Li "!%%flv%%" 3925in the packing-list template trigger the inclusion of 3926.Pa ${PKGDIR}/PFRAG.flv${SUBPACKAGE} 3927or 3928.Pa ${PKGDIR}/PFRAG.no-flv${SUBPACKAGE} . 3929Other fragments can be defined by simply adding 3930.Li "-Dfrag=1" 3931or 3932.Li "-Dfrag=0" 3933to 3934.Ev PKG_ARGS . 3935.Pp 3936If libraries are built using 3937.Pa bsd.lib.mk , 3938special care should be taken for mips64* architectures, 3939which do not ever build 3940.Pa *pic.a 3941files (all mips code is pic already). 3942.Nm 3943automatically adds 3944.Li "-Dno_mips64=1" 3945or 3946.Li "-Dno_mips64=0" 3947to 3948.Ev PKG_ARGS , 3949and the porter only needs to provide the appropriate fragment. 3950.Pp 3951.Xr pkg_add 1 3952now calls 3953.Xr ldconfig 8 3954directly, provided dynamic libraries have been annotated with 3955.Li "@lib libthingy.so.5.0" . 3956Adding new directories to the dynamic loader cache has been 3957deprecated. 3958It is often better to let libraries be visible as a link 3959under ${LOCALBASE}. 3960Having a separate directory is enough to trick 3961.Xr ld 1 3962into grabbing the right version. 3963Libraries used only for 3964.Xr dlopen 3 3965do not need to be visible. 3966Some programs will prefer to use rpath to find their own libraries. 3967.Pp 3968The special 3969.Cm update-plist 3970target does a fairly good job of automatically generating the packing-list 3971information. 3972.Pp 3973If 3974.Ev PLIST_REPOSITORY 3975points to a directory, all packing-lists from packages generated by 3976.Xr pkg_create 1 3977during the 3978.Cm package 3979stage are saved in 3980.Pa ${PLIST_REPOSITORY}/${MACHINE_ARCH} 3981by a script: 3982.Pa ${PORTSDIR}/infrastructure/bin/register-plist . 3983This script strips some irrelevant information and normalizes the 3984packing-list somehow, and compares it to existing information, looking 3985for relevant changes. 3986Since a package name must always be changed when the packing-list changes, 3987any attempt to replace a packing-list of a given name with a different 3988packing-list will be flagged as an error. 3989.Pp 3990In 3991.Ev MULTI_PACKAGES 3992mode, there must be separate COMMENT, DESCR, and PLIST 3993templates for each SUBPACKAGE (and optional distinct MESSAGE, UNMESSAGE 3994files in a similar way). 3995This contrasts with the 3996.Ev FLAVORS 3997situation, where all these files will automatically default to the 3998non-flavor version if there is no flavor-specific file around. 3999.Sh OBSOLETE TARGETS 4000.Bl -tag -width Ds 4001.It Cm {build,run,lib}-depends 4002The dependency mechanism now meshes 4003.Ev BUILD_DEPENDS , LIB_DEPENDS , RUN_DEPENDS, WANTLIB 4004and 4005.Ev MULTI_PACKAGES . 4006Refer to 4007.Cm prepare , install-depends , test-depends . 4008.El 4009.Sh OBSOLETE VARIABLES 4010.Bl -tag -width Ds 4011.It Ev FETCH_BEFORE_ARGS , FETCH_AFTER_ARGS 4012Set 4013.Ev FETCH_CMD 4014to point to a script that does any required special treatment instead. 4015.It Ev FETCH_DEPENDS 4016Used to specify dependencies that were needed to fetch files. 4017It is much easier to mirror locally weird distribution files. 4018.It Ev NO_EXTRACT 4019Set EXTRACT_ONLY= instead. 4020.It Ev NO_WRKDIR 4021All ports should have a working directory, as this is necessary to store 4022cookies and keep state. 4023.It Ev NO_WRKSUBDIR 4024The same functionality is obtained by setting WRKDIST=${WRKDIR}. 4025.It Ev OPSYS_VER 4026Use 4027.Ev OSREV 4028instead. 4029.It Ev PKGNAME 4030Used to refer to the full package name, has been superseded by 4031.Ev FULLPKGNAME-foo , 4032for 4033.Ev SUBPACKAGE 4034-foo. 4035.Ev PKGNAME 4036now holds the package name, not taking multi-packages or flavors 4037into account. 4038Most ports are not concerned by this change. 4039.It Ev PLIST_SUBST 4040From 4041.Nx 4042and 4043.Fx . 4044Use SUBST_VARS instead. 4045.Ox 4046does not allow general substitutions of the form VAR=value, but uses 4047only a list of variables instead. 4048Most package files gets transformed, instead of only the packing-list. 4049.It Ev SCRIPTDIR 4050Old location for scripts related to the current port. 4051There is no reason for the semantic distinction, use 4052.Ev FILESDIR 4053for those. 4054.It Ev USE_BZIP2 4055The framework will automatically detect the presence of 4056.Pa .tar.bz2 4057files to extract. 4058See also 4059.Ev BZIP2 , EXTRACT_CASES , 4060and 4061.Ev EXTRACT_SUFX . 4062.It Ev USE_ZIP 4063The framework will automatically detect the presence of 4064.Pa .zip 4065files to extract. 4066See also 4067.Ev ZIP , EXTRACT_CASES , 4068and 4069.Ev EXTRACT_SUFX . 4070.El 4071.Sh FILES 4072.Bl -tag -width Ds 4073.It Pa ../Makefile.inc 4074Common Makefile fragment for a set of ports, included automatically. 4075.It Pa /cdrom/distfiles 4076Default path to a CD-ROM (or other media) full of distribution files. 4077.It Pa ${PORTSDIR}/distfiles 4078Default setup of ${DISTDIR}. 4079.It Pa ${DISTDIR} 4080Cache of all distribution files. 4081.It Pa distinfo 4082Checksum file. 4083Holds the output of 4084.Xr cksum 1 , 4085using 4086.Xr sha256 1 4087for the port's ${DISTFILES} and ${PATCHFILES}, 4088as well as the sizes of these files. 4089.It Pa ${DISTDIR}/${CHECKSUMFILES} 4090Cache of normal distribution files for a given port. 4091.It Pa ${DISTDIR}/${MAKESUMFILES} 4092Cache of all distribution files for a given port. 4093.It Pa ${PORTSDIR}/infrastructure/mk/*.mk 4094Actual location of the 4095.Xr make 1 4096glue for the ports tree. 4097.Xr make 1 4098looks for 4099.Pa bsd.port.mk 4100.Po 4101and 4102.Pa bsd.port.subdir.mk 4103.Pc 4104under 4105.Pa /usr/share/mk/bsd.port.mk , 4106but that file is just a stub that redirects to the real location. 4107.It Pa ${PKGDIR}/DESCR 4108Description for the port. 4109Variables such as ${HOMEPAGE} and ${MAINTAINER} will be expanded 4110(see SUBST_VARS). 4111Multi-package ports will use DESCR${SUBPACKAGE}. 4112.It Pa ${PKGDIR}/README 4113.Ox 4114specific documentation for a port, that will be installed as 4115.Pa ${LOCALBASE}/share/doc/pkg-readmes/${PKGSTEM} 4116at the end of 4117.Cm fake . 4118Variables from 4119.Ev SUBST_VARS 4120will be expanded. 4121Multi-package ports will use 4122.Pa README${SUBPACKAGE} . 4123.It Pa ${PKGDIR}/<foo>.login 4124login.conf.d file for class <foo>. 4125Will be installed as 4126.Ar ${PREFIX}/share/examples/login.conf.d/foo 4127at the end of 4128.Cm fake . 4129When a port provides a daemon started by 4130.Xr rc.d 8 4131requiring non-default 4132.Xr login.conf 5 4133attributes, a sample file should be provided 4134and used as a template by adding 4135.Cm @sample /etc/login.conf.d/${ Ns Va class Ns } 4136to the packing list. 4137.It Pa ${PKGDIR}/<foo>.rc 4138Startup script for <foo>. 4139Will be installed as 4140.Ar ${RCDIR}/<foo> 4141at the end of 4142.Cm fake . 4143Variables from 4144.Ev SUBST_VARS 4145will be expanded. 4146.It Pa ${PORTSDIR}/plist 4147Default setup of ${PLIST_REPOSITORY}. 4148.It Pa ${PORTSDIR}/packages 4149Default setup of ${PACKAGE_REPOSITORY}. 4150.It Pa ${PACKAGE_REPOSITORY}/no-arch 4151Location of arch-independent packages. 4152.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/all 4153Location of all built packages. 4154.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cache 4155Location of packages retrieved through the network. 4156.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cksums 4157Location of checksums, see 4158.Ev CHECKSUM_PACKAGES . 4159.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cdrom 4160Location of packages suitable for the CD. 4161.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/ftp 4162Location of packages suitable for FTP. 4163.It Pa ${PORTSDIR}/bulk/${MACHINE_ARCH} 4164Default setup of ${BULK_COOKIES_DIR}. 4165.It Pa ${PORTSDIR}/update/${MACHINE_ARCH} 4166Default setup of ${UPDATE_COOKIES_DIR}. 4167.It Pa ${PORTSDIR}/mystuff 4168Extra directory used to store local ports before committing them. 4169All depend targets will normally look there after the normal lookup fails. 4170See 4171.Ev PORTSDIR_PATH . 4172.El 4173.Sh DIAGNOSTICS 4174Note that some of these messages are actually emitted by some other external 4175commands, but grouped here for convenience: easier to look for in 4176.Xr dpb 1 Ns 's 4177logs. 4178.Bl -diag 4179.It "/bin/sh: cd .../pkg - No such file or directory" 4180Emitted during 4181.Cm generate-readmes . 4182.Pa ${PKGDIR} 4183must point to an existing directory, so that 4184.Nm 4185can be certain there are no 4186.Pa MESSAGEs 4187or 4188other files pertinent to the package. 4189.It "Discovered old directory in ..." 4190This message comes from 4191.Xr update-plist 1 . 4192A directory was found in the packing-list file mentioned in the diagnostic. 4193That directory line used to be needed but is no longer, 4194because it's now accounted for through dependencies. 4195Indicates the old directory has been removed. 4196.It "Error: change in plist between ..." 4197Error message comes from 4198.Xr register-plist 1 . 4199.It "Error: duplicate item in packing-list" 4200Error message comes from 4201.Xr pkg_create 1 , 4202and will result from incorrect packing-lists, such as including several 4203fragments with the same file, or having incorrect 4204.Ev PKG_ARGS-sub . 4205.It "Error: Libraries in packing-lists...and libraries from installed packages don't match" 4206The ports tree and the installed packages are out-of-sync. 4207Mixing library information from both sources might produce packages that can't 4208be installed elsewhere. 4209Cleanest fix is to update the out-of-date source (e.g., update the ports tree, 4210or build and install new packages). 4211Developers may use 4212.Ev PKG_CREATE_NO_CHECKS 4213instead, assuming they understand the implications. 4214See 4215.Cm print-package-args Pq Cm wantlib-args 4216for details. 4217.It "Fatal: can't flavor a SUBDIR" 4218A dependency mentions top_subdir,flavor. 4219Flavor would then be ignored, as it is only applied to individual ports. 4220.It "Fatal: can't subpackage a SUBDIR" 4221A dependency mentions top_subdir,-sub. 4222Subpackage would then be ignored, as it is only applied to individual ports. 4223.It "Fatal: flavor should never start with a digit" 4224This would utterly confuse 4225.Xr pkg_add 1 . 4226See 4227.Xr packages-specs 7 . 4228.It "Fatal: inclusion of <file> from <file>" 4229.Pa bsd.port.mk 4230or 4231.Pa bsd.port.subdir.mk 4232has been included from a 4233.Ev MODULE 4234or from 4235.Pa Makefile.inc , 4236resulting in a double inclusion. 4237This would lead to weird results, such as 4238.Ev PKG_ARGS 4239being defined twice. 4240.It "Fatal: SUBPACKAGES should always begin with -: <offending list>" 4241That is the only way to differentiate between 4242.Ev FLAVOR 4243and 4244.Ev SUBPACKAGE 4245in 4246.Xr pkgpath 7 4247specifications. 4248.It "Fatal: building ports requires correctly installed X11" 4249All file sets of the base OS, including xenocara, must be installed 4250before building ports. 4251.It "Fatal: /usr/local/lib/X11/app-defaults should exist and be a symlink" 4252/usr/local/lib/X11/app-defaults is distributed as a symlink in the 4253xshare*.tgz file set. 4254If xenocara was not fully installed before packages were added, it may 4255have been created as a directory instead. 4256.It "Fatal: the licensing info for <pkgname> is incomplete..." 4257Every port must have explicit defines of all 4258.Ev PERMIT_* 4259values. 4260.It "Fatal: Use 'env FLAVOR=flavor make' instead" 4261Arguments specified after 4262.Xr make 1 4263are hardcoded for all recursive sub-makes, and very difficult to override. 4264Thus, 4265.Ev FLAVOR 4266must be specified in the environment instead. 4267.It "Fatal: Use 'env SUBPACKAGE=-sub make' instead" 4268Arguments specified after 4269.Xr make 1 4270are hardcoded for all recursive sub-makes, and very difficult to override. 4271Thus, 4272.Ev SUBPACKAGE 4273must be specified in the environment instead. 4274.It "ldconfig: <dir>: No such file or directory" 4275Usually produced by 4276.Xr pkg_add 1 4277running 4278.Xr ldconfig 8 . 4279Some tools such as GNU libtool will add directories living under 4280.Pa ${WRKINST} 4281to the shared library path during the 4282.Cm fake 4283stage. 4284Of course, 4285.Xr ldconfig 8 4286will later complain after the directory no longer exists. 4287The bogus tool should be fixed to conform to 4288.Ox 4289usage. 4290.It LIB_DEPENDS <spec> not needed for <FULLPKGPATH> 4291There doesn't seem to be any WANTLIB to match the given LIB_DEPENDS. 4292Thus, the LIB_DEPENDS won't turn into a @depends line in the created package. 4293This is often because of confusion between LIB_DEPENDS and RUN_DEPENDS: 4294RUN_DEPENDS is needed for dlopen'd libraries. 4295.Pp 4296Might be intentional sometimes, if some compile flavors create static binaries, 4297for instance. 4298Also, will happen for multi-packages, where one sets LIB_DEPENDS to have 4299a given build dependency (and corresponding WANTLIB for a given SUBPACKAGE). 4300.Pp 4301See 4302.Cm print-package-args Pq Cm lib-depends-args 4303for details. 4304.It "Warning: FULLPKGNAME-sub defined but not FULLPKGPATH-sub" 4305.Ev FULLPKGNAME-sub 4306has been explicitly defined by the port, instead of relying on the default, 4307but no value of 4308.Ev FULLPKGPATH-sub 4309has been given. 4310This is often an error. 4311.It "Warning: no debug-info in ..." 4312Port uses 4313.Ev DEBUG_PACKAGES 4314so the 4315.Xr build-debug-info 1 4316script expects debug information on all binaries and libraries. 4317Most probably, the build machinery for that specific port omitted -g 4318somewhere, or it runs strips during fake anyway. 4319It can also occur if 4320.Ev DEBUG_PACKAGES 4321includes subpackages with no files holding debug info. 4322.It "Warning: symlink(s) point to non existent file." 4323Warning message comes from 4324.Xr pkg_create 1 . 4325The symlink resides in the fake area, under 4326.Pa ${WRKINST} . 4327This is only a warning because the symlink may point to a run-time dependency, 4328which obviously won't exist under 4329.Pa ${WRKINST} 4330at the time 4331.Ql make package 4332is run. 4333.It "Warning: @option no-default-conflict with no @conflict" 4334Warning message comes from 4335.Xr pkg_create 1 . 4336Most packages that waive "default-conflict" will have explicit conflict markers 4337instead. 4338Otherwise, the package will only conflict with the exact same version, with 4339some possible 4340.Ev REVISION 4341bumps. 4342Any other version or 4343.Ev FLAVOR 4344won't conflict. 4345This is generally an error, apart from very few ports like 4346.Pa devel/autoconf/* . 4347.It "groff produced empty result for <manpage>..." 4348Warning message comes from 4349.Xr pkg_create 1 . 4350Manpages are automatically formatted with 4351.Xr groff 1 4352if 4353.Ev USE_GROFF 4354is set. 4355The above message denotes an actual problem while formatting the page, 4356which should be addressed. 4357In the meantime, 4358.Xr pkg_create 1 4359still produces a package, but leaves the manpage unformatted, in the hope 4360that something will be able to make sense of it. 4361.El 4362.Sh SEE ALSO 4363.Xr clean-old-distfiles 1 , 4364.Xr ftp 1 , 4365.Xr pkg_add 1 , 4366.Xr pkg_create 1 , 4367.Xr OpenBSD::Intro 3p , 4368.Xr bsd.port.arch.mk 5 , 4369.Xr mk.conf 5 , 4370.Xr port-modules 5 , 4371.Xr library-specs 7 , 4372.Xr mirroring-ports 7 , 4373.Xr packages-specs 7 , 4374.Xr pkgpath 7 , 4375.Xr ports 7 4376.Sh HISTORY 4377The ports mechanism originally came from 4378.Fx . 4379A lot of additions were taken from 4380.Nx 4381over the seminal years. 4382.Pp 4383Since 1998, the framework has been systematically cleaned-up and reorganized 4384to remove bugs. 4385New features have been carefully introduced, trying hard to avoid 4386inconsistencies. 4387.Pp 4388.Ev FLAVORS , 4389.Ev MULTI_PACKAGES , 4390.Ev SEPARATE_BUILD 4391and FAKE are 4392.Ox 4393improvements. 4394Most recent additions do not come from another 4395.Bx . 4396.\" Voluntarily undocumented: 4397.\" AUTOCONF_ENV: probably not needed anyway, should be internal. 4398.Sh BUGS 4399.Ev LOCALBASE , 4400.Ev X11BASE , 4401.Ev BASESYSCONFDIR , 4402.Ev VARBASE 4403and 4404.Ev PREFIX 4405are not heeded consistently. 4406Using anything but the default values has not been heavily tested. 4407Some ports may not build if you change them. 4408