diff options
Diffstat (limited to 'documentation/content/en/books/porters-handbook/special/_index.adoc')
| -rw-r--r-- | documentation/content/en/books/porters-handbook/special/_index.adoc | 676 |
1 files changed, 535 insertions, 141 deletions
diff --git a/documentation/content/en/books/porters-handbook/special/_index.adoc b/documentation/content/en/books/porters-handbook/special/_index.adoc index f12830c179..c30e8c058e 100644 --- a/documentation/content/en/books/porters-handbook/special/_index.adoc +++ b/documentation/content/en/books/porters-handbook/special/_index.adoc @@ -6,7 +6,7 @@ description: Special considerations when creating a new FreeBSD Port tags: ["special considerations", "Handling Symbolic Links", "Bundled Libraries"] showBookMenu: true weight: 6 -path: "/books/porters-handbook/" +path: "/books/porters-handbook/special/" --- [[special]] @@ -49,6 +49,30 @@ endif::[] This section explains the most common things to consider when creating a port. +[[splitting-long-files]] +== Splitting long files + +Sometimes, port [.filename]#Makefiles# can be really long. +For example, rust ports can have a very long `CARGO_CRATES` list. +In other cases, the [.filename]#Makefile# might have code that varies depending on the architecture. +In such cases, it can be convenient to split the original [.filename]#Makefile# into several files. +[.filename]#bsd.port.mk# automatically includes some types of [.filename]#Makefiles# into the main port [.filename]#Makefile#. + +These are the files that the framework handles automatically if they are found: + +* [.filename]#Makefile.crates#. An example can be found in package:audio/ebur128[]. +* [.filename]#Makefile.inc#. An example can be found in package:net/ntp[]. +* [.filename]#Makefile.${ARCH}-${OPSYS}# +* [.filename]#Makefile.${OPSYS}#. An example can be found in package:net/cvsup-static[]. +* [.filename]#Makefile.${ARCH}# +* [.filename]#Makefile.local# + +It is also usual practice to split the packaging list of the port into several files if the list varies a lot from one architecture to another or depends on the selected flavor. +In this case, the [.filename]#pkg-plist# file for each architecture is named following the pattern [.filename]#pkg-plist.${ARCH}# or [.filename]#pkg-plist.${FLAVOR}#. +The framework does not create the packaging list automatically if multiple [.filename]#pkg-plist# files exist. +It is the responsibility of the porter to select the proper [.filename]#pkg-plist# and assign it to the `PLIST` variable. +Examples on how to deal with this can be found in package:audio/logitechmediaserver[] and package:deskutils/libportal[]. + [[staging]] == Staging @@ -82,7 +106,7 @@ It sets up defaults for ports that do not fetch, build, or install anything. ==== Staging is enabled by prepending `STAGEDIR` to paths used in the `pre-install`, `do-install`, and `post-install` targets (see the examples through the book). -Typically, this includes `PREFIX`, `ETCDIR`, `DATADIR`, `EXAMPLESDIR`, `MANPREFIX`, `DOCSDIR`, and so on. +Typically, this includes `PREFIX`, `ETCDIR`, `DATADIR`, `EXAMPLESDIR`, `DOCSDIR`, and so on. Directories should be created as part of the `post-install` target. Avoid using absolute paths whenever possible. @@ -138,7 +162,7 @@ Some software requires the porter to locate third-party libraries and add the re Other software bundles all necessary libraries into the distribution file. The second approach seems easier at first, but there are some serious drawbacks: -This list is loosely based on the https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries[Fedora] and http://wiki.gentoo.org/wiki/Why_not_bundle_dependencies[Gentoo] wikis, both licensed under the http://creativecommons.org/licenses/by-sa/3.0/[CC-BY-SA 3.0] license. +This list is loosely based on the https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries[Fedora] and https://wiki.gentoo.org/wiki/Why_not_bundle_dependencies[Gentoo] wikis, both licensed under the https://creativecommons.org/licenses/by-sa/3.0/[CC-BY-SA 3.0] license. Security:: If vulnerabilities are found in the upstream library and fixed there, they might not be fixed in the library bundled with the port. @@ -337,7 +361,7 @@ Otherwise, it is almost impossible to either fix the problem, or test if it has [[using-make]] === `make`, `gmake`, and `imake` -Several differing `make` implementations exist. Ported software often requires a particular implementation, like GNU`make`, known in FreeBSD as `gmake`. +Several differing `make` implementations exist. Ported software often requires a particular implementation, like GNU `make`, known in FreeBSD as `gmake`. If the port uses GNU make, add `gmake` to `USES`. @@ -354,7 +378,7 @@ The same goes for `install` and `INSTALL_TARGET`. === `configure` Script If the port uses the `configure` script to generate [.filename]#Makefile# from [.filename]#Makefile.in#, set `GNU_CONFIGURE=yes`. -To give extra arguments to the `configure` script (the default argument is `--prefix=${PREFIX} --infodir=${PREFIX}/${INFO_PATH} --mandir=${MANPREFIX}/man --build=${CONFIGURE_TARGET}`), set those extra arguments in `CONFIGURE_ARGS`. +To give extra arguments to the `configure` script (the default argument is `--prefix=${PREFIX} --infodir=${PREFIX}/${INFO_PATH} --mandir=${PREFIX}/man --build=${CONFIGURE_TARGET}`), set those extra arguments in `CONFIGURE_ARGS`. Extra environment variables can be passed using `CONFIGURE_ENV`. [[using-configure-variables]] @@ -505,6 +529,9 @@ For ports that use Cargo, define `USES=cargo`. |`CARGO_CRATES` | |List of crates the port depends on. Each entry needs to have a format like `cratename-semver` for example, `libc-0.2.40`. Port maintainers can generate this list from [.filename]#Cargo.lock# using `make cargo-crates`. Manually bumping crate versions is possible but be mindful of transitive dependencies. +If the list generated by `make cargo-crates` is big, it might be convenient to place it inside a `Makefile.crates` file in the top-level port directory. +If present, the ports framework sources that file automatically. +This help keep the main port Makefile within a manageable size. |`CARGO_FEATURES` | @@ -607,6 +634,7 @@ CATEGORIES= devel MAINTAINER= tobik@FreeBSD.org COMMENT= Display statistics about your code +WWW= https://github.com/XAMPPRocky/tokei/ USES= cargo USE_GITHUB= yes @@ -651,6 +679,7 @@ CATEGORIES= devel MAINTAINER= tobik@FreeBSD.org COMMENT= Display statistics about your code +WWW= https://github.com/XAMPPRocky/tokei/ USES= cargo USE_GITHUB= yes @@ -690,7 +719,7 @@ rust/crates/atty-0.2.9.tar.gz 100% of 5898 B 81 MBps 00m00s The port is now ready for a test build and further adjustments like creating a plist, writing a description, adding license information, options, etc. as normal. -If you are not testing your port in a clean environment like with Poudriere, remember to run `make clean` before any testing. +If you are not testing your port in a clean environment like with poudriere, remember to run `make clean` before any testing. ==== [[cargo-ex2]] @@ -815,12 +844,13 @@ In most cases, it is sufficient to set the `GO_MODULE` variable to the value spe [.programlisting] .... PORTNAME= hey -PORTVERSION= 0.1.4 -DISTVERSIONPREFIX= v +DISTVERSIONPREFIX= v +DISTVERSION= 0.1.4 CATEGORIES= benchmarks MAINTAINER= dmgk@FreeBSD.org COMMENT= Tiny program that sends some load to a web application +WWW= https://github.com/rakyll/hey/ LICENSE= APACHE20 LICENSE_FILE= ${WRKSRC}/LICENSE @@ -835,7 +865,7 @@ PLIST_FILES= bin/hey If the "easy" way is not adequate or more control over dependencies is needed, the full porting process is described below. -Creating a Go based port is a five stage process. +Creating a Go-based port is a five-stage process. First we need to provide a ports template that fetches the application distribution file: [.programlisting] @@ -847,6 +877,7 @@ CATEGORIES= devel MAINTAINER= tobik@FreeBSD.org COMMENT= Remote repository management made easy +WWW= https://github.com/x-motemen/ghq/ USES= go:modules USE_GITHUB= yes @@ -896,6 +927,7 @@ CATEGORIES= devel MAINTAINER= tobik@FreeBSD.org COMMENT= Remote repository management made easy +WWW= https://github.com/x-motemen/ghq/ USES= go:modules USE_GITHUB= yes @@ -930,7 +962,7 @@ daviddengcn-go-colortext-186a3d44e920_GH0.tar. 4534 B 1098 kBps 00s The port is now ready for a test build and further adjustments like creating a plist, writing a description, adding license information, options, etc. as normal. -If you are not testing your port in a clean environment like with Poudriere, remember to run `make clean` before any testing. +If you are not testing your port in a clean environment like with poudriere, remember to run `make clean` before any testing. ==== [[go-ex2]] @@ -965,8 +997,8 @@ Refer to crossref:uses[uses-cabal,`cabal`] for a list of variables that can be s .Creating a Port for a Hackage-hosted Haskell Application [example] ==== -When preparing a Haskell Cabal port, the package:devel/hs-cabal-install[] program is required, so make sure it is installed beforehand. -First we need to define common ports variables that allows cabal-install to fetch the package distribution file: +When preparing a Haskell Cabal port, package:devel/hs-cabal-install[] and package:ports-mgmt/hs-cabal2tuple[] programs are required, so make sure they are installed beforehand. +First we need to define common ports variables that allow cabal-install to fetch the package distribution file: [.programlisting] .... @@ -976,13 +1008,14 @@ CATEGORIES= devel MAINTAINER= haskell@FreeBSD.org COMMENT= Shell script analysis tool +WWW= https://www.shellcheck.net/ USES= cabal .include <bsd.port.mk> .... -This minimal Makefile allows us to fetch the distribution file: +This minimal Makefile fetches the distribution file with the `cabal-extract` helper target: [source,shell] .... @@ -995,49 +1028,34 @@ Downloaded ShellCheck-0.6.0 Unpacking to ShellCheck-0.6.0/ .... -Now we have ShellCheck.cabal package description file, which allows us to fetch all package's dependencies, including transitive ones: +Now that we have ShellCheck.cabal package description file under `${WRKSRC}`, we can use `cabal-configure` to generate the build plan: [source,shell] .... -% make cabal-extract-deps +% make cabal-configure [...] Resolving dependencies... -Downloading base-orphans-0.8.2 -Downloaded base-orphans-0.8.2 -Downloading primitive-0.7.0.0 -Starting base-orphans-0.8.2 (lib) -Building base-orphans-0.8.2 (lib) -Downloaded primitive-0.7.0.0 -Downloading dlist-0.8.0.7 +Build profile: -w ghc-8.10.7 -O1 +In order, the following would be built (use -v for more details): + - Diff-0.4.1 (lib) (requires download & build) + - OneTuple-0.3.1 (lib) (requires download & build) [...] .... -As a side effect, the package's dependencies are also compiled, so the command may take some time. Once done, a list of required dependencies can generated: [source,shell] .... % make make-use-cabal -USE_CABAL=QuickCheck-2.12.6.1 \ -hashable-1.3.0.0 \ -integer-logarithms-1.0.3 \ +USE_CABAL= QuickCheck-2.12.6.1 \ + hashable-1.3.0.0 \ + integer-logarithms-1.0.3 \ [...] .... Haskell packages may contain revisions, just like FreeBSD ports. -Revisions can affect only [.filename]#.cabal# files, but it is still important to pull them in. -To check `USE_CABAL` items for available revision updates, run following command: - -[source,shell] -.... -% make make-use-cabal-revs -USE_CABAL=QuickCheck-2.12.6.1_1 \ -hashable-1.3.0.0 \ -integer-logarithms-1.0.3_2 \ -[...] -.... - -Note additional version numbers after `_` symbol. +Revisions can affect [.filename]#.cabal# files only. +Note additional version numbers after the `_` symbol. Put newly generated `USE_CABAL` list instead of an old one. Finally, [.filename]#distinfo# needs to be regenerated to contain all the distribution files: @@ -1056,7 +1074,126 @@ QuickCheck-2.12.6.1/QuickCheck-2.12.6.1.tar.gz 65 kB 361 kBps 00s The port is now ready for a test build and further adjustments like creating a plist, writing a description, adding license information, options, etc. as normal. -If you are not testing your port in a clean environment like with Poudriere, remember to run `make clean` before any testing. +If you are not testing your port in a clean environment like with poudriere, remember to run `make clean` before any testing. +==== + +Some Haskell ports install various data files under `share/${PORTNAME}`. For such cases special handling is required on the port side. +The port should define the `CABAL_WRAPPER_SCRIPTS` knob listing each executable that is going to use data files. Moreover, in rare cases the program +being ported uses data files of other Haskell packages, in which case the `FOO_DATADIR_VARS` comes to the rescue. + +[[cabal-ex2]] +.Handling Data Files in a Haskell Port +[example] +==== +`devel/hs-profiteur` is a Haskell application that generates a single-page HTML with some content. + +[.programlisting] +.... +PORTNAME= profiteur + +[...] + +USES= cabal + +USE_CABAL= OneTuple-0.3.1_2 \ + QuickCheck-2.14.2 \ + [...] + +.include <bsd.port.mk> +.... + +It installs HTML templates under `share/profiteur`, so we need to add `CABAL_WRAPPER_SCRIPTS` knob: + +[.programlisting] +.... +[...] + +USE_CABAL= OneTuple-0.3.1_2 \ + QuickCheck-2.14.2 \ + [...] + + +CABAL_WRAPPER_SCRIPTS= ${CABAL_EXECUTABLES} + +.include <bsd.port.mk> +.... + +The program also tries to access the `jquery.js` file, which is a part of `js-jquery-3.3.1` Haskell package. +For that file to be found, we need to make the wrapper script to look for `js-jquery` data files in `share/profiteur` too. +We use `profiteur_DATADIR_VARS` for this: + +[.programlisting] +.... +[...] + +CABAL_WRAPPER_SCRIPTS= ${CABAL_EXECUTABLES} +profiteur_DATADIR_VARS= js-jquery + +.include <bsd.port.mk> +.... + +Now the port will install the actual binary into `libexec/cabal/profiteur` and the script into `bin/profiteur`. + +==== + +There is no easy way to find out a proper value for the `FOO_DATADIR_VARS` knob apart from running the program and checking that everything works. +Luckily, the need to use `FOO_DATADIR_VARS` is very rare. + +Another corner case when porting complex Haskell programs is the presence of VCS dependencies in the `cabal.project` file. + +[[cabal-ex3]] +.Porting Haskell Applications with VCS Dependencies +[example] +==== + +`net-p2p/cardano-node` is an extremely complex piece of software. In its `cabal.project` there are a lot of blocks like this: + +[.programlisting] +.... +[...] +source-repository-package + type: git + location: https://github.com/input-output-hk/cardano-crypto + tag: f73079303f663e028288f9f4a9e08bcca39a923e +[...] +.... + +Dependencies of type `source-repository-package` are automatically pulled in by `cabal` during the build process. +Unfortunately, this makes use of the network after the `fetch` stage. This is disallowed by the ports framework. +These sources need to be listed in the port's Makefile. The `make-use-cabal` helper target can make it easy for packages hosted on GitHub. +Running this target after the usual `cabal-extract` and `cabal-configure` will produce not only the `USE_CABAL` knob, but also `GH_TUPLE`: + +[source,shell] +.... +% make make-use-cabal +USE_CABAL= Diff-0.4.1 \ + Glob-0.10.2_3 \ + HUnit-1.6.2.0 \ + [...] + +GH_TUPLE= input-output-hk:cardano-base:0f3a867493059e650cda69e20a5cbf1ace289a57:cardano_base/dist-newstyle/src/cardano-b_-c8db9876882556ed \ + input-output-hk:cardano-crypto:f73079303f663e028288f9f4a9e08bcca39a923e:cardano_crypto/dist-newstyle/src/cardano-c_-253fd88117badd8f \ + [...] +.... + +It might be useful to separate the `GH_TUPLE` items coming from `make-use-cabal` from the other ones to make it easy to update the port: + +[.programlisting] +.... +GH_TUPLE= input-output-hk:cardano-base:0f3a867493059e650cda69e20a5cbf1ace289a57:cardano_base/dist-newstyle/src/cardano-b_-c8db9876882556ed \ + input-output-hk:cardano-crypto:f73079303f663e028288f9f4a9e08bcca39a923e:cardano_crypto/dist-newstyle/src/cardano-c_-253fd88117badd8f \ + [...] + +GH_TUPLE+= bitcoin-core:secp256k1:ac83be33d0956faf6b7f61a60ab524ef7d6a473a:secp +.... + +Haskell ports with VCS dependencies also require the following hack for the time being: + +[.programlisting] +.... +BINARY_ALIAS= git=true +.... + ==== [[using-autotools]] @@ -1165,7 +1302,7 @@ If `MASTER_SITES` is set to `CPAN`, the correct subdirectory is usually selected If the default subdirectory is wrong, `CPAN/Module` can be used to change it. `MASTER_SITES` can also be set to the old `MASTER_SITE_PERL_CPAN`, then the preferred value of `MASTER_SITE_SUBDIR` is the top-level hierarchy name. For example, the recommended value for `p5-Module-Name` is `Module`. -The top-level hierarchy can be examined at http://cpan.org/modules/by-module/[cpan.org]. +The top-level hierarchy can be examined at https://cpan.org/modules/by-module/[cpan.org]. This keeps the port working when the author of the module changes. The exception to this rule is when the relevant directory does not exist or the distfile does not exist in that directory. @@ -1203,8 +1340,8 @@ When a port needs Perl support, it must set `USES=perl5` with the optional `USE_ [NOTE] ==== -Ports of Perl modules which do not have an official website must link to `cpan.org` in the WWW line of [.filename]#pkg-descr#. -The preferred URL form is `http://search.cpan.org/dist/Module-Name/` (including the trailing slash). +Ports of Perl modules which do not have an official website must link to `cpan.org` in the WWW line of [.filename]#Makefile#. +The preferred URL form is `https://search.cpan.org/dist/Module-Name/` (including the trailing slash). ==== [NOTE] @@ -1371,6 +1508,7 @@ USE_XORG= x11 xpm If the port requires a Motif library, define `USES= motif` in the [.filename]#Makefile#. Default Motif implementation is package:x11-toolkits/open-motif[]. Users can choose package:x11-toolkits/lesstif[] instead by setting `WANT_LESSTIF` in their [.filename]#make.conf#. +Similarly package:x11-toolkits/open-motif-devel[] can be chosen by setting `WANT_OPEN_MOTIF_DEVEL` in [.filename]#make.conf#. `MOTIFLIB` will be set by [.filename]#motif.mk# to reference the appropriate Motif library. Please patch the source of the port to use `${MOTIFLIB}` wherever the Motif library is referenced in the original [.filename]#Makefile# or [.filename]#Imakefile#. @@ -1405,7 +1543,7 @@ USES= display [[desktop-entries]] === Desktop Entries -Desktop entries (http://standards.freedesktop.org/desktop-entry-spec/latest/[a Freedesktop standard]) provide a way to automatically adjust desktop features when a new program is installed, without requiring user intervention. +Desktop entries (https://standards.freedesktop.org/desktop-entry-spec/latest/[a Freedesktop standard]) provide a way to automatically adjust desktop features when a new program is installed, without requiring user intervention. For example, newly-installed programs automatically appear in the application menus of compatible desktop environments. Desktop entries originated in the GNOME desktop environment, but are now a standard and also work with KDE and Xfce. This bit of automation provides a real benefit to the user, and desktop entries are encouraged for applications which can be used in a desktop environment. @@ -1434,7 +1572,7 @@ Syntax is: DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify .... -The list of possible categories is available on the http://standards.freedesktop.org/menu-spec/latest/apa.html[Freedesktop website]. +The list of possible categories is available on the https://standards.freedesktop.org/menu-spec/latest/apa.html[Freedesktop website]. `StartupNotify` indicates whether the application is compatible with _startup notifications_. These are typically a graphic indicator like a clock that appear at the mouse pointer, menu, or panel to give the user an indication when a program is starting. A program that is compatible with startup notifications clears the indicator after it has started. @@ -1450,6 +1588,10 @@ DESKTOP_ENTRIES= "ToME" "Roguelike game based on JRR Tolkien's work" \ false .... +`DESKTOP_ENTRIES` are installed in the directory pointed to by the `DESKTOPDIR` +variable. +`DESKTOPDIR` defaults to [.filename]#${PREFIX}/share/applications# + [[using-gnome]] == Using GNOME @@ -1483,8 +1625,6 @@ Please use it as a guide for creating new ports. [.programlisting] .... -# $FreeBSD$ - PORTNAME= regexxer DISTVERSION= 0.10 CATEGORIES= devel textproc gnome @@ -1492,6 +1632,7 @@ MASTER_SITES= GNOME MAINTAINER= kwm@FreeBSD.org COMMENT= Interactive tool for performing search and replace operations +WWW= http://regexxer.sourceforge.net/ USES= gettext gmake localbase:ldflags pathfix pkgconfig tar:xz GNU_CONFIGURE= yes @@ -1955,7 +2096,8 @@ For ports that are part of Qt itself, see crossref:uses[uses-qt-dist,`qt-dist`]. [[qt-common]] === Ports That Require Qt -The Ports Collection provides support for Qt 5 with `USES+=qt:5`. +The Ports Collection provides support for Qt 5 and Qt 6 with `USES+=qt:5` and +`USES+=qt:6` respectively. Set `USE_QT` to the list of required Qt components (libraries, tools, plugins). The Qt framework exports a number of variables which can be used by ports, some of them listed below: @@ -1996,7 +2138,7 @@ Individual Qt tool and library dependencies must be specified in `USE_QT`. Every component can be suffixed with `_build` or `_run`, the suffix indicating whether the dependency on the component is at buildtime or runtime. If unsuffixed, the component will be depended on at both build- and runtime. Usually, library components are specified unsuffixed, tool components are mostly specified with the `_build` suffix and plugin components are specified with the `_run` suffix. -The most commonly used components are listed below (all available components are listed in `_USE_QT_ALL`, and `_USE_QT5_ONLY` in [.filename]#/usr/ports/Mk/Uses/qt.mk#): +The most commonly used components are listed below (all available components are listed in `_USE_QT_ALL`, which is generated from `_USE_QT_COMMON` and `_USE_QT[56]_ONLY` in [.filename]#/usr/ports/Mk/Uses/qt.mk#): [[using-qt-library-list]] .Available Qt Library Components @@ -2008,9 +2150,15 @@ The most commonly used components are listed below (all available components are |`3d` |Qt3D module +|`5compat` +|Qt 5 compatibility module for Qt 6 + |`assistant` |Qt 5 documentation browser +|`base` +|Qt 6 base module + |`canvas3d` |Qt canvas3d module @@ -2062,12 +2210,18 @@ The most commonly used components are listed below (all available components are |`l10n` |Qt localized messages +|`languageserver` +|Qt 6 Language Server Protocol implementation + |`linguist` |Qt 5 translation tool |`location` |Qt location module +|`lottie` +|Qt 6 QML API for rendering graphics and animations + |`multimedia` |Qt audio, video, radio and camera support module @@ -2090,7 +2244,10 @@ The most commonly used components are listed below (all available components are |Qt 5 screen magnifier |`plugininfo` -|Qt5 plugin metadata dumper +|Qt 5 plugin metadata dumper + +|`positioning` +|Qt 6 positioning API from sources such as satellite, wifi or text files. |`printsupport` |Qt print support module @@ -2120,7 +2277,7 @@ The most commonly used components are listed below (all available components are |Set of controls for building complete interfaces in Qt Quick |`remoteobjects` -|Qt5 SXCML module +|Qt 5 SXCML module |`script` |Qt 4-compatible scripting module @@ -2129,7 +2286,7 @@ The most commonly used components are listed below (all available components are |Qt Script additional components |`scxml` -|Qt5 SXCML module +|Qt 5 SXCML module |`sensors` |Qt sensors module @@ -2140,8 +2297,11 @@ The most commonly used components are listed below (all available components are |`serialport` |Qt functions to access serial ports +|`shadertools` +|Qt 6 tools for the cross-platform Qt shader pipeline + |`speech` -|Accessibilty features for Qt5 +|Accessibility features for Qt5 |`sql` |Qt SQL database integration module @@ -2173,6 +2333,12 @@ The most commonly used components are listed below (all available components are |`testlib` |Qt unit testing module +|`tools` +|Qt 6 assorted tools + +|`translations` +|Qt 6 translation module + |`uiplugin` |Custom Qt widget plugin interface for Qt Designer @@ -2183,7 +2349,7 @@ The most commonly used components are listed below (all available components are |Qt 5 Virtual Keyboard Module |`wayland` -|Qt5 wrapper for Wayland +|Qt 5 wrapper for Wayland |`webchannel` |Qt 5 library for integration of C++/QML with HTML/js clients @@ -3004,7 +3170,8 @@ The most current version is package:java/openjdk18[], with package:java/openjdk1 |Define for the remaining variables to have any effect. |`JAVA_VERSION` -|List of space-separated suitable Java versions for the port. An optional `"+"` allows specifying a range of versions (allowed values: `7[+] 8[+] 11[+] 12[+] 13[+] 14[+] 15[+] 16[+] 17[+] 18[+]`). +|List of space-separated suitable Java versions for the port. +An optional `\+` allows specifying a range of versions (allowed values: `8[+] 11[\+] 17[+] 18[\+] 19[+] 20[\+] 21[+]`). |`JAVA_OS` |List of space-separated suitable JDK port operating systems for the port (allowed values: `native linux`). @@ -3292,8 +3459,9 @@ PORTNAME= Date DISTVERSION= 1.4.3 CATEGORIES= devel www pear -MAINTAINER= example@domain.com +MAINTAINER= someone@example.org COMMENT= PEAR Date and Time Zone Classes +WWW= https://pear.php.net/package/Date/ USES= pear @@ -3341,6 +3509,7 @@ CATEGORIES= devel www pear MAINTAINER= horde@FreeBSD.org COMMENT= Horde Core Framework libraries +WWW= https://pear.horde.org/ OPTIONS_DEFINE= KOLAB SOCKETS KOLAB_DESC= Enable Kolab server support @@ -3386,7 +3555,7 @@ PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX} [cols="1,1", frame="none"] |=== |`USES=python` -|The port needs Python. The minimal required version can be specified with values such as `2.7+`. Version ranges can also be specified by separating two version numbers with a dash: `USES=python:3.2-3.3` +|The port needs Python. The minimal required version can be specified with values such as `3.10+`. Version ranges can also be specified by separating two version numbers with a dash: `USES=python:3.8-3.9`. Note that `USES=python` does _not_ cover Python 2.7, it needs to be requested explicitly with `USES=python:2.7+`. |`USE_PYTHON=distutils` |Use Python distutils for configuring, compiling, and installing. This is required when the port comes with [.filename]#setup.py#. This overrides the `do-build` and `do-install` targets and may also override `do-configure` if `GNU_CONFIGURE` is not defined. Additionally, it implies `USE_PYTHON=flavors`. @@ -3463,8 +3632,9 @@ PORTNAME= sample DISTVERSION= 1.2.3 CATEGORIES= devel -MAINTAINER= john@doe.tld +MAINTAINER= fred.bloggs@example.com COMMENT= Python sample module +WWW= https://example.com/project/sample/ RUN_DEPENDS= ${PYTHON_PKGNAMEPREFIX}six>0:devel/py-six@${PY_FLAVOR} @@ -3529,69 +3699,6 @@ It is possible to specify the desired version of `tcl` by appending `:_xx_`, for See the crossref:uses[uses-tcl,`USES=tcl`] and crossref:uses[uses-tk,`USES=tk`] of crossref:uses[uses,Using `USES` Macros] for a full description of those variables. A complete list of those variables is available in [.filename]#/usr/ports/Mk/Uses/tcl.mk#. -[[using-ruby]] -== Using Ruby - -[[using-ruby-variables]] -.Useful Variables for Ports That Use Ruby -[cols="1,1", frame="none", options="header"] -|=== -| Variable -| Description - -|`USE_RUBY` -|Adds build and run dependencies on Ruby. - -|`USE_RUBY_EXTCONF` -|The port uses [.filename]#extconf.rb# to configure. - -|`USE_RUBY_SETUP` -|The port uses [.filename]#setup.rb# to configure. - -|`RUBY_SETUP` -|Override the name of the setup script from [.filename]#setup.rb#. Another common value is [.filename]#install.rb#. -|=== - -This table shows the selected variables available to port authors via the ports infrastructure. -These variables are used to install files into their proper locations. -Use them in [.filename]#pkg-plist# as much as possible. -Do not redefine these variables in the port. - -[[using-ruby-variables-ro]] -.Selected Read-Only Variables for Ports That Use Ruby -[cols="1,1,1", frame="none", options="header"] -|=== -| Variable -| Description -| Example value - -|`RUBY_PKGNAMEPREFIX` -|Used as a `PKGNAMEPREFIX` to distinguish packages for different Ruby versions. -|`ruby19-` - -|`RUBY_VERSION` -|Full version of Ruby in the form of `x.y.z[.p]`. -|`1.9.3.484` - -|`RUBY_SITELIBDIR` -|Architecture independent libraries installation path. -|`/usr/local/lib/ruby/site_ruby/1.9` - -|`RUBY_SITEARCHLIBDIR` -|Architecture dependent libraries installation path. -|`/usr/local/lib/ruby/site_ruby/1.9/amd64-freebsd10` - -|`RUBY_MODDOCDIR` -|Module documentation installation path. -|`/usr/local/share/doc/ruby19/patsy` - -|`RUBY_MODEXAMPLESDIR` -|Module examples installation path. -|`/usr/local/share/examples/ruby19/patsy` -|=== - -A complete list of available variables can be found in [.filename]#/usr/ports/Mk/bsd.ruby.mk#. - [[using-sdl]] == Using SDL @@ -3991,11 +4098,11 @@ the Lua API changes to some extent in every version, and configuration tools lik Software that uses Lua may have been written to auto-detect the Lua version in use. In general ports should override this assumption, and force the use of the specific Lua version selected as described above. -Depending on the software being ported, this might require any or all of: +Depending on the software being ported, this might require any or all of: -* Using `LUA_VER` as part of a parameter to the software's configuration script via `CONFIGURE_ARGS` or `CONFIGURE_ENV` (or equivalent for other build systems); -* Adding `-I${LUA_INCDIR}`, `-L${LUA_LIBDIR}`, and `-llua-${LUA_VER}` to `CFLAGS`, `LDFLAGS`, `LIBS` respectively as appropriate; -* Patch the software's configuration or build files to select the correct version. +* Using `LUA_VER` as part of a parameter to the software's configuration script via `CONFIGURE_ARGS` or `CONFIGURE_ENV` (or equivalent for other build systems); +* Adding `-I${LUA_INCDIR}`, `-L${LUA_LIBDIR}`, and `-llua-${LUA_VER}` to `CFLAGS`, `LDFLAGS`, `LIBS` respectively as appropriate; +* Patch the software's configuration or build files to select the correct version. [[lua-version-flavors]] @@ -4029,10 +4136,10 @@ USES= lua:flavors .... This operates the same way as the `module` parameter described above, but without the assumption that the package should be documented as a Lua module (so `LUA_DOCSDIR` and `LUA_EXAMPLESDIR` are not defined by default). -However, the port may choose to define `LUA_DOCSUBDIR` as a suitable subdirectory name (usually the port's `PORTNAME` as long as this does not conflict with the `PORTNAME` of any module), in which case the framework will define both `LUA_DOCSDIR` and `LUA_EXAMPLESDIR`. +However, the port may choose to define `LUA_DOCSUBDIR` as a suitable subdirectory name (usually the port's `PORTNAME` as long as this does not conflict with the `PORTNAME` of any module), in which case the framework will define both `LUA_DOCSDIR` and `LUA_EXAMPLESDIR`. As with module ports, a flavored port should avoid installing files that would conflict between versions. -Typically this is done by adding `LUA_VER_STR` as a suffix to program names (e.g. using crossref:uses[uses-uniquefiles,`uniquefiles`]), and otherwise using either `LUA_VER` or `LUA_VER_STR` as part of any other files or subdirectories used outside of `LUA_MODLIBDIR` and `LUA_MODSHAREDIR`. +Typically this is done by adding `LUA_VER_STR` as a suffix to program names (e.g. using crossref:uses[uses-uniquefiles,`uniquefiles`]), and otherwise using either `LUA_VER` or `LUA_VER_STR` as part of any other files or subdirectories used outside of `LUA_MODLIBDIR` and `LUA_MODSHAREDIR`. [[lua-defined-variables]] === Defined Variables @@ -4047,10 +4154,10 @@ These variables are available in the port. | Description |`LUA_VER` -|The Lua version that is going to be used (for example, `5.1`) +|The Lua version that is going to be used (for example, `5.4`) |`LUA_VER_STR` -|The Lua version without the dots (for example, `51`) +|The Lua version without the dots (for example, `54`) |`LUA_FLAVOR` |The flavor name corresponding to the selected Lua version, to be used for specifying dependencies @@ -4083,10 +4190,10 @@ These variables are available in the port. |The package name prefix used by Lua modules |`LUA_CMD` -|The name of the Lua interpreter (e.g. `lua53`) +|The name of the Lua interpreter (e.g. `lua54`) |`LUAC_CMD` -|The name of the Lua compiler (e.g. `luac53`) +|The name of the Lua compiler (e.g. `luac54`) |=== These additional variables are available for ports that specified the `module` parameter: @@ -4121,8 +4228,9 @@ PORTNAME= sample DISTVERSION= 1.2.3 CATEGORIES= whatever -MAINTAINER= john@doe.tld +MAINTAINER= fred.bloggs@example.com COMMENT= Sample +WWW= https://example.com/lua_sample/sample/ RUN_DEPENDS= ${LUA_REFMODLIBDIR}/lpeg.so:devel/lua-lpeg@${LUA_FLAVOR} @@ -4144,8 +4252,9 @@ DISTVERSION= 1.2.3 CATEGORIES= whatever PKGNAMEPREFIX= ${LUA_PKGNAMEPREFIX} -MAINTAINER= john@doe.tld +MAINTAINER= fred.bloggs@example.com COMMENT= Sample +WWW= https://example.com/lua_sample/sample/ USES= lua:module @@ -4156,6 +4265,244 @@ DOCSDIR= ${LUA_DOCSDIR} ==== +[[using-guile]] +== Using Guile + +This section describes the status of Guile in the ports tree and its integration with the ports system. + +[[guile-introduction]] +=== Introduction + +There are multiple versions of the Guile libraries and corresponding interpreters, which conflict between them (install files under the same name). +In the ports tree this problem has been solved by installing each version under a different name using version number suffixes. +In most cases, applications should detect the correct version from the configuration variables provided and use `pkg-config` to determine the name and associated paths. +However, some applications (especially those using their own configuration rules for `cmake` or `meson`) will always try to use the latest available version. +In this case, either patch the port or declare a build conflict (see the `conflicts` option below) to ensure that the correct dependency is generated when building outside of poudriere. + +Applications that use Guile should normally build for just one version, +preferably the one specified in `DEFAULT_VERSIONS`, +or failing that the latest version that they support. +However, Guile or Scheme libraries, or extension modules for Guile are built in a separate flavor for each Guile version that they support, +and dependencies on such ports should specify the flavor using the `@${GUILE_FLAVOR}` suffix on the port origin. + +[[guile-version]] +=== Version Selection + +A port using Guile should define `USES=guile:__arg,arg...__` with appropriate arguments as follows: + +[[guile-defined-uses-args]] +.Arguments Defined for Ports That Use Guile +[cols="1m,4", frame="none", options="header"] +|=== +| Name +| Description + +|_X.Y_ +|Declare compatibility with Guile version `X.Y`. +Currently available versions are `1.8` (obsolete), `2.2` and `3.0`. +Multiple versions may be specified. + +|flavors +|Create a flavor for every Guile version specified. +The version specified by `DEFAULT_VERSIONS` will become the default flavor. +Flavor names are of the form `guileXY`. + +|build +|Add the Guile interpreter as a build dependency only, rather than a library dependency. +`build` and `run` may both be specified. + +|run +|Add the Guile interpreter as a runtime dependency only, rather than a library dependency. +`build` and `run` may both be specified. + +|alias +|Add `BINARY_ALIAS` values for the interpreter and tools. + +|conflicts +|Declare `CONFLICTS_BUILD` for Guile versions newer than the one selected. +Use this when the port cannot be configured to use a specific Guile version. +|=== + +Some additional arguments are available for handling unusual cases; see `Mk/Uses/guile.mk` for details. + +Unless `build` or `run` is specified, then `LIB_DEPENDS` receives both the `libguile` library dependency and also any additional dependencies required by the guile version, e.g. `libgc`. +Normally the port should not need any additional dependencies related to its use of Guile. + +[[guile-version-config]] +=== Configuration flags + +Software that uses Guile should be using the `pkg-config` mechanism to obtain compiler and linker flags. +Some older or esoteric ports may be using `guile-config` or obtaining values directly from `guile` instead, +which should also work (the `alias` argument may be useful in some of these cases). + +The framework tries to inform the port of the desired Guile version using the following methods: + +* `GUILE_EFFECTIVE_VERSION` is added to `CONFIGURE_ENV`; +* The full path to the Guile binary is specified in the `GUILE` variable in `CONFIGURE_ENV` and `MAKE_ENV`; +* If the `alias` option is used, the desired Guile version's binaries are the ones aliased; +* If the `alias` option is not used, paths to the desired Guile version's tools (`guild`, `guile-config`, etc.) are added to `CONFIGURE_ENV` and `MAKE_ENV` as variables `GUILD`, `GUILE_CONFIG`, etc. + +For some ports, it may be necessary to specify the version in additional ways, such as via `CONFIGURE_ARGS` or `MESON_ARGS`, +depending on the port. + +If none of these methods cause the port to select the specified Guile version when other versions are present, +then preferably patch it to do so. +If that is not feasible, specify the `conflicts` option to prevent building the port under conditions where it will detect the wrong version. + +[[guile-version-flavors]] +=== Version Flavors + +A port which installs a Guile extension or library, or a Scheme library that precompiles for Guile, +should build a separate flavor for each supported Guile version. +This is done by adding the `flavors` option. + +Since each flavor must have a different package name, such ports must set `PKGNAMESUFFIX`, typically: + +[.programlisting] +.... +PKGNAMESUFFIX= -${FLAVOR} +.... + +Such ports must install Scheme files to `GUILE_SITE_DIR` rather than to `GUILE_GLOBAL_SITE_DIR` even when the files are not version-specific. +This often requires patching the port. + +Additionally, if such a port installs a `.pc` file, it must be placed in `GUILE_PKGCONFIG_PATH` rather than in the global `pkgconfig` directory. +This allows dependent ports to find a correct configuration for the specific Guile version in use. + +If a Guile extension port installs a `.so` file, then it must usually be placed in the Guile-version-specific `extensions` directory. +`USE_LDCONFIG` should usually not be used. + +Any other files installed by a flavored port must likewise be in version-specific directories or use version-specific filenames. +For documentation and examples, `GUILE_DOCS_DIR` and `GUILE_EXAMPLES_DIR` specify suitable locations in which the port should create a subdirectory, +see below. + +[[guile-defined-variables]] +=== Defined Variables + +These variables are available in the port. + +[[using-guile-variables-ports]] +.Variables Defined for Ports That Use Guile +[cols="1,3m,6", frame="none", options="header"] +|=== +| Name +| Sample Value +| Description + +|`GUILE_VER` +|3.0 +|Guile version in use. + +|`GUILE_SFX` +|3 +|Short suffix used on some names. +Use only with care; may be non-unique or may change in the future. + +|`GUILE_FLAVOR` +|guile30 +|Flavor name corresponding to the selected version. + +|`GUILE_PORT` +|lang/guile3 +|Port origin of the specified Guile version. + +|`GUILE_PREFIX` +|${PREFIX} +|Directory prefix to be used for installation. + +|`GUILE_CMD` +|guile-3.0 +|Name of the Guile interpreter, with version suffix. + +|`GUILE_CMDPATH` +|${LOCALBASE}/bin/guile-3.0 +|Full path to the Guile interpreter. + +|`GUILD_CMD` +|guild-3.0 +|Name of the Guild tool, with version suffix. + +|`GUILD_CMDPATH` +|${LOCALBASE}/bin/guild-3.0 +|Full path to the Guild tool. + +|`++GUILE_*_CMD++` + +`++GUILE_*_CMDPATH++` +| +|Like `GUILE_CMD` and `GUILE_CMDPATH`, but for other tool binaries. + +|`GUILE_PKGCONFIG_PATH` +|${LOCALBASE}/libdata/pkgconfig/guile/3.0 +|Where packages using `flavors` should install `.pc` files. + +|`GUILE_INFO_PATH` +|share/info/guile3 +|A suitable value for `INFO_PATH` for ports using the `flavors` option. +|=== + +The following are defined as variables and as `PLIST_SUB` entries. +The variable form is suffixed with `_DIR` and is a full path (prefixed with `GUILE_PREFIX`). + +[[using-guile-path-variables-ports]] +.Path Substitutions Defined for Ports That Use Guile +[cols="1m,3m,6", frame="none", options="header"] +|=== +| Name +| Sample Value +| Description + +|GUILE_GLOBAL_SITE +|share/guile/site +|Site directory shared by all guile versions; this should not usually be used. + +|GUILE_SITE +|share/guile/3.0/site +|Site directory for the selected Guile version. + +|GUILE_SITE_CCACHE +|lib/guile/3.0/site-ccache +|Directory for compiled bytecode files. + +|GUILE_DOCS +|share/doc/guile30 +|Parent directory for version-specific documentation. + +|GUILE_EXAMPLES +|share/examples/guile30 +|Parent directory for version-specific examples. +|=== + +[[guile-examples]] +=== Examples + +[[guile-app-Makefile]] +.Makefile for an application using Guile +[example] +==== +This example shows how to reference a Guile library required at build and run time. +Notice that the reference must specify a flavor. +This example assumes that the application is using `pkg-config` to locate dependencies. + +[.programlisting] +.... +PORTNAME= sample +DISTVERSION= 1.2.3 +CATEGORIES= whatever + +MAINTAINER= fred.bloggs@example.com +COMMENT= Sample +WWW= https://example.com/guile_sample/sample/ + +BUILD_DEPENDS= guile-lib-${GUILE_FLAVOR}>=0.2.5:devel/guile-lib@${GUILE_FLAVOR} +RUN_DEPENDS= guile-lib-${GUILE_FLAVOR}>=0.2.5:devel/guile-lib@${GUILE_FLAVOR} + +USES= guile:2.2,3.0 pkgconfig + +.include <bsd.port.mk> +.... + +==== + [[using-iconv]] == Using `iconv` @@ -4354,6 +4701,53 @@ However, Xfce components and non-Xfce dependencies of the port must be included Do not count on an Xfce component to provide a sub-dependency other than itself for the main port. ==== +[[using-budgie]] +== Using Budgie + +Applications or libraries depending on the Budgie desktop should set `USES= budgie` and set `USE_BUDGIE` to the list of required components. + +[cols="1,1", frame="none", options="header"] +|=== +| Name +| Description + +| `libbudgie` +| Desktop core (library) + +| `libmagpie` +| Budgie's X11 window manager and compositor library + +| `raven` +| All-in-one center in panel for accessing different applications widgets + +| `screensaver` +| Desktop-specific screensaver + +|=== + +[NOTE] +==== +All application widgets communicate through the *org.budgie_desktop.Raven* service. + +The default dependency is lib- and run-time, it can be changed with `:build` or `:run`, for example: + +[.programlisting] +.... +USES= budgie +USE_BUDGIE= screensaver:build +.... +==== + +[[budgie-components-example]] +.`USE_BUDGIE` Example +[example] +==== +[.programlisting] +.... +USES= budgie gettext gnome meson pkgconfig +USE_BUDGIE= libbudgie +.... +==== [[using-databases]] == Using Databases @@ -4464,8 +4858,6 @@ An example simple [.filename]#rc.d# script to start the doormand daemon: .... #!/bin/sh -# $FreeBSD$ -# # PROVIDE: doormand # REQUIRE: LOGIN # KEYWORD: shutdown @@ -4538,7 +4930,6 @@ The package:devel/rclint[] port can check for most of these, but it is not a sub [.procedure] . If this is a new file, does it have a [.filename]#.sh# extension? If so, that must be changed to just [.filename]#file.in# since [.filename]#rc.d# files may not end with that extension. -. Does the file have a `$FreeBSD$` tag? . Do the name of the file (minus [.filename]#.in#), the `PROVIDE` line, and `$` _name_ all match? The file name matching `PROVIDE` makes debugging easier, especially for man:rcorder[8] issues. Matching the file name and `$`_name_ makes it easier to figure out which variables are relevant in [.filename]#rc.conf[.local]#. It is also a policy for all new scripts, including those in the base system. . Is the `REQUIRE` line set to `LOGIN`? This is mandatory for scripts that run as a non-root user. If it runs as root, is there a good reason for it to run prior to `LOGIN`? If not, it must run after so that local scrips can be loosely grouped to a point in man:rcorder[8] after most everything in the base is already running. . Does the script start a persistent service? If so, it must have `KEYWORD: shutdown`. @@ -4624,17 +5015,20 @@ It is not necessary to make an option for it. If an option is used, though, always enable it in `OPTIONS_DEFAULT`. [[shell-completion-paths]] -.Shell completion file paths -[cols="1,1", frame="none"] +.Full shell completion file names +[cols="1,1,1", frame="none"] |=== |`bash` -|[.filename]#${PREFIX}/etc/bash_completion.d# +|[.filename]#${PREFIX}/etc/bash_completion.d# or [.filename]#${PREFIX}/share/bash-completion/completions# +|(any unique file names in one of these folders) |`fish` -|[.filename]#${PREFIX}/share/fish/vendor_completions.d# +|[.filename]#${PREFIX}/share/fish/completions/${PORTNAME}.fish# +| |`zsh` -|[.filename]#${PREFIX}/share/zsh/site-functions# +|[.filename]#${PREFIX}/share/zsh/site-functions/_${PORTNAME}# +| |=== Do not register any dependencies on the shells themselves. |