diff --git a/documentation/content/en/articles/linux-users/_index.adoc b/documentation/content/en/articles/linux-users/_index.adoc index 7086c93f7c..50a0c2d54f 100644 --- a/documentation/content/en/articles/linux-users/_index.adoc +++ b/documentation/content/en/articles/linux-users/_index.adoc @@ -1,378 +1,378 @@ --- title: FreeBSD Quickstart Guide for Linux® Users authors: - author: John Ferrell copyright: 2008 The FreeBSD Documentation Project description: This document is intended to quickly familiarize intermediate to advanced Linux® users with the basics of FreeBSD. trademarks: ["freebsd", "intel", "redhat", "linux", "unix", "general"] tags: ["Quickstart", "guide", "Linux", "FreeBSD"] --- = FreeBSD Quickstart Guide for Linux(R) Users :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :images-path: articles/linux-users/ ifdef::env-beastie[] ifdef::backend-html5[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] :imagesdir: ../../../images/{images-path} endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [.abstract-title] Abstract This document is intended to quickly familiarize intermediate to advanced Linux(R) users with the basics of FreeBSD. ''' toc::[] [[intro]] == Introduction This document highlights some of the technical differences between FreeBSD and Linux(R) so that intermediate to advanced Linux(R) users can quickly familiarize themselves with the basics of FreeBSD. This document assumes that FreeBSD is already installed. Refer to the extref:{handbook}[Installing FreeBSD, bsdinstall] chapter of the FreeBSD Handbook for help with the installation process. [[shells]] == Default Shell Linux(R) users are often surprised to find that Bash is not the default shell in FreeBSD. In fact, Bash is not included in the default installation. Instead, the Bourne shell-compatible man:sh[1] as the default user shell. The root shell is man:tcsh[1] by default on FreeBSD 13 and earlier and man:sh[1] on FreeBSD 14 and later. man:sh[1] is very similar to Bash but with a much smaller feature-set. Generally shell scripts written for man:sh[1] will run in Bash, but the reverse is not always true. However, Bash and other shells are available for installation using the FreeBSD extref:{handbook}[Packages and Ports Collection, ports]. After installing another shell, use man:chsh[1] to change a user's default shell. It is recommended that the `root` user's default shell remain unchanged since shells which are not included in the base distribution are installed to [.filename]#/usr/local/bin#. In the event of a problem, the file system where [.filename]#/usr/local/bin# is located may not be mounted. In this case, `root` would not have access to its default shell, preventing `root` from logging in and fixing the problem. [[software]] == Packages and Ports: Adding Software in FreeBSD FreeBSD provides two methods for installing applications: binary packages and compiled ports. Each method has its own benefits: .Binary Packages * Faster installation as compared to compiling large applications. * Does not require an understanding of how to compile software. * No need to install a compiler. .Ports * Ability to customize installation options. * Custom patches can be applied. If an application installation does not require any customization, installing the package is sufficient. Compile the port instead whenever an application requires customization of the default options. If needed, a custom package can be compiled from ports using `make package`. -A complete list of all available ports and packages can be found https://www.freebsd.org/ports/[here]. +A complete list of all available ports and packages can be found https://ports.freebsd.org[here]. [[packages]] === Packages Packages are pre-compiled applications, the FreeBSD equivalents of [.filename]#.deb# files on Debian/Ubuntu based systems and [.filename]#.rpm# files on Red Hat/Fedora based systems. Packages are installed using `pkg`. For example, the following command installs Apache 2.4: [source,shell] .... # pkg install apache24 .... For more information on packages refer to section 5.4 of the FreeBSD Handbook: extref:{handbook}[Using pkgng for Binary Package Management, pkgng-intro]. [[ports]] === Ports The FreeBSD Ports Collection is a framework of [.filename]#Makefiles# and patches specifically customized for installing applications from source on FreeBSD. When installing a port, the system will fetch the source code, apply any required patches, compile the code, and install the application and any required dependencies. The Ports Collection, sometimes referred to as the ports tree, can be installed to [.filename]#/usr/ports# using link:{handbook}mirrors/#git[Git]. Detailed instructions for installing the Ports Collection can be found in extref:{handbook}[section 4.5.1, ports-using-installation-methods] of the FreeBSD Handbook. To compile a port, change to the port's directory and start the build process. The following example installs Apache 2.4 from the Ports Collection: [source,shell] .... # cd /usr/ports/www/apache24 # make install clean .... A benefit of using ports to install software is the ability to customize the installation options. This example specifies that the mod_ldap module should also be installed: [source,shell] .... # cd /usr/ports/www/apache24 # make WITH_LDAP="YES" install clean .... Refer to extref:{handbook}[Using the Ports Collection, ports-using] for more information. [[startup]] == System Startup Many Linux(R) distributions use the SysV init system, whereas FreeBSD uses the traditional BSD-style man:init[8]. Under the BSD-style man:init[8], there are no run-levels and [.filename]#/etc/inittab# does not exist. Instead, startup is controlled by man:rc[8] scripts. At system boot, [.filename]#/etc/rc# reads [.filename]#/etc/rc.conf# and [.filename]#/etc/defaults/rc.conf# to determine which services are to be started. The specified services are then started by running the corresponding service initialization scripts located in [.filename]#/etc/rc.d/# and [.filename]#/usr/local/etc/rc.d/#. These scripts are similar to the scripts located in [.filename]#/etc/init.d/# on Linux(R) systems. The scripts found in [.filename]#/etc/rc.d/# are for applications that are part of the "base" system, such as man:cron[8], man:sshd[8], and man:syslog[3]. The scripts in [.filename]#/usr/local/etc/rc.d/# are for user-installed applications such as Apache and Squid. Since FreeBSD is developed as a complete operating system, user-installed applications are not considered to be part of the "base" system. User-installed applications are generally installed using extref:{handbook}[Packages or Ports, ports-using]. In order to keep them separate from the base system, user-installed applications are installed under [.filename]#/usr/local/#. Therefore, user-installed binaries reside in [.filename]#/usr/local/bin/#, configuration files are in [.filename]#/usr/local/etc/#, and so on. Services are enabled by adding an entry for the service in [.filename]#/etc/rc.conf#. The system defaults are found in [.filename]#/etc/defaults/rc.conf# and these default settings are overridden by settings in [.filename]#/etc/rc.conf#. Refer to man:rc.conf[5] for more information about the available entries. When installing additional applications, review the application's install message to determine how to enable any associated services. The following entries in [.filename]#/etc/rc.conf# enable man:sshd[8], enable Apache 2.4, and specify that Apache should be started with SSL. [.programlisting] .... # enable SSHD sshd_enable="YES" # enable Apache with SSL apache24_enable="YES" apache24_flags="-DSSL" .... Once a service has been enabled in [.filename]#/etc/rc.conf#, it can be started without rebooting the system: [source,shell] .... # service sshd start # service apache24 start .... If a service has not been enabled, it can be started from the command line using `onestart`: [source,shell] .... # service sshd onestart .... [[network]] == Network Configuration Instead of a generic _ethX_ identifier that Linux(R) uses to identify a network interface, FreeBSD uses the driver name followed by a number. The following output from man:ifconfig[8] shows two Intel(R) Pro 1000 network interfaces ([.filename]#em0# and [.filename]#em1#): [source,shell] .... % ifconfig em0: flags=8843 mtu 1500 options=b inet 10.10.10.100 netmask 0xffffff00 broadcast 10.10.10.255 ether 00:50:56:a7:70:b2 media: Ethernet autoselect (1000baseTX ) status: active em1: flags=8843 mtu 1500 options=b inet 192.168.10.222 netmask 0xffffff00 broadcast 192.168.10.255 ether 00:50:56:a7:03:2b media: Ethernet autoselect (1000baseTX ) status: active .... An IP address can be assigned to an interface using man:ifconfig[8]. To remain persistent across reboots, the IP configuration must be included in [.filename]#/etc/rc.conf#. The following [.filename]#/etc/rc.conf# entries specify the hostname, IP address, and default gateway: [.programlisting] .... hostname="server1.example.com" ifconfig_em0="inet 10.10.10.100 netmask 255.255.255.0" defaultrouter="10.10.10.1" .... Use the following entries to instead configure an interface for DHCP: [.programlisting] .... hostname="server1.example.com" ifconfig_em0="DHCP" .... [[firewall]] == Firewall FreeBSD does not use Linux(R) IPTABLES for its firewall. Instead, FreeBSD offers a choice of three kernel level firewalls: * extref:{handbook}[PF, firewalls-pf] * extref:{handbook}[IPFILTER, firewalls-ipf] * extref:{handbook}[IPFW, firewalls-ipfw] PF is developed by the OpenBSD project and ported to FreeBSD. PF was created as a replacement for IPFILTER and its syntax is similar to that of IPFILTER. PF can be paired with man:altq[4] to provide QoS features. This sample PF entry allows inbound SSH: [.programlisting] .... pass in on $ext_if inet proto tcp from any to ($ext_if) port 22 .... IPFILTER is the firewall application developed by Darren Reed. It is not specific to FreeBSD and has been ported to several operating systems including NetBSD, OpenBSD, SunOS, HP/UX, and Solaris. The IPFILTER syntax to allow inbound SSH is: [.programlisting] .... pass in on $ext_if proto tcp from any to any port = 22 .... IPFW is the firewall developed and maintained by FreeBSD. It can be paired with man:dummynet[4] to provide traffic shaping capabilities and simulate different types of network connections. The IPFW syntax to allow inbound SSH would be: [.programlisting] .... ipfw add allow tcp from any to me 22 in via $ext_if .... [[updates]] == Updating FreeBSD There are two methods for updating a FreeBSD system: from source or binary updates. Updating from source is the most involved update method, but offers the greatest amount of flexibility. The process involves synchronizing a local copy of the FreeBSD source code with the FreeBSD Git repository. Once the local source code is up-to-date, a new version of the kernel and userland can be compiled. Binary updates are similar to using `yum` or `apt-get` to update a Linux(R) system. In FreeBSD, man:freebsd-update[8] can be used fetch new binary updates and install them. These updates can be scheduled using man:cron[8]. [NOTE] ==== When using man:cron[8] to schedule updates, use `freebsd-update cron` in the man:crontab[1] to reduce the possibility of a large number of machines all pulling updates at the same time: [.programlisting] .... 0 3 * * * root /usr/sbin/freebsd-update cron .... ==== For more information on source and binary updates, refer to extref:{handbook}[the chapter on updating, updating-upgrading-freebsdupdate] in the FreeBSD Handbook. [[procfs]] == procfs: Gone But Not Forgotten In some Linux(R) distributions, one could look at [.filename]#/proc/sys/net/ipv4/ip_forward# to determine if IP forwarding is enabled. In FreeBSD, man:sysctl[8] is instead used to view this and other system settings. For example, use the following to determine if IP forwarding is enabled on a FreeBSD system: [source,shell] .... % sysctl net.inet.ip.forwarding net.inet.ip.forwarding: 0 .... Use `-a` to list all the system settings: [source,shell] .... % sysctl -a | more .... If an application requires procfs, add the following entry to [.filename]#/etc/fstab#: [source,shell] .... proc /proc procfs rw,noauto 0 0 .... Including `noauto` will prevent [.filename]#/proc# from being automatically mounted at boot. To mount the file system without rebooting: [source,shell] .... # mount /proc .... [[commands]] == Common Commands Some common command equivalents are as follows: [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Linux(R) command (Red Hat/Debian) | FreeBSD equivalent | Purpose |`yum install _package_` / `apt-get install _package_` |`pkg install _package_` |Install package from remote repository |`rpm -ivh _package_` / `dpkg -i _package_` |`pkg add _package_` |Install local package |`rpm -qa` / `dpkg -l` |`pkg info` |List installed packages |`lspci` |`pciconf` |List PCI devices |`lsmod` |`kldstat` |List loaded kernel modules |`modprobe` |`kldload` / `kldunload` |Load/Unload kernel modules |`strace` |`truss` |Trace system calls |=== [[conclusion]] == Conclusion This document has provided an overview of FreeBSD. Refer to the extref:{handbook}[FreeBSD Handbook] for more in-depth coverage of these topics as well as the many topics not covered by this document. diff --git a/documentation/content/en/articles/releng/_index.adoc b/documentation/content/en/articles/releng/_index.adoc index 9a48f7ee22..34a81675b9 100644 --- a/documentation/content/en/articles/releng/_index.adoc +++ b/documentation/content/en/articles/releng/_index.adoc @@ -1,447 +1,447 @@ --- title: Legacy FreeBSD Release Engineering authors: - author: Murray Stokely email: murray@FreeBSD.org webpage: https://people.FreeBSD.org/~murray/ description: This paper describes the approach previously used by the FreeBSD release engineering team to make production quality releases of the FreeBSD Operating System trademarks: ["freebsd", "intel", "general"] tags: ["Release", "Engineering", "Historical", "FreeBSD"] --- = FreeBSD Release Engineering :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :images-path: articles/releng/ ifdef::env-beastie[] ifdef::backend-html5[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] :imagesdir: ../../../images/{images-path} endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [.abstract-title] Abstract [NOTE] ==== This document is outdated and does not accurately describe the current release procedures of the FreeBSD Release Engineering team. It is retained for historical purposes. The current procedures used by the FreeBSD Release Engineering team are available in the extref:{freebsd-releng}[FreeBSD Release Engineering] article. ==== This paper describes the approach used by the FreeBSD release engineering team to make production quality releases of the FreeBSD Operating System. It details the methodology used for the official FreeBSD releases and describes the tools available for those interested in producing customized FreeBSD releases for corporate rollouts or commercial productization. ''' toc::[] [[introduction]] == Introduction The development of FreeBSD is a very open process. FreeBSD is comprised of contributions from thousands of people around the world. The FreeBSD Project provides Subversion footnote:[Subversion, http://subversion.apache.org] access to the general public so that others can have access to log messages, diffs (patches) between development branches, and other productivity enhancements that formal source code management provides. This has been a huge help in attracting more talented developers to FreeBSD. However, I think everyone would agree that chaos would soon manifest if write access to the main repository was opened up to everyone on the Internet. Therefore only a "select" group of nearly 300 people are given write access to the Subversion repository. These extref:{contributors}[FreeBSD committers, staff-committers]footnote:[extref:{contributors}[FreeBSD committers, staff-committers]] are usually the people who do the bulk of FreeBSD development. An elected link:https://www.FreeBSD.org/administration/#t-core[Core Team]footnote:[link:https://www.FreeBSD.org/administration/#t-core[FreeBSD Core Team]] of developers provide some level of direction over the project. The rapid pace of `FreeBSD` development makes the main development branch unsuitable for the everyday use by the general public. In particular, stabilizing efforts are required for polishing the development system into a production quality release. To solve this conflict, development continues on several parallel tracks. The main development branch is the _HEAD_ or _trunk_ of our Subversion tree, known as "FreeBSD-CURRENT" or "-CURRENT" for short. A set of more stable branches are maintained, known as "FreeBSD-STABLE" or "-STABLE" for short. All branches live in a master Subversion repository maintained by the FreeBSD Project. FreeBSD-CURRENT is the "bleeding-edge" of FreeBSD development where all new changes first enter the system. FreeBSD-STABLE is the development branch from which major releases are made. Changes go into this branch at a different pace, and with the general assumption that they have first gone into FreeBSD-CURRENT and have been thoroughly tested by our user community. The term _stable_ in the name of the branch refers to the presumed Application Binary Interface stability, which is promised by the project. This means that a user application compiled on an older version of the system from the same branch works on a newer system from the same branch. The ABI stability has improved greatly from the compared to previous releases. In most cases, binaries from the older _STABLE_ systems run unmodified on newer systems, including __HEAD__, assuming that the system management interfaces are not used. In the interim period between releases, weekly snapshots are built automatically by the FreeBSD Project build machines and made available for download from `https:/download.FreeBSD.org/snapshots/`. The widespread availability of binary release snapshots, and the tendency of our user community to keep up with -STABLE development with Subversion and "`make buildworld`" footnote:[extref:{handbook}[Rebuilding world, makeworld]] helps to keep FreeBSD-STABLE in a very reliable condition even before the quality assurance activities ramp up pending a major release. In addition to installation ISO snapshots, weekly virtual machine images are also provided for use with VirtualBox, qemu, or other popular emulation software. The virtual machine images can be downloaded from `https://download.FreeBSD.org/snapshots/VM-IMAGES/`. The virtual machine images are approximately 150MB man:xz[1] compressed, and contain a 10GB sparse filesystem when attached to a virtual machine. Bug reports and feature requests are continuously submitted by users throughout the release cycle. Problems reports are entered into our Bugzilla database through the web interface provided at https://www.freebsd.org/support/bugreports/[https://www.freebsd.org/support/bugreports/]. To service our most conservative users, individual release branches were introduced with FreeBSD 4.3. These release branches are created shortly before a final release is made. After the release goes out, only the most critical security fixes and additions are merged onto the release branch. In addition to source updates via Subversion, binary patchkits are available to keep systems on the _releng/X.Y_ branches updated. === What This Article Describes The following sections of this article describe: <>:: The different phases of the release engineering process leading up to the actual system build. <>:: The actual build process. <>:: How the base release may be extended by third parties. <>:: Some of the lessons learned through the release of FreeBSD 4.4. <>:: Future directions of development. [[release-proc]] == Release Process New releases of FreeBSD are released from the -STABLE branch at approximately four month intervals. The FreeBSD release process begins to ramp up 70-80 days before the anticipated release date when the release engineer sends an email to the development mailing lists to remind developers that they only have 15 days to integrate new changes before the code freeze. During this time, many developers perform what have become known as "MFC sweeps". MFC stands for "Merge From CURRENT" and it describes the process of merging a tested change from our -CURRENT development branch to our -STABLE branch. Project policy requires any change to be first applied to trunk, and merged to the -STABLE branches after sufficient external testing was done by -CURRENT users (developers are expected to extensively test the change before committing to -CURRENT, but it is impossible for a person to exercise all usages of the general-purpose operating system). Minimal MFC period is 3 days, which is typically used only for trivial or critical bugfixes. === Code Review Sixty days before the anticipated release, the source repository enters a "code freeze". During this time, all commits to the -STABLE branch must be approved by `{re}`. The approval process is technically enforced by a pre-commit hook. The kinds of changes that are allowed during this period include: * Bug fixes. * Documentation updates. * Security-related fixes of any kind. * Minor changes to device drivers, such as adding new Device IDs. * Driver updates from the vendors. * Any additional change that the release engineering team feels is justified, given the potential risk. Shortly after the code freeze is started, a _BETA1_ image is built and released for widespread testing. During the code freeze, at least one beta image or release candidate is released every two weeks until the final release is ready. During the days preceding the final release, the release engineering team is in constant communication with the security-officer team, the documentation maintainers, and the port maintainers to ensure that all of the different components required for a successful release are available. After the quality of the BETA images is satisfying enough, and no large and potentially risky changes are planned, the release branch is created and _Release Candidate_ (RC) images are built from the release branch, instead of the BETA images from the STABLE branch. Also, the freeze on the STABLE branch is lifted and release branch enters a "hard code freeze" where it becomes much harder to justify new changes to the system unless a serious bug-fix or security issue is involved. === Final Release Checklist When several BETA images have been made available for widespread testing and all major issues have been resolved, the final release "polishing" can begin. [[rel-branch]] ==== Creating the Release Branch [NOTE] ==== In all examples below, `$FSVN` refers to the location of the FreeBSD Subversion repository, `svn+ssh://svn.FreeBSD.org/base/`. ==== The layout of FreeBSD branches in Subversion is described in the extref:{committers-guide}[Committer's Guide, subversion-primer-base-layout]. The first step in creating a branch is to identify the revision of the `stable/_X_` sources that you want to branch _from_. [source,shell] .... # svn log -v $FSVN/stable/9 .... The next step is to create the _release branch_ [source,shell] .... # svn cp $FSVN/stable/9@REVISION $FSVN/releng/9.2 .... This branch can be checked out: [source,shell] .... # svn co $FSVN/releng/9.2 src .... [NOTE] ==== Creating the `releng` branch and `release` tags is done by the link:https://www.FreeBSD.org/administration/#t-re[Release Engineering Team]. ==== image::branches-head.png[FreeBSD Development Branch] image::branches-releng3.png[FreeBSD 3.x STABLE Branch] image::branches-releng4.png[FreeBSD 4.x STABLE Branch] image::branches-releng5.png[FreeBSD 5.x STABLE Branch] image::branches-releng6.png[FreeBSD 6.x STABLE Branch] image::branches-releng7.png[FreeBSD 7.x STABLE Branch] image::branches-releng8.png[FreeBSD 8.x STABLE Branch] image::branches-releng9.png[FreeBSD 9.x STABLE Branch] [[versionbump]] ==== Bumping up the Version Number Before the final release can be tagged, built, and released, the following files need to be modified to reflect the correct version of FreeBSD: * [.filename]#doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml# * [.filename]#doc/en_US.ISO8859-1/books/porters-handbook/book.xml# * [.filename]#doc/en_US.ISO8859-1/htdocs/cgi/ports.cgi# * [.filename]#ports/Tools/scripts/release/config# * [.filename]#doc/shared/xml/freebsd.ent# * [.filename]#src/Makefile.inc1# * [.filename]#src/UPDATING# * [.filename]#src/gnu/usr.bin/groff/tmac/mdoc.local# * [.filename]#src/release/Makefile# * [.filename]#src/release/doc/en_US.ISO8859-1/shared/xml/release.dsl# * [.filename]#src/release/doc/shared/examples/Makefile.relnotesng# * [.filename]#src/release/doc/shared/xml/release.ent# * [.filename]#src/sys/conf/newvers.sh# * [.filename]#src/sys/sys/param.h# * [.filename]#src/usr.sbin/pkg_install/add/main.c# * [.filename]#doc/en_US.ISO8859-1/htdocs/search/opensearch/man.xml# The release notes and errata files also need to be adjusted for the new release (on the release branch) and truncated appropriately (on the stable/current branch): * [.filename]#src/release/doc/en_US.ISO8859-1/relnotes/common/new.xml# * [.filename]#src/release/doc/en_US.ISO8859-1/errata/article.xml# Sysinstall should be updated to note the number of available ports and the amount of disk space required for the Ports Collection. -footnote:[FreeBSD Ports Collection https://www.FreeBSD.org/ports] +footnote:[FreeBSD Ports Collection https://ports.FreeBSD.org] This information is currently kept in [.filename]#src/usr.sbin/bsdinstall/dist.c#. After the release has been built, a number of files should be updated to announce the release to the world. These files are relative to `head/` within the `doc/` subversion tree. * [.filename]#share/images/articles/releng/branches-relengX.pic# * [.filename]#head/shared/xml/release.ent# * [.filename]#en_US.ISO8859-1/htdocs/releases/*# * [.filename]#en_US.ISO8859-1/htdocs/releng/index.xml# * [.filename]#share/xml/news.xml# Additionally, update the "BSD Family Tree" file: * [.filename]#src/shared/misc/bsd-family-tree# ==== Creating the Release Tag When the final release is ready, the following command will create the `release/9.2.0` tag. [source,shell] .... # svn cp $FSVN/releng/9.2 $FSVN/release/9.2.0 .... The Documentation and Ports managers are responsible for tagging their respective trees with the `tags/RELEASE_9_2_0` tag. When the Subversion `svn cp` command is used to create a __release tag__, this identifies the source at a specific point in time. By creating tags, we ensure that future release builders will always be able to use the same source we used to create the official FreeBSD Project releases. [[release-build]] == Release Building FreeBSD "releases" can be built by anyone with a fast machine and access to a source repository. (That should be everyone, since we offer Subversion access! See the extref:{handbook}[Subversion section in the Handbook, svn] for details.) The _only_ special requirement is that the man:md[4] device must be available. If the device is not loaded into your kernel, then the kernel module should be automatically loaded when man:mdconfig[8] is executed during the boot media creation phase. All of the tools necessary to build a release are available from the Subversion repository in [.filename]#src/release#. These tools aim to provide a consistent way to build FreeBSD releases. A complete release can actually be built with only a single command, including the creation of ISO images suitable for burning to CDROM or DVD, and an FTP install directory. man:release[7] fully documents the `src/release/generate-release.sh` script which is used to build a release. `generate-release.sh` is a wrapper around the Makefile target: `make release`. === Building a Release man:release[7] documents the exact commands required to build a FreeBSD release. The following sequences of commands can build an 9.2.0 release: [source,shell] .... # cd /usr/src/release # sh generate-release.sh release/9.2.0 /local3/release .... After running these commands, all prepared release files are available in [.filename]#/local3/release/R# directory. The release [.filename]#Makefile# can be broken down into several distinct steps. * Creation of a sanitized system environment in a separate directory hierarchy with "`make installworld`". * Checkout from Subversion of a clean version of the system source, documentation, and ports into the release build hierarchy. * Population of [.filename]#/etc# and [.filename]#/dev# in the chrooted environment. * chroot into the release build hierarchy, to make it harder for the outside environment to taint this build. * `make world` in the chrooted environment. * Build of Kerberos-related binaries. * Build [.filename]#GENERIC# kernel. * Creation of a staging directory tree where the binary distributions will be built and packaged. * Build and installation of the documentation toolchain needed to convert the documentation source (SGML) into HTML and text documents that will accompany the release. * Build and installation of the actual documentation (user manuals, tutorials, release notes, hardware compatibility lists, and so on.) * Package up distribution tarballs of the binaries and sources. * Create FTP installation hierarchy. * _(optionally)_ Create ISO images for CDROM/DVD media. For more information about the release build infrastructure, please see man:release[7]. [NOTE] ==== It is important to remove any site-specific settings from [.filename]#/etc/make.conf#. For example, it would be unwise to distribute binaries that were built on a system with `CPUTYPE` set to a specific processor. ==== === Contributed Software ("ports") -The https://www.FreeBSD.org/ports[FreeBSD Ports collection] is a collection of over {numports} third-party software packages available for FreeBSD. +The https://ports.FreeBSD.org[FreeBSD Ports collection] is a collection of over {numports} third-party software packages available for FreeBSD. The `{portmgr}` is responsible for maintaining a consistent ports tree that can be used to create the binary packages that accompany official FreeBSD releases. === Release ISOs Starting with FreeBSD 4.4, the FreeBSD Project decided to release all four ISO images that were previously sold on the _BSDi/Wind River Systems/FreeBSD Mall_ "official" CDROM distributions. Each of the four discs must contain a [.filename]#README.TXT# file that explains the contents of the disc, a [.filename]#CDROM.INF# file that provides meta-data for the disc so that man:bsdinstall[8] can validate and use the contents, and a [.filename]#filename.txt# file that provides a manifest for the disc. This _manifest_ can be created with a simple command: [source,shell] .... /stage/cdrom# find . -type f | sed -e 's/^\.\///' | sort > filename.txt .... The specific requirements of each CD are outlined below. ==== Disc 1 The first disc is almost completely created by `make release`. The only changes that should be made to the [.filename]#disc1# directory are the addition of a [.filename]#tools# directory, and as many popular third party software packages as will fit on the disc. The [.filename]#tools# directory contains software that allow users to create installation floppies from other operating systems. This disc should be made bootable so that users of modern PCs do not need to create installation floppy disks. If a custom kernel of FreeBSD is to be included, then man:bsdinstall[8] and man:release[7] must be updated to include installation instructions. The relevant code is contained in [.filename]#src/release# and [.filename]#src/usr.sbin/bsdinstall#. Specifically, the file [.filename]#src/release/Makefile#, and [.filename]#dist.c#, [.filename]#dist.h#, [.filename]#menus.c#, [.filename]#install.c#, and [.filename]#Makefile# will need to be updated under [.filename]#src/usr.sbin/bsdinstall#. Optionally, you may choose to update [.filename]#bsdinstall.8#. ==== Disc 2 The second disc is also largely created by `make release`. This disc contains a "live filesystem" that can be used from man:bsdinstall[8] to troubleshoot a FreeBSD installation. This disc should be bootable and should also contain a compressed copy of the CVS repository in the [.filename]#CVSROOT# directory and commercial software demos in the [.filename]#commerce# directory. ==== Multi-volume Support Sysinstall supports multiple volume package installations. This requires that each disc have an [.filename]#INDEX# file containing all of the packages on all volumes of a set, along with an extra field that indicates which volume that particular package is on. Each volume in the set must also have the `CD_VOLUME` variable set in the [.filename]#cdrom.inf# file so that bsdinstall can tell which volume is which. When a user attempts to install a package that is not on the current disc, bsdinstall will prompt the user to insert the appropriate one. [[distribution]] == Distribution [[dist-ftp]] === FTP Sites When the release has been thoroughly tested and packaged for distribution, the master FTP site must be updated. The official FreeBSD public FTP sites are all mirrors of a master server that is open only to other FTP sites. This site is known as `ftp-master`. When the release is ready, the following files must be modified on `ftp-master`: [.filename]#/pub/FreeBSD/releases/arch/X.Y-RELEASE/#:: The installable FTP directory as output from `make release`. [.filename]#/pub/FreeBSD/ports/arch/packages-X.Y-release/#:: The complete package build for this release. [.filename]#/pub/FreeBSD/releases/arch/X.Y-RELEASE/tools#:: A symlink to [.filename]#../../../tools#. [.filename]#/pub/FreeBSD/releases/arch/X.Y-RELEASE/packages#:: A symlink to [.filename]#../../../ports/arch/packages-X.Y-release#. [.filename]#/pub/FreeBSD/releases/arch/ISO-IMAGES/X.Y/X.Y-RELEASE-arch-*.iso#:: The ISO images. The "*" is [.filename]#disc1#, [.filename]#disc2#, etc. Only if there is a [.filename]#disc1# and there is an alternative first installation CD (for example a stripped-down install with no windowing system) there may be a [.filename]#mini# as well. For more information about the distribution mirror architecture of the FreeBSD FTP sites, please see the extref:{hubs}[Mirroring FreeBSD] article. It may take many hours to two days after updating `ftp-master` before a majority of the Tier-1 FTP sites have the new software depending on whether or not a package set got loaded at the same time. It is imperative that the release engineers coordinate with the {mirror-announce} before announcing the general availability of new software on the FTP sites. Ideally the release package set should be loaded at least four days prior to release day. The release bits should be loaded between 24 and 48 hours before the planned release time with "other" file permissions turned off. This will allow the mirror sites to download it but the general public will not be able to download it from the mirror sites. Mail should be sent to {mirror-announce} at the time the release bits get posted saying the release has been staged and giving the time that the mirror sites should begin allowing access. Be sure to include a time zone with the time, for example make it relative to GMT. [[dist-cdrom]] === CD-ROM Replication Coming soon: Tips for sending FreeBSD ISOs to a replicator and quality assurance measures to be taken. [[extensibility]] == Extensibility Although FreeBSD forms a complete operating system, there is nothing that forces you to use the system exactly as we have packaged it up for distribution. We have tried to design the system to be as extensible as possible so that it can serve as a platform that other commercial products can be built on top of. The only "rule" we have about this is that if you are going to distribute FreeBSD with non-trivial changes, we encourage you to document your enhancements! The FreeBSD community can only help support users of the software we provide. We certainly encourage innovation in the form of advanced installation and administration tools, for example, but we cannot be expected to answer questions about it. === Scripting `bsdinstall` The FreeBSD system installation and configuration tool, man:bsdinstall[8], can be scripted to provide automated installs for large sites. This functionality can be used in conjunction with Intel(R) PXE footnote:[extref:{handbook}[Diskless Operation with PXE, network-diskless]] to bootstrap systems from the network. [[lessons-learned]] == Lessons Learned from FreeBSD 4.4 The release engineering process for 4.4 formally began on August 1st, 2001. After that date all commits to the `RELENG_4` branch of FreeBSD had to be explicitly approved by the `{re}`. The first release candidate for the x86 architecture was released on August 16, followed by 4 more release candidates leading up to the final release on September 18th. The security officer was very involved in the last week of the process as several security issues were found in the earlier release candidates. A total of over _500_ emails were sent to the `{re}` in little over a month. Our user community has made it very clear that the security and stability of a FreeBSD release should not be sacrificed for any self-imposed deadlines or target release dates. The FreeBSD Project has grown tremendously over its lifetime and the need for standardized release engineering procedures has never been more apparent. This will become even more important as FreeBSD is ported to new platforms. [[future]] == Future Directions It is imperative for our release engineering activities to scale with our growing userbase. Along these lines we are working very hard to document the procedures involved in producing FreeBSD releases. * _Parallelism_ - Certain portions of the release build are actually "embarrassingly parallel". Most of the tasks are very I/O intensive, so having multiple high-speed disk drives is actually more important than using multiple processors in speeding up the `make release` process. If multiple disks are used for different hierarchies in the man:chroot[2] environment, then the CVS checkout of the [.filename]#ports# and [.filename]#doc# trees can be happening simultaneously as the `make world` on another disk. Using a RAID solution (hardware or software) can significantly decrease the overall build time. * _Cross-building releases_ - Building IA-64 or Alpha release on x86 hardware? `make TARGET=ia64 release`. * _Regression Testing_ - We need better automated correctness testing for FreeBSD. * _Installation Tools_ - Our installation program has long since outlived its intended life span. Several projects are under development to provide a more advanced installation mechanism. The libh project was one such project that aimed to provide an intelligent new package framework and GUI installation program. [[ackno]] == Acknowledgements I would like to thank Jordan Hubbard for giving me the opportunity to take on some of the release engineering responsibilities for FreeBSD 4.4 and also for all of his work throughout the years making FreeBSD what it is today. Of course the release would not have been possible without all of the release-related work done by `{asami}`, `{steve}`, `{bmah}`, `{nik}`, `{obrien}`, `{kris}`, `{jhb}` and the rest of the FreeBSD development community. I would also like to thank `{rgrimes}`, `{phk}`, and others who worked on the release engineering tools in the very early days of FreeBSD. This article was influenced by release engineering documents from the CSRG footnote:[Marshall Kirk McKusick, Michael J. Karels, and Keith Bostic: link:http://docs.FreeBSD.org/44doc/papers/releng.html[The Release Engineering of 4.3BSD]] , the NetBSD Project, footnote:[NetBSD Developer Documentation: Release Engineering http://www.NetBSD.org/developers/releng/index.html] , and John Baldwin's proposed release engineering process notes. footnote:[John Baldwin's FreeBSD Release Engineering Proposal https://people.FreeBSD.org/~jhb/docs/releng.txt] diff --git a/documentation/content/en/articles/releng/_index.po b/documentation/content/en/articles/releng/_index.po index 01474b48ba..7991335ad8 100644 --- a/documentation/content/en/articles/releng/_index.po +++ b/documentation/content/en/articles/releng/_index.po @@ -1,1253 +1,1253 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2024-01-17 20:35-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: YAML Front Matter: description #: documentation/content/en/articles/releng/_index.adoc:1 #, no-wrap msgid "This paper describes the approach previously used by the FreeBSD release engineering team to make production quality releases of the FreeBSD Operating System" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/articles/releng/_index.adoc:1 #, no-wrap msgid "Legacy FreeBSD Release Engineering" msgstr "" #. type: Title = #: documentation/content/en/articles/releng/_index.adoc:12 #, no-wrap msgid "FreeBSD Release Engineering" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:45 msgid "Abstract" msgstr "" #. type: delimited block = 4 #: documentation/content/en/articles/releng/_index.adoc:51 msgid "" "This document is outdated and does not accurately describe the current " "release procedures of the FreeBSD Release Engineering team. It is retained " "for historical purposes. The current procedures used by the FreeBSD Release " "Engineering team are available in the extref:{freebsd-releng}[FreeBSD " "Release Engineering] article." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:55 msgid "" "This paper describes the approach used by the FreeBSD release engineering " "team to make production quality releases of the FreeBSD Operating System. " "It details the methodology used for the official FreeBSD releases and " "describes the tools available for those interested in producing customized " "FreeBSD releases for corporate rollouts or commercial productization." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:57 msgid "'''" msgstr "" #. type: Title == #: documentation/content/en/articles/releng/_index.adoc:61 #, no-wrap msgid "Introduction" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:71 msgid "" "The development of FreeBSD is a very open process. FreeBSD is comprised of " "contributions from thousands of people around the world. The FreeBSD " "Project provides Subversion footnote:[Subversion, http://subversion.apache." "org] access to the general public so that others can have access to log " "messages, diffs (patches) between development branches, and other " "productivity enhancements that formal source code management provides. This " "has been a huge help in attracting more talented developers to FreeBSD. " "However, I think everyone would agree that chaos would soon manifest if " "write access to the main repository was opened up to everyone on the " "Internet. Therefore only a \"select\" group of nearly 300 people are given " "write access to the Subversion repository. These extref:{contributors}" "[FreeBSD committers, staff-committers]footnote:[extref:{contributors}" "[FreeBSD committers, staff-committers]] are usually the people who do the " "bulk of FreeBSD development. An elected link:https://www.FreeBSD.org/" "administration/#t-core[Core Team]footnote:[link:https://www.FreeBSD.org/" "administration/#t-core[FreeBSD Core Team]] of developers provide some level " "of direction over the project." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:76 msgid "" "The rapid pace of `FreeBSD` development makes the main development branch " "unsuitable for the everyday use by the general public. In particular, " "stabilizing efforts are required for polishing the development system into a " "production quality release. To solve this conflict, development continues " "on several parallel tracks. The main development branch is the _HEAD_ or " "_trunk_ of our Subversion tree, known as \"FreeBSD-CURRENT\" or \"-CURRENT\" " "for short." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:82 msgid "" "A set of more stable branches are maintained, known as \"FreeBSD-STABLE\" or " "\"-STABLE\" for short. All branches live in a master Subversion repository " "maintained by the FreeBSD Project. FreeBSD-CURRENT is the \"bleeding-edge\" " "of FreeBSD development where all new changes first enter the system. " "FreeBSD-STABLE is the development branch from which major releases are " "made. Changes go into this branch at a different pace, and with the general " "assumption that they have first gone into FreeBSD-CURRENT and have been " "thoroughly tested by our user community." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:87 msgid "" "The term _stable_ in the name of the branch refers to the presumed " "Application Binary Interface stability, which is promised by the project. " "This means that a user application compiled on an older version of the " "system from the same branch works on a newer system from the same branch. " "The ABI stability has improved greatly from the compared to previous " "releases. In most cases, binaries from the older _STABLE_ systems run " "unmodified on newer systems, including __HEAD__, assuming that the system " "management interfaces are not used." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:90 msgid "" "In the interim period between releases, weekly snapshots are built " "automatically by the FreeBSD Project build machines and made available for " "download from `https:/download.FreeBSD.org/snapshots/`. The widespread " "availability of binary release snapshots, and the tendency of our user " "community to keep up with -STABLE development with Subversion and \"`make " "buildworld`\" footnote:[extref:{handbook}[Rebuilding world, makeworld]] " "helps to keep FreeBSD-STABLE in a very reliable condition even before the " "quality assurance activities ramp up pending a major release." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:93 msgid "" "In addition to installation ISO snapshots, weekly virtual machine images are " "also provided for use with VirtualBox, qemu, or other popular emulation " "software. The virtual machine images can be downloaded from `https://" "download.FreeBSD.org/snapshots/VM-IMAGES/`." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:95 msgid "" "The virtual machine images are approximately 150MB man:xz[1] compressed, and " "contain a 10GB sparse filesystem when attached to a virtual machine." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:98 msgid "" "Bug reports and feature requests are continuously submitted by users " "throughout the release cycle. Problems reports are entered into our " "Bugzilla database through the web interface provided at https://www.freebsd." "org/support/bugreports/[https://www.freebsd.org/support/bugreports/]." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:103 msgid "" "To service our most conservative users, individual release branches were " "introduced with FreeBSD 4.3. These release branches are created shortly " "before a final release is made. After the release goes out, only the most " "critical security fixes and additions are merged onto the release branch. " "In addition to source updates via Subversion, binary patchkits are available " "to keep systems on the _releng/X.Y_ branches updated." msgstr "" #. type: Title === #: documentation/content/en/articles/releng/_index.adoc:104 #, no-wrap msgid "What This Article Describes" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:107 msgid "The following sections of this article describe:" msgstr "" #. type: Labeled list #: documentation/content/en/articles/releng/_index.adoc:108 #, no-wrap msgid "<>" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:110 msgid "" "The different phases of the release engineering process leading up to the " "actual system build." msgstr "" #. type: Labeled list #: documentation/content/en/articles/releng/_index.adoc:111 #, no-wrap msgid "<>" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:113 msgid "The actual build process." msgstr "" #. type: Labeled list #: documentation/content/en/articles/releng/_index.adoc:114 #, no-wrap msgid "<>" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:116 msgid "How the base release may be extended by third parties." msgstr "" #. type: Labeled list #: documentation/content/en/articles/releng/_index.adoc:117 #, no-wrap msgid "<>" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:119 msgid "Some of the lessons learned through the release of FreeBSD 4.4." msgstr "" #. type: Labeled list #: documentation/content/en/articles/releng/_index.adoc:120 #, no-wrap msgid "<>" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:122 msgid "Future directions of development." msgstr "" #. type: Title == #: documentation/content/en/articles/releng/_index.adoc:124 #, no-wrap msgid "Release Process" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:129 msgid "" "New releases of FreeBSD are released from the -STABLE branch at " "approximately four month intervals. The FreeBSD release process begins to " "ramp up 70-80 days before the anticipated release date when the release " "engineer sends an email to the development mailing lists to remind " "developers that they only have 15 days to integrate new changes before the " "code freeze. During this time, many developers perform what have become " "known as \"MFC sweeps\"." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:133 msgid "" "MFC stands for \"Merge From CURRENT\" and it describes the process of " "merging a tested change from our -CURRENT development branch to our -STABLE " "branch. Project policy requires any change to be first applied to trunk, " "and merged to the -STABLE branches after sufficient external testing was " "done by -CURRENT users (developers are expected to extensively test the " "change before committing to -CURRENT, but it is impossible for a person to " "exercise all usages of the general-purpose operating system). Minimal MFC " "period is 3 days, which is typically used only for trivial or critical " "bugfixes." msgstr "" #. type: Title === #: documentation/content/en/articles/releng/_index.adoc:134 #, no-wrap msgid "Code Review" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:140 msgid "" "Sixty days before the anticipated release, the source repository enters a " "\"code freeze\". During this time, all commits to the -STABLE branch must " "be approved by `{re}`. The approval process is technically enforced by a " "pre-commit hook. The kinds of changes that are allowed during this period " "include:" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:142 msgid "Bug fixes." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:143 msgid "Documentation updates." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:144 msgid "Security-related fixes of any kind." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:145 msgid "Minor changes to device drivers, such as adding new Device IDs." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:146 msgid "Driver updates from the vendors." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:147 msgid "" "Any additional change that the release engineering team feels is justified, " "given the potential risk." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:151 msgid "" "Shortly after the code freeze is started, a _BETA1_ image is built and " "released for widespread testing. During the code freeze, at least one beta " "image or release candidate is released every two weeks until the final " "release is ready. During the days preceding the final release, the release " "engineering team is in constant communication with the security-officer " "team, the documentation maintainers, and the port maintainers to ensure that " "all of the different components required for a successful release are " "available." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:154 msgid "" "After the quality of the BETA images is satisfying enough, and no large and " "potentially risky changes are planned, the release branch is created and " "_Release Candidate_ (RC) images are built from the release branch, instead " "of the BETA images from the STABLE branch. Also, the freeze on the STABLE " "branch is lifted and release branch enters a \"hard code freeze\" where it " "becomes much harder to justify new changes to the system unless a serious " "bug-fix or security issue is involved." msgstr "" #. type: Title === #: documentation/content/en/articles/releng/_index.adoc:155 #, no-wrap msgid "Final Release Checklist" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:158 msgid "" "When several BETA images have been made available for widespread testing and " "all major issues have been resolved, the final release \"polishing\" can " "begin." msgstr "" #. type: Title ==== #: documentation/content/en/articles/releng/_index.adoc:160 #, no-wrap msgid "Creating the Release Branch" msgstr "" #. type: delimited block = 4 #: documentation/content/en/articles/releng/_index.adoc:165 msgid "" "In all examples below, `$FSVN` refers to the location of the FreeBSD " "Subversion repository, `svn+ssh://svn.FreeBSD.org/base/`." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:169 msgid "" "The layout of FreeBSD branches in Subversion is described in the extref:" "{committers-guide}[Committer's Guide, subversion-primer-base-layout]. The " "first step in creating a branch is to identify the revision of the `stable/" "_X_` sources that you want to branch _from_." msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/releng/_index.adoc:173 #, no-wrap msgid "# svn log -v $FSVN/stable/9\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:176 msgid "The next step is to create the _release branch_" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/releng/_index.adoc:180 #, no-wrap msgid "# svn cp $FSVN/stable/9@REVISION $FSVN/releng/9.2\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:183 msgid "This branch can be checked out:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/releng/_index.adoc:187 #, no-wrap msgid "# svn co $FSVN/releng/9.2 src\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/articles/releng/_index.adoc:192 msgid "" "Creating the `releng` branch and `release` tags is done by the link:https://" "www.FreeBSD.org/administration/#t-re[Release Engineering Team]." msgstr "" #. type: Positional ($1) AttributeList argument for macro 'image' #: documentation/content/en/articles/releng/_index.adoc:194 #, no-wrap msgid "FreeBSD Development Branch" msgstr "" #. type: Target for macro image #: documentation/content/en/articles/releng/_index.adoc:194 #, no-wrap msgid "branches-head.png" msgstr "" #. type: Positional ($1) AttributeList argument for macro 'image' #: documentation/content/en/articles/releng/_index.adoc:196 #, no-wrap msgid "FreeBSD 3.x STABLE Branch" msgstr "" #. type: Target for macro image #: documentation/content/en/articles/releng/_index.adoc:196 #, no-wrap msgid "branches-releng3.png" msgstr "" #. type: Positional ($1) AttributeList argument for macro 'image' #: documentation/content/en/articles/releng/_index.adoc:198 #, no-wrap msgid "FreeBSD 4.x STABLE Branch" msgstr "" #. type: Target for macro image #: documentation/content/en/articles/releng/_index.adoc:198 #, no-wrap msgid "branches-releng4.png" msgstr "" #. type: Positional ($1) AttributeList argument for macro 'image' #: documentation/content/en/articles/releng/_index.adoc:200 #, no-wrap msgid "FreeBSD 5.x STABLE Branch" msgstr "" #. type: Target for macro image #: documentation/content/en/articles/releng/_index.adoc:200 #, no-wrap msgid "branches-releng5.png" msgstr "" #. type: Positional ($1) AttributeList argument for macro 'image' #: documentation/content/en/articles/releng/_index.adoc:202 #, no-wrap msgid "FreeBSD 6.x STABLE Branch" msgstr "" #. type: Target for macro image #: documentation/content/en/articles/releng/_index.adoc:202 #, no-wrap msgid "branches-releng6.png" msgstr "" #. type: Positional ($1) AttributeList argument for macro 'image' #: documentation/content/en/articles/releng/_index.adoc:204 #, no-wrap msgid "FreeBSD 7.x STABLE Branch" msgstr "" #. type: Target for macro image #: documentation/content/en/articles/releng/_index.adoc:204 #, no-wrap msgid "branches-releng7.png" msgstr "" #. type: Positional ($1) AttributeList argument for macro 'image' #: documentation/content/en/articles/releng/_index.adoc:206 #, no-wrap msgid "FreeBSD 8.x STABLE Branch" msgstr "" #. type: Target for macro image #: documentation/content/en/articles/releng/_index.adoc:206 #, no-wrap msgid "branches-releng8.png" msgstr "" #. type: Positional ($1) AttributeList argument for macro 'image' #: documentation/content/en/articles/releng/_index.adoc:208 #, no-wrap msgid "FreeBSD 9.x STABLE Branch" msgstr "" #. type: Target for macro image #: documentation/content/en/articles/releng/_index.adoc:208 #, no-wrap msgid "branches-releng9.png" msgstr "" #. type: Title ==== #: documentation/content/en/articles/releng/_index.adoc:211 #, no-wrap msgid "Bumping up the Version Number" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:214 msgid "" "Before the final release can be tagged, built, and released, the following " "files need to be modified to reflect the correct version of FreeBSD:" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:216 msgid "[.filename]#doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:217 msgid "[.filename]#doc/en_US.ISO8859-1/books/porters-handbook/book.xml#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:218 msgid "[.filename]#doc/en_US.ISO8859-1/htdocs/cgi/ports.cgi#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:219 msgid "[.filename]#ports/Tools/scripts/release/config#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:220 msgid "[.filename]#doc/shared/xml/freebsd.ent#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:221 msgid "[.filename]#src/Makefile.inc1#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:222 msgid "[.filename]#src/UPDATING#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:223 msgid "[.filename]#src/gnu/usr.bin/groff/tmac/mdoc.local#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:224 msgid "[.filename]#src/release/Makefile#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:225 msgid "[.filename]#src/release/doc/en_US.ISO8859-1/shared/xml/release.dsl#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:226 msgid "[.filename]#src/release/doc/shared/examples/Makefile.relnotesng#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:227 msgid "[.filename]#src/release/doc/shared/xml/release.ent#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:228 msgid "[.filename]#src/sys/conf/newvers.sh#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:229 msgid "[.filename]#src/sys/sys/param.h#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:230 msgid "[.filename]#src/usr.sbin/pkg_install/add/main.c#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:231 msgid "[.filename]#doc/en_US.ISO8859-1/htdocs/search/opensearch/man.xml#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:233 msgid "" "The release notes and errata files also need to be adjusted for the new " "release (on the release branch) and truncated appropriately (on the stable/" "current branch):" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:235 msgid "[.filename]#src/release/doc/en_US.ISO8859-1/relnotes/common/new.xml#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:236 msgid "[.filename]#src/release/doc/en_US.ISO8859-1/errata/article.xml#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:240 msgid "" "Sysinstall should be updated to note the number of available ports and the " "amount of disk space required for the Ports Collection. footnote:[FreeBSD " -"Ports Collection https://www.FreeBSD.org/ports] This information is " +"Ports Collection https://ports.FreeBSD.org] This information is " "currently kept in [.filename]#src/usr.sbin/bsdinstall/dist.c#." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:243 msgid "" "After the release has been built, a number of files should be updated to " "announce the release to the world. These files are relative to `head/` " "within the `doc/` subversion tree." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:245 msgid "[.filename]#share/images/articles/releng/branches-relengX.pic#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:246 msgid "[.filename]#head/shared/xml/release.ent#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:247 msgid "[.filename]#en_US.ISO8859-1/htdocs/releases/*#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:248 msgid "[.filename]#en_US.ISO8859-1/htdocs/releng/index.xml#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:249 msgid "[.filename]#share/xml/news.xml#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:251 msgid "Additionally, update the \"BSD Family Tree\" file:" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:253 msgid "[.filename]#src/shared/misc/bsd-family-tree#" msgstr "" #. type: Title ==== #: documentation/content/en/articles/releng/_index.adoc:254 #, no-wrap msgid "Creating the Release Tag" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:257 msgid "" "When the final release is ready, the following command will create the " "`release/9.2.0` tag." msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/releng/_index.adoc:261 #, no-wrap msgid "# svn cp $FSVN/releng/9.2 $FSVN/release/9.2.0\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:264 msgid "" "The Documentation and Ports managers are responsible for tagging their " "respective trees with the `tags/RELEASE_9_2_0` tag." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:267 msgid "" "When the Subversion `svn cp` command is used to create a __release tag__, " "this identifies the source at a specific point in time. By creating tags, " "we ensure that future release builders will always be able to use the same " "source we used to create the official FreeBSD Project releases." msgstr "" #. type: Title == #: documentation/content/en/articles/releng/_index.adoc:269 #, no-wrap msgid "Release Building" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:280 msgid "" "FreeBSD \"releases\" can be built by anyone with a fast machine and access " "to a source repository. (That should be everyone, since we offer Subversion " "access! See the extref:{handbook}[Subversion section in the Handbook, svn] " "for details.) The _only_ special requirement is that the man:md[4] device " "must be available. If the device is not loaded into your kernel, then the " "kernel module should be automatically loaded when man:mdconfig[8] is " "executed during the boot media creation phase. All of the tools necessary " "to build a release are available from the Subversion repository in [." "filename]#src/release#. These tools aim to provide a consistent way to " "build FreeBSD releases. A complete release can actually be built with only " "a single command, including the creation of ISO images suitable for burning " "to CDROM or DVD, and an FTP install directory. man:release[7] fully " "documents the `src/release/generate-release.sh` script which is used to " "build a release. `generate-release.sh` is a wrapper around the Makefile " "target: `make release`." msgstr "" #. type: Title === #: documentation/content/en/articles/releng/_index.adoc:281 #, no-wrap msgid "Building a Release" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:285 msgid "" "man:release[7] documents the exact commands required to build a FreeBSD " "release. The following sequences of commands can build an 9.2.0 release:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/releng/_index.adoc:290 #, no-wrap msgid "" "# cd /usr/src/release\n" "# sh generate-release.sh release/9.2.0 /local3/release\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:293 msgid "" "After running these commands, all prepared release files are available in [." "filename]#/local3/release/R# directory." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:295 msgid "" "The release [.filename]#Makefile# can be broken down into several distinct " "steps." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:297 msgid "" "Creation of a sanitized system environment in a separate directory hierarchy " "with \"`make installworld`\"." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:298 msgid "" "Checkout from Subversion of a clean version of the system source, " "documentation, and ports into the release build hierarchy." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:299 msgid "" "Population of [.filename]#/etc# and [.filename]#/dev# in the chrooted " "environment." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:300 msgid "" "chroot into the release build hierarchy, to make it harder for the outside " "environment to taint this build." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:301 msgid "`make world` in the chrooted environment." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:302 msgid "Build of Kerberos-related binaries." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:303 msgid "Build [.filename]#GENERIC# kernel." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:304 msgid "" "Creation of a staging directory tree where the binary distributions will be " "built and packaged." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:305 msgid "" "Build and installation of the documentation toolchain needed to convert the " "documentation source (SGML) into HTML and text documents that will accompany " "the release." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:306 msgid "" "Build and installation of the actual documentation (user manuals, tutorials, " "release notes, hardware compatibility lists, and so on.)" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:307 msgid "Package up distribution tarballs of the binaries and sources." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:308 msgid "Create FTP installation hierarchy." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:309 msgid "_(optionally)_ Create ISO images for CDROM/DVD media." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:311 msgid "" "For more information about the release build infrastructure, please see man:" "release[7]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/articles/releng/_index.adoc:316 msgid "" "It is important to remove any site-specific settings from [.filename]#/etc/" "make.conf#. For example, it would be unwise to distribute binaries that " "were built on a system with `CPUTYPE` set to a specific processor." msgstr "" #. type: Title === #: documentation/content/en/articles/releng/_index.adoc:318 #, no-wrap msgid "Contributed Software (\"ports\")" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:322 msgid "" -"The https://www.FreeBSD.org/ports[FreeBSD Ports collection] is a collection " +"The https://ports.FreeBSD.org[FreeBSD Ports collection] is a collection " "of over {numports} third-party software packages available for FreeBSD. The " "`{portmgr}` is responsible for maintaining a consistent ports tree that can " "be used to create the binary packages that accompany official FreeBSD " "releases." msgstr "" #. type: Title === #: documentation/content/en/articles/releng/_index.adoc:323 #, no-wrap msgid "Release ISOs" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:328 msgid "" "Starting with FreeBSD 4.4, the FreeBSD Project decided to release all four " "ISO images that were previously sold on the _BSDi/Wind River Systems/FreeBSD " "Mall_ \"official\" CDROM distributions. Each of the four discs must contain " "a [.filename]#README.TXT# file that explains the contents of the disc, a [." "filename]#CDROM.INF# file that provides meta-data for the disc so that man:" "bsdinstall[8] can validate and use the contents, and a [.filename]#filename." "txt# file that provides a manifest for the disc. This _manifest_ can be " "created with a simple command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/releng/_index.adoc:332 #, no-wrap msgid "/stage/cdrom# find . -type f | sed -e 's/^\\.\\///' | sort > filename.txt\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:335 msgid "The specific requirements of each CD are outlined below." msgstr "" #. type: Title ==== #: documentation/content/en/articles/releng/_index.adoc:336 #, no-wrap msgid "Disc 1" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:342 msgid "" "The first disc is almost completely created by `make release`. The only " "changes that should be made to the [.filename]#disc1# directory are the " "addition of a [.filename]#tools# directory, and as many popular third party " "software packages as will fit on the disc. The [.filename]#tools# directory " "contains software that allow users to create installation floppies from " "other operating systems. This disc should be made bootable so that users of " "modern PCs do not need to create installation floppy disks." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:347 msgid "" "If a custom kernel of FreeBSD is to be included, then man:bsdinstall[8] and " "man:release[7] must be updated to include installation instructions. The " "relevant code is contained in [.filename]#src/release# and [.filename]#src/" "usr.sbin/bsdinstall#. Specifically, the file [.filename]#src/release/" "Makefile#, and [.filename]#dist.c#, [.filename]#dist.h#, [.filename]#menus." "c#, [.filename]#install.c#, and [.filename]#Makefile# will need to be " "updated under [.filename]#src/usr.sbin/bsdinstall#. Optionally, you may " "choose to update [.filename]#bsdinstall.8#." msgstr "" #. type: Title ==== #: documentation/content/en/articles/releng/_index.adoc:348 #, no-wrap msgid "Disc 2" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:353 msgid "" "The second disc is also largely created by `make release`. This disc " "contains a \"live filesystem\" that can be used from man:bsdinstall[8] to " "troubleshoot a FreeBSD installation. This disc should be bootable and " "should also contain a compressed copy of the CVS repository in the [." "filename]#CVSROOT# directory and commercial software demos in the [." "filename]#commerce# directory." msgstr "" #. type: Title ==== #: documentation/content/en/articles/releng/_index.adoc:354 #, no-wrap msgid "Multi-volume Support" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:360 msgid "" "Sysinstall supports multiple volume package installations. This requires " "that each disc have an [.filename]#INDEX# file containing all of the " "packages on all volumes of a set, along with an extra field that indicates " "which volume that particular package is on. Each volume in the set must " "also have the `CD_VOLUME` variable set in the [.filename]#cdrom.inf# file so " "that bsdinstall can tell which volume is which. When a user attempts to " "install a package that is not on the current disc, bsdinstall will prompt " "the user to insert the appropriate one." msgstr "" #. type: Title == #: documentation/content/en/articles/releng/_index.adoc:362 #, no-wrap msgid "Distribution" msgstr "" #. type: Title === #: documentation/content/en/articles/releng/_index.adoc:365 #, no-wrap msgid "FTP Sites" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:371 msgid "" "When the release has been thoroughly tested and packaged for distribution, " "the master FTP site must be updated. The official FreeBSD public FTP sites " "are all mirrors of a master server that is open only to other FTP sites. " "This site is known as `ftp-master`. When the release is ready, the " "following files must be modified on `ftp-master`:" msgstr "" #. type: Labeled list #: documentation/content/en/articles/releng/_index.adoc:372 #, no-wrap msgid "[.filename]#/pub/FreeBSD/releases/arch/X.Y-RELEASE/#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:374 msgid "The installable FTP directory as output from `make release`." msgstr "" #. type: Labeled list #: documentation/content/en/articles/releng/_index.adoc:375 #, no-wrap msgid "[.filename]#/pub/FreeBSD/ports/arch/packages-X.Y-release/#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:377 msgid "The complete package build for this release." msgstr "" #. type: Labeled list #: documentation/content/en/articles/releng/_index.adoc:378 #, no-wrap msgid "[.filename]#/pub/FreeBSD/releases/arch/X.Y-RELEASE/tools#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:380 msgid "A symlink to [.filename]#../../../tools#." msgstr "" #. type: Labeled list #: documentation/content/en/articles/releng/_index.adoc:381 #, no-wrap msgid "[.filename]#/pub/FreeBSD/releases/arch/X.Y-RELEASE/packages#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:383 msgid "A symlink to [.filename]#../../../ports/arch/packages-X.Y-release#." msgstr "" #. type: Labeled list #: documentation/content/en/articles/releng/_index.adoc:384 #, no-wrap msgid "[.filename]#/pub/FreeBSD/releases/arch/ISO-IMAGES/X.Y/X.Y-RELEASE-arch-*.iso#" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:387 msgid "" "The ISO images. The \"*\" is [.filename]#disc1#, [.filename]#disc2#, etc. " "Only if there is a [.filename]#disc1# and there is an alternative first " "installation CD (for example a stripped-down install with no windowing " "system) there may be a [.filename]#mini# as well." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:389 msgid "" "For more information about the distribution mirror architecture of the " "FreeBSD FTP sites, please see the extref:{hubs}[Mirroring FreeBSD] article." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:397 msgid "" "It may take many hours to two days after updating `ftp-master` before a " "majority of the Tier-1 FTP sites have the new software depending on whether " "or not a package set got loaded at the same time. It is imperative that the " "release engineers coordinate with the {mirror-announce} before announcing " "the general availability of new software on the FTP sites. Ideally the " "release package set should be loaded at least four days prior to release " "day. The release bits should be loaded between 24 and 48 hours before the " "planned release time with \"other\" file permissions turned off. This will " "allow the mirror sites to download it but the general public will not be " "able to download it from the mirror sites. Mail should be sent to {mirror-" "announce} at the time the release bits get posted saying the release has " "been staged and giving the time that the mirror sites should begin allowing " "access. Be sure to include a time zone with the time, for example make it " "relative to GMT." msgstr "" #. type: Title === #: documentation/content/en/articles/releng/_index.adoc:399 #, no-wrap msgid "CD-ROM Replication" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:402 msgid "" "Coming soon: Tips for sending FreeBSD ISOs to a replicator and quality " "assurance measures to be taken." msgstr "" #. type: Title == #: documentation/content/en/articles/releng/_index.adoc:404 #, no-wrap msgid "Extensibility" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:411 msgid "" "Although FreeBSD forms a complete operating system, there is nothing that " "forces you to use the system exactly as we have packaged it up for " "distribution. We have tried to design the system to be as extensible as " "possible so that it can serve as a platform that other commercial products " "can be built on top of. The only \"rule\" we have about this is that if you " "are going to distribute FreeBSD with non-trivial changes, we encourage you " "to document your enhancements! The FreeBSD community can only help support " "users of the software we provide. We certainly encourage innovation in the " "form of advanced installation and administration tools, for example, but we " "cannot be expected to answer questions about it." msgstr "" #. type: Title === #: documentation/content/en/articles/releng/_index.adoc:412 #, no-wrap msgid "Scripting `bsdinstall`" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:416 msgid "" "The FreeBSD system installation and configuration tool, man:bsdinstall[8], " "can be scripted to provide automated installs for large sites. This " "functionality can be used in conjunction with Intel(R) PXE footnote:[extref:" "{handbook}[Diskless Operation with PXE, network-diskless]] to bootstrap " "systems from the network." msgstr "" #. type: Title == #: documentation/content/en/articles/releng/_index.adoc:418 #, no-wrap msgid "Lessons Learned from FreeBSD 4.4" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:425 msgid "" "The release engineering process for 4.4 formally began on August 1st, 2001. " "After that date all commits to the `RELENG_4` branch of FreeBSD had to be " "explicitly approved by the `{re}`. The first release candidate for the x86 " "architecture was released on August 16, followed by 4 more release " "candidates leading up to the final release on September 18th. The security " "officer was very involved in the last week of the process as several " "security issues were found in the earlier release candidates. A total of " "over _500_ emails were sent to the `{re}` in little over a month." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:429 msgid "" "Our user community has made it very clear that the security and stability of " "a FreeBSD release should not be sacrificed for any self-imposed deadlines or " "target release dates. The FreeBSD Project has grown tremendously over its " "lifetime and the need for standardized release engineering procedures has " "never been more apparent. This will become even more important as FreeBSD " "is ported to new platforms." msgstr "" #. type: Title == #: documentation/content/en/articles/releng/_index.adoc:431 #, no-wrap msgid "Future Directions" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:435 msgid "" "It is imperative for our release engineering activities to scale with our " "growing userbase. Along these lines we are working very hard to document " "the procedures involved in producing FreeBSD releases." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:437 msgid "" "_Parallelism_ - Certain portions of the release build are actually " "\"embarrassingly parallel\". Most of the tasks are very I/O intensive, so " "having multiple high-speed disk drives is actually more important than using " "multiple processors in speeding up the `make release` process. If multiple " "disks are used for different hierarchies in the man:chroot[2] environment, " "then the CVS checkout of the [.filename]#ports# and [.filename]#doc# trees " "can be happening simultaneously as the `make world` on another disk. Using a " "RAID solution (hardware or software) can significantly decrease the overall " "build time." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:438 msgid "" "_Cross-building releases_ - Building IA-64 or Alpha release on x86 hardware? " "`make TARGET=ia64 release`." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:439 msgid "" "_Regression Testing_ - We need better automated correctness testing for " "FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:440 msgid "" "_Installation Tools_ - Our installation program has long since outlived its " "intended life span. Several projects are under development to provide a more " "advanced installation mechanism. The libh project was one such project that " "aimed to provide an intelligent new package framework and GUI installation " "program." msgstr "" #. type: Title == #: documentation/content/en/articles/releng/_index.adoc:442 #, no-wrap msgid "Acknowledgements" msgstr "" #. type: Plain text #: documentation/content/en/articles/releng/_index.adoc:447 msgid "" "I would like to thank Jordan Hubbard for giving me the opportunity to take " "on some of the release engineering responsibilities for FreeBSD 4.4 and also " "for all of his work throughout the years making FreeBSD what it is today. " "Of course the release would not have been possible without all of the " "release-related work done by `{asami}`, `{steve}`, `{bmah}`, `{nik}`, " "`{obrien}`, `{kris}`, `{jhb}` and the rest of the FreeBSD development " "community. I would also like to thank `{rgrimes}`, `{phk}`, and others who " "worked on the release engineering tools in the very early days of FreeBSD. " "This article was influenced by release engineering documents from the CSRG " "footnote:[Marshall Kirk McKusick, Michael J. Karels, and Keith Bostic: link:" "http://docs.FreeBSD.org/44doc/papers/releng.html[The Release Engineering of " "4.3BSD]] , the NetBSD Project, footnote:[NetBSD Developer Documentation: " "Release Engineering http://www.NetBSD.org/developers/releng/index.html] , " "and John Baldwin's proposed release engineering process notes. footnote:" "[John Baldwin's FreeBSD Release Engineering Proposal https://people.FreeBSD." "org/~jhb/docs/releng.txt]" msgstr "" diff --git a/documentation/content/en/books/handbook/l10n/_index.adoc b/documentation/content/en/books/handbook/l10n/_index.adoc index 756d74be55..3fdda1c32e 100644 --- a/documentation/content/en/books/handbook/l10n/_index.adoc +++ b/documentation/content/en/books/handbook/l10n/_index.adoc @@ -1,642 +1,642 @@ --- title: Chapter 25. Localization - i18n/L10n Usage and Setup part: Part III. System Administration prev: books/handbook/virtualization next: books/handbook/cutting-edge description: FreeBSD supports localization into many languages, allowing users to view, input, or process data in non-English languages tags: ["i18n", "L10n", "localization", "Locale", "LANG", "MM_CHARSET", "cap_mkdb"] showBookMenu: true weight: 29 path: "/books/handbook/l10n/" --- [[l10n]] = Localization - i18n/L10n Usage and Setup :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 25 :partnums: :source-highlighter: rouge :experimental: :images-path: books/handbook/l10n/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[l10n-synopsis]] == Synopsis FreeBSD is a distributed project with users and contributors located all over the world. As such, FreeBSD supports localization into many languages, allowing users to view, input, or process data in non-English languages. One can choose from most of the major languages, including, but not limited to: Chinese, German, Japanese, Korean, French, Russian, and Vietnamese. The term internationalization has been shortened to i18n, which represents the number of letters between the first and the last letters of `internationalization`. L10n uses the same naming scheme, but from `localization`. The i18n/L10n methods, protocols, and applications allow users to use languages of their choice. This chapter discusses the internationalization and localization features of FreeBSD. After reading this chapter, you will know: * How locale names are constructed. * How to set the locale for a login shell. * How to configure the console for non-English languages. * How to configure Xorg for different languages. * How to find i18n-compliant applications. * Where to find more information for configuring specific languages. Before reading this chapter, you should: * Know how to crossref:ports[ports,install additional third-party applications]. [[using-localization]] == Using Localization Localization settings are based on three components: the language code, country code, and encoding. Locale names are constructed from these parts as follows: [.programlisting] .... LanguageCode_CountryCode.Encoding .... The _LanguageCode_ and _CountryCode_ are used to determine the country and the specific language variation. <> provides some examples of __LanguageCode_CountryCode__: [[locale-lang-country]] .Common Language and Country Codes [cols="1,1", frame="none", options="header"] |=== | LanguageCode_Country Code | Description |en_US |English, United States |ru_RU |Russian, Russia |zh_TW |Traditional Chinese, Taiwan |=== A complete listing of available locales can be found by typing: [source,shell] .... % locale -a | more .... To determine the current locale setting: [source,shell] .... % locale .... Language specific character sets, such as ISO8859-1, ISO8859-15, KOI8-R, and CP437, are described in man:multibyte[3]. The active list of character sets can be found at the http://www.iana.org/assignments/character-sets[IANA Registry]. Some languages, such as Chinese or Japanese, cannot be represented using ASCII characters and require an extended language encoding using either wide or multibyte characters. Examples of wide or multibyte encodings include EUC and Big5. Older applications may mistake these encodings for control characters while newer applications usually recognize these characters. Depending on the implementation, users may be required to compile an application with wide or multibyte character support, or to configure it correctly. [NOTE] ==== FreeBSD uses Xorg-compatible locale encodings. ==== The rest of this section describes the various methods for configuring the locale on a FreeBSD system. The next section will discuss the considerations for finding and compiling applications with i18n support. [[setting-locale]] === Setting Locale for Login Shell Locale settings are configured either in a user's [.filename]#~/.login_conf# or in the startup file of the user's shell: [.filename]#~/.profile#, [.filename]#~/.bashrc#, or [.filename]#~/.cshrc#. Two environment variables should be set: * `LANG`, which sets the locale * `MM_CHARSET`, which sets the MIME character set used by applications In addition to the user's shell configuration, these variables should also be set for specific application configuration and Xorg configuration. Two methods are available for making the needed variable assignments: the <> method, which is the recommended method, and the <> method. The next two sections demonstrate how to use both methods. [[login-class]] ==== Login Classes Method This first method is the recommended method as it assigns the required environment variables for locale name and MIME character sets for every possible shell. This setup can either be performed by each user or it can be configured for all users by the superuser. This minimal example sets both variables for Latin-1 encoding in the [.filename]#.login_conf# of an individual user's home directory: [.programlisting] .... me:\ :charset=ISO-8859-1:\ :lang=de_DE.ISO8859-1: .... Here is an example of a user's [.filename]#~/.login_conf# that sets the variables for Traditional Chinese in BIG-5 encoding. More variables are needed because some applications do not correctly respect locale variables for Chinese, Japanese, and Korean: [.programlisting] .... #Users who do not wish to use monetary units or time formats #of Taiwan can manually change each variable me:\ :lang=zh_TW.Big5:\ :setenv=LC_ALL=zh_TW.Big5,LC_COLLATE=zh_TW.Big5,LC_CTYPE=zh_TW.Big5,LC_MESSAGES=zh_TW.Big5,LC_MONETARY=zh_TW.Big5,LC_NUMERIC=zh_TW.Big5,LC_TIME=zh_TW.Big5:\ :charset=big5:\ :xmodifiers="@im=gcin": #Set gcin as the XIM Input Server .... Alternately, the superuser can configure all users of the system for localization. The following variables in [.filename]#/etc/login.conf# are used to set the locale and MIME character set: [.programlisting] .... language_name|Account Type Description:\ :charset=MIME_charset:\ :lang=locale_name:\ :tc=default: .... So, the previous Latin-1 example would look like this: [.programlisting] .... german|German Users Accounts:\ :charset=ISO-8859-1:\ :lang=de_DE.ISO8859-1:\ :tc=default: .... See man:login.conf[5] for more details about these variables. Note that it already contains pre-defined _russian_ class. Whenever [.filename]#/etc/login.conf# is edited, remember to execute the following command to update the capability database: [source,shell] .... # cap_mkdb /etc/login.conf .... [NOTE] ==== For an end user, the `cap_mkdb` command will need to be run on their [.filename]#~/.login_conf# for any changes to take effect. ==== ===== Utilities Which Change Login Classes In addition to manually editing [.filename]#/etc/login.conf#, several utilities are available for setting the locale for newly created users. When using `vipw` to add new users, specify the _language_ to set the locale: [.programlisting] .... user:password:1111:11:language:0:0:User Name:/home/user:/bin/sh .... When using `adduser` to add new users, the default language can be pre-configured for all new users or specified for an individual user. If all new users use the same language, set `defaultclass=_language_` in [.filename]#/etc/adduser.conf#. To override this setting when creating a user, either input the required locale at this prompt: [source,shell] .... Enter login class: default []: .... or specify the locale to set when invoking `adduser`: [source,shell] .... # adduser -class language .... If `pw` is used to add new users, specify the locale as follows: [source,shell] .... # pw useradd user_name -L language .... To change the login class of an existing user, `chpass` can be used. Invoke it as superuser and provide the username to edit as the argument. [source,shell] .... # chpass user_name .... [[startup-file]] ==== Shell Startup File Method This second method is not recommended as each shell that is used requires manual configuration, where each shell has a different configuration file and differing syntax. As an example, to set the German language for the `sh` shell, these lines could be added to [.filename]#~/.profile# to set the shell for that user only. These lines could also be added to [.filename]#/etc/profile# or [.filename]#/usr/share/skel/dot.profile# to set that shell for all users: [.programlisting] .... LANG=de_DE.ISO8859-1; export LANG MM_CHARSET=ISO-8859-1; export MM_CHARSET .... However, the name of the configuration file and the syntax used differs for the `csh` shell. These are the equivalent settings for [.filename]#~/.login#, [.filename]#/etc/csh.login#, or [.filename]#/usr/share/skel/dot.login#: [.programlisting] .... setenv LANG de_DE.ISO8859-1 setenv MM_CHARSET ISO-8859-1 .... To complicate matters, the syntax needed to configure Xorg in [.filename]#~/.xinitrc# also depends upon the shell. The first example is for the `sh` shell and the second is for the `csh` shell: [.programlisting] .... LANG=de_DE.ISO8859-1; export LANG .... [.programlisting] .... setenv LANG de_DE.ISO8859-1 .... [[setting-console]] === Console Setup Several localized fonts are available for the console. To see a listing of available fonts, type `ls /usr/share/syscons/fonts`. To configure the console font, specify the _font_name_, without the [.filename]#.fnt# suffix, in [.filename]#/etc/rc.conf#: [.programlisting] .... font8x16=font_name font8x14=font_name font8x8=font_name .... The keymap and screenmap can be set by adding the following to [.filename]#/etc/rc.conf#: [.programlisting] .... scrnmap=screenmap_name keymap=keymap_name keychange="fkey_number sequence" .... To see the list of available screenmaps, type `ls /usr/share/syscons/scrnmaps`. Do not include the [.filename]#.scm# suffix when specifying _screenmap_name_. A screenmap with a corresponding mapped font is usually needed as a workaround for expanding bit 8 to bit 9 on a VGA adapter's font character matrix so that letters are moved out of the pseudographics area if the screen font uses a bit 8 column. To see the list of available keymaps, type `ls /usr/share/syscons/keymaps`. When specifying the _keymap_name_, do not include the [.filename]#.kbd# suffix. To test keymaps without rebooting, use man:kbdmap[1]. The `keychange` entry is usually needed to program function keys to match the selected terminal type because function key sequences cannot be defined in the keymap. Next, set the correct console terminal type in [.filename]#/etc/ttys# for all virtual terminal entries. <> summarizes the available terminal types.: [[locale-charset]] .Defined Terminal Types for Character Sets [cols="1,1", frame="none", options="header"] |=== | Character Set | Terminal Type |ISO8859-1 or ISO8859-15 |`cons25l1` |ISO8859-2 |`cons25l2` |ISO8859-7 |`cons25l7` |KOI8-R |`cons25r` |KOI8-U |`cons25u` |CP437 (VGA default) |`cons25` |US-ASCII |`cons25w` |=== For languages with wide or multibyte characters, install a console for that language from the FreeBSD Ports Collection. The available ports are summarized in <>. Once installed, refer to the port's [.filename]#pkg-message# or man pages for configuration and usage instructions. [[locale-console]] .Available Console from Ports Collection [cols="1,1", frame="none", options="header"] |=== | Language | Port Location |Traditional Chinese (BIG-5) |package:chinese/big5con[] |Chinese/Japanese/Korean |package:chinese/cce[] |Chinese/Japanese/Korean |package:chinese/zhcon[] |Japanese |package:chinese/kon2[] |Japanese |package:japanese/kon2-14dot[] |Japanese |package:japanese/kon2-16dot[] |=== If moused is enabled in [.filename]#/etc/rc.conf#, additional configuration may be required. By default, the mouse cursor of the man:syscons[4] driver occupies the `0xd0`-`0xd3` range in the character set. If the language uses this range, move the cursor's range by adding the following line to [.filename]#/etc/rc.conf#: [.programlisting] .... mousechar_start=3 .... === Xorg Setup crossref:x11[x11,The X Window System] describes how to install and configure Xorg. When configuring Xorg for localization, additional fonts and input methods are available from the FreeBSD Ports Collection. Application specific i18n settings such as fonts and menus can be tuned in [.filename]#~/.Xresources# and should allow users to view their selected language in graphical application menus. The X Input Method (XIM) protocol is an Xorg standard for inputting non-English characters. <> summarizes the input method applications which are available in the FreeBSD Ports Collection. Additional Fcitx and Uim applications are also available. [[locale-xim]] .Available Input Methods [cols="1,1", frame="none", options="header"] |=== | Language | Input Method |Chinese |package:chinese/gcin[] |Chinese |package:chinese/ibus-chewing[] |Chinese |package:chinese/ibus-pinyin[] |Chinese |package:chinese/oxim[] |Chinese |package:chinese/scim-fcitx[] |Chinese |package:chinese/scim-pinyin[] |Chinese |package:chinese/scim-tables[] |Japanese |package:japanese/ibus-anthy[] |Japanese |package:japanese/ibus-mozc[] |Japanese |package:japanese/ibus-skk[] |Japanese |package:japanese/im-ja[] |Japanese |package:japanese/kinput2[] |Japanese |package:japanese/scim-anthy[] |Japanese |package:japanese/scim-canna[] |Japanese |package:japanese/scim-honoka[] |Japanese |package:japanese/scim-honoka-plugin-romkan[] |Japanese |package:japanese/scim-honoka-plugin-wnn[] |Japanese |package:japanese/scim-prime[] |Japanese |package:japanese/scim-skk[] |Japanese |package:japanese/scim-tables[] |Japanese |package:japanese/scim-tomoe[] |Japanese |package:japanese/scim-uim[] |Japanese |package:japanese/skkinput[] |Japanese |package:japanese/skkinput3[] |Japanese |package:japanese/uim-anthy[] |Korean |package:korean/ibus-hangul[] |Korean |package:korean/imhangul[] |Korean |package:korean/nabi[] |Korean |package:korean/scim-hangul[] |Korean |package:korean/scim-tables[] |Vietnamese |package:vietnamese/xvnkb[] |Vietnamese |package:vietnamese/x-unikey[] |=== [[l10n-compiling]] == Finding i18n Applications i18n applications are programmed using i18n kits under libraries. These allow developers to write a simple file and translate displayed menus and texts to each language. -The link:https://www.FreeBSD.org/ports/[FreeBSD Ports Collection] contains many applications with built-in support for wide or multibyte characters for several languages. +The link:https://ports.FreeBSD.org[FreeBSD Ports Collection] contains many applications with built-in support for wide or multibyte characters for several languages. Such applications include `i18n` in their names for easy identification. However, they do not always support the language needed. Some applications can be compiled with the specific charset. This is usually done in the port's [.filename]#Makefile# or by passing a value to configure. Refer to the i18n documentation in the respective FreeBSD port's source for more information on how to determine the needed configure value or the port's [.filename]#Makefile# to determine which compile options to use when building the port. [[lang-setup]] == Locale Configuration for Specific Languages This section provides configuration examples for localizing a FreeBSD system for the Russian language. It then provides some additional resources for localizing other languages. [[ru-localize]] === Russian Language (KOI8-R Encoding) This section shows the specific settings needed to localize a FreeBSD system for the Russian language. Refer to <> for a complete description of each type of setting. To set this locale for the login shell, add the following lines to each user's [.filename]#~/.login_conf#: [.programlisting] .... me:My Account:\ :charset=KOI8-R:\ :lang=ru_RU.KOI8-R: .... To configure the console, add the following lines to [.filename]#/etc/rc.conf#: [.programlisting] .... keymap="ru.utf-8" scrnmap="utf-82cp866" font8x16="cp866b-8x16" font8x14="cp866-8x14" font8x8="cp866-8x8" mousechar_start=3 .... For each `ttyv` entry in [.filename]#/etc/ttys#, use `cons25r` as the terminal type. To configure printing, a special output filter is needed to convert from KOI8-R to CP866 since most printers with Russian characters come with hardware code page CP866. FreeBSD includes a default filter for this purpose, [.filename]#/usr/libexec/lpr/ru/koi2alt#. To use this filter, add this entry to [.filename]#/etc/printcap#: [.programlisting] .... lp|Russian local line printer:\ :sh:of=/usr/libexec/lpr/ru/koi2alt:\ :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs: .... Refer to man:printcap[5] for a more detailed explanation. To configure support for Russian filenames in mounted MS-DOS(R) file systems, include `-L` and the locale name when adding an entry to [.filename]#/etc/fstab#: [.programlisting] .... /dev/ad0s2 /dos/c msdos rw,-Lru_RU.KOI8-R 0 0 .... Refer to man:mount_msdosfs[8] for more details. To configure Russian fonts for Xorg, install the package:x11-fonts/xorg-fonts-cyrillic[] package. Then, check the `"Files"` section in [.filename]#/etc/X11/xorg.conf#. The following line must be added _before_ any other `FontPath` entries: [.programlisting] .... FontPath "/usr/local/lib/X11/fonts/cyrillic" .... Additional Cyrillic fonts are available in the Ports Collection. To activate a Russian keyboard, add the following to the `"Keyboard"` section of [.filename]#/etc/xorg.conf#: [.programlisting] .... Option "XkbLayout" "us,ru" Option "XkbOptions" "grp:toggle" .... Make sure that `XkbDisable` is commented out in that file. For `grp:toggle` use kbd:[Right Alt], for `grp:ctrl_shift_toggle` use kbd:[Ctrl+Shift]. For `grp:caps_toggle` use kbd:[CapsLock]. The old kbd:[CapsLock] function is still available in LAT mode only using kbd:[Shift+CapsLock]. `grp:caps_toggle` does not work in Xorg for some unknown reason. If the keyboard has "Windows(R)" keys, and some non-alphabetical keys are mapped incorrectly, add the following line to [.filename]#/etc/xorg.conf#: [.programlisting] .... Option "XkbVariant" ",winkeys" .... [NOTE] ==== The Russian XKB keyboard may not work with non-localized applications. Minimally localized applications should call a `XtSetLanguageProc (NULL, NULL, NULL);` function early in the program. ==== See http://koi8.pp.ru/xwin.html[http://koi8.pp.ru/xwin.html] for more instructions on localizing Xorg applications. For more general information about KOI8-R encoding, refer to http://koi8.pp.ru/[http://koi8.pp.ru/]. === Additional Language-Specific Resources This section lists some additional resources for configuring other locales. Traditional Chinese for Taiwan:: The FreeBSD-Taiwan Project has a Chinese HOWTO for FreeBSD at http://netlab.cse.yzu.edu.tw/\~statue/freebsd/zh-tut/[http://netlab.cse.yzu.edu.tw/~statue/freebsd/zh-tut/]. Greek Language Localization:: A complete article on Greek support in FreeBSD is available https://www.FreeBSD.org/doc/gr/articles/greek-language-support/[here], in Greek only, as part of the official FreeBSD Greek documentation. Japanese and Korean Language Localization:: For Japanese, refer to http://www.jp.FreeBSD.org/[http://www.jp.FreeBSD.org/], and for Korean, refer to http://www.kr.FreeBSD.org/[http://www.kr.FreeBSD.org/]. Non-English FreeBSD Documentation:: Some FreeBSD contributors have translated parts of the FreeBSD documentation to other languages. They are available through links on the link:https://www.FreeBSD.org/[FreeBSD web site] or in [.filename]#/usr/share/doc#. diff --git a/documentation/content/en/books/handbook/l10n/_index.po b/documentation/content/en/books/handbook/l10n/_index.po index 58e2e7dd9f..e58b155f83 100644 --- a/documentation/content/en/books/handbook/l10n/_index.po +++ b/documentation/content/en/books/handbook/l10n/_index.po @@ -1,1412 +1,1412 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2024-01-17 20:35-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: YAML Front Matter: description #: documentation/content/en/books/handbook/l10n/_index.adoc:1 #, no-wrap msgid "FreeBSD supports localization into many languages, allowing users to view, input, or process data in non-English languages" msgstr "" #. type: YAML Front Matter: part #: documentation/content/en/books/handbook/l10n/_index.adoc:1 #, no-wrap msgid "Part III. System Administration" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/handbook/l10n/_index.adoc:1 #, no-wrap msgid "Chapter 25. Localization - i18n/L10n Usage and Setup" msgstr "" #. type: Title = #: documentation/content/en/books/handbook/l10n/_index.adoc:14 #, no-wrap msgid "Localization - i18n/L10n Usage and Setup" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/l10n/_index.adoc:52 #, no-wrap msgid "Synopsis" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:57 msgid "" "FreeBSD is a distributed project with users and contributors located all " "over the world. As such, FreeBSD supports localization into many languages, " "allowing users to view, input, or process data in non-English languages. " "One can choose from most of the major languages, including, but not limited " "to: Chinese, German, Japanese, Korean, French, Russian, and Vietnamese." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:61 msgid "" "The term internationalization has been shortened to i18n, which represents " "the number of letters between the first and the last letters of " "`internationalization`. L10n uses the same naming scheme, but from " "`localization`. The i18n/L10n methods, protocols, and applications allow " "users to use languages of their choice." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:64 msgid "" "This chapter discusses the internationalization and localization features of " "FreeBSD. After reading this chapter, you will know:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:66 msgid "How locale names are constructed." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:67 msgid "How to set the locale for a login shell." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:68 msgid "How to configure the console for non-English languages." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:69 msgid "How to configure Xorg for different languages." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:70 msgid "How to find i18n-compliant applications." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:71 msgid "Where to find more information for configuring specific languages." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:73 msgid "Before reading this chapter, you should:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:75 msgid "" "Know how to crossref:ports[ports,install additional third-party " "applications]." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/l10n/_index.adoc:77 #, no-wrap msgid "Using Localization" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:81 msgid "" "Localization settings are based on three components: the language code, " "country code, and encoding. Locale names are constructed from these parts " "as follows:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:85 #, no-wrap msgid "LanguageCode_CountryCode.Encoding\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:89 msgid "" "The _LanguageCode_ and _CountryCode_ are used to determine the country and " "the specific language variation. <> provides some " "examples of __LanguageCode_CountryCode__:" msgstr "" #. type: Block title #: documentation/content/en/books/handbook/l10n/_index.adoc:91 #, no-wrap msgid "Common Language and Country Codes" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:95 #, no-wrap msgid "LanguageCode_Country Code" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:97 #, no-wrap msgid "Description" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:98 #, no-wrap msgid "en_US" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:100 #, no-wrap msgid "English, United States" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:101 #, no-wrap msgid "ru_RU" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:103 #, no-wrap msgid "Russian, Russia" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:104 #, no-wrap msgid "zh_TW" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:105 #, no-wrap msgid "Traditional Chinese, Taiwan" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:108 msgid "A complete listing of available locales can be found by typing:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:112 #, no-wrap msgid "% locale -a | more\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:115 msgid "To determine the current locale setting:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:119 #, no-wrap msgid "% locale\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:123 msgid "" "Language specific character sets, such as ISO8859-1, ISO8859-15, KOI8-R, and " "CP437, are described in man:multibyte[3]. The active list of character sets " "can be found at the http://www.iana.org/assignments/character-sets[IANA " "Registry]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:128 msgid "" "Some languages, such as Chinese or Japanese, cannot be represented using " "ASCII characters and require an extended language encoding using either wide " "or multibyte characters. Examples of wide or multibyte encodings include " "EUC and Big5. Older applications may mistake these encodings for control " "characters while newer applications usually recognize these characters. " "Depending on the implementation, users may be required to compile an " "application with wide or multibyte character support, or to configure it " "correctly." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:132 msgid "FreeBSD uses Xorg-compatible locale encodings." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:136 msgid "" "The rest of this section describes the various methods for configuring the " "locale on a FreeBSD system. The next section will discuss the " "considerations for finding and compiling applications with i18n support." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/l10n/_index.adoc:138 #, no-wrap msgid "Setting Locale for Login Shell" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:141 msgid "" "Locale settings are configured either in a user's [.filename]#~/.login_conf# " "or in the startup file of the user's shell: [.filename]#~/.profile#, [." "filename]#~/.bashrc#, or [.filename]#~/.cshrc#." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:143 msgid "Two environment variables should be set:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:145 msgid "`LANG`, which sets the locale" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:146 msgid "`MM_CHARSET`, which sets the MIME character set used by applications" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:148 msgid "" "In addition to the user's shell configuration, these variables should also " "be set for specific application configuration and Xorg configuration." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:151 msgid "" "Two methods are available for making the needed variable assignments: the " "<> method, which is the recommended method, and the " "<> method. The next two sections demonstrate how " "to use both methods." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/l10n/_index.adoc:153 #, no-wrap msgid "Login Classes Method" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:157 msgid "" "This first method is the recommended method as it assigns the required " "environment variables for locale name and MIME character sets for every " "possible shell. This setup can either be performed by each user or it can " "be configured for all users by the superuser." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:159 msgid "" "This minimal example sets both variables for Latin-1 encoding in the [." "filename]#.login_conf# of an individual user's home directory:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:165 #, no-wrap msgid "" "me:\\\n" "\t:charset=ISO-8859-1:\\\n" "\t:lang=de_DE.ISO8859-1:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:169 msgid "" "Here is an example of a user's [.filename]#~/.login_conf# that sets the " "variables for Traditional Chinese in BIG-5 encoding. More variables are " "needed because some applications do not correctly respect locale variables " "for Chinese, Japanese, and Korean:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:179 #, no-wrap msgid "" "#Users who do not wish to use monetary units or time formats\n" "#of Taiwan can manually change each variable\n" "me:\\\n" "\t:lang=zh_TW.Big5:\\\n" "\t:setenv=LC_ALL=zh_TW.Big5,LC_COLLATE=zh_TW.Big5,LC_CTYPE=zh_TW.Big5,LC_MESSAGES=zh_TW.Big5,LC_MONETARY=zh_TW.Big5,LC_NUMERIC=zh_TW.Big5,LC_TIME=zh_TW.Big5:\\\n" "\t:charset=big5:\\\n" "\t:xmodifiers=\"@im=gcin\": #Set gcin as the XIM Input Server\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:183 msgid "" "Alternately, the superuser can configure all users of the system for " "localization. The following variables in [.filename]#/etc/login.conf# are " "used to set the locale and MIME character set:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:190 #, no-wrap msgid "" "language_name|Account Type Description:\\\n" "\t:charset=MIME_charset:\\\n" "\t:lang=locale_name:\\\n" "\t:tc=default:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:193 msgid "So, the previous Latin-1 example would look like this:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:200 #, no-wrap msgid "" "german|German Users Accounts:\\\n" "\t:charset=ISO-8859-1:\\\n" "\t:lang=de_DE.ISO8859-1:\\\n" "\t:tc=default:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:204 msgid "" "See man:login.conf[5] for more details about these variables. Note that it " "already contains pre-defined _russian_ class." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:206 msgid "" "Whenever [.filename]#/etc/login.conf# is edited, remember to execute the " "following command to update the capability database:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:210 #, no-wrap msgid "# cap_mkdb /etc/login.conf\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:215 msgid "" "For an end user, the `cap_mkdb` command will need to be run on their [." "filename]#~/.login_conf# for any changes to take effect." msgstr "" #. type: Title ===== #: documentation/content/en/books/handbook/l10n/_index.adoc:217 #, no-wrap msgid "Utilities Which Change Login Classes" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:220 msgid "" "In addition to manually editing [.filename]#/etc/login.conf#, several " "utilities are available for setting the locale for newly created users." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:222 msgid "" "When using `vipw` to add new users, specify the _language_ to set the locale:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:226 #, no-wrap msgid "user:password:1111:11:language:0:0:User Name:/home/user:/bin/sh\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:229 msgid "" "When using `adduser` to add new users, the default language can be pre-" "configured for all new users or specified for an individual user." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:231 msgid "" "If all new users use the same language, set `defaultclass=_language_` in [." "filename]#/etc/adduser.conf#." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:233 msgid "" "To override this setting when creating a user, either input the required " "locale at this prompt:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:237 #, no-wrap msgid "Enter login class: default []:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:240 msgid "or specify the locale to set when invoking `adduser`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:244 #, no-wrap msgid "# adduser -class language\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:247 msgid "If `pw` is used to add new users, specify the locale as follows:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:251 #, no-wrap msgid "# pw useradd user_name -L language\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:255 msgid "" "To change the login class of an existing user, `chpass` can be used. Invoke " "it as superuser and provide the username to edit as the argument." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:259 #, no-wrap msgid "# chpass user_name\n" msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/l10n/_index.adoc:263 #, no-wrap msgid "Shell Startup File Method" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:268 msgid "" "This second method is not recommended as each shell that is used requires " "manual configuration, where each shell has a different configuration file " "and differing syntax. As an example, to set the German language for the " "`sh` shell, these lines could be added to [.filename]#~/.profile# to set the " "shell for that user only. These lines could also be added to [.filename]#/" "etc/profile# or [.filename]#/usr/share/skel/dot.profile# to set that shell " "for all users:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:273 #, no-wrap msgid "" "LANG=de_DE.ISO8859-1; export LANG\n" "MM_CHARSET=ISO-8859-1; export MM_CHARSET\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:277 msgid "" "However, the name of the configuration file and the syntax used differs for " "the `csh` shell. These are the equivalent settings for [.filename]#~/." "login#, [.filename]#/etc/csh.login#, or [.filename]#/usr/share/skel/dot." "login#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:282 #, no-wrap msgid "" "setenv LANG de_DE.ISO8859-1\n" "setenv MM_CHARSET ISO-8859-1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:286 msgid "" "To complicate matters, the syntax needed to configure Xorg in [.filename]#~/." "xinitrc# also depends upon the shell. The first example is for the `sh` " "shell and the second is for the `csh` shell:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:290 #, no-wrap msgid "LANG=de_DE.ISO8859-1; export LANG\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:296 #, no-wrap msgid "setenv LANG de_DE.ISO8859-1\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/l10n/_index.adoc:300 #, no-wrap msgid "Console Setup" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:305 msgid "" "Several localized fonts are available for the console. To see a listing of " "available fonts, type `ls /usr/share/syscons/fonts`. To configure the " "console font, specify the _font_name_, without the [.filename]#.fnt# suffix, " "in [.filename]#/etc/rc.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:311 #, no-wrap msgid "" "font8x16=font_name\n" "font8x14=font_name\n" "font8x8=font_name\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:314 msgid "" "The keymap and screenmap can be set by adding the following to [.filename]#/" "etc/rc.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:320 #, no-wrap msgid "" "scrnmap=screenmap_name\n" "keymap=keymap_name\n" "keychange=\"fkey_number sequence\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:325 msgid "" "To see the list of available screenmaps, type `ls /usr/share/syscons/" "scrnmaps`. Do not include the [.filename]#.scm# suffix when specifying " "_screenmap_name_. A screenmap with a corresponding mapped font is usually " "needed as a workaround for expanding bit 8 to bit 9 on a VGA adapter's font " "character matrix so that letters are moved out of the pseudographics area if " "the screen font uses a bit 8 column." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:329 msgid "" "To see the list of available keymaps, type `ls /usr/share/syscons/keymaps`. " "When specifying the _keymap_name_, do not include the [.filename]#.kbd# " "suffix. To test keymaps without rebooting, use man:kbdmap[1]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:331 msgid "" "The `keychange` entry is usually needed to program function keys to match " "the selected terminal type because function key sequences cannot be defined " "in the keymap." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:334 msgid "" "Next, set the correct console terminal type in [.filename]#/etc/ttys# for " "all virtual terminal entries. <> summarizes the available " "terminal types.:" msgstr "" #. type: Block title #: documentation/content/en/books/handbook/l10n/_index.adoc:336 #, no-wrap msgid "Defined Terminal Types for Character Sets" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:340 #, no-wrap msgid "Character Set" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:342 #, no-wrap msgid "Terminal Type" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:343 #, no-wrap msgid "ISO8859-1 or ISO8859-15" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:345 #, no-wrap msgid "`cons25l1`" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:346 #, no-wrap msgid "ISO8859-2" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:348 #, no-wrap msgid "`cons25l2`" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:349 #, no-wrap msgid "ISO8859-7" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:351 #, no-wrap msgid "`cons25l7`" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:352 #, no-wrap msgid "KOI8-R" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:354 #, no-wrap msgid "`cons25r`" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:355 #, no-wrap msgid "KOI8-U" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:357 #, no-wrap msgid "`cons25u`" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:358 #, no-wrap msgid "CP437 (VGA default)" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:360 #, no-wrap msgid "`cons25`" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:361 #, no-wrap msgid "US-ASCII" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:362 #, no-wrap msgid "`cons25w`" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:367 msgid "" "For languages with wide or multibyte characters, install a console for that " "language from the FreeBSD Ports Collection. The available ports are " "summarized in <>. Once installed, refer to the port's [." "filename]#pkg-message# or man pages for configuration and usage instructions." msgstr "" #. type: Block title #: documentation/content/en/books/handbook/l10n/_index.adoc:369 #, no-wrap msgid "Available Console from Ports Collection" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:373 #: documentation/content/en/books/handbook/l10n/_index.adoc:418 #, no-wrap msgid "Language" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:375 #, no-wrap msgid "Port Location" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:376 #, no-wrap msgid "Traditional Chinese (BIG-5)" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:378 #, no-wrap msgid "package:chinese/big5con[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:379 #: documentation/content/en/books/handbook/l10n/_index.adoc:382 #, no-wrap msgid "Chinese/Japanese/Korean" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:381 #, no-wrap msgid "package:chinese/cce[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:384 #, no-wrap msgid "package:chinese/zhcon[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:385 #: documentation/content/en/books/handbook/l10n/_index.adoc:388 #: documentation/content/en/books/handbook/l10n/_index.adoc:391 #: documentation/content/en/books/handbook/l10n/_index.adoc:442 #: documentation/content/en/books/handbook/l10n/_index.adoc:445 #: documentation/content/en/books/handbook/l10n/_index.adoc:448 #: documentation/content/en/books/handbook/l10n/_index.adoc:451 #: documentation/content/en/books/handbook/l10n/_index.adoc:454 #: documentation/content/en/books/handbook/l10n/_index.adoc:457 #: documentation/content/en/books/handbook/l10n/_index.adoc:460 #: documentation/content/en/books/handbook/l10n/_index.adoc:463 #: documentation/content/en/books/handbook/l10n/_index.adoc:466 #: documentation/content/en/books/handbook/l10n/_index.adoc:469 #: documentation/content/en/books/handbook/l10n/_index.adoc:472 #: documentation/content/en/books/handbook/l10n/_index.adoc:475 #: documentation/content/en/books/handbook/l10n/_index.adoc:478 #: documentation/content/en/books/handbook/l10n/_index.adoc:481 #: documentation/content/en/books/handbook/l10n/_index.adoc:484 #: documentation/content/en/books/handbook/l10n/_index.adoc:487 #: documentation/content/en/books/handbook/l10n/_index.adoc:490 #: documentation/content/en/books/handbook/l10n/_index.adoc:493 #, no-wrap msgid "Japanese" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:387 #, no-wrap msgid "package:chinese/kon2[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:390 #, no-wrap msgid "package:japanese/kon2-14dot[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:392 #, no-wrap msgid "package:japanese/kon2-16dot[]" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:397 msgid "" "If moused is enabled in [.filename]#/etc/rc.conf#, additional configuration " "may be required. By default, the mouse cursor of the man:syscons[4] driver " "occupies the `0xd0`-`0xd3` range in the character set. If the language uses " "this range, move the cursor's range by adding the following line to [." "filename]#/etc/rc.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:401 #, no-wrap msgid "mousechar_start=3\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/l10n/_index.adoc:403 #, no-wrap msgid "Xorg Setup" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:408 msgid "" "crossref:x11[x11,The X Window System] describes how to install and configure " "Xorg. When configuring Xorg for localization, additional fonts and input " "methods are available from the FreeBSD Ports Collection. Application " "specific i18n settings such as fonts and menus can be tuned in [." "filename]#~/.Xresources# and should allow users to view their selected " "language in graphical application menus." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:412 msgid "" "The X Input Method (XIM) protocol is an Xorg standard for inputting non-" "English characters. <> summarizes the input method applications " "which are available in the FreeBSD Ports Collection. Additional Fcitx and " "Uim applications are also available." msgstr "" #. type: Block title #: documentation/content/en/books/handbook/l10n/_index.adoc:414 #, no-wrap msgid "Available Input Methods" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:420 #, no-wrap msgid "Input Method" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:421 #: documentation/content/en/books/handbook/l10n/_index.adoc:424 #: documentation/content/en/books/handbook/l10n/_index.adoc:427 #: documentation/content/en/books/handbook/l10n/_index.adoc:430 #: documentation/content/en/books/handbook/l10n/_index.adoc:433 #: documentation/content/en/books/handbook/l10n/_index.adoc:436 #: documentation/content/en/books/handbook/l10n/_index.adoc:439 #, no-wrap msgid "Chinese" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:423 #, no-wrap msgid "package:chinese/gcin[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:426 #, no-wrap msgid "package:chinese/ibus-chewing[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:429 #, no-wrap msgid "package:chinese/ibus-pinyin[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:432 #, no-wrap msgid "package:chinese/oxim[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:435 #, no-wrap msgid "package:chinese/scim-fcitx[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:438 #, no-wrap msgid "package:chinese/scim-pinyin[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:441 #, no-wrap msgid "package:chinese/scim-tables[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:444 #, no-wrap msgid "package:japanese/ibus-anthy[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:447 #, no-wrap msgid "package:japanese/ibus-mozc[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:450 #, no-wrap msgid "package:japanese/ibus-skk[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:453 #, no-wrap msgid "package:japanese/im-ja[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:456 #, no-wrap msgid "package:japanese/kinput2[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:459 #, no-wrap msgid "package:japanese/scim-anthy[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:462 #, no-wrap msgid "package:japanese/scim-canna[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:465 #, no-wrap msgid "package:japanese/scim-honoka[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:468 #, no-wrap msgid "package:japanese/scim-honoka-plugin-romkan[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:471 #, no-wrap msgid "package:japanese/scim-honoka-plugin-wnn[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:474 #, no-wrap msgid "package:japanese/scim-prime[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:477 #, no-wrap msgid "package:japanese/scim-skk[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:480 #, no-wrap msgid "package:japanese/scim-tables[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:483 #, no-wrap msgid "package:japanese/scim-tomoe[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:486 #, no-wrap msgid "package:japanese/scim-uim[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:489 #, no-wrap msgid "package:japanese/skkinput[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:492 #, no-wrap msgid "package:japanese/skkinput3[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:495 #, no-wrap msgid "package:japanese/uim-anthy[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:496 #: documentation/content/en/books/handbook/l10n/_index.adoc:499 #: documentation/content/en/books/handbook/l10n/_index.adoc:502 #: documentation/content/en/books/handbook/l10n/_index.adoc:505 #: documentation/content/en/books/handbook/l10n/_index.adoc:508 #, no-wrap msgid "Korean" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:498 #, no-wrap msgid "package:korean/ibus-hangul[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:501 #, no-wrap msgid "package:korean/imhangul[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:504 #, no-wrap msgid "package:korean/nabi[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:507 #, no-wrap msgid "package:korean/scim-hangul[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:510 #, no-wrap msgid "package:korean/scim-tables[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:511 #: documentation/content/en/books/handbook/l10n/_index.adoc:514 #, no-wrap msgid "Vietnamese" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:513 #, no-wrap msgid "package:vietnamese/xvnkb[]" msgstr "" #. type: Table #: documentation/content/en/books/handbook/l10n/_index.adoc:515 #, no-wrap msgid "package:vietnamese/x-unikey[]" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/l10n/_index.adoc:518 #, no-wrap msgid "Finding i18n Applications" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:522 msgid "" "i18n applications are programmed using i18n kits under libraries. These " "allow developers to write a simple file and translate displayed menus and " "texts to each language." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:526 msgid "" -"The link:https://www.FreeBSD.org/ports/[FreeBSD Ports Collection] contains " +"The link:https://ports.FreeBSD.org[FreeBSD Ports Collection] contains " "many applications with built-in support for wide or multibyte characters for " "several languages. Such applications include `i18n` in their names for easy " "identification. However, they do not always support the language needed." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:530 msgid "" "Some applications can be compiled with the specific charset. This is " "usually done in the port's [.filename]#Makefile# or by passing a value to " "configure. Refer to the i18n documentation in the respective FreeBSD port's " "source for more information on how to determine the needed configure value " "or the port's [.filename]#Makefile# to determine which compile options to " "use when building the port." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/l10n/_index.adoc:532 #, no-wrap msgid "Locale Configuration for Specific Languages" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:536 msgid "" "This section provides configuration examples for localizing a FreeBSD system " "for the Russian language. It then provides some additional resources for " "localizing other languages." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/l10n/_index.adoc:538 #, no-wrap msgid "Russian Language (KOI8-R Encoding)" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:542 msgid "" "This section shows the specific settings needed to localize a FreeBSD system " "for the Russian language. Refer to <> for a complete description of each type of setting." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:544 msgid "" "To set this locale for the login shell, add the following lines to each " "user's [.filename]#~/.login_conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:550 #, no-wrap msgid "" "me:My Account:\\\n" "\t:charset=KOI8-R:\\\n" "\t:lang=ru_RU.KOI8-R:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:553 msgid "" "To configure the console, add the following lines to [.filename]#/etc/rc." "conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:562 #, no-wrap msgid "" "keymap=\"ru.utf-8\"\n" "scrnmap=\"utf-82cp866\"\n" "font8x16=\"cp866b-8x16\"\n" "font8x14=\"cp866-8x14\"\n" "font8x8=\"cp866-8x8\"\n" "mousechar_start=3\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:565 msgid "" "For each `ttyv` entry in [.filename]#/etc/ttys#, use `cons25r` as the " "terminal type." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:569 msgid "" "To configure printing, a special output filter is needed to convert from " "KOI8-R to CP866 since most printers with Russian characters come with " "hardware code page CP866. FreeBSD includes a default filter for this " "purpose, [.filename]#/usr/libexec/lpr/ru/koi2alt#. To use this filter, add " "this entry to [.filename]#/etc/printcap#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:575 #, no-wrap msgid "" "lp|Russian local line printer:\\\n" "\t:sh:of=/usr/libexec/lpr/ru/koi2alt:\\\n" "\t:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:578 msgid "Refer to man:printcap[5] for a more detailed explanation." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:580 msgid "" "To configure support for Russian filenames in mounted MS-DOS(R) file " "systems, include `-L` and the locale name when adding an entry to [." "filename]#/etc/fstab#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:584 #, no-wrap msgid "/dev/ad0s2 /dos/c msdos rw,-Lru_RU.KOI8-R 0 0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:587 msgid "Refer to man:mount_msdosfs[8] for more details." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:590 msgid "" "To configure Russian fonts for Xorg, install the package:x11-fonts/xorg-" "fonts-cyrillic[] package. Then, check the `\"Files\"` section in [." "filename]#/etc/X11/xorg.conf#. The following line must be added _before_ any " "other `FontPath` entries:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:594 #, no-wrap msgid "FontPath \"/usr/local/lib/X11/fonts/cyrillic\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:597 msgid "Additional Cyrillic fonts are available in the Ports Collection." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:599 msgid "" "To activate a Russian keyboard, add the following to the `\"Keyboard\"` " "section of [.filename]#/etc/xorg.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:604 #, no-wrap msgid "" "Option \"XkbLayout\" \"us,ru\"\n" "Option \"XkbOptions\" \"grp:toggle\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:607 msgid "Make sure that `XkbDisable` is commented out in that file." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:610 msgid "" "For `grp:toggle` use kbd:[Right Alt], for `grp:ctrl_shift_toggle` use kbd:" "[Ctrl+Shift]. For `grp:caps_toggle` use kbd:[CapsLock]. The old kbd:" "[CapsLock] function is still available in LAT mode only using kbd:" "[Shift+CapsLock]. `grp:caps_toggle` does not work in Xorg for some unknown " "reason." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:612 msgid "" "If the keyboard has \"Windows(R)\" keys, and some non-alphabetical keys are " "mapped incorrectly, add the following line to [.filename]#/etc/xorg.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:616 #, no-wrap msgid "Option \"XkbVariant\" \",winkeys\"\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/l10n/_index.adoc:622 msgid "" "The Russian XKB keyboard may not work with non-localized applications. " "Minimally localized applications should call a `XtSetLanguageProc (NULL, " "NULL, NULL);` function early in the program." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:626 msgid "" "See http://koi8.pp.ru/xwin.html[http://koi8.pp.ru/xwin.html] for more " "instructions on localizing Xorg applications. For more general information " "about KOI8-R encoding, refer to http://koi8.pp.ru/[http://koi8.pp.ru/]." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/l10n/_index.adoc:627 #, no-wrap msgid "Additional Language-Specific Resources" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:630 msgid "" "This section lists some additional resources for configuring other locales." msgstr "" #. type: Labeled list #: documentation/content/en/books/handbook/l10n/_index.adoc:631 #, no-wrap msgid "Traditional Chinese for Taiwan" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:633 msgid "" "The FreeBSD-Taiwan Project has a Chinese HOWTO for FreeBSD at http://netlab." "cse.yzu.edu.tw/\\~statue/freebsd/zh-tut/[http://netlab.cse.yzu.edu.tw/" "~statue/freebsd/zh-tut/]." msgstr "" #. type: Labeled list #: documentation/content/en/books/handbook/l10n/_index.adoc:634 #, no-wrap msgid "Greek Language Localization" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:636 msgid "" "A complete article on Greek support in FreeBSD is available https://www." "FreeBSD.org/doc/gr/articles/greek-language-support/[here], in Greek only, as " "part of the official FreeBSD Greek documentation." msgstr "" #. type: Labeled list #: documentation/content/en/books/handbook/l10n/_index.adoc:637 #, no-wrap msgid "Japanese and Korean Language Localization" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:639 msgid "" "For Japanese, refer to http://www.jp.FreeBSD.org/[http://www.jp.FreeBSD." "org/], and for Korean, refer to http://www.kr.FreeBSD.org/[http://www.kr." "FreeBSD.org/]." msgstr "" #. type: Labeled list #: documentation/content/en/books/handbook/l10n/_index.adoc:640 #, no-wrap msgid "Non-English FreeBSD Documentation" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/l10n/_index.adoc:642 msgid "" "Some FreeBSD contributors have translated parts of the FreeBSD documentation " "to other languages. They are available through links on the link:https://" "www.FreeBSD.org/[FreeBSD web site] or in [.filename]#/usr/share/doc#." msgstr "" diff --git a/documentation/content/en/books/handbook/ports/_index.adoc b/documentation/content/en/books/handbook/ports/_index.adoc index a85cea963d..e5ed68368a 100644 --- a/documentation/content/en/books/handbook/ports/_index.adoc +++ b/documentation/content/en/books/handbook/ports/_index.adoc @@ -1,1309 +1,1309 @@ --- title: "Chapter 4. Installing Applications: Packages and Ports" part: Part I. Getting Started prev: books/handbook/basics next: books/handbook/x11 description: "FreeBSD provides two complementary technologies for installing third-party software: the FreeBSD Ports Collection, for installing from source, and packages, for installing from pre-built binaries" tags: ["ports", "collection", "pkg", "poudriere", "management"] showBookMenu: true weight: 6 path: "/books/handbook/ports/" --- [[ports]] = Installing Applications: Packages and Ports :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 4 :partnums: :source-highlighter: rouge :experimental: :images-path: books/handbook/ports/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[ports-synopsis]] == Synopsis FreeBSD is bundled with a rich collection of system tools as part of the base system. In addition, FreeBSD provides two complementary technologies for installing third-party software: the FreeBSD Ports Collection, for installing from source, and packages, for installing from pre-built binaries. Either method may be used to install software from local media or from the network. After reading this chapter, you will know: * The difference between binary packages and ports. * How to find third-party software that has been ported to FreeBSD. * How to manage binary packages using pkg. * How to build third-party software from source using the Ports Collection. * How to find the files installed with the application for post-installation configuration. * What to do if a software installation fails. [[ports-overview]] == Overview of Software Installation A FreeBSD _port_ is a collection of files designed to automate the process of compiling an application from source code. The files that comprise a port contain all the necessary information to automatically download, extract, patch, compile, and install the application. If the software has not already been adapted and tested on FreeBSD, the source code might need editing in order for it to install and run properly. -However, over link:https://www.FreeBSD.org/ports/[{numports}] third-party applications have already been ported to FreeBSD. +However, over link:https://ports.FreeBSD.org[{numports}] third-party applications have already been ported to FreeBSD. When feasible, these applications are made available for download as pre-compiled _packages_. Packages can be manipulated with the FreeBSD package management commands. Both packages and ports understand dependencies. If a package or port is used to install an application and a dependent library is not already installed, the library will automatically be installed first. A FreeBSD package contains pre-compiled copies of all the commands for an application, as well as any configuration files and documentation. A package can be manipulated with the man:pkg[8] commands, such as `pkg install`. While the two technologies are similar, packages and ports each have their own strengths. Select the technology that meets your requirements for installing a particular application. .Package Benefits * A compressed package tarball is typically smaller than the compressed tarball containing the source code for the application. * Packages do not require compilation time. For large applications, such as Firefox, KDE Plasma, or GNOME, this can be important on a slow system. * Packages do not require any understanding of the process involved in compiling software on FreeBSD. .Port Benefits * Packages are normally compiled with conservative options because they have to run on the maximum number of systems. By compiling from the port, one can change the compilation options. * Some applications have compile-time options relating to which features are installed. For example, NGINX(R) can be configured with a wide variety of different built-in options. + In some cases, multiple packages will exist for the same application to specify certain settings. For example, NGINX(R) is available as a `nginx` package and a `nginx-lite` package, depending on whether or not Xorg is installed. Creating multiple packages rapidly becomes impossible if an application has more than one or two different compile-time options. * The licensing conditions of some software forbid binary distribution. Such software must be distributed as source code which must be compiled by the end-user. * Some people do not trust binary distributions or prefer to read through source code in order to look for potential problems. * Source code is needed in order to apply custom patches. To keep track of updated ports, subscribe to the {freebsd-ports} and the {freebsd-ports-bugs}. [WARNING] ==== Before installing an application, check https://vuxml.freebsd.org/[] for related security issues. To audit installed packages against known vulnerabilities, run `pkg audit -F`. ==== The remainder of this chapter explains how to use packages and ports to install and manage third-party software on FreeBSD. [[ports-finding-applications]] == Finding Software FreeBSD's list of available applications is growing all the time. There are a number of ways to find software to install: -* The FreeBSD web site maintains an up-to-date searchable list of all the available applications, at link:https://www.FreeBSD.org/ports/[Ports Portal]. The ports can be searched by application name or by software category. +* The FreeBSD web site maintains an up-to-date searchable list of all the available applications, at link:https://ports.FreeBSD.org[Ports Portal]. The ports can be searched by application name or by software category. * Dan Langille maintains https://www.freshports.org/[FreshPorts] which provides a comprehensive search utility and also tracks changes to the applications in the Ports Collection. Registered users can create a customized watch list in order to receive an automated email when their watched ports are updated. -* If finding a particular application becomes challenging, try searching a site like https://sourceforge.net/[SourceForge] or https://github.com/[GitHub] then check back at the link:https://www.FreeBSD.org/ports/[Ports Portal] to see if the application has been ported. +* If finding a particular application becomes challenging, try searching a site like https://sourceforge.net/[SourceForge] or https://github.com/[GitHub] then check back at the link:https://ports.FreeBSD.org[Ports Portal] to see if the application has been ported. * Search the binary package repository for an application using the man:pkg[8] command [[pkgng-intro]] == Using pkg for Binary Package Management man:pkg[8] provides an interface for manipulating packages: registering, adding, removing and upgrading packages. For sites wishing to only use prebuilt binary packages from the FreeBSD mirrors, managing packages with man:pkg[8] can be sufficient. However, for those sites building from source a separate <> will be needed. Since man:pkg[8] only works with binary packages, it is not a replacement for such tools. Those tools can be used to install software from both binary packages and the Ports Collection, while man:pkg[8] installs only binary packages. [[pkgng-initial-setup]] === Getting Started with pkg All supported versions of FreeBSD now contain `/usr/sbin/pkg` a.k.a man:pkg[7]. This is a small placeholder that has just the minimum functionality required to install the real man:pkg[8]. [NOTE] ==== An Internet working connection is required for the bootstrap process to succeed. ==== Run man:pkg[8] command line: [source,shell] .... # pkg .... The output should be similar to the following: [.programlisting] .... The package management tool is not yet installed on your system. Do you want to fetch and install it now? [y/N] .... man:pkg[7] will intercept the command, and if you confirm that is your intention, download the man:pkg[8] tarball, install man:pkg[8] from it, bootstrap the local package database and then proceed to run the command you originally requested. More recent versions of man:pkg[7] understand `pkg -N` as a test to see if man:pkg[8] is installed without triggering the installation, and conversely, pkg bootstrap[-f] to install man:pkg[8] (or force it to be reinstalled) without performing any other actions. Usage information for pkg is available in the man:pkg[8] manual page or by running `pkg` without additional arguments. Additional pkg configuration options are described in man:pkg.conf[5]. Each pkg command argument is documented in a command-specific manual page. To read the manual page for `pkg install`, for example, run this command: [source,shell] .... # pkg help install .... The rest of this section demonstrates common binary package management tasks which can be performed using man:pkg[8]. Each demonstrated command provides many switches to customize its use. Refer to a command's help or man page for details and more examples. [[quarterly-latest-branch]] === Quarterly and Latest Ports Branches The `Quarterly` branch provides users with a more predictable and stable experience for port and package installation and upgrades. This is done essentially by only allowing non-feature updates. Quarterly branches aim to receive security fixes (that may be version updates, or backports of commits), bug fixes and ports compliance or framework changes. The Quarterly branch is cut from HEAD at the beginning of every (yearly) quarter in January, April, July, and October. Branches are named according to the year (YYYY) and quarter (Q1-4) they are created in. For example, the quarterly branch created in January 2023, is named 2023Q1. And the `Latest` branch provides the latest versions of the packages to the users. To switch man:pkg[8] from Quarterly to Latest run the following commands: [source,shell] .... # mkdir -p /usr/local/etc/pkg/repos # echo 'FreeBSD: { url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest" }' > /usr/local/etc/pkg/repos/FreeBSD.conf .... Then run this command to update the local package repositories catalogues for the Latest branch: [source,shell] .... # pkg update -f .... [[pkg-configuration]] === Configure pkg man:pkg.conf[5] is the system-wide configuration file used by the man:pkg[8] tools. The default location of this file is `/usr/local/etc/pkg.conf`. [NOTE] ==== FreeBSD does not need to have a `pkg.conf` file. Many installations will work well with no `pkg.conf` at all or with an empty `pkg.conf` (other than comment lines). ==== Lines in the file beginning with a "#" are comments and are ignored. The file is in UCL format. For more information on the syntax of man:libucl[3], please visit the link:https://github.com/vstakhov/libucl[official UCL website]. The following types of options are recognized - boolean, string and list options. A boolean option is marked as enabled if one of the following values is specified in the configuration file - YES, TRUE and ON. [[pkg-search]] === Searching Packages To search a package man:pkg-search[8] can be used: [source,shell] .... # pkg search nginx .... The output should be similar to the following: [.programlisting] .... modsecurity3-nginx-1.0.3 Instruction detection and prevention engine / nginx Wrapper nginx-1.22.1_2,3 Robust and small WWW server nginx-devel-1.23.2_4 Robust and small WWW server nginx-full-1.22.1_1,3 Robust and small WWW server (full package) nginx-lite-1.22.1,3 Robust and small WWW server (lite package) nginx-naxsi-1.22.1,3 Robust and small WWW server (plus NAXSI) nginx-prometheus-exporter-0.10.0_7 Prometheus exporter for NGINX and NGINX Plus stats nginx-ultimate-bad-bot-blocker-4.2020.03.2005_1 Nginx bad bot and other things blocker nginx-vts-exporter-0.10.7_7 Server that scraps NGINX vts stats and export them via HTTP p5-Nginx-ReadBody-0.07_1 Nginx embeded perl module to read and evaluate a request body p5-Nginx-Simple-0.07_1 Perl 5 module for easy to use interface for Nginx Perl Module p5-Test-Nginx-0.30 Testing modules for Nginx C module development py39-certbot-nginx-2.0.0 NGINX plugin for Certbot rubygem-passenger-nginx-6.0.15 Modules for running Ruby on Rails and Rack applications .... [[pkg-installing-fetching]] === Installing and Fetching Packages To install a binary package man:pkg-install[8] can be used. This command uses repository data to determine which version of the software to install and if it has any uninstalled dependencies. For example, to install curl: [source,shell] .... # pkg install curl .... The output should be similar to the following: [.programlisting] .... Updating FreeBSD repository catalogue... FreeBSD repository is up to date. All repositories are up to date. The following 9 package(s) will be affected (of 0 checked): New packages to be INSTALLED: ca_root_nss: 3.83 curl: 7.86.0 gettext-runtime: 0.21 indexinfo: 0.3.1 libidn2: 2.3.3 libnghttp2: 1.48.0 libpsl: 0.21.1_4 libssh2: 1.10.0.3 libunistring: 1.0 Number of packages to be installed: 9 The process will require 11 MiB more space. 3 MiB to be downloaded Proceed with this action? [y/N] .... The new package and any additional packages that were installed as dependencies can be seen in the installed packages list: [source,shell] .... # pkg info .... The output should be similar to the following: [.programlisting] .... ca_root_nss-3.83 Root certificate bundle from the Mozilla Project curl-7.86.0 Command line tool and library for transferring data with URLs gettext-runtime-0.21.1 GNU gettext runtime libraries and programs indexinfo-0.3.1 Utility to regenerate the GNU info page index libidn2-2.3.3 Implementation of IDNA2008 internationalized domain names libnghttp2-1.48.0 HTTP/2.0 C Library libpsl-0.21.1_6 C library to handle the Public Suffix List libssh2-1.10.0.3 Library implementing the SSH2 protocol libunistring-1.0 Unicode string library pkg-1.18.4 Package manager .... To fetch a package and install it later or in another place use man:pkg-fetch[8]. For example, to download `nginx-lite`: [source,shell] .... # pkg fetch -d -o /usr/home/user/packages/ nginx-lite .... * `-d`: used to fetch all the dependencies * `-o`: used to specify the download directory The output should be similar to the following: [.programlisting] .... Updating FreeBSD repository catalogue... FreeBSD repository is up to date. All repositories are up to date. The following packages will be fetched: New packages to be FETCHED: nginx-lite: 1.22.1,3 (342 KiB: 22.20% of the 2 MiB to download) pcre: 8.45_3 (1 MiB: 77.80% of the 2 MiB to download) Number of packages to be fetched: 2 The process will require 2 MiB more space. 2 MiB to be downloaded. Proceed with fetching packages? [y/N]: .... To install the downloaded packages man:pkg-install[8] can be used as follows: [source,shell] .... # cd /usr/home/user/packages/ .... [source,shell] .... # pkg install nginx-lite-1.22.1,3.pkg .... [[pkgng-pkg-info]] === Obtaining Information About Installed Packages Information about the packages installed on a system can be viewed by running man:pkg-info[8] which, when run without any switches, will list the package version for either all installed packages or the specified package. For example, to see which version of pkg is installed, run: [source,shell] .... # pkg info pkg .... The output should be similar to the following: [.programlisting] .... pkg-1.19.0 Name : pkg Version : 1.19.0 Installed on : Sat Dec 17 11:05:28 2022 CET Origin : ports-mgmt/pkg Architecture : FreeBSD:13:amd64 Prefix : /usr/local Categories : ports-mgmt Licenses : BSD2CLAUSE Maintainer : pkg@FreeBSD.org WWW : https://github.com/freebsd/pkg Comment : Package manager Options : DOCS : on Shared Libs provided: libpkg.so.4 Annotations : FreeBSD_version: 1301000 repo_type : binary repository : FreeBSD Flat size : 33.2MiB Description : Package management tool WWW: https://github.com/freebsd/pkg .... [[pkgng-upgrading]] === Upgrading Installed Packages Installed packages can be upgraded to their latest versions using man:pkg-upgrade[8]: [source,shell] .... # pkg upgrade .... This command will compare the installed versions with those available in the repository catalogue and upgrade them from the repository. [[pkgng-auditing]] === Auditing Installed Packages Software vulnerabilities are regularly discovered in third-party applications. To address this, pkg includes a built-in auditing mechanism. To determine if there are any known vulnerabilities for the software installed on the system, use man:pkg-audit[8]: [source,shell] .... # pkg audit -F .... The output should be similar to the following: [.programlisting] .... Fetching vuln.xml.xz: 100% 976 KiB 499.5kB/s 00:02 chromium-108.0.5359.98 is vulnerable: chromium -- multiple vulnerabilities CVE: CVE-2022-4440 CVE: CVE-2022-4439 CVE: CVE-2022-4438 CVE: CVE-2022-4437 CVE: CVE-2022-4436 WWW: https://vuxml.FreeBSD.org/freebsd/83eb9374-7b97-11ed-be8f-3065ec8fd3ec.html .... [[pkg-delete]] === Removing Packages Packages that are no longer needed can be removed with man:pkg-delete[8]. For example: [source,shell] .... # pkg delete curl .... The output should be similar to the following: [.programlisting] .... Checking integrity... done (0 conflicting) Deinstallation has been requested for the following 1 packages (of 0 packages in the universe): Installed packages to be REMOVED: curl :7.86.0 Number of packages to be removed: 1 The operation will free 4 MiB. Proceed with deinstallation packages? [y/N]: y [1/1] Deinstalling curl-7.86.0... [1/1] Deleting files for curl-7.86.0: 100% .... [[pkgng-autoremove]] === Automatically Removing Unused Packages Removing a package may leave behind dependencies which are no longer required. Unneeded packages that were installed as dependencies (leaf packages) can be automatically detected and removed using man:pkg-autoremove[8]: [source,shell] .... # pkg autoremove .... The output should be similar to the following: [.programlisting] .... Checking integrity... done (0 conflicting) Deinstallation has been requested for the following 1 packages: Installed packages to be REMOVED: ca_root_nss-3.83 Number of packages to be removed: 1 The operation will free 723 KiB. Proceed with deinstalling packages? [y/N]: .... Packages installed as dependencies are called _automatic_ packages. Non-automatic packages, i.e the packages that were explicitly installed not as a dependency to another package, can be listed using: [source,shell] .... # pkg prime-list .... The output should be similar to the following: [.programlisting] .... nginx openvpn sudo .... `pkg prime-list` is an alias command declared in `/usr/local/etc/pkg.conf`. There are many others that can be used to query the package database of the system. For instance, command `pkg prime-origins` can be used to get the origin port directory of the list mentioned above: [source,shell] .... # pkg prime-origins .... The output should be similar to the following: [.programlisting] .... www/nginx security/openvpn security/sudo .... This list can be used to rebuild all packages installed on a system using build tools such as package:ports-mgmt/poudriere[] or package:ports-mgmt/synth[]. Marking an installed package as automatic can be done using: [source,shell] .... # pkg set -A 1 devel/cmake .... Once a package is a leaf package and is marked as automatic, it gets selected by `pkg autoremove`. Marking an installed package as _not_ automatic can be done using: [source,shell] .... # pkg set -A 0 devel/cmake .... [[pkgng-clean]] === Removing Stale Packages By default, pkg stores binary packages in a cache directory defined by `PKG_CACHEDIR` in man:pkg.conf[5]. Only copies of the latest installed packages are kept. Older versions of pkg kept all previous packages. To remove these outdated binary packages, run: [source,shell] .... # pkg clean .... The entire cache may be cleared by running: [source,shell] .... # pkg clean -a .... [[pkg-locking-unlocking]] === Locking and Unlocking Packages man:pkg-lock[8] is used to lock packages against reinstallation, modification or deletion. man:pkg-unlock[8] unlocks the named packages. Either variant only has an effect on currently installed packages. Consequently it is impossible to block installation of a new package by using this mechanism, unless such an installation implies updating a locked package. For example, to lock `nginx-lite`: [source,shell] .... # pkg lock nginx-lite .... And to unlock `nginx-lite`: [source,shell] .... # pkg unlock nginx-lite .... [[pkgng-set]] === Modifying Package Metadata Software within the FreeBSD Ports Collection can undergo major version number changes. To address this, pkg has a built-in command to update package origins. This can be useful, for example, if package:lang/python3[] is renamed to package:lang/python311[] so that package:lang/python3[] can now represent version `3.11`. To change the package origin for the above example, run: [source,shell] .... # pkg set -o lang/python3:lang/python311 .... As another example, to update package:lang/ruby31[] to package:lang/ruby32[], run: [source,shell] .... # pkg set -o lang/ruby31:lang/ruby32 .... [NOTE] ==== When changing package origins, it is important to reinstall packages that are dependent on the package with the modified origin. To force a reinstallation of dependent packages, run: [source,shell] .... # pkg install -Rf lang/ruby32 .... ==== [[ports-using]] == Using the Ports Collection The Ports Collection is a set of `Makefiles`, patches, and description files. Each set of these files is used to compile and install an individual application on FreeBSD, and is called a _port_. By default, the Ports Collection itself is stored as a subdirectory of `/usr/ports`. [WARNING] ==== Before installing and using the Ports Collection, please be aware that it is generally ill-advised to use the Ports Collection in conjunction with the binary packages provided via pkg to install software. pkg, by default, tracks quarterly branch-releases of the ports tree and not HEAD. Dependencies could be different for a port in HEAD compared to its counterpart in a quarterly branch release and this could result in conflicts between dependencies installed by pkg and those from the Ports Collection. If the Ports Collection and pkg must be used in conjunction, then be sure that your Ports Collection and pkg are on the same branch release of the ports tree. ==== The Ports Collection contains directories for software categories. Inside each category are subdirectories for individual applications. Each application subdirectory contains a set of files that tells FreeBSD how to compile and install that program, called a _ports skeleton_. Each port skeleton includes these files and directories: * *Makefile*: contains statements that specify how the application should be compiled and where its components should be installed. * *distinfo*: contains the names and checksums of the files that must be downloaded to build the port. * *files/*: this directory contains any patches needed for the program to compile and install on FreeBSD. This directory may also contain other files used to build the port. * *pkg-descr*: provides a more detailed description of the program. * *pkg-plist*: a list of all the files that will be installed by the port. It also tells the ports system which files to remove upon deinstallation. Some ports include `pkg-message` or other files to handle special situations. For more details on these files, and on ports in general, refer to the extref:{porters-handbook}[FreeBSD Porter's Handbook]. The port does not include the actual source code, also known as a `distfile`. The extract portion of building a port will automatically save the downloaded source to `/usr/ports/distfiles`. [[ports-using-installation-methods]] === Installing the Ports Collection Before an application can be compiled using a port, the Ports Collection must first be installed. If it was not installed during the installation of FreeBSD, use the following method to install it: [[ports-using-git-method]] [.procedure] **** *Procedure: Git Method* If more control over the ports tree is needed or if local changes need to be maintained, or if running FreeBSD-CURRENT, Git can be used to obtain the Ports Collection. Refer to extref:{committers-guide}[the Git Primer, git-primer] for a detailed description of Git. We add --depth 1 to the git command line to clone the tree without obtaining the commit history, which saves time and is acceptable for most users. If you have your own changes to the ports tree, or need the history for any reason, omit the --depth 1 argument below. . Git must be installed before it can be used to check out the ports tree. If a copy of the ports tree is already present, install Git like this: + [source,shell] .... # cd /usr/ports/devel/git # make install clean .... + If the ports tree is not available, or pkg is being used to manage packages, Git can be installed as a package: + [source,shell] .... # pkg install git .... + . Check out a copy of the HEAD branch of the ports tree: + [source,shell] .... # git clone --depth 1 https://git.FreeBSD.org/ports.git /usr/ports .... + . Or, check out a copy of a quarterly branch: + [source,shell] .... # git clone --depth 1 https://git.FreeBSD.org/ports.git -b 2023Q1 /usr/ports .... + . As needed, update `/usr/ports` after the initial Git checkout: + [source,shell] .... # git -C /usr/ports pull .... + . As needed, switch `/usr/ports` to a different quarterly branch: + [source,shell] .... # git -C /usr/ports switch 2023Q1 .... **** === Installing Ports This section provides basic instructions on using the Ports Collection to install or remove software. The detailed description of available `make` targets and environment variables is available in man:ports[7]. [WARNING] ==== Before compiling any port, be sure to update the Ports Collection as described in the previous section. Since the installation of any third-party software can introduce security vulnerabilities, it is recommended to first check https://vuxml.freebsd.org/[] for known security issues related to the port. Alternatively, run `pkg audit -F` before installing a new port. This command can be configured to automatically perform a security audit and an update of the vulnerability database during the daily security system check. For more information, refer to man:pkg-audit[8] and man:periodic[8]. ==== Using the Ports Collection assumes a working Internet connection. It also requires superuser privilege. To compile and install the port, change to the directory of the port to be installed, then type `make install` at the prompt. Messages will indicate the progress: [source,shell] .... # cd /usr/ports/sysutils/lsof # make install >> lsof_4.88D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/. >> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/. ===> Extracting for lsof-4.88 ... [extraction output snipped] ... >> Checksum OK for lsof_4.88D.freebsd.tar.gz. ===> Patching for lsof-4.88.d,8 ===> Applying FreeBSD patches for lsof-4.88.d,8 ===> Configuring for lsof-4.88.d,8 ... [configure output snipped] ... ===> Building for lsof-4.88.d,8 ... [compilation output snipped] ... ===> Installing for lsof-4.88.d,8 ... [installation output snipped] ... ===> Generating temporary packing list ===> Compressing manual pages for lsof-4.88.d,8 ===> Registering installation for lsof-4.88.d,8 ===> SECURITY NOTE: This port has installed the following binaries which execute with increased privileges. /usr/local/sbin/lsof # .... Since `lsof` is a program that runs with increased privileges, a security warning is displayed as it is installed. Once the installation is complete, the prompt will be returned. Some shells keep a cache of the commands that are available in the directories listed in the `PATH` environment variable, to speed up lookup operations for the executable file of these commands. Users of the `tcsh` shell should type `rehash` so that a newly installed command can be used without specifying its full path. Use `hash -r` instead for the `sh` shell. Refer to the documentation for the shell for more information. During installation, a working subdirectory is created which contains all the temporary files used during compilation. Removing this directory saves disk space and minimizes the chance of problems later when upgrading to the newer version of the port: [source,shell] .... # make clean ===> Cleaning for lsof-88.d,8 # .... [NOTE] ==== To save this extra step, instead use `make install clean` when compiling the port. ==== ==== Customizing Ports Installation Some ports provide build options which can be used to enable or disable application components, provide security options, or allow for other customizations. Examples include package:www/firefox[] and package:security/gpgme[]. If the port depends upon other ports which have configurable options, it may pause several times for user interaction as the default behavior is to prompt the user to select options from a menu. To avoid this and do all of the configuration in one batch, run `make config-recursive` within the port skeleton. Then, run `make install [clean]` to compile and install the port. [TIP] ==== When using `config-recursive`, the list of ports to configure are gathered by the `all-depends-list` target. It is recommended to run `make config-recursive` until all dependent ports options have been defined, and ports options screens no longer appear, to be certain that all dependency options have been configured. ==== There are several ways to revisit a port's build options menu in order to add, remove, or change these options after a port has been built. One method is to `cd` into the directory containing the port and type `make config`. Another option is to use `make showconfig`. Another option is to execute `make rmconfig` which will remove all selected options and allow you to start over. All of these options, and others, are explained in great detail in man:ports[7]. The ports system uses man:fetch[1] to download the source files, which supports various environment variables. The `FTP_PASSIVE_MODE`, `FTP_PROXY`, and `FTP_PASSWORD` variables may need to be set if the FreeBSD system is behind a firewall or FTP/HTTP proxy. See man:fetch[3] for the complete list of supported variables. For users who cannot be connected to the Internet all the time, `make fetch` can be run within `/usr/ports`, to fetch all distfiles, or within a category, such as `/usr/ports/net`, or within the specific port skeleton. Note that if a port has any dependencies, running this command in a category or ports skeleton will _not_ fetch the distfiles of ports from another category. Instead, use `make fetch-recursive` to also fetch the distfiles for all the dependencies of a port. In rare cases, such as when an organization has a local distfiles repository, the `MASTER_SITES` variable can be used to override the download locations specified in the `Makefile`. When using, specify the alternate location: [source,shell] .... # cd /usr/ports/directory # make MASTER_SITE_OVERRIDE= \ ftp://ftp.organization.org/pub/FreeBSD/ports/distfiles/ fetch .... The `WRKDIRPREFIX` and `PREFIX` variables can override the default working and target directories. For example: [source,shell] .... # make WRKDIRPREFIX=/usr/home/example/ports install .... will compile the port in `/usr/home/example/ports` and install everything under `/usr/local`. [source,shell] .... # make PREFIX=/usr/home/example/local install .... will compile the port in `/usr/ports` and install it in `/usr/home/example/local`. And: [source,shell] .... # make WRKDIRPREFIX=../ports PREFIX=../local install .... will combine the two. These can also be set as environmental variables. Refer to the manual page for your shell for instructions on how to set an environmental variable. [[ports-removing]] === Removing Installed Ports Installed ports can be uninstalled using `pkg delete`. Examples for using this command can be found in the man:pkg-delete[8] manual page. Alternately, `make deinstall` can be run in the port\'s directory: [source,shell] .... # cd /usr/ports/sysutils/lsof # make deinstall ===> Deinstalling for sysutils/lsof ===> Deinstalling Deinstallation has been requested for the following 1 packages: lsof-4.88.d,8 The deinstallation will free 229 kB [1/1] Deleting lsof-4.88.d,8... done .... It is recommended to read the messages as the port is uninstalled. If the port has any applications that depend upon it, this information will be displayed but the uninstallation will proceed. In such cases, it may be better to reinstall the application in order to prevent broken dependencies. [[ports-upgrading]] === Upgrading Ports Over time, newer versions of software become available in the Ports Collection. This section describes how to determine which software can be upgraded and how to perform the upgrade. To determine if newer versions of installed ports are available, ensure that the latest version of the ports tree is installed, using the updating command described in <>. The following command will list the installed ports which are out of date: [source,shell] .... # pkg version -l "<" .... [IMPORTANT] ==== Before attempting an upgrade, read `/usr/ports/UPDATING` from the top of the file to the date closest to the last time ports were upgraded or the system was installed. This file describes various issues and additional steps users may encounter and need to perform when updating a port, including such things as file format changes, changes in locations of configuration files, or any incompatibilities with previous versions. Make note of any instructions which match any of the ports that need upgrading and follow these instructions when performing the upgrade. ==== [[ports-upgrading-tools]] ==== Tools to Upgrade and Manage Ports The Ports Collection contains several utilities to perform the actual upgrade. Each has its strengths and weaknesses. Historically, most installations used either Portmaster or Portupgrade. Synth is a newer alternative. [NOTE] ==== The choice of which tool is best for a particular system is up to the system administrator. It is recommended practice to back up your data before using any of these tools. ==== [[portmaster]] ==== Upgrading Ports Using Portmaster package:ports-mgmt/portmaster[] is a very small utility for upgrading installed ports. It is designed to use the tools installed with the FreeBSD base system without depending on other ports or databases. To install this utility as a port: [source,shell] .... # cd /usr/ports/ports-mgmt/portmaster # make install clean .... Portmaster defines four categories of ports: * Root port: has no dependencies and is not a dependency of any other ports. * Trunk port: has no dependencies, but other ports depend upon it. * Branch port: has dependencies and other ports depend upon it. * Leaf port: has dependencies but no other ports depend upon it. To list these categories and search for updates: [source,shell] .... # portmaster -L ===>>> Root ports (No dependencies, not depended on) ===>>> ispell-3.2.06_18 ===>>> screen-4.0.3 ===>>> New version available: screen-4.0.3_1 ===>>> tcpflow-0.21_1 ===>>> 7 root ports ... ===>>> Branch ports (Have dependencies, are depended on) ===>>> apache22-2.2.3 ===>>> New version available: apache22-2.2.8 ... ===>>> Leaf ports (Have dependencies, not depended on) ===>>> automake-1.9.6_2 ===>>> bash-3.1.17 ===>>> New version available: bash-3.2.33 ... ===>>> 32 leaf ports ===>>> 137 total installed ports ===>>> 83 have new versions available .... This command is used to upgrade all outdated ports: [source,shell] .... # portmaster -a .... [NOTE] ==== By default, Portmaster makes a backup package before deleting the existing port. If the installation of the new version is successful, Portmaster deletes the backup. Using `-b` instructs Portmaster not to automatically delete the backup. Adding `-i` starts Portmaster in interactive mode, prompting for confirmation before upgrading each port. Many other options are available. Read through the manual page for man:portmaster[8] for details regarding their usage. ==== If errors are encountered during the upgrade process, add `-f` to upgrade and rebuild all ports: [source,shell] .... # portmaster -af .... Portmaster can also be used to install new ports on the system, upgrading all dependencies before building and installing the new port. To use this function, specify the location of the port in the Ports Collection: [source,shell] .... # portmaster shells/bash .... More information about package:ports-mgmt/portmaster[] may be found in its `pkg-descr`. [[portupgrade]] ==== Upgrading Ports Using Portupgrade package:ports-mgmt/portupgrade[] is another utility that can be used to upgrade ports. It installs a suite of applications which can be used to manage ports. However, it is dependent upon Ruby. To install the port: [source,shell] .... # cd /usr/ports/ports-mgmt/portupgrade # make install clean .... Before performing an upgrade using this utility, it is recommended to scan the list of installed ports using `pkgdb -F` and to fix all the inconsistencies it reports. To upgrade all the outdated ports installed on the system, use `portupgrade -a`. Alternately, include `-i` to be asked for confirmation of every individual upgrade: [source,shell] .... # portupgrade -ai .... To upgrade only a specified application instead of all available ports, use `portupgrade _pkgname_`. It is very important to include `-R` to first upgrade all the ports required by the given application: [source,shell] .... # portupgrade -R firefox .... If `-P` is included, Portupgrade searches for available packages in the local directories listed in `PKG_PATH`. If none are available locally, it then fetches packages from a remote site. If packages can not be found locally or fetched remotely, Portupgrade will use ports. To avoid using ports entirely, specify `-PP`. This last set of options tells Portupgrade to abort if no packages are available: [source,shell] .... # portupgrade -PP gnome3 .... To just fetch the port distfiles, or packages, if `-P` is specified, without building or installing anything, use `-F`. For further information on all of the available switches, refer to the manual page for `portupgrade`. More information about package:ports-mgmt/portupgrade[] may be found in its `pkg-descr`. [[ports-disk-space]] === Ports and Disk Space Using the Ports Collection will use up disk space over time. After building and installing a port, running `make clean` within the ports skeleton will clean up the temporary `work` directory. If Portmaster is used to install a port, it will automatically remove this directory unless `-K` is specified. If Portupgrade is installed, this command will remove all `work` directories found within the local copy of the Ports Collection: [source,shell] .... # portsclean -C .... In addition, outdated source distribution files accumulate in `/usr/ports/distfiles` over time. To use Portupgrade to delete all the distfiles that are no longer referenced by any ports: [source,shell] .... # portsclean -D .... Portupgrade can remove all distfiles not referenced by any port currently installed on the system: [source,shell] .... # portsclean -DD .... If Portmaster is installed, use: [source,shell] .... # portmaster --clean-distfiles .... By default, this command is interactive and prompts the user to confirm if a distfile should be deleted. In addition to these commands, package:ports-mgmt/pkg_cutleaves[] automates the task of removing installed ports that are no longer needed. [[ports-poudriere]] == Building Packages with poudriere poudriere is a `BSD`-licensed utility for creating and testing FreeBSD packages. It uses FreeBSD jails to set up isolated compilation environments. These jails can be used to build packages for versions of FreeBSD that are different from the system on which it is installed, and also to build packages for i386 if the host is an amd64 system. Once the packages are built, they are in a layout identical to the official mirrors. These packages are usable by man:pkg[8] and other package management tools. poudriere is installed using the package:ports-mgmt/poudriere[] package or port. The installation includes a sample configuration file `/usr/local/etc/poudriere.conf.sample`. Copy this file to `/usr/local/etc/poudriere.conf`. Edit the copied file to suit the local configuration. While `ZFS` is not required on the system running poudriere, it is beneficial. When `ZFS` is used, `ZPOOL` must be specified in `/usr/local/etc/poudriere.conf` and `FREEBSD_HOST` should be set to a nearby mirror. Defining `CCACHE_DIR` enables the use of package:devel/ccache[] to cache compilation and reduce build times for frequently-compiled code. It may be convenient to put poudriere datasets in an isolated tree mounted at `/poudriere`. Defaults for the other configuration values are adequate. The number of processor cores detected is used to define how many builds will run in parallel. Supply enough virtual memory, either with `RAM` or swap space. If virtual memory runs out, the compilation jails will stop and be torn down, resulting in weird error messages. [[poudriere-initialization]] === Initialize Jails and Port Trees After configuration, initialize poudriere so that it installs a jail with the required FreeBSD tree and a ports tree. Specify a name for the jail using `-j` and the FreeBSD version with `-v`. On systems running FreeBSD/amd64, the architecture can be set with `-a` to either `i386` or `amd64`. The default is the architecture shown by `uname`. [source,shell] .... # poudriere jail -c -j 13amd64 -v 13.1-RELEASE [00:00:00] Creating 13amd64 fs at /poudriere/jails/13amd64... done [00:00:00] Using pre-distributed MANIFEST for FreeBSD 13.1-RELEASE amd64 [00:00:00] Fetching base for FreeBSD 13.1-RELEASE amd64 /poudriere/jails/13amd64/fromftp/base.txz 125 MB 4110 kBps 31s [00:00:33] Extracting base... done [00:00:54] Fetching src for FreeBSD 13.1-RELEASE amd64 /poudriere/jails/13amd64/fromftp/src.txz 154 MB 4178 kBps 38s [00:01:33] Extracting src... done [00:02:31] Fetching lib32 for FreeBSD 13.1-RELEASE amd64 /poudriere/jails/13amd64/fromftp/lib32.txz 24 MB 3969 kBps 06s [00:02:38] Extracting lib32... done [00:02:42] Cleaning up... done [00:02:42] Recording filesystem state for clean... done [00:02:42] Upgrading using ftp /etc/resolv.conf -> /poudriere/jails/13amd64/etc/resolv.conf Looking up update.FreeBSD.org mirrors... 3 mirrors found. Fetching public key from update4.freebsd.org... done. Fetching metadata signature for 13.1-RELEASE from update4.freebsd.org... done. Fetching metadata index... done. Fetching 2 metadata files... done. Inspecting system... done. Preparing to download files... done. Fetching 124 patches.....10....20....30....40....50....60....70....80....90....100....110....120.. done. Applying patches... done. Fetching 6 files... done. The following files will be added as part of updating to 13.1-RELEASE-p1: /usr/src/contrib/unbound/.github /usr/src/contrib/unbound/.github/FUNDING.yml /usr/src/contrib/unbound/contrib/drop2rpz /usr/src/contrib/unbound/contrib/unbound_portable.service.in /usr/src/contrib/unbound/services/rpz.c /usr/src/contrib/unbound/services/rpz.h /usr/src/lib/libc/tests/gen/spawnp_enoexec.sh The following files will be updated as part of updating to 13.1-RELEASE-p1: […] Installing updates...Scanning //usr/share/certs/blacklisted for certificates... Scanning //usr/share/certs/trusted for certificates... done. 13.1-RELEASE-p1 [00:04:06] Recording filesystem state for clean... done [00:04:07] Jail 13amd64 13.1-RELEASE-p1 amd64 is ready to be used .... [source,shell] .... # poudriere ports -c -p local -m git+https [00:00:00] Creating local fs at /poudriere/ports/local... done [00:00:00] Checking out the ports tree... done .... On a single computer, poudriere can build ports with multiple configurations, in multiple jails, and from different port trees. Custom configurations for these combinations are called _sets_. See the CUSTOMIZATION section of man:poudriere[8] for details after package:ports-mgmt/poudriere[] or package:ports-mgmt/poudriere-devel[] is installed. The basic configuration shown here puts a single jail-, port-, and set-specific `make.conf` in `/usr/local/etc/poudriere.d`. The filename in this example is created by combining the jail name, port name, and set name: `13amd64-local-workstation-make.conf`. The system `make.conf` and this new file are combined at build time to create the `make.conf` used by the build jail. Packages to be built are entered in `13amd64-local-workstation-pkglist` (ports with extref:{porters-handbook}flavors[FLAVORS] can be defined with @FLAVOR): [.programlisting] .... editors/emacs devel/git devel/php-composer2@php82 ports-mgmt/pkg ... .... Options and dependencies for the specified ports are configured: [source,shell] .... # poudriere options -j 13amd64 -p local -z workstation -f 13amd64-local-workstation-pkglist .... Finally, packages are built and a package repository is created: [source,shell] .... # poudriere bulk -j 13amd64 -p local -z workstation -f 13amd64-local-workstation-pkglist .... While running, pressing kbd:[Ctrl+t] displays the current state of the build. poudriere also builds files in `/poudriere/logs/bulk/jailname` that can be used with a web server to display build information. After completion, the new packages are now available for installation from the poudriere repository. For more information on using poudriere, see man:poudriere[8] and the main web site, https://github.com/freebsd/poudriere/wiki[]. === Configuring pkg Clients to Use a poudriere Repository While it is possible to use both a custom repository along side of the official repository, sometimes it is useful to disable the official repository. This is done by creating a configuration file that overrides and disables the official configuration file. Create `/usr/local/etc/pkg/repos/FreeBSD.conf` that contains the following: [.programlisting] .... FreeBSD: { enabled: no } .... Usually it is easiest to serve a poudriere repository to the client machines via HTTP. Set up a webserver to serve up the package directory, for instance: `/usr/local/poudriere/data/packages/13amd64`, where `13amd64` is the name of the build. If the URL to the package repository is: `http://pkg.example.com/13amd64`, then the repository configuration file in `/usr/local/etc/pkg/repos/custom.conf` would look like: [.programlisting] .... custom: { url: "http://pkg.example.com/13amd64", enabled: yes, } .... If exposing the package repository to the internet is not desired, the `file://` protocol can be used to point to the repository directly: [.programlisting] .... custom: { url: "file:///usr/local/poudriere/data/packages/11amd64", enabled: yes, } .... [[ports-nextsteps]] == Post-Installation Considerations Regardless of whether the software was installed from a binary package or port, most third-party applications require some level of configuration after installation. The following commands and locations can be used to help determine what was installed with the application. * Most applications install at least one default configuration file in `/usr/local/etc`. In cases where an application has a large number of configuration files, a subdirectory will be created to hold them. Often, sample configuration files are installed which end with a suffix such as `.sample`. The configuration files should be reviewed and possibly edited to meet the system's needs. To edit a sample file, first copy it without the `.sample` extension. * Applications which provide documentation will install it into `/usr/local/share/doc` and many applications also install manual pages. This documentation should be consulted before continuing. * Some applications run services which must be added to `/etc/rc.conf` before starting the application. These applications usually install a startup script in `/usr/local/etc/rc.d`. See crossref:config[configtuning-starting-services,Starting Services] for more information. + [NOTE] ==== By design, applications do not run their startup script upon installation, nor do they run their stop script upon deinstallation or upgrade. This decision is left to the individual system administrator. ==== * Users of man:csh[1] should run `rehash` to rebuild the known binary list in the shells `PATH`. * Use `pkg info` to determine which files, man pages, and binaries were installed with the application. [[ports-broken]] == Dealing with Broken Ports When a port does not build or install, try the following: . Search to see if there is a fix pending for the port in the link:https://www.FreeBSD.org/support/[Problem Report database]. If so, implementing the proposed fix may fix the issue. . Ask the maintainer of the port for help. Type `make maintainer` in the ports skeleton or read the port's `Makefile` to find the maintainer's email address. Remember to include the output leading up to the error in the email to the maintainer. + [NOTE] ==== Some ports are not maintained by an individual but instead by a group maintainer represented by a extref:{mailing-list-faq}[mailing list]. Many, but not all, of these addresses look like mailto:freebsd-listname@FreeBSD.org[freebsd-listname@FreeBSD.org]. Please take this into account when sending an email. In particular, ports maintained by mailto:ports@FreeBSD.org[ports@FreeBSD.org] are not maintained by a specific individual. Instead, any fixes and support come from the general community who subscribe to that mailing list. More volunteers are always needed! ==== + If there is no response to the email, use Bugzilla to submit a bug report using the instructions in extref:{problem-reports}[Writing FreeBSD Problem Reports]. . Fix it! The extref:{porters-handbook}[Porter's Handbook] includes detailed information on the ports infrastructure so that you can fix the occasional broken port or even submit your own! . Install the package instead of the port using the instructions in <>. diff --git a/documentation/content/en/books/handbook/ports/_index.po b/documentation/content/en/books/handbook/ports/_index.po index 5045dee568..e62c483199 100644 --- a/documentation/content/en/books/handbook/ports/_index.po +++ b/documentation/content/en/books/handbook/ports/_index.po @@ -1,2503 +1,2503 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2024-01-17 20:35-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: YAML Front Matter: description #: documentation/content/en/books/handbook/ports/_index.adoc:1 #, no-wrap msgid "FreeBSD provides two complementary technologies for installing third-party software: the FreeBSD Ports Collection, for installing from source, and packages, for installing from pre-built binaries" msgstr "" #. type: YAML Front Matter: part #: documentation/content/en/books/handbook/ports/_index.adoc:1 #, no-wrap msgid "Part I. Getting Started" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/handbook/ports/_index.adoc:1 #, no-wrap msgid "Chapter 4. Installing Applications: Packages and Ports" msgstr "" #. type: Title = #: documentation/content/en/books/handbook/ports/_index.adoc:14 #, no-wrap msgid "Installing Applications: Packages and Ports" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/ports/_index.adoc:52 #, no-wrap msgid "Synopsis" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:58 msgid "" "FreeBSD is bundled with a rich collection of system tools as part of the " "base system. In addition, FreeBSD provides two complementary technologies " "for installing third-party software: the FreeBSD Ports Collection, for " "installing from source, and packages, for installing from pre-built " "binaries. Either method may be used to install software from local media or " "from the network." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:60 msgid "After reading this chapter, you will know:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:62 msgid "The difference between binary packages and ports." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:63 msgid "How to find third-party software that has been ported to FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:64 msgid "How to manage binary packages using pkg." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:65 msgid "" "How to build third-party software from source using the Ports Collection." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:66 msgid "" "How to find the files installed with the application for post-installation " "configuration." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:67 msgid "What to do if a software installation fails." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/ports/_index.adoc:69 #, no-wrap msgid "Overview of Software Installation" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:73 msgid "" "A FreeBSD _port_ is a collection of files designed to automate the process " "of compiling an application from source code. The files that comprise a " "port contain all the necessary information to automatically download, " "extract, patch, compile, and install the application." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:75 msgid "" "If the software has not already been adapted and tested on FreeBSD, the " "source code might need editing in order for it to install and run properly." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:78 msgid "" -"However, over link:https://www.FreeBSD.org/ports/[{numports}] third-party " +"However, over link:https://ports.FreeBSD.org[{numports}] third-party " "applications have already been ported to FreeBSD. When feasible, these " "applications are made available for download as pre-compiled _packages_." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:80 msgid "" "Packages can be manipulated with the FreeBSD package management commands." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:83 msgid "" "Both packages and ports understand dependencies. If a package or port is " "used to install an application and a dependent library is not already " "installed, the library will automatically be installed first." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:86 msgid "" "A FreeBSD package contains pre-compiled copies of all the commands for an " "application, as well as any configuration files and documentation. A " "package can be manipulated with the man:pkg[8] commands, such as `pkg " "install`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:89 msgid "" "While the two technologies are similar, packages and ports each have their " "own strengths. Select the technology that meets your requirements for " "installing a particular application." msgstr "" #. type: Block title #: documentation/content/en/books/handbook/ports/_index.adoc:90 #, no-wrap msgid "Package Benefits" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:92 msgid "" "A compressed package tarball is typically smaller than the compressed " "tarball containing the source code for the application." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:93 msgid "" "Packages do not require compilation time. For large applications, such as " "Firefox, KDE Plasma, or GNOME, this can be important on a slow system." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:94 msgid "" "Packages do not require any understanding of the process involved in " "compiling software on FreeBSD." msgstr "" #. type: Block title #: documentation/content/en/books/handbook/ports/_index.adoc:95 #, no-wrap msgid "Port Benefits" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:97 msgid "" "Packages are normally compiled with conservative options because they have " "to run on the maximum number of systems. By compiling from the port, one can " "change the compilation options." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:98 msgid "" "Some applications have compile-time options relating to which features are " "installed. For example, NGINX(R) can be configured with a wide variety of " "different built-in options." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:100 msgid "" "In some cases, multiple packages will exist for the same application to " "specify certain settings. For example, NGINX(R) is available as a `nginx` " "package and a `nginx-lite` package, depending on whether or not Xorg is " "installed. Creating multiple packages rapidly becomes impossible if an " "application has more than one or two different compile-time options." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:101 msgid "" "The licensing conditions of some software forbid binary distribution. Such " "software must be distributed as source code which must be compiled by the " "end-user." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:102 msgid "" "Some people do not trust binary distributions or prefer to read through " "source code in order to look for potential problems." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:103 msgid "Source code is needed in order to apply custom patches." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:105 msgid "" "To keep track of updated ports, subscribe to the {freebsd-ports} and the " "{freebsd-ports-bugs}." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:109 msgid "" "Before installing an application, check https://vuxml.freebsd.org/[] for " "related security issues." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:111 msgid "" "To audit installed packages against known vulnerabilities, run `pkg audit -" "F`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:114 msgid "" "The remainder of this chapter explains how to use packages and ports to " "install and manage third-party software on FreeBSD." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/ports/_index.adoc:116 #, no-wrap msgid "Finding Software" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:120 msgid "" "FreeBSD's list of available applications is growing all the time. There are " "a number of ways to find software to install:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:122 msgid "" "The FreeBSD web site maintains an up-to-date searchable list of all the " -"available applications, at link:https://www.FreeBSD.org/ports/[Ports " +"available applications, at link:https://ports.FreeBSD.org[Ports " "Portal]. The ports can be searched by application name or by software " "category." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:123 msgid "" "Dan Langille maintains https://www.freshports.org/[FreshPorts] which " "provides a comprehensive search utility and also tracks changes to the " "applications in the Ports Collection. Registered users can create a " "customized watch list in order to receive an automated email when their " "watched ports are updated." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:124 msgid "" "If finding a particular application becomes challenging, try searching a " "site like https://sourceforge.net/[SourceForge] or https://github.com/" -"[GitHub] then check back at the link:https://www.FreeBSD.org/ports/[Ports " +"[GitHub] then check back at the link:https://ports.FreeBSD.org[Ports " "Portal] to see if the application has been ported." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:125 msgid "" "Search the binary package repository for an application using the man:pkg[8] " "command" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/ports/_index.adoc:127 #, no-wrap msgid "Using pkg for Binary Package Management" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:130 msgid "" "man:pkg[8] provides an interface for manipulating\tpackages: registering, " "adding, removing and upgrading packages." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:132 msgid "" "For sites wishing to only use prebuilt binary packages from the FreeBSD " "mirrors, managing packages with man:pkg[8] can be sufficient." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:134 msgid "" "However, for those sites building from source a separate <> will be needed." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:137 msgid "" "Since man:pkg[8] only works with binary packages, it is not a replacement " "for such tools. Those tools can be used to install software from both " "binary packages and the Ports Collection, while man:pkg[8] installs only " "binary packages." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:139 #, no-wrap msgid "Getting Started with pkg" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:143 msgid "" "All supported versions of FreeBSD now contain `/usr/sbin/pkg` a.k.a man:" "pkg[7]. This is a small placeholder that has just the minimum functionality " "required to install the real man:pkg[8]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:147 msgid "" "An Internet working connection is required for the bootstrap process to " "succeed." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:150 msgid "Run man:pkg[8] command line:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:154 #, no-wrap msgid "# pkg\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:157 #: documentation/content/en/books/handbook/ports/_index.adoc:242 #: documentation/content/en/books/handbook/ports/_index.adoc:274 #: documentation/content/en/books/handbook/ports/_index.adoc:309 #: documentation/content/en/books/handbook/ports/_index.adoc:336 #: documentation/content/en/books/handbook/ports/_index.adoc:381 #: documentation/content/en/books/handbook/ports/_index.adoc:436 #: documentation/content/en/books/handbook/ports/_index.adoc:463 #: documentation/content/en/books/handbook/ports/_index.adoc:493 #: documentation/content/en/books/handbook/ports/_index.adoc:518 #: documentation/content/en/books/handbook/ports/_index.adoc:536 msgid "The output should be similar to the following:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:162 #, no-wrap msgid "" "The package management tool is not yet installed on your system.\n" "Do you want to fetch and install it now? [y/N]\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:165 msgid "" "man:pkg[7] will intercept the command, and if you confirm that is your " "intention, download the man:pkg[8] tarball, install man:pkg[8] from it, " "bootstrap the local package database and then proceed to run the command you " "originally requested." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:167 msgid "" "More recent versions of man:pkg[7] understand `pkg -N` as a test to see if " "man:pkg[8] is installed without triggering the installation, and conversely, " "pkg bootstrap[-f] to install man:pkg[8] (or force it to be reinstalled) " "without performing any other actions." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:170 msgid "" "Usage information for pkg is available in the man:pkg[8] manual page or by " "running `pkg` without additional arguments. Additional pkg configuration " "options are described in man:pkg.conf[5]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:172 msgid "" "Each pkg command argument is documented in a command-specific manual page." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:174 msgid "" "To read the manual page for `pkg install`, for example, run this command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:178 #, no-wrap msgid "# pkg help install\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:183 msgid "" "The rest of this section demonstrates common binary package management tasks " "which can be performed using man:pkg[8]. Each demonstrated command provides " "many switches to customize its use. Refer to a command's help or man page " "for details and more examples." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:185 #, no-wrap msgid "Quarterly and Latest Ports Branches" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:194 msgid "" "The `Quarterly` branch provides users with a more predictable and stable " "experience for port and package installation and upgrades. This is done " "essentially by only allowing non-feature updates. Quarterly branches aim to " "receive security fixes (that may be version updates, or backports of " "commits), bug fixes and ports compliance or framework changes. The " "Quarterly branch is cut from HEAD at the beginning of every (yearly) quarter " "in January, April, July, and October. Branches are named according to the " "year (YYYY) and quarter (Q1-4) they are created in. For example, the " "quarterly branch created in January 2023, is named 2023Q1. And the `Latest` " "branch provides the latest versions of the packages to the users." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:196 msgid "" "To switch man:pkg[8] from Quarterly to Latest run the following commands:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:201 #, no-wrap msgid "" "# mkdir -p /usr/local/etc/pkg/repos\n" "# echo 'FreeBSD: { url: \"pkg+http://pkg.FreeBSD.org/${ABI}/latest\" }' > /usr/local/etc/pkg/repos/FreeBSD.conf\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:204 msgid "" "Then run this command to update the local package repositories catalogues " "for the Latest branch:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:208 #, no-wrap msgid "# pkg update -f\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:211 #, no-wrap msgid "Configure pkg" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:215 msgid "" "man:pkg.conf[5] is the system-wide configuration file used by the man:pkg[8] " "tools. The default location of this file is `/usr/local/etc/pkg.conf`." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:220 msgid "" "FreeBSD does not need to have a `pkg.conf` file. Many installations will " "work well with no `pkg.conf` at all or with an empty `pkg.conf` (other than " "comment lines)." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:223 msgid "Lines in the file beginning with a \"#\" are\tcomments and are ignored." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:226 msgid "" "The file is in UCL format. For more information on the syntax of man:" "libucl[3], please visit the link:https://github.com/vstakhov/libucl[official " "UCL website]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:228 msgid "" "The following types of options are recognized - boolean, string and list " "options." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:230 msgid "" "A boolean option is marked as enabled if one of the following values is " "specified in the configuration file - YES, TRUE and ON." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:232 #, no-wrap msgid "Searching Packages" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:235 msgid "To search a package man:pkg-search[8] can be used:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:239 #, no-wrap msgid "# pkg search nginx\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:259 #, no-wrap msgid "" "modsecurity3-nginx-1.0.3 Instruction detection and prevention engine / nginx Wrapper\n" "nginx-1.22.1_2,3 Robust and small WWW server\n" "nginx-devel-1.23.2_4 Robust and small WWW server\n" "nginx-full-1.22.1_1,3 Robust and small WWW server (full package)\n" "nginx-lite-1.22.1,3 Robust and small WWW server (lite package)\n" "nginx-naxsi-1.22.1,3 Robust and small WWW server (plus NAXSI)\n" "nginx-prometheus-exporter-0.10.0_7 Prometheus exporter for NGINX and NGINX Plus stats\n" "nginx-ultimate-bad-bot-blocker-4.2020.03.2005_1 Nginx bad bot and other things blocker\n" "nginx-vts-exporter-0.10.7_7 Server that scraps NGINX vts stats and export them via HTTP\n" "p5-Nginx-ReadBody-0.07_1 Nginx embeded perl module to read and evaluate a request body\n" "p5-Nginx-Simple-0.07_1 Perl 5 module for easy to use interface for Nginx Perl Module\n" "p5-Test-Nginx-0.30 Testing modules for Nginx C module development\n" "py39-certbot-nginx-2.0.0 NGINX plugin for Certbot\n" "rubygem-passenger-nginx-6.0.15 Modules for running Ruby on Rails and Rack applications\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:262 #, no-wrap msgid "Installing and Fetching Packages" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:267 msgid "" "To install a binary package man:pkg-install[8] can be used. This command " "uses repository data to determine which version of the software to install " "and if it has any uninstalled dependencies. For example, to install curl:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:271 #, no-wrap msgid "# pkg install curl\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:281 #, no-wrap msgid "" "Updating FreeBSD repository catalogue...\n" "FreeBSD repository is up to date.\n" "All repositories are up to date.\n" "The following 9 package(s) will be affected (of 0 checked):\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:292 #, no-wrap msgid "" "New packages to be INSTALLED:\n" " ca_root_nss: 3.83\n" " curl: 7.86.0\n" " gettext-runtime: 0.21\n" " indexinfo: 0.3.1\n" " libidn2: 2.3.3\n" " libnghttp2: 1.48.0\n" " libpsl: 0.21.1_4\n" " libssh2: 1.10.0.3\n" " libunistring: 1.0\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:294 #, no-wrap msgid "Number of packages to be installed: 9\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:297 #, no-wrap msgid "" "The process will require 11 MiB more space.\n" "3 MiB to be downloaded\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:299 #, no-wrap msgid "Proceed with this action? [y/N]\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:302 msgid "" "The new package and any additional packages that were installed as " "dependencies can be seen in the installed packages list:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:306 #, no-wrap msgid "# pkg info\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:322 #, no-wrap msgid "" "ca_root_nss-3.83 Root certificate bundle from the Mozilla Project\n" "curl-7.86.0 Command line tool and library for transferring data with URLs\n" "gettext-runtime-0.21.1 GNU gettext runtime libraries and programs\n" "indexinfo-0.3.1 Utility to regenerate the GNU info page index\n" "libidn2-2.3.3 Implementation of IDNA2008 internationalized domain names\n" "libnghttp2-1.48.0 HTTP/2.0 C Library\n" "libpsl-0.21.1_6 C library to handle the Public Suffix List\n" "libssh2-1.10.0.3 Library implementing the SSH2 protocol\n" "libunistring-1.0 Unicode string library\n" "pkg-1.18.4 Package manager\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:326 msgid "" "To fetch a package and install it later or in another place use man:pkg-" "fetch[8]. For example, to download `nginx-lite`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:330 #, no-wrap msgid "# pkg fetch -d -o /usr/home/user/packages/ nginx-lite\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:333 msgid "`-d`: used to fetch all the dependencies" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:334 msgid "`-o`: used to specify the download directory" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:343 #, no-wrap msgid "" "Updating FreeBSD repository catalogue...\n" "FreeBSD repository is up to date.\n" "All repositories are up to date.\n" "The following packages will be fetched:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:347 #, no-wrap msgid "" "New packages to be FETCHED:\n" " nginx-lite: 1.22.1,3 (342 KiB: 22.20% of the 2 MiB to download)\n" " pcre: 8.45_3 (1 MiB: 77.80% of the 2 MiB to download)\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:349 #, no-wrap msgid "Number of packages to be fetched: 2\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:352 #, no-wrap msgid "" "The process will require 2 MiB more space.\n" "2 MiB to be downloaded.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:354 #, no-wrap msgid "Proceed with fetching packages? [y/N]:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:357 msgid "" "To install the downloaded packages man:pkg-install[8] can be used as follows:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:361 #, no-wrap msgid "# cd /usr/home/user/packages/\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:366 #, no-wrap msgid "# pkg install nginx-lite-1.22.1,3.pkg\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:369 #, no-wrap msgid "Obtaining Information About Installed Packages" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:372 msgid "" "Information about the packages installed on a system can be viewed by " "running man:pkg-info[8] which, when run without any switches, will list the " "package version for either all installed packages or the specified package." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:374 msgid "For example, to see which version of pkg is installed, run:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:378 #, no-wrap msgid "# pkg info pkg\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:407 #, no-wrap msgid "" "pkg-1.19.0\n" "Name : pkg\n" "Version : 1.19.0\n" "Installed on : Sat Dec 17 11:05:28 2022 CET\n" "Origin : ports-mgmt/pkg\n" "Architecture : FreeBSD:13:amd64\n" "Prefix : /usr/local\n" "Categories : ports-mgmt\n" "Licenses : BSD2CLAUSE\n" "Maintainer : pkg@FreeBSD.org\n" "WWW : https://github.com/freebsd/pkg\n" "Comment : Package manager\n" "Options :\n" " DOCS : on\n" "Shared Libs provided:\n" " libpkg.so.4\n" "Annotations :\n" " FreeBSD_version: 1301000\n" " repo_type : binary\n" " repository : FreeBSD\n" "Flat size : 33.2MiB\n" "Description :\n" "Package management tool\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:409 #, no-wrap msgid "WWW: https://github.com/freebsd/pkg\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:412 #, no-wrap msgid "Upgrading Installed Packages" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:415 msgid "" "Installed packages can be upgraded to their latest versions using man:pkg-" "upgrade[8]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:419 #, no-wrap msgid "# pkg upgrade\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:422 msgid "" "This command will compare the installed versions with those available in the " "repository catalogue and upgrade them from the repository." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:424 #, no-wrap msgid "Auditing Installed Packages" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:429 msgid "" "Software vulnerabilities are regularly discovered in third-party " "applications. To address this, pkg includes a built-in auditing mechanism. " "To determine if there are any known vulnerabilities for the software " "installed on the system, use man:pkg-audit[8]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:433 #, no-wrap msgid "# pkg audit -F\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:448 #, no-wrap msgid "" "Fetching vuln.xml.xz: 100% 976 KiB 499.5kB/s 00:02\n" "chromium-108.0.5359.98 is vulnerable:\n" " chromium -- multiple vulnerabilities\n" " CVE: CVE-2022-4440\n" " CVE: CVE-2022-4439\n" " CVE: CVE-2022-4438\n" " CVE: CVE-2022-4437\n" " CVE: CVE-2022-4436\n" " WWW: https://vuxml.FreeBSD.org/freebsd/83eb9374-7b97-11ed-be8f-3065ec8fd3ec.html\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:451 #, no-wrap msgid "Removing Packages" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:454 msgid "" "Packages that are no longer needed can be removed with man:pkg-delete[8]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:456 msgid "For example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:460 #, no-wrap msgid "# pkg delete curl\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:468 #, no-wrap msgid "" "Checking integrity... done (0 conflicting)\n" "Deinstallation has been requested for the following 1 packages (of 0 packages in the universe):\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:471 #, no-wrap msgid "" "Installed packages to be REMOVED:\n" " curl :7.86.0\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:473 #: documentation/content/en/books/handbook/ports/_index.adoc:503 #, no-wrap msgid "Number of packages to be removed: 1\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:475 #, no-wrap msgid "The operation will free 4 MiB.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:479 #, no-wrap msgid "" "Proceed with deinstallation packages? [y/N]: y\n" "[1/1] Deinstalling curl-7.86.0...\n" "[1/1] Deleting files for curl-7.86.0: 100%\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:482 #, no-wrap msgid "Automatically Removing Unused Packages" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:486 msgid "" "Removing a package may leave behind dependencies which are no longer " "required. Unneeded packages that were installed as dependencies (leaf " "packages) can be automatically detected and removed using man:pkg-" "autoremove[8]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:490 #, no-wrap msgid "# pkg autoremove\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:498 #, no-wrap msgid "" "Checking integrity... done (0 conflicting)\n" "Deinstallation has been requested for the following 1 packages:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:501 #, no-wrap msgid "" "Installed packages to be REMOVED:\n" " ca_root_nss-3.83\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:505 #, no-wrap msgid "The operation will free 723 KiB.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:507 #, no-wrap msgid "Proceed with deinstalling packages? [y/N]:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:511 msgid "" "Packages installed as dependencies are called _automatic_ packages. Non-" "automatic packages, i.e the packages that were explicitly installed not as a " "dependency to another package, can be listed using:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:515 #, no-wrap msgid "# pkg prime-list\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:524 #, no-wrap msgid "" "nginx\n" "openvpn\n" "sudo\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:529 msgid "" "`pkg prime-list` is an alias command declared in `/usr/local/etc/pkg.conf`. " "There are many others that can be used to query the package database of the " "system. For instance, command `pkg prime-origins` can be used to get the " "origin port directory of the list mentioned above:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:533 #, no-wrap msgid "# pkg prime-origins\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:542 #, no-wrap msgid "" "www/nginx\n" "security/openvpn\n" "security/sudo\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:545 msgid "" "This list can be used to rebuild all packages installed on a system using " "build tools such as package:ports-mgmt/poudriere[] or package:ports-mgmt/" "synth[]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:547 msgid "Marking an installed package as automatic can be done using:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:551 #, no-wrap msgid "# pkg set -A 1 devel/cmake\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:554 msgid "" "Once a package is a leaf package and is marked as automatic, it gets " "selected by `pkg autoremove`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:556 msgid "Marking an installed package as _not_ automatic can be done using:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:560 #, no-wrap msgid "# pkg set -A 0 devel/cmake\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:563 #, no-wrap msgid "Removing Stale Packages" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:568 msgid "" "By default, pkg stores binary packages in a cache directory defined by " "`PKG_CACHEDIR` in man:pkg.conf[5]. Only copies of the latest installed " "packages are kept. Older versions of pkg kept all previous packages. To " "remove these outdated binary packages, run:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:572 #, no-wrap msgid "# pkg clean\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:575 msgid "The entire cache may be cleared by running:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:579 #, no-wrap msgid "# pkg clean -a\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:582 #, no-wrap msgid "Locking and Unlocking Packages" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:588 msgid "" "man:pkg-lock[8] is used to lock packages against reinstallation, " "modification or deletion. man:pkg-unlock[8] unlocks the named packages. " "Either variant only has an effect on currently installed packages. " "Consequently it is impossible to block installation of a new package by " "using this mechanism, unless such an installation implies updating a locked " "package." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:590 msgid "For example, to lock `nginx-lite`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:594 #, no-wrap msgid "# pkg lock nginx-lite\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:597 msgid "And to unlock `nginx-lite`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:601 #, no-wrap msgid "# pkg unlock nginx-lite\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:604 #, no-wrap msgid "Modifying Package Metadata" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:609 msgid "" "Software within the FreeBSD Ports Collection can undergo major version " "number changes. To address this, pkg has a built-in command to update " "package origins. This can be useful, for example, if package:lang/python3[] " "is renamed to package:lang/python311[] so that package:lang/python3[] can " "now represent version `3.11`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:611 msgid "To change the package origin for the above example, run:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:615 #, no-wrap msgid "# pkg set -o lang/python3:lang/python311\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:618 msgid "" "As another example, to update package:lang/ruby31[] to package:lang/" "ruby32[], run:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:622 #, no-wrap msgid "# pkg set -o lang/ruby31:lang/ruby32\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:628 msgid "" "When changing package origins, it is important to reinstall packages that " "are dependent on the package with the modified origin. To force a " "reinstallation of dependent packages, run:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:632 #, no-wrap msgid "# pkg install -Rf lang/ruby32\n" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/ports/_index.adoc:636 #, no-wrap msgid "Using the Ports Collection" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:640 msgid "" "The Ports Collection is a set of `Makefiles`, patches, and description " "files. Each set of these files is used to compile and install an individual " "application on FreeBSD, and is called a _port_." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:642 msgid "" "By default, the Ports Collection itself is stored as a subdirectory of `/usr/" "ports`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:649 msgid "" "Before installing and using the Ports Collection, please be aware that it is " "generally ill-advised to use the Ports Collection in conjunction with the " "binary packages provided via pkg to install software. pkg, by default, " "tracks quarterly branch-releases of the ports tree and not HEAD. " "Dependencies could be different for a port in HEAD compared to its " "counterpart in a quarterly branch release and this could result in conflicts " "between dependencies installed by pkg and those from the Ports Collection. " "If the Ports Collection and pkg must be used in conjunction, then be sure " "that your Ports Collection and pkg are on the same branch release of the " "ports tree." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:655 msgid "" "The Ports Collection contains directories for software categories. Inside " "each category are subdirectories for individual applications. Each " "application subdirectory contains a set of files that tells FreeBSD how to " "compile and install that program, called a _ports skeleton_. Each port " "skeleton includes these files and directories:" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:657 #, no-wrap msgid "*Makefile*: contains statements that specify how the application should be compiled and where its components should be installed.\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:658 #, no-wrap msgid "*distinfo*: contains the names and checksums of the files that must be downloaded to build the port.\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:659 #, no-wrap msgid "*files/*: this directory contains any patches needed for the program to compile and install on FreeBSD. This directory may also contain other files used to build the port.\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:660 #, no-wrap msgid "*pkg-descr*: provides a more detailed description of the program.\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:661 #, no-wrap msgid "*pkg-plist*: a list of all the files that will be installed by the port. It also tells the ports system which files to remove upon deinstallation.\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:664 msgid "" "Some ports include `pkg-message` or other files to handle special " "situations. For more details on these files, and on ports in general, refer " "to the extref:{porters-handbook}[FreeBSD Porter's Handbook]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:667 msgid "" "The port does not include the actual source code, also known as a " "`distfile`. The extract portion of building a port will automatically save " "the downloaded source to `/usr/ports/distfiles`." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:669 #, no-wrap msgid "Installing the Ports Collection" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:673 msgid "" "Before an application can be compiled using a port, the Ports Collection " "must first be installed. If it was not installed during the installation of " "FreeBSD, use one of the following methods to install it:" msgstr "" #. type: delimited block * 4 #: documentation/content/en/books/handbook/ports/_index.adoc:678 #, no-wrap msgid "*Procedure: Git Method*\n" msgstr "" #. type: delimited block * 4 #: documentation/content/en/books/handbook/ports/_index.adoc:682 msgid "" "If more control over the ports tree is needed or if local changes need to be " "maintained, or if running FreeBSD-CURRENT, Git can be used to obtain the " "Ports Collection. Refer to extref:{committers-guide}[the Git Primer, git-" "primer] for a detailed description of Git." msgstr "" #. type: delimited block * 4 #: documentation/content/en/books/handbook/ports/_index.adoc:684 msgid "" "Git must be installed before it can be used to check out the ports tree. If " "a copy of the ports tree is already present, install Git like this:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:689 #, no-wrap msgid "" "# cd /usr/ports/devel/git\n" "# make install clean\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:692 msgid "" "If the ports tree is not available, or pkg is being used to manage packages, " "Git can be installed as a package:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:696 #, no-wrap msgid "# pkg install git\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:699 msgid "Check out a copy of the HEAD branch of the ports tree:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:703 #, no-wrap msgid "# git clone https://git.FreeBSD.org/ports.git /usr/ports\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:706 msgid "Or, check out a copy of a quarterly branch:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:710 #, no-wrap msgid "# git clone https://git.FreeBSD.org/ports.git -b 2023Q1 /usr/ports\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:713 msgid "As needed, update `/usr/ports` after the initial Git checkout:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:717 #, no-wrap msgid "# git -C /usr/ports pull\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:720 msgid "As needed, switch `/usr/ports` to a different quarterly branch:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:724 #, no-wrap msgid "# git -C /usr/ports switch 2023Q1\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:727 #, no-wrap msgid "Installing Ports" msgstr "" #. type: delimited block * 4 #: documentation/content/en/books/handbook/ports/_index.adoc:731 msgid "" "This section provides basic instructions on using the Ports Collection to " "install or remove software. The detailed description of available `make` " "targets and environment variables is available in man:ports[7]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:739 msgid "" "Before compiling any port, be sure to update the Ports Collection as " "described in the previous section. Since the installation of any third-" "party software can introduce security vulnerabilities, it is recommended to " "first check https://vuxml.freebsd.org/[] for known security issues related " "to the port. Alternatively, run `pkg audit -F` before installing a new " "port. This command can be configured to automatically perform a security " "audit and an update of the vulnerability database during the daily security " "system check. For more information, refer to man:pkg-audit[8] and man:" "periodic[8]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:743 msgid "" "Using the Ports Collection assumes a working Internet connection. It also " "requires superuser privilege." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:746 msgid "" "To compile and install the port, change to the directory of the port to be " "installed, then type `make install` at the prompt. Messages will indicate " "the progress:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:768 #, no-wrap msgid "" "# cd /usr/ports/sysutils/lsof\n" "# make install\n" ">> lsof_4.88D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.\n" ">> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/.\n" "===> Extracting for lsof-4.88\n" "...\n" "[extraction output snipped]\n" "...\n" ">> Checksum OK for lsof_4.88D.freebsd.tar.gz.\n" "===> Patching for lsof-4.88.d,8\n" "===> Applying FreeBSD patches for lsof-4.88.d,8\n" "===> Configuring for lsof-4.88.d,8\n" "...\n" "[configure output snipped]\n" "...\n" "===> Building for lsof-4.88.d,8\n" "...\n" "[compilation output snipped]\n" "...\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:781 #, no-wrap msgid "" "===> Installing for lsof-4.88.d,8\n" "...\n" "[installation output snipped]\n" "...\n" "===> Generating temporary packing list\n" "===> Compressing manual pages for lsof-4.88.d,8\n" "===> Registering installation for lsof-4.88.d,8\n" "===> SECURITY NOTE:\n" " This port has installed the following binaries which execute with\n" " increased privileges.\n" "/usr/local/sbin/lsof\n" "#\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:785 msgid "" "Since `lsof` is a program that runs with increased privileges, a security " "warning is displayed as it is installed. Once the installation is complete, " "the prompt will be returned." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:790 msgid "" "Some shells keep a cache of the commands that are available in the " "directories listed in the `PATH` environment variable, to speed up lookup " "operations for the executable file of these commands. Users of the `tcsh` " "shell should type `rehash` so that a newly installed command can be used " "without specifying its full path. Use `hash -r` instead for the `sh` " "shell. Refer to the documentation for the shell for more information." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:793 msgid "" "During installation, a working subdirectory is created which contains all " "the temporary files used during compilation. Removing this directory saves " "disk space and minimizes the chance of problems later when upgrading to the " "newer version of the port:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:799 #, no-wrap msgid "" "# make clean\n" "===> Cleaning for lsof-88.d,8\n" "#\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:804 msgid "" "To save this extra step, instead use `make install clean` when compiling the " "port." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/ports/_index.adoc:806 #, no-wrap msgid "Customizing Ports Installation" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:814 msgid "" "Some ports provide build options which can be used to enable or disable " "application components, provide security options, or allow for other " "customizations. Examples include package:www/firefox[] and package:security/" "gpgme[]. If the port depends upon other ports which have configurable " "options, it may pause several times for user interaction as the default " "behavior is to prompt the user to select options from a menu. To avoid this " "and do all of the configuration in one batch, run `make config-recursive` " "within the port skeleton. Then, run `make install [clean]` to compile and " "install the port." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:820 msgid "" "When using `config-recursive`, the list of ports to configure are gathered " "by the `all-depends-list` target. It is recommended to run `make config-" "recursive` until all dependent ports options have been defined, and ports " "options screens no longer appear, to be certain that all dependency options " "have been configured." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:827 msgid "" "There are several ways to revisit a port's build options menu in order to " "add, remove, or change these options after a port has been built. One " "method is to `cd` into the directory containing the port and type `make " "config`. Another option is to use `make showconfig`. Another option is to " "execute `make rmconfig` which will remove all selected options and allow you " "to start over. All of these options, and others, are explained in great " "detail in man:ports[7]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:831 msgid "" "The ports system uses man:fetch[1] to download the source files, which " "supports various environment variables. The `FTP_PASSIVE_MODE`, " "`FTP_PROXY`, and `FTP_PASSWORD` variables may need to be set if the FreeBSD " "system is behind a firewall or FTP/HTTP proxy. See man:fetch[3] for the " "complete list of supported variables." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:836 msgid "" "For users who cannot be connected to the Internet all the time, `make fetch` " "can be run within `/usr/ports`, to fetch all distfiles, or within a " "category, such as `/usr/ports/net`, or within the specific port skeleton. " "Note that if a port has any dependencies, running this command in a category " "or ports skeleton will _not_ fetch the distfiles of ports from another " "category. Instead, use `make fetch-recursive` to also fetch the distfiles " "for all the dependencies of a port." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:839 msgid "" "In rare cases, such as when an organization has a local distfiles " "repository, the `MASTER_SITES` variable can be used to override the download " "locations specified in the `Makefile`. When using, specify the alternate " "location:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:845 #, no-wrap msgid "" "# cd /usr/ports/directory\n" "# make MASTER_SITE_OVERRIDE= \\\n" "ftp://ftp.organization.org/pub/FreeBSD/ports/distfiles/ fetch\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:848 msgid "" "The `WRKDIRPREFIX` and `PREFIX` variables can override the default working " "and target directories. For example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:852 #, no-wrap msgid "# make WRKDIRPREFIX=/usr/home/example/ports install\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:855 msgid "" "will compile the port in `/usr/home/example/ports` and install everything " "under `/usr/local`." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:859 #, no-wrap msgid "# make PREFIX=/usr/home/example/local install\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:862 msgid "" "will compile the port in `/usr/ports` and install it in `/usr/home/example/" "local`. And:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:866 #, no-wrap msgid "# make WRKDIRPREFIX=../ports PREFIX=../local install\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:869 msgid "will combine the two." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:872 msgid "" "These can also be set as environmental variables. Refer to the manual page " "for your shell for instructions on how to set an environmental variable." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:874 #, no-wrap msgid "Removing Installed Ports" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:878 msgid "" "Installed ports can be uninstalled using `pkg delete`. Examples for using " "this command can be found in the man:pkg-delete[8] manual page." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:880 msgid "Alternately, `make deinstall` can be run in the port\\'s directory:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:888 #, no-wrap msgid "" "# cd /usr/ports/sysutils/lsof\n" "# make deinstall\n" "===> Deinstalling for sysutils/lsof\n" "===> Deinstalling\n" "Deinstallation has been requested for the following 1 packages:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:890 #, no-wrap msgid "\tlsof-4.88.d,8\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:893 #, no-wrap msgid "" "The deinstallation will free 229 kB\n" "[1/1] Deleting lsof-4.88.d,8... done\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:898 msgid "" "It is recommended to read the messages as the port is uninstalled. If the " "port has any applications that depend upon it, this information will be " "displayed but the uninstallation will proceed. In such cases, it may be " "better to reinstall the application in order to prevent broken dependencies." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:900 #, no-wrap msgid "Upgrading Ports" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:904 msgid "" "Over time, newer versions of software become available in the Ports " "Collection. This section describes how to determine which software can be " "upgraded and how to perform the upgrade." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:908 msgid "" "To determine if newer versions of installed ports are available, ensure that " "the latest version of the ports tree is installed, using the updating " "command described in <>. The " "following command will list the installed ports which are out of date:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:912 #, no-wrap msgid "# pkg version -l \"<\"\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:919 msgid "" "Before attempting an upgrade, read `/usr/ports/UPDATING` from the top of the " "file to the date closest to the last time ports were upgraded or the system " "was installed. This file describes various issues and additional steps " "users may encounter and need to perform when updating a port, including such " "things as file format changes, changes in locations of configuration files, " "or any incompatibilities with previous versions. Make note of any " "instructions which match any of the ports that need upgrading and follow " "these instructions when performing the upgrade." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/ports/_index.adoc:922 #, no-wrap msgid "Tools to Upgrade and Manage Ports" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:926 msgid "" "The Ports Collection contains several utilities to perform the actual " "upgrade. Each has its strengths and weaknesses." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:929 msgid "" "Historically, most installations used either Portmaster or Portupgrade. " "Synth is a newer alternative." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:934 msgid "" "The choice of which tool is best for a particular system is up to the system " "administrator. It is recommended practice to back up your data before using " "any of these tools." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/ports/_index.adoc:937 #, no-wrap msgid "Upgrading Ports Using Portmaster" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:942 msgid "" "package:ports-mgmt/portmaster[] is a very small utility for upgrading " "installed ports. It is designed to use the tools installed with the FreeBSD " "base system without depending on other ports or databases. To install this " "utility as a port:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:947 #, no-wrap msgid "" "# cd /usr/ports/ports-mgmt/portmaster\n" "# make install clean\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:950 msgid "Portmaster defines four categories of ports:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:952 msgid "" "Root port: has no dependencies and is not a dependency of any other ports." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:953 msgid "Trunk port: has no dependencies, but other ports depend upon it." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:954 msgid "Branch port: has dependencies and other ports depend upon it." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:955 msgid "Leaf port: has dependencies but no other ports depend upon it." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:957 msgid "To list these categories and search for updates:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:978 #, no-wrap msgid "" "# portmaster -L\n" "===>>> Root ports (No dependencies, not depended on)\n" "===>>> ispell-3.2.06_18\n" "===>>> screen-4.0.3\n" " ===>>> New version available: screen-4.0.3_1\n" "===>>> tcpflow-0.21_1\n" "===>>> 7 root ports\n" "...\n" "===>>> Branch ports (Have dependencies, are depended on)\n" "===>>> apache22-2.2.3\n" " ===>>> New version available: apache22-2.2.8\n" "...\n" "===>>> Leaf ports (Have dependencies, not depended on)\n" "===>>> automake-1.9.6_2\n" "===>>> bash-3.1.17\n" " ===>>> New version available: bash-3.2.33\n" "...\n" "===>>> 32 leaf ports\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:981 #, no-wrap msgid "" "===>>> 137 total installed ports\n" " ===>>> 83 have new versions available\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:984 msgid "This command is used to upgrade all outdated ports:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:988 #, no-wrap msgid "# portmaster -a\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:998 msgid "" "By default, Portmaster makes a backup package before deleting the existing " "port. If the installation of the new version is successful, Portmaster " "deletes the backup. Using `-b` instructs Portmaster not to automatically " "delete the backup. Adding `-i` starts Portmaster in interactive mode, " "prompting for confirmation before upgrading each port. Many other options " "are available. Read through the manual page for man:portmaster[8] for " "details regarding their usage." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1001 msgid "" "If errors are encountered during the upgrade process, add `-f` to upgrade " "and rebuild all ports:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1005 #, no-wrap msgid "# portmaster -af\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1009 msgid "" "Portmaster can also be used to install new ports on the system, upgrading " "all dependencies before building and installing the new port. To use this " "function, specify the location of the port in the Ports Collection:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1013 #, no-wrap msgid "# portmaster shells/bash\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1016 msgid "" "More information about package:ports-mgmt/portmaster[] may be found in its " "`pkg-descr`." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/ports/_index.adoc:1018 #, no-wrap msgid "Upgrading Ports Using Portupgrade" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1023 msgid "" "package:ports-mgmt/portupgrade[] is another utility that can be used to " "upgrade ports. It installs a suite of applications which can be used to " "manage ports. However, it is dependent upon Ruby. To install the port:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1028 #, no-wrap msgid "" "# cd /usr/ports/ports-mgmt/portupgrade\n" "# make install clean\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1031 msgid "" "Before performing an upgrade using this utility, it is recommended to scan " "the list of installed ports using `pkgdb -F` and to fix all the " "inconsistencies it reports." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1034 msgid "" "To upgrade all the outdated ports installed on the system, use `portupgrade -" "a`. Alternately, include `-i` to be asked for confirmation of every " "individual upgrade:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1038 #, no-wrap msgid "# portupgrade -ai\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1042 msgid "" "To upgrade only a specified application instead of all available ports, use " "`portupgrade _pkgname_`. It is very important to include `-R` to first " "upgrade all the ports required by the given application:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1046 #, no-wrap msgid "# portupgrade -R firefox\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1053 msgid "" "If `-P` is included, Portupgrade searches for available packages in the " "local directories listed in `PKG_PATH`. If none are available locally, it " "then fetches packages from a remote site. If packages can not be found " "locally or fetched remotely, Portupgrade will use ports. To avoid using " "ports entirely, specify `-PP`. This last set of options tells Portupgrade " "to abort if no packages are available:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1057 #, no-wrap msgid "# portupgrade -PP gnome3\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1061 msgid "" "To just fetch the port distfiles, or packages, if `-P` is specified, without " "building or installing anything, use `-F`. For further information on all " "of the available switches, refer to the manual page for `portupgrade`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1063 msgid "" "More information about package:ports-mgmt/portupgrade[] may be found in its " "`pkg-descr`." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:1065 #, no-wrap msgid "Ports and Disk Space" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1071 msgid "" "Using the Ports Collection will use up disk space over time. After building " "and installing a port, running `make clean` within the ports skeleton will " "clean up the temporary `work` directory. If Portmaster is used to install a " "port, it will automatically remove this directory unless `-K` is specified. " "If Portupgrade is installed, this command will remove all `work` directories " "found within the local copy of the Ports Collection:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1075 #, no-wrap msgid "# portsclean -C\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1079 msgid "" "In addition, outdated source distribution files accumulate in `/usr/ports/" "distfiles` over time. To use Portupgrade to delete all the distfiles that " "are no longer referenced by any ports:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1083 #, no-wrap msgid "# portsclean -D\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1086 msgid "" "Portupgrade can remove all distfiles not referenced by any port currently " "installed on the system:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1090 #, no-wrap msgid "# portsclean -DD\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1093 msgid "If Portmaster is installed, use:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1097 #, no-wrap msgid "# portmaster --clean-distfiles\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1100 msgid "" "By default, this command is interactive and prompts the user to confirm if a " "distfile should be deleted." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1102 msgid "" "In addition to these commands, package:ports-mgmt/pkg_cutleaves[] automates " "the task of removing installed ports that are no longer needed." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/ports/_index.adoc:1104 #, no-wrap msgid "Building Packages with poudriere" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1111 msgid "" "poudriere is a `BSD`-licensed utility for creating and testing FreeBSD " "packages. It uses FreeBSD jails to set up isolated compilation " "environments. These jails can be used to build packages for versions of " "FreeBSD that are different from the system on which it is installed, and " "also to build packages for i386 if the host is an amd64 system. Once the " "packages are built, they are in a layout identical to the official mirrors. " "These packages are usable by man:pkg[8] and other package management tools." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1116 msgid "" "poudriere is installed using the package:ports-mgmt/poudriere[] package or " "port. The installation includes a sample configuration file `/usr/local/etc/" "poudriere.conf.sample`. Copy this file to `/usr/local/etc/poudriere.conf`. " "Edit the copied file to suit the local configuration." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1122 msgid "" "While `ZFS` is not required on the system running poudriere, it is " "beneficial. When `ZFS` is used, `ZPOOL` must be specified in `/usr/local/" "etc/poudriere.conf` and `FREEBSD_HOST` should be set to a nearby mirror. " "Defining `CCACHE_DIR` enables the use of package:devel/ccache[] to cache " "compilation and reduce build times for frequently-compiled code. It may be " "convenient to put poudriere datasets in an isolated tree mounted at `/" "poudriere`. Defaults for the other configuration values are adequate." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1126 msgid "" "The number of processor cores detected is used to define how many builds " "will run in parallel. Supply enough virtual memory, either with `RAM` or " "swap space. If virtual memory runs out, the compilation jails will stop and " "be torn down, resulting in weird error messages." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:1128 #, no-wrap msgid "Initialize Jails and Port Trees" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1134 msgid "" "After configuration, initialize poudriere so that it installs a jail with " "the required FreeBSD tree and a ports tree. Specify a name for the jail " "using `-j` and the FreeBSD version with `-v`. On systems running FreeBSD/" "amd64, the architecture can be set with `-a` to either `i386` or `amd64`. " "The default is the architecture shown by `uname`." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1181 #, no-wrap msgid "" "# poudriere jail -c -j 13amd64 -v 13.1-RELEASE\n" "[00:00:00] Creating 13amd64 fs at /poudriere/jails/13amd64... done\n" "[00:00:00] Using pre-distributed MANIFEST for FreeBSD 13.1-RELEASE amd64\n" "[00:00:00] Fetching base for FreeBSD 13.1-RELEASE amd64\n" "/poudriere/jails/13amd64/fromftp/base.txz 125 MB 4110 kBps 31s\n" "[00:00:33] Extracting base... done\n" "[00:00:54] Fetching src for FreeBSD 13.1-RELEASE amd64\n" "/poudriere/jails/13amd64/fromftp/src.txz 154 MB 4178 kBps 38s\n" "[00:01:33] Extracting src... done\n" "[00:02:31] Fetching lib32 for FreeBSD 13.1-RELEASE amd64\n" "/poudriere/jails/13amd64/fromftp/lib32.txz 24 MB 3969 kBps 06s\n" "[00:02:38] Extracting lib32... done\n" "[00:02:42] Cleaning up... done\n" "[00:02:42] Recording filesystem state for clean... done\n" "[00:02:42] Upgrading using ftp\n" "/etc/resolv.conf -> /poudriere/jails/13amd64/etc/resolv.conf\n" "Looking up update.FreeBSD.org mirrors... 3 mirrors found.\n" "Fetching public key from update4.freebsd.org... done.\n" "Fetching metadata signature for 13.1-RELEASE from update4.freebsd.org... done.\n" "Fetching metadata index... done.\n" "Fetching 2 metadata files... done.\n" "Inspecting system... done.\n" "Preparing to download files... done.\n" "Fetching 124 patches.....10....20....30....40....50....60....70....80....90....100....110....120.. done.\n" "Applying patches... done.\n" "Fetching 6 files... done.\n" "The following files will be added as part of updating to\n" "13.1-RELEASE-p1:\n" "/usr/src/contrib/unbound/.github\n" "/usr/src/contrib/unbound/.github/FUNDING.yml\n" "/usr/src/contrib/unbound/contrib/drop2rpz\n" "/usr/src/contrib/unbound/contrib/unbound_portable.service.in\n" "/usr/src/contrib/unbound/services/rpz.c\n" "/usr/src/contrib/unbound/services/rpz.h\n" "/usr/src/lib/libc/tests/gen/spawnp_enoexec.sh\n" "The following files will be updated as part of updating to\n" "13.1-RELEASE-p1:\n" "[…]\n" "Installing updates...Scanning //usr/share/certs/blacklisted for certificates...\n" "Scanning //usr/share/certs/trusted for certificates...\n" " done.\n" "13.1-RELEASE-p1\n" "[00:04:06] Recording filesystem state for clean... done\n" "[00:04:07] Jail 13amd64 13.1-RELEASE-p1 amd64 is ready to be used\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1188 #, no-wrap msgid "" "# poudriere ports -c -p local -m git+https\n" "[00:00:00] Creating local fs at /poudriere/ports/local... done\n" "[00:00:00] Checking out the ports tree... done\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1193 msgid "" "On a single computer, poudriere can build ports with multiple " "configurations, in multiple jails, and from different port trees. Custom " "configurations for these combinations are called _sets_. See the " "CUSTOMIZATION section of man:poudriere[8] for details after package:ports-" "mgmt/poudriere[] or package:ports-mgmt/poudriere-devel[] is installed." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1197 msgid "" "The basic configuration shown here puts a single jail-, port-, and set-" "specific `make.conf` in `/usr/local/etc/poudriere.d`. The filename in this " "example is created by combining the jail name, port name, and set name: " "`13amd64-local-workstation-make.conf`. The system `make.conf` and this new " "file are combined at build time to create the `make.conf` used by the build " "jail." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1199 msgid "" "Packages to be built are entered in `13amd64-local-workstation-pkglist` " "(ports with extref:{porters-handbook}flavors[FLAVORS] can be defined with " "@FLAVOR):" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1207 #, no-wrap msgid "" "editors/emacs\n" "devel/git\n" "devel/php-composer2@php82\n" "ports-mgmt/pkg\n" "...\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1210 msgid "Options and dependencies for the specified ports are configured:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1214 #, no-wrap msgid "# poudriere options -j 13amd64 -p local -z workstation -f 13amd64-local-workstation-pkglist\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1217 msgid "Finally, packages are built and a package repository is created:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1221 #, no-wrap msgid "# poudriere bulk -j 13amd64 -p local -z workstation -f 13amd64-local-workstation-pkglist\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1225 msgid "" "While running, pressing kbd:[Ctrl+t] displays the current state of the " "build. poudriere also builds files in `/poudriere/logs/bulk/jailname` that " "can be used with a web server to display build information." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1227 msgid "" "After completion, the new packages are now available for installation from " "the poudriere repository." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1229 msgid "" "For more information on using poudriere, see man:poudriere[8] and the main " "web site, https://github.com/freebsd/poudriere/wiki[]." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/ports/_index.adoc:1230 #, no-wrap msgid "Configuring pkg Clients to Use a poudriere Repository" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1235 msgid "" "While it is possible to use both a custom repository along side of the " "official repository, sometimes it is useful to disable the official " "repository. This is done by creating a configuration file that overrides " "and disables the official configuration file. Create `/usr/local/etc/pkg/" "repos/FreeBSD.conf` that contains the following:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1241 #, no-wrap msgid "" "FreeBSD: {\n" "\tenabled: no\n" "}\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1245 msgid "" "Usually it is easiest to serve a poudriere repository to the client machines " "via HTTP. Set up a webserver to serve up the package directory, for " "instance: `/usr/local/poudriere/data/packages/13amd64`, where `13amd64` is " "the name of the build." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1248 msgid "" "If the URL to the package repository is: `http://pkg.example.com/13amd64`, " "then the repository configuration file in `/usr/local/etc/pkg/repos/custom." "conf` would look like:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1255 #, no-wrap msgid "" "custom: {\n" "\turl: \"http://pkg.example.com/13amd64\",\n" "\tenabled: yes,\n" "}\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1258 msgid "" "If exposing the package repository to the internet is not desired, the " "`file://` protocol can be used to point to the repository directly:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1265 #, no-wrap msgid "" "custom: {\n" "\turl: \"file:///usr/local/poudriere/data/packages/11amd64\",\n" "\tenabled: yes,\n" "}\n" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/ports/_index.adoc:1268 #, no-wrap msgid "Post-Installation Considerations" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1272 msgid "" "Regardless of whether the software was installed from a binary package or " "port, most third-party applications require some level of configuration " "after installation. The following commands and locations can be used to " "help determine what was installed with the application." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1274 msgid "" "Most applications install at least one default configuration file in `/usr/" "local/etc`. In cases where an application has a large number of " "configuration files, a subdirectory will be created to hold them. Often, " "sample configuration files are installed which end with a suffix such as `." "sample`. The configuration files should be reviewed and possibly edited to " "meet the system's needs. To edit a sample file, first copy it without the `." "sample` extension." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1275 msgid "" "Applications which provide documentation will install it into `/usr/local/" "share/doc` and many applications also install manual pages. This " "documentation should be consulted before continuing." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1276 msgid "" "Some applications run services which must be added to `/etc/rc.conf` before " "starting the application. These applications usually install a startup " "script in `/usr/local/etc/rc.d`. See crossref:config[configtuning-starting-" "services,Starting Services] for more information." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1281 msgid "" "By design, applications do not run their startup script upon installation, " "nor do they run their stop script upon deinstallation or upgrade. This " "decision is left to the individual system administrator." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1284 msgid "" "Users of man:csh[1] should run `rehash` to rebuild the known binary list in " "the shells `PATH`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1285 msgid "" "Use `pkg info` to determine which files, man pages, and binaries were " "installed with the application." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/ports/_index.adoc:1287 #, no-wrap msgid "Dealing with Broken Ports" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1290 msgid "When a port does not build or install, try the following:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1292 msgid "" "Search to see if there is a fix pending for the port in the link:https://www." "FreeBSD.org/support/[Problem Report database]. If so, implementing the " "proposed fix may fix the issue." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1293 msgid "" "Ask the maintainer of the port for help. Type `make maintainer` in the ports " "skeleton or read the port's `Makefile` to find the maintainer's email " "address. Remember to include the output leading up to the error in the email " "to the maintainer." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1299 msgid "" "Some ports are not maintained by an individual but instead by a group " "maintainer represented by a extref:{mailing-list-faq}[mailing list]. Many, " "but not all, of these addresses look like mailto:freebsd-listname@FreeBSD." "org[freebsd-listname@FreeBSD.org]. Please take this into account when " "sending an email." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/ports/_index.adoc:1302 msgid "" "In particular, ports maintained by mailto:ports@FreeBSD.org[ports@FreeBSD." "org] are not maintained by a specific individual. Instead, any fixes and " "support come from the general community who subscribe to that mailing list. " "More volunteers are always needed!" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1305 msgid "" "If there is no response to the email, use Bugzilla to submit a bug report " "using the instructions in extref:{problem-reports}[Writing FreeBSD Problem " "Reports]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1306 msgid "" "Fix it! The extref:{porters-handbook}[Porter's Handbook] includes detailed " "information on the ports infrastructure so that you can fix the occasional " "broken port or even submit your own!" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/ports/_index.adoc:1306 msgid "" "Install the package instead of the port using the instructions in <>." msgstr "" diff --git a/documentation/content/en/books/porters-handbook/special/_index.adoc b/documentation/content/en/books/porters-handbook/special/_index.adoc index c30e8c058e..cbc1ee4cf6 100644 --- a/documentation/content/en/books/porters-handbook/special/_index.adoc +++ b/documentation/content/en/books/porters-handbook/special/_index.adoc @@ -1,5034 +1,5034 @@ --- title: Chapter 6. Special Considerations prev: books/porters-handbook/makefiles next: books/porters-handbook/flavors 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/special/" --- [[special]] = Special Considerations :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 6 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] 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 [.filename]#bsd.port.mk# expects ports to work with a "stage directory". This means that a port must not install files directly to the regular destination directories (that is, under `PREFIX`, for example) but instead into a separate directory from which the package is then built. In many cases, this does not require root privileges, making it possible to build packages as an unprivileged user. With staging, the port is built and installed into the stage directory, `STAGEDIR`. A package is created from the stage directory and then installed on the system. Automake tools refer to this concept as `DESTDIR`, but in FreeBSD, `DESTDIR` has a different meaning (see crossref:testing[porting-prefix,`PREFIX` and `DESTDIR`]). [NOTE] ==== No port _really_ needs to be root. It can mostly be avoided by using crossref:uses[uses-uidfix,`USES=uidfix`]. If the port still runs commands like man:chown[8], man:chgrp[1], or forces owner or group with man:install[1] then use crossref:uses[uses-fakeroot,`USES=fakeroot`] to fake those calls. Some patching of the port's [.filename]#Makefiles# will be needed. ==== Meta ports, or ports that do not install files themselves but only depend on other ports, must avoid needlessly extracting the man:mtree[8] to the stage directory. This is the basic directory layout of the package, and these empty directories will be seen as orphans. To prevent man:mtree[8] extraction, add this line: [.programlisting] .... NO_MTREE= yes .... [TIP] ==== Metaports should use <>. 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`, `DOCSDIR`, and so on. Directories should be created as part of the `post-install` target. Avoid using absolute paths whenever possible. [TIP] ==== Ports that install kernel modules must prepend `STAGEDIR` to their destination, by default [.filename]#/boot/modules#. ==== [[staging-symlink]] === Handling Symbolic Links When creating a symbolic link, relative ones are strongly recommended. Use `${RLN}` to create relative symbolic links. It uses man:install[1] under the hood to automatically figure out the relative link to create. [[staging-ex1]] .Create Relative Symbolic Links Automatically [example] ==== `${RLN}` uses man:install[1]'s relative symbolic feature which frees the porter of computing the relative path. [.programlisting] .... ${RLN} ${STAGEDIR}${PREFIX}/lib/libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so ${RLN} ${STAGEDIR}${PREFIX}/libexec/foo/bar ${STAGEDIR}${PREFIX}/bin/bar ${RLN} ${STAGEDIR}/var/cache/foo ${STAGEDIR}${PREFIX}/share/foo .... Will generate: [source,shell] .... % ls -lF ${STAGEDIR}${PREFIX}/lib lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 libfoo.so@ -> libfoo.so.42 -rwxr-xr-x 1 nobody nobody 15 Aug 3 11:24 libfoo.so.42* % ls -lF ${STAGEDIR}${PREFIX}/bin lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 bar@ -> ../libexec/foo/bar % ls -lF ${STAGEDIRDIR}${PREFIX}/share lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 foo@ -> ../../../var/cache/foo .... ==== [[bundled-libs]] == Bundled Libraries This section explains why bundled dependencies are considered bad and what to do about them. [[bundled-libs-why-bad]] === Why Bundled Libraries Are Bad Some software requires the porter to locate third-party libraries and add the required dependencies to the port. 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 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. One reason could be that the author is not aware of the problem. This means that the porter must fix them, or upgrade to a non-vulnerable version, and send a patch to the author. This all takes time, which results in software being vulnerable longer than necessary. This in turn makes it harder to coordinate a fix without unnecessarily leaking information about the vulnerability. Bugs:: This problem is similar to the problem with security in the last paragraph, but generally less severe. Forking:: It is easier for the author to fork the upstream library once it is bundled. While convenient on first sight, it means that the code diverges from upstream making it harder to address security or other problems with the software. A reason for this is that patching becomes harder. + Another problem of forking is that because code diverges from upstream, bugs get solved over and over again instead of just once at a central location. This defeats the idea of open source software in the first place. Symbol collision:: When a library is installed on the system, it might collide with the bundled version. This can cause immediate errors at compile or link time. It can also cause errors when running the program which might be harder to track down. The latter problem could be caused because the versions of the two libraries are incompatible. Licensing:: When bundling projects from different sources, license issues can arise more easily, especially when licenses are incompatible. Waste of resources:: Bundled libraries waste resources on several levels. It takes longer to build the actual application, especially if these libraries are already present on the system. At run-time, they can take up unnecessary memory when the system-wide library is already loaded by one program and the bundled library is loaded by another program. Waste of effort:: When a library needs patches for FreeBSD, these patches have to be duplicated again in the bundled library. This wastes developer time because the patches might not apply cleanly. It can also be hard to notice that these patches are required in the first place. [[bundled-libs-practices]] === What to do About Bundled Libraries Whenever possible, use the unbundled version of the library by adding a `LIB_DEPENDS` to the port. If such a port does not exist yet, consider creating it. Only use bundled libraries if the upstream has a good track record on security and using unbundled versions leads to overly complex patches. [NOTE] ==== In some very special cases, for example emulators, like Wine, a port has to bundle libraries, because they are in a different architecture, or they have been modified to fit the software's use. In that case, those libraries should not be exposed to other ports for linking. Add `BUNDLE_LIBS=yes` to the port's [.filename]#Makefile#. This will tell man:pkg[8] to not compute provided libraries. Always ask the {portmgr} before adding this to a port. ==== [[porting-shlibs]] == Shared Libraries If the port installs one or more shared libraries, define a `USE_LDCONFIG` make variable, which will instruct a [.filename]#bsd.port.mk# to run `${LDCONFIG} -m` on the directory where the new library is installed (usually [.filename]#PREFIX/lib#) during `post-install` target to register it into the shared library cache. This variable, when defined, will also facilitate addition of an appropriate `@exec /sbin/ldconfig -m` and `@unexec /sbin/ldconfig -R` pair into [.filename]#pkg-plist#, so that a user who installed the package can start using the shared library immediately and de-installation will not cause the system to still believe the library is there. [.programlisting] .... USE_LDCONFIG= yes .... The default directory can be overridden by setting `USE_LDCONFIG` to a list of directories into which shared libraries are to be installed. For example, if the port installs shared libraries into [.filename]#PREFIX/lib/foo# and [.filename]#PREFIX/lib/bar# use this in [.filename]#Makefile#: [.programlisting] .... USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar .... Please double-check, often this is not necessary at all or can be avoided through `-rpath` or setting `LD_RUN_PATH` during linking (see package:lang/mosml[] for an example), or through a shell-wrapper which sets `LD_LIBRARY_PATH` before invoking the binary, like package:www/seamonkey[] does. When installing 32-bit libraries on a 64-bit system, use `USE_LDCONFIG32` instead. If the software uses <>, and specifically `libtool`, add crossref:uses[uses-libtool,`USES=libtool`]. When the major library version number increments in the update to the new port version, all other ports that link to the affected library must have their `PORTREVISION` incremented, to force recompilation with the new library version. [[porting-restrictions]] == Ports with Distribution Restrictions or Legal Concerns Licenses vary, and some of them place restrictions on how the application can be packaged, whether it can be sold for profit, and so on. [IMPORTANT] ==== It is the responsibility of a porter to read the licensing terms of the software and make sure that the FreeBSD project will not be held accountable for violating them by redistributing the source or compiled binaries either via FTP/HTTP or CD-ROM. If in doubt, please contact the {freebsd-ports}. ==== In situations like this, the variables described in the next sections can be set. [[porting-restrictions-no_package]] === `NO_PACKAGE` This variable indicates that we may not generate a binary package of the application. For instance, the license may disallow binary redistribution, or it may prohibit distribution of packages created from patched sources. However, the port's `DISTFILES` may be freely mirrored on FTP/HTTP. They may also be distributed on a CD-ROM (or similar media) unless `NO_CDROM` is set as well. If the binary package is not generally useful, and the application must always be compiled from the source code, use `NO_PACKAGE`. For example, if the application has configuration information that is site specific hard coded into it at compile time, set `NO_PACKAGE`. Set `NO_PACKAGE` to a string describing the reason why the package cannot be generated. [[porting-restrictions-no_cdrom]] === `NO_CDROM` This variable alone indicates that, although we are allowed to generate binary packages, we may put neither those packages nor the port's `DISTFILES` onto a CD-ROM (or similar media) for resale. However, the binary packages and the port's `DISTFILES` will still be available via FTP/HTTP. If this variable is set along with `NO_PACKAGE`, then only the port's `DISTFILES` will be available, and only via FTP/HTTP. Set `NO_CDROM` to a string describing the reason why the port cannot be redistributed on CD-ROM. For instance, use this if the port's license is for "non-commercial" use only. [[porting-restrictions-nofetchfiles]] === `NOFETCHFILES` Files defined in `NOFETCHFILES` are not fetchable from any of `MASTER_SITES`. An example of such a file is when the file is supplied on CD-ROM by the vendor. Tools which check for the availability of these files on `MASTER_SITES` have to ignore these files and not report about them. [[porting-restrictions-restricted]] === `RESTRICTED` Set this variable alone if the application's license permits neither mirroring the application's `DISTFILES` nor distributing the binary package in any way. Do not set `NO_CDROM` or `NO_PACKAGE` along with `RESTRICTED`, since the latter variable implies the former ones. Set `RESTRICTED` to a string describing the reason why the port cannot be redistributed. Typically, this indicates that the port contains proprietary software and that the user will need to manually download the `DISTFILES`, possibly after registering for the software or agreeing to accept the terms of an EULA. [[porting-restrictions-restricted_files]] === `RESTRICTED_FILES` When `RESTRICTED` or `NO_CDROM` is set, this variable defaults to `${DISTFILES} ${PATCHFILES}`, otherwise it is empty. If only some of the distribution files are restricted, then set this variable to list them. [[porting-restrictions-legal_text]] === `LEGAL_TEXT` If the port has legal concerns not addressed by the above variables, set `LEGAL_TEXT` to a string explaining the concern. For example, if special permission was obtained for FreeBSD to redistribute the binary, this variable must indicate so. [[porting-restrictions-legal]] === [.filename]#/usr/ports/LEGAL# and `LEGAL` A port which sets any of the above variables must also be added to [.filename]#/usr/ports/LEGAL#. The first column is a glob which matches the restricted distfiles. The second column is the port's origin. The third column is the output of `make -VLEGAL`. [[porting-restrictions-examples]] === Examples The preferred way to state "the distfiles for this port must be fetched manually" is as follows: [.programlisting] .... .if !exists(${DISTDIR}/${DISTNAME}${EXTRACT_SUFX}) IGNORE= may not be redistributed because of licensing reasons. Please visit some-website to accept their license and download ${DISTFILES} into ${DISTDIR} .endif .... This both informs the user, and sets the proper metadata on the user's machine for use by automated programs. Note that this stanza must be preceded by an inclusion of [.filename]#bsd.port.pre.mk#. [[building]] == Building Mechanisms [[parallel-builds]] === Building Ports in Parallel The FreeBSD ports framework supports parallel building using multiple `make` sub-processes, which allows SMP systems to utilize all of their available CPU power, allowing port builds to be faster and more effective. This is achieved by passing `-jX` flag to man:make[1] running on vendor code. This is the default build behavior of ports. Unfortunately, not all ports handle parallel building well and it may be required to explicitly disable this feature by adding the `MAKE_JOBS_UNSAFE=yes` variable. It is used when a port is known to be broken with `-jX` due to race conditions causing intermittent build failures. [IMPORTANT] ==== When setting `MAKE_JOBS_UNSAFE`, it is very important to explain either with a comment in the [.filename]#Makefile#, or at least in the commit message, _why_ the port does not build when enabling. Otherwise, it is almost impossible to either fix the problem, or test if it has been fixed when committing an update at a later date. ==== [[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`. If the port uses GNU make, add `gmake` to `USES`. `MAKE_CMD` can be used to reference the specific command configured by the `USES` setting in the port's [.filename]#Makefile#. Only use `MAKE_CMD` within the application [.filename]##Makefile##s in `WRKSRC` to call the `make` implementation expected by the ported software. If the port is an X application that uses imake to create [.filename]##Makefile##s from [.filename]##Imakefile##s, set `USES= imake`. See the crossref:uses[uses-imake,`USES=imake`] section of crossref:uses[uses,Using `USES` Macros] for more details. If the port's source [.filename]#Makefile# has something other than `all` as the main build target, set `ALL_TARGET` accordingly. The same goes for `install` and `INSTALL_TARGET`. [[using-configure]] === `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=${PREFIX}/man --build=${CONFIGURE_TARGET}`), set those extra arguments in `CONFIGURE_ARGS`. Extra environment variables can be passed using `CONFIGURE_ENV`. [[using-configure-variables]] .Variables for Ports That Use `configure` [cols="1,1", frame="none", options="header"] |=== | Variable | Means |`GNU_CONFIGURE` |The port uses `configure` script to prepare build. |`HAS_CONFIGURE` |Same as `GNU_CONFIGURE`, except default configure target is not added to `CONFIGURE_ARGS`. |`CONFIGURE_ARGS` |Additional arguments passed to `configure` script. |`CONFIGURE_ENV` |Additional environment variables to be set for `configure` script run. |`CONFIGURE_TARGET` |Override default configure target. Default value is `${MACHINE_ARCH}-portbld-freebsd${OSREL}`. |=== [[using-cmake]] === Using `cmake` For ports that use CMake, define `USES= cmake`. [[using-cmake-variables]] .Variables for Ports That Use `cmake` [cols="1,1", frame="none", options="header"] |=== | Variable | Means |`CMAKE_ARGS` |Port specific CMake flags to be passed to the `cmake` binary. |`CMAKE_ON` |For each entry in `CMAKE_ON`, an enabled boolean value is added to `CMAKE_ARGS`. See <>. |`CMAKE_OFF` |For each entry in `CMAKE_OFF`, a disabled boolean value is added to `CMAKE_ARGS`. See <>. |`CMAKE_BUILD_TYPE` |Type of build (CMake predefined build profiles). Default is `Release`, or `Debug` if `WITH_DEBUG` is set. |`CMAKE_SOURCE_PATH` |Path to the source directory. Default is `${WRKSRC}`. |`CONFIGURE_ENV` |Additional environment variables to be set for the `cmake` binary. |=== [[using-cmake-user-variables]] .Variables the Users Can Define for `cmake` Builds [cols="1,1", frame="none", options="header"] |=== | Variable | Means |`CMAKE_NOCOLOR` |Disables color build output. Default not set, unless `BATCH` or `PACKAGE_BUILDING` are set. |=== CMake supports these build profiles: `Debug`, `Release`, `RelWithDebInfo` and `MinSizeRel`. `Debug` and `Release` profiles respect system `\*FLAGS`, `RelWithDebInfo` and `MinSizeRel` will set `CFLAGS` to `-O2 -g` and `-Os -DNDEBUG` correspondingly. The lower-cased value of `CMAKE_BUILD_TYPE` is exported to `PLIST_SUB` and must be used if the port installs [.filename]#*.cmake# depending on the build type (see package:devel/kf5-kcrash[] for an example). Please note that some projects may define their own build profiles and/or force particular build type by setting `CMAKE_BUILD_TYPE` in [.filename]#CMakeLists.txt#. To make a port for such a project respect `CFLAGS` and `WITH_DEBUG`, the `CMAKE_BUILD_TYPE` definitions must be removed from those files. Most CMake-based projects support an out-of-source method of building. The out-of-source build for a port is the default setting. An in-source build can be requested by using the `:insource` suffix. With out-of-source builds, `CONFIGURE_WRKSRC`, `BUILD_WRKSRC` and `INSTALL_WRKSRC` will be set to `${WRKDIR}/.build` and this directory will be used to keep all files generated during configuration and build stages, leaving the source directory intact. [[using-cmake-example]] .`USES= cmake` Example [example] ==== This snippet demonstrates the use of CMake for a port. `CMAKE_SOURCE_PATH` is not usually required, but can be set when the sources are not located in the top directory, or if only a subset of the project is intended to be built by the port. [.programlisting] .... USES= cmake CMAKE_SOURCE_PATH= ${WRKSRC}/subproject .... ==== [[using-cmake-example2]] .`CMAKE_ON` and `CMAKE_OFF` [example] ==== When adding boolean values to `CMAKE_ARGS`, it is easier to use the `CMAKE_ON` and `CMAKE_OFF` variables instead. This: [.programlisting] .... CMAKE_ON= VAR1 VAR2 CMAKE_OFF= VAR3 .... Is equivalent to: [.programlisting] .... CMAKE_ARGS= -DVAR1:BOOL=TRUE -DVAR2:BOOL=TRUE -DVAR3:BOOL=FALSE .... [IMPORTANT] ====== This is only for the default values off `CMAKE_ARGS`. The helpers described in crossref:makefiles[options-cmake_bool,`OPT_CMAKE_BOOL` and `OPT_CMAKE_BOOL_OFF`] use the same semantics, but for optional values. ====== ==== [[using-scons]] === Using `scons` If the port uses SCons, define `USES=scons`. To make third party [.filename]#SConstruct# respect everything that is passed to SCons in the environment (that is, most importantly, `CC/CXX/CFLAGS/CXXFLAGS`), patch [.filename]#SConstruct# so build `Environment` is constructed like this: [.programlisting] .... env = Environment(**ARGUMENTS) .... It may be then modified with `env.Append` and `env.Replace`. [[using-cargo]] === Building Rust Applications with `cargo` For ports that use Cargo, define `USES=cargo`. [[using-cargo-user-variables]] .Variables the Users Can Define for `cargo` Builds [cols="1,1,1", frame="none", options="header"] |=== | Variable | Default | Description |`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` | |List of application features to build (space separated list). To deactivate all default features add the special token `--no-default-features` to `CARGO_FEATURES`. Manually passing it to `CARGO_BUILD_ARGS`, `CARGO_INSTALL_ARGS`, and `CARGO_TEST_ARGS` is not needed. |`CARGO_CARGOTOML` |`${WRKSRC}/Cargo.toml` |The path to the [.filename]#Cargo.toml# to use. |`CARGO_CARGOLOCK` |`${WRKSRC}/Cargo.lock` |The path to the [.filename]#Cargo.lock# to use for `make cargo-crates`. It is possible to specify more than one lock file when necessary. |`CARGO_ENV` | |A list of environment variables to pass to Cargo similar to `MAKE_ENV`. |`RUSTFLAGS` | |Flags to pass to the Rust compiler. |`CARGO_CONFIGURE` |`yes` |Use the default `do-configure`. |`CARGO_UPDATE_ARGS` | |Extra arguments to pass to Cargo during the configure phase. Valid arguments can be looked up with `cargo update --help`. |`CARGO_BUILDDEP` |`yes` |Add a build dependency on package:lang/rust[]. |`CARGO_CARGO_BIN` |`${LOCALBASE}/bin/cargo` |Location of the `cargo` binary. |`CARGO_BUILD` |`yes` |Use the default `do-build`. |`CARGO_BUILD_ARGS` | |Extra arguments to pass to Cargo during the build phase. Valid arguments can be looked up with `cargo build --help`. |`CARGO_INSTALL` |`yes` |Use the default `do-install`. |`CARGO_INSTALL_ARGS` | |Extra arguments to pass to Cargo during the install phase. Valid arguments can be looked up with `cargo install --help`. |`CARGO_INSTALL_PATH` |`.` |Path to the crate to install. This is passed to `cargo install` via its `--path` argument. When multiple paths are specified `cargo install` is run multiple times. |`CARGO_TEST` |`yes` |Use the default `do-test`. |`CARGO_TEST_ARGS` | |Extra arguments to pass to Cargo during the test phase. Valid arguments can be looked up with `cargo test --help`. |`CARGO_TARGET_DIR` |`${WRKDIR}/target` |Location of the cargo output directory. |`CARGO_DIST_SUBDIR` |[.filename]#rust/crates# |Directory relative to `DISTDIR` where the crate distribution files will be stored. |`CARGO_VENDOR_DIR` |`${WRKSRC}/cargo-crates` |Location of the vendor directory where all crates will be extracted to. Try to keep this under `PATCH_WRKSRC`, so that patches can be applied easily. |`CARGO_USE_GITHUB` |`no` |Enable fetching of crates locked to specific Git commits on GitHub via `GH_TUPLE`. This will try to patch all [.filename]#Cargo.toml# under `WRKDIR` to point to the offline sources instead of fetching them from a Git repository during the build. |`CARGO_USE_GITLAB` |`no` |Same as `CARGO_USE_GITHUB` but for GitLab instances and `GL_TUPLE`. |=== [[cargo-ex1]] .Creating a Port for a Simple Rust Application [example] ==== Creating a Cargo based port is a three stage process. First we need to provide a ports template that fetches the application distribution file: [.programlisting] .... PORTNAME= tokei DISTVERSIONPREFIX= v DISTVERSION= 7.0.2 CATEGORIES= devel MAINTAINER= tobik@FreeBSD.org COMMENT= Display statistics about your code WWW= https://github.com/XAMPPRocky/tokei/ USES= cargo USE_GITHUB= yes GH_ACCOUNT= Aaronepower .include .... Generate an initial [.filename]#distinfo#: [source,shell] .... % make makesum => Aaronepower-tokei-v7.0.2_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://codeload.github.com/Aaronepower/tokei/tar.gz/v7.0.2?dummy=/Aaronepower-tokei-v7.0.2_GH0.tar.gz fetch: https://codeload.github.com/Aaronepower/tokei/tar.gz/v7.0.2?dummy=/Aaronepower-tokei-v7.0.2_GH0.tar.gz: size of remote file is not known Aaronepower-tokei-v7.0.2_GH0.tar.gz 45 kB 239 kBps 00m00s .... Now the distribution file is ready to use and we can go ahead and extract crate dependencies from the bundled [.filename]#Cargo.lock#: [source,shell] .... % make cargo-crates CARGO_CRATES= aho-corasick-0.6.4 \ ansi_term-0.11.0 \ arrayvec-0.4.7 \ atty-0.2.9 \ bitflags-1.0.1 \ byteorder-1.2.2 \ [...] .... The output of this command needs to be pasted directly into the Makefile: [.programlisting] .... PORTNAME= tokei DISTVERSIONPREFIX= v DISTVERSION= 7.0.2 CATEGORIES= devel MAINTAINER= tobik@FreeBSD.org COMMENT= Display statistics about your code WWW= https://github.com/XAMPPRocky/tokei/ USES= cargo USE_GITHUB= yes GH_ACCOUNT= Aaronepower CARGO_CRATES= aho-corasick-0.6.4 \ ansi_term-0.11.0 \ arrayvec-0.4.7 \ atty-0.2.9 \ bitflags-1.0.1 \ byteorder-1.2.2 \ [...] .include .... [.filename]#distinfo# needs to be regenerated to contain all the crate distribution files: [source,shell] .... % make makesum => rust/crates/aho-corasick-0.6.4.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://crates.io/api/v1/crates/aho-corasick/0.6.4/download?dummy=/rust/crates/aho-corasick-0.6.4.tar.gz rust/crates/aho-corasick-0.6.4.tar.gz 100% of 24 kB 6139 kBps 00m00s => rust/crates/ansi_term-0.11.0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://crates.io/api/v1/crates/ansi_term/0.11.0/download?dummy=/rust/crates/ansi_term-0.11.0.tar.gz rust/crates/ansi_term-0.11.0.tar.gz 100% of 16 kB 21 MBps 00m00s => rust/crates/arrayvec-0.4.7.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://crates.io/api/v1/crates/arrayvec/0.4.7/download?dummy=/rust/crates/arrayvec-0.4.7.tar.gz rust/crates/arrayvec-0.4.7.tar.gz 100% of 22 kB 3237 kBps 00m00s => rust/crates/atty-0.2.9.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://crates.io/api/v1/crates/atty/0.2.9/download?dummy=/rust/crates/atty-0.2.9.tar.gz rust/crates/atty-0.2.9.tar.gz 100% of 5898 B 81 MBps 00m00s => rust/crates/bitflags-1.0.1.tar.gz doesn't seem to exist in /usr/ports/distfiles/. [...] .... 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. ==== [[cargo-ex2]] .Enabling Additional Application Features [example] ==== Some applications define additional features in their [.filename]#Cargo.toml#. They can be compiled in by setting `CARGO_FEATURES` in the port. Here we enable Tokei's `json` and `yaml` features: [.programlisting] .... CARGO_FEATURES= json yaml .... ==== [[cargo-ex4]] .Encoding Application Features As Port Options [example] ==== An example `[features]` section in [.filename]#Cargo.toml# could look like this: [.programlisting] .... [features] pulseaudio_backend = ["librespot-playback/pulseaudio-backend"] portaudio_backend = ["librespot-playback/portaudio-backend"] default = ["pulseaudio_backend"] .... `pulseaudio_backend` is a default feature. It is always enabled unless we explicitly turn off default features by adding `--no-default-features` to `CARGO_FEATURES`. Here we turn the `portaudio_backend` and `pulseaudio_backend` features into port options: [.programlisting] .... CARGO_FEATURES= --no-default-features OPTIONS_DEFINE= PORTAUDIO PULSEAUDIO PORTAUDIO_VARS= CARGO_FEATURES+=portaudio_backend PULSEAUDIO_VARS= CARGO_FEATURES+=pulseaudio_backend .... ==== [[cargo-ex3]] .Listing Crate Licenses [example] ==== Crates have their own licenses. It is important to know what they are when adding a `LICENSE` block to the port (see crossref:makefiles[licenses,Licenses]). The helper target `cargo-crates-licenses` will try to list all the licenses of all crates defined in `CARGO_CRATES`. [source,shell] .... % make cargo-crates-licenses aho-corasick-0.6.4 Unlicense/MIT ansi_term-0.11.0 MIT arrayvec-0.4.7 MIT/Apache-2.0 atty-0.2.9 MIT bitflags-1.0.1 MIT/Apache-2.0 byteorder-1.2.2 Unlicense/MIT [...] .... [NOTE] ====== The license names `make cargo-crates-licenses` outputs are SPDX 2.1 licenses expression which do not match the license names defined in the ports framework. They need to be translated to the names from crossref:makefiles[licenses-license-list,Predefined License List]. ====== ==== [[using-meson]] === Using `meson` For ports that use Meson, define `USES=meson`. [[using-meson-variables]] .Variables for Ports That Use `meson` [cols="1,1", frame="none", options="header"] |=== | Variable | Description |`MESON_ARGS` |Port specific Meson flags to be passed to the `meson` binary. |`MESON_BUILD_DIR` |Path to the build directory relative to `WRKSRC`. Default is `_build`. |=== [[using-meson-example]] .`USES=meson` Example [example] ==== This snippet demonstrates the use of Meson for a port. [.programlisting] .... USES= meson MESON_ARGS= -Dfoo=enabled .... ==== [[using-go]] === Building Go Applications For ports that use Go, define `USES=go`. Refer to crossref:uses[uses-go,`go`] for a list of variables that can be set to control the build process. [[go-ex1]] .Creating a Port for a Go Modules Based Application [example] ==== In most cases, it is sufficient to set the `GO_MODULE` variable to the value specified by the `module` directive in `go.mod`: [.programlisting] .... PORTNAME= hey 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 USES= go:modules GO_MODULE= github.com/rakyll/hey PLIST_FILES= bin/hey .include .... 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. First we need to provide a ports template that fetches the application distribution file: [.programlisting] .... PORTNAME= ghq DISTVERSIONPREFIX= v DISTVERSION= 0.12.5 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 GH_ACCOUNT= motemen .include .... Generate an initial [.filename]#distinfo#: [source,shell] .... % make makesum ===> License MIT accepted by the user => motemen-ghq-v0.12.5_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://codeload.github.com/motemen/ghq/tar.gz/v0.12.5?dummy=/motemen-ghq-v0.12.5_GH0.tar.gz fetch: https://codeload.github.com/motemen/ghq/tar.gz/v0.12.5?dummy=/motemen-ghq-v0.12.5_GH0.tar.gz: size of remote file is not known motemen-ghq-v0.12.5_GH0.tar.gz 32 kB 177 kBps 00s .... Now the distribution file is ready to use and we can extract the required Go module dependencies. This step requires having package:ports-mgmt/modules2tuple[] installed: [source,shell] .... % make gomod-vendor [...] GH_TUPLE= \ Songmu:gitconfig:v0.0.2:songmu_gitconfig/vendor/github.com/Songmu/gitconfig \ daviddengcn:go-colortext:186a3d44e920:daviddengcn_go_colortext/vendor/github.com/daviddengcn/go-colortext \ go-yaml:yaml:v2.2.2:go_yaml_yaml/vendor/gopkg.in/yaml.v2 \ golang:net:3ec191127204:golang_net/vendor/golang.org/x/net \ golang:sync:112230192c58:golang_sync/vendor/golang.org/x/sync \ golang:xerrors:3ee3066db522:golang_xerrors/vendor/golang.org/x/xerrors \ motemen:go-colorine:45d19169413a:motemen_go_colorine/vendor/github.com/motemen/go-colorine \ urfave:cli:v1.20.0:urfave_cli/vendor/github.com/urfave/cli .... The output of this command needs to be pasted directly into the Makefile: [.programlisting] .... PORTNAME= ghq DISTVERSIONPREFIX= v DISTVERSION= 0.12.5 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 GH_ACCOUNT= motemen GH_TUPLE= Songmu:gitconfig:v0.0.2:songmu_gitconfig/vendor/github.com/Songmu/gitconfig \ daviddengcn:go-colortext:186a3d44e920:daviddengcn_go_colortext/vendor/github.com/daviddengcn/go-colortext \ go-yaml:yaml:v2.2.2:go_yaml_yaml/vendor/gopkg.in/yaml.v2 \ golang:net:3ec191127204:golang_net/vendor/golang.org/x/net \ golang:sync:112230192c58:golang_sync/vendor/golang.org/x/sync \ golang:xerrors:3ee3066db522:golang_xerrors/vendor/golang.org/x/xerrors \ motemen:go-colorine:45d19169413a:motemen_go_colorine/vendor/github.com/motemen/go-colorine \ urfave:cli:v1.20.0:urfave_cli/vendor/github.com/urfave/cli .include .... [.filename]#distinfo# needs to be regenerated to contain all the distribution files: [source,shell] .... % make makesum => Songmu-gitconfig-v0.0.2_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://codeload.github.com/Songmu/gitconfig/tar.gz/v0.0.2?dummy=/Songmu-gitconfig-v0.0.2_GH0.tar.gz fetch: https://codeload.github.com/Songmu/gitconfig/tar.gz/v0.0.2?dummy=/Songmu-gitconfig-v0.0.2_GH0.tar.gz: size of remote file is not known Songmu-gitconfig-v0.0.2_GH0.tar.gz 5662 B 936 kBps 00s => daviddengcn-go-colortext-186a3d44e920_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. => Attempting to fetch https://codeload.github.com/daviddengcn/go-colortext/tar.gz/186a3d44e920?dummy=/daviddengcn-go-colortext-186a3d44e920_GH0.tar.gz fetch: https://codeload.github.com/daviddengcn/go-colortext/tar.gz/186a3d44e920?dummy=/daviddengcn-go-colortext-186a3d44e920_GH0.tar.gz: size of remote file is not known 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. ==== [[go-ex2]] .Setting Output Binary Name or Installation Path [example] ==== Some ports need to install the resulting binary under a different name or to a path other than the default `${PREFIX}/bin`. This can be done by using `GO_TARGET` tuple syntax, for example: [.programlisting] .... GO_TARGET= ./cmd/ipfs:ipfs-go .... will install `ipfs` binary as `${PREFIX}/bin/ipfs-go` and [.programlisting] .... GO_TARGET= ./dnscrypt-proxy:${PREFIX}/sbin/dnscrypt-proxy .... will install `dnscrypt-proxy` to `${PREFIX}/sbin`. ==== [[using-cabal]] === Building Haskell Applications with `cabal` For ports that use Cabal, build system defines `USES=cabal`. Refer to crossref:uses[uses-cabal,`cabal`] for a list of variables that can be set to control the build process. [[cabal-ex1]] .Creating a Port for a Hackage-hosted Haskell Application [example] ==== 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] .... PORTNAME= ShellCheck DISTVERSION= 0.6.0 CATEGORIES= devel MAINTAINER= haskell@FreeBSD.org COMMENT= Shell script analysis tool WWW= https://www.shellcheck.net/ USES= cabal .include .... This minimal Makefile fetches the distribution file with the `cabal-extract` helper target: [source,shell] .... % make cabal-extract [...] Downloading the latest package list from hackage.haskell.org cabal get ShellCheck-0.6.0 Downloading ShellCheck-0.6.0 Downloaded ShellCheck-0.6.0 Unpacking to ShellCheck-0.6.0/ .... 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-configure [...] Resolving dependencies... 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) [...] .... 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 \ [...] .... Haskell packages may contain revisions, just like FreeBSD ports. 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: [source,shell] .... % make makesum => ShellCheck-0.6.0.tar.gz doesn't seem to exist in /usr/local/poudriere/ports/git/distfiles/cabal. => Attempting to fetch https://hackage.haskell.org/package/ShellCheck-0.6.0/ShellCheck-0.6.0.tar.gz ShellCheck-0.6.0.tar.gz 136 kB 642 kBps 00s => QuickCheck-2.12.6.1/QuickCheck-2.12.6.1.tar.gz doesn't seem to exist in /usr/local/poudriere/ports/git/distfiles/cabal. => Attempting to fetch https://hackage.haskell.org/package/QuickCheck-2.12.6.1/QuickCheck-2.12.6.1.tar.gz 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. ==== 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 .... 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 .... 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 .... 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]] == Using GNU Autotools If a port needs any of the GNU Autotools software, add `USES=autoreconf`. See crossref:uses[uses-autoreconf,`autoreconf`] for more information. [[using-gettext]] == Using GNU `gettext` [[using-gettext-basic]] === Basic Usage If the port requires `gettext`, set `USES= gettext`, and the port will inherit a dependency on [.filename]#libintl.so# from package:devel/gettext[]. Other values for `gettext` usage are listed in crossref:uses[uses-gettext,`USES=gettext`]. A rather common case is a port using `gettext` and `configure`. Generally, GNU `configure` should be able to locate `gettext` automatically. [.programlisting] .... USES= gettext GNU_CONFIGURE= yes .... If it ever fails to, hints at the location of `gettext` can be passed in `CPPFLAGS` and `LDFLAGS` using `localbase` as follows: [.programlisting] .... USES= gettext localbase:ldflags GNU_CONFIGURE= yes .... [[using-gettext-optional]] === Optional Usage Some software products allow for disabling NLS. For example, through passing `--disable-nls` to `configure`. In that case, the port must use `gettext` conditionally, depending on the status of the `NLS` option. For ports of low to medium complexity, use this idiom: [.programlisting] .... GNU_CONFIGURE= yes OPTIONS_DEFINE= NLS OPTIONS_SUB= yes NLS_USES= gettext NLS_CONFIGURE_ENABLE= nls .include .... Or using the older way of using options: [.programlisting] .... GNU_CONFIGURE= yes OPTIONS_DEFINE= NLS .include .if ${PORT_OPTIONS:MNLS} USES+= gettext PLIST_SUB+= NLS="" .else CONFIGURE_ARGS+= --disable-nls PLIST_SUB+= NLS="@comment " .endif .include .... The next item on the to-do list is to arrange so that the message catalog files are included in the packing list conditionally. The [.filename]#Makefile# part of this task is already provided by the idiom. It is explained in the section on crossref:plist[plist-sub,advanced [.filename]#pkg-plist# practices]. In a nutshell, each occurrence of `%%NLS%%` in [.filename]#pkg-plist# will be replaced by "`@comment `" if NLS is disabled, or by a null string if NLS is enabled. Consequently, the lines prefixed by `%%NLS%%` will become mere comments in the final packing list if NLS is off; otherwise the prefix will be just left out. Then insert `%%NLS%%` before each path to a message catalog file in [.filename]#pkg-plist#. For example: [.programlisting] .... %%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo %%NLS%%share/locale/no/LC_MESSAGES/foobar.mo .... In high complexity cases, more advanced techniques may be needed, such as crossref:plist[plist-dynamic,dynamic packing list generation]. [[using-gettext-catalog-directories]] === Handling Message Catalog Directories There is a point to note about installing message catalog files. The target directories for them, which reside under [.filename]#LOCALBASE/share/locale#, must not be created and removed by a port. The most popular languages have their respective directories listed in [.filename]#PORTSDIR/Templates/BSD.local.dist#. The directories for many other languages are governed by the package:devel/gettext[] port. Consult its [.filename]#pkg-plist# and see whether the port is going to install a message catalog file for a unique language. [[using-perl]] == Using Perl If `MASTER_SITES` is set to `CPAN`, the correct subdirectory is usually selected automatically. 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 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. In such case, using author's id as `MASTER_SITE_SUBDIR` is allowed. The `CPAN:AUTHOR` macro can be used, which will be translated to the hashed author directory. For example, `CPAN:AUTHOR` will be converted to `authors/id/A/AU/AUTHOR`. When a port needs Perl support, it must set `USES=perl5` with the optional `USE_PERL5` described in crossref:uses[uses-perl5,the perl5 USES description]. [[using-perl-variables]] .Read-Only Variables for Ports That Use Perl [cols="1,1", frame="none", options="header"] |=== | Read only variables | Means |`PERL` |The full path of the Perl 5 interpreter, either in the system or installed from a port, but without the version number. Use this when the software needs the path to the Perl interpreter. To replace "``#!``"lines in scripts, use crossref:uses[uses-shebangfix,`shebangfix`]. |`PERL_VERSION` |The full version of Perl installed (for example, `5.8.9`). |`PERL_LEVEL` |The installed Perl version as an integer of the form `MNNNPP` (for example, `500809`). |`PERL_ARCH` |Where Perl stores architecture dependent libraries. Defaults to `${ARCH}-freebsd`. |`PERL_PORT` |Name of the Perl port that is installed (for example, `perl5`). |`SITE_PERL` |Directory name where site specific Perl packages go. This value is added to `PLIST_SUB`. |=== [NOTE] ==== 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] ==== Do not use `${SITE_PERL}` in dependency declarations. Doing so assumes that [.filename]#perl5.mk# has been included, which is not always true. Ports depending on this port will have incorrect dependencies if this port's files move later in an upgrade. The right way to declare Perl module dependencies is shown in the example below. ==== [[use-perl-dependency-example]] .Perl Dependency Example [example] ==== [.programlisting] .... p5-IO-Tee>=0.64:devel/p5-IO-Tee .... ==== For Perl ports that install manual pages, the macro `PERL5_MAN3` and `PERL5_MAN1` can be used inside [.filename]#pkg-plist#. For example, [.programlisting] .... lib/perl5/5.14/man/man1/event.1.gz lib/perl5/5.14/man/man3/AnyEvent::I3.3.gz .... can be replaced with [.programlisting] .... %%PERL5_MAN1%%/event.1.gz %%PERL5_MAN3%%/AnyEvent::I3.3.gz .... [NOTE] ==== There are no `PERL5_MAN_x_` macros for the other sections (_x_ in `2` and `4` to `9`) because those get installed in the regular directories. ==== [[use-perl-ex-build]] .A Port Which Only Requires Perl to Build [example] ==== As the default USE_PERL5 value is build and run, set it to: [.programlisting] .... USES= perl5 USE_PERL5= build .... ==== [[use-perl-ex-patch]] .A Port Which Also Requires Perl to Patch [example] ==== From time to time, using man:sed[1] for patching is not enough. When using man:perl[1] is easier, use: [.programlisting] .... USES= perl5 USE_PERL5= patch build run .... ==== [[use-perl-ex-configure]] .A Perl Module Which Needs `ExtUtils::MakeMaker` to Build [example] ==== Most Perl modules come with a [.filename]#Makefile.PL# configure script. In this case, set: [.programlisting] .... USES= perl5 USE_PERL5= configure .... ==== [[use-perl-ex-modbuild]] .A Perl Module Which Needs `Module::Build` to Build [example] ==== When a Perl module comes with a [.filename]#Build.PL# configure script, it can require Module::Build, in which case, set [.programlisting] .... USES= perl5 USE_PERL5= modbuild .... If it instead requires Module::Build::Tiny, set [.programlisting] .... USES= perl5 USE_PERL5= modbuildtiny .... ==== [[using-x11]] == Using X11 [[x11-variables]] === X.Org Components The X11 implementation available in The Ports Collection is X.Org. If the application depends on X components, add `USES= xorg` and set `USE_XORG` to the list of required components. A full list can be found in crossref:uses[uses-xorg,`xorg`]. The Mesa Project is an effort to provide free OpenGL implementation. To specify a dependency on various components of this project, use `USES= gl` and `USE_GL`. See crossref:uses[uses-gl,`gl`] for a full list of available components. For backwards compatibility, the value of `yes` maps to `glu`. [[use-xorg-example]] .`USE_XORG` Example [example] ==== [.programlisting] .... USES= gl xorg USE_GL= glu USE_XORG= xrender xft xkbfile xt xaw .... ==== [[using-xorg-variables]] .Variables for Ports That Use X [cols="1,1", frame="none"] |=== |`USES= imake` |The port uses `imake`. |`XMKMF` |Set to the path of `xmkmf` if not in the `PATH`. Defaults to `xmkmf -a`. |=== [[using-x11-vars]] .Using X11-Related Variables [example] ==== [.programlisting] .... # Use some X11 libraries USES= xorg USE_XORG= x11 xpm .... ==== [[x11-motif]] === Ports That Require Motif 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#. There are two common cases: * If the port refers to the Motif library as `-lXm` in its [.filename]#Makefile# or [.filename]#Imakefile#, substitute `${MOTIFLIB}` for it. * If the port uses `XmClientLibs` in its [.filename]#Imakefile#, change it to `${MOTIFLIB} ${XTOOLLIB} ${XLIB}`. Note that `MOTIFLIB` (usually) expands to `-L/usr/local/lib -lXm -lXp` or `/usr/local/lib/libXm.a`, so there is no need to add `-L` or `-l` in front. [[x11-fonts]] === X11 Fonts If the port installs fonts for the X Window System, put them in [.filename]#LOCALBASE/lib/X11/fonts/local#. [[x11-fake-display]] === Getting a Fake `DISPLAY` with Xvfb Some applications require a working X11 display for compilation to succeed. This poses a problem for machines that operate headless. When this variable is used, the build infrastructure will start the virtual framebuffer X server. The working `DISPLAY` is then passed to the build. See crossref:uses[uses-display,`USES=display`] for the possible arguments. [.programlisting] .... USES= display .... [[desktop-entries]] === Desktop Entries 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. [[desktop-entries-predefined]] ==== Using Predefined [.filename]#.desktop# Files Ports that include predefined [.filename]#*.desktop# must include those files in [.filename]#pkg-plist# and install them in the [.filename]#$LOCALBASE/share/applications# directory. The crossref:makefiles[install-macros,`INSTALL_DATA` macro] is useful for installing these files. [[updating-desktop-database]] ==== Updating Desktop Database If a port has a MimeType entry in its [.filename]#portname.desktop#, the desktop database must be updated after install and deinstall. To do this, define `USES`= desktop-file-utils. [[desktop-entries-macro]] ==== Creating Desktop Entries with `DESKTOP_ENTRIES` Desktop entries can be easily created for applications by using `DESKTOP_ENTRIES`. A file named [.filename]#name.desktop# will be created, installed, and added to [.filename]#pkg-plist# automatically. Syntax is: [.programlisting] .... DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify .... 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. Programs that are not compatible with startup notifications would never clear the indicator (potentially confusing and infuriating the user), and must have `StartupNotify` set to `false` so the indicator is not shown at all. Example: [.programlisting] .... DESKTOP_ENTRIES= "ToME" "Roguelike game based on JRR Tolkien's work" \ "${DATADIR}/xtra/graf/tome-128.png" \ "tome -v -g" "Application;Game;RolePlaying;" \ 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 [[using-gnome-introduction]] === Introduction This chapter explains the GNOME framework as used by ports. The framework can be loosely divided into the base components, GNOME desktop components, and a few special macros that simplify the work of port maintainers. [[use-gnome]] === Using `USE_GNOME` Adding this variable to the port allows the use of the macros and components defined in [.filename]#bsd.gnome.mk#. The code in [.filename]#bsd.gnome.mk# adds the needed build-time, run-time or library dependencies or the handling of special files. GNOME applications under FreeBSD use the `USE_GNOME` infrastructure. Include all the needed components as a space-separated list. The `USE_GNOME` components are divided into these virtual lists: basic components, GNOME 3 components and legacy components. If the port needs only GTK3 libraries, this is the shortest way to define it: [.programlisting] .... USE_GNOME= gtk30 .... `USE_GNOME` components automatically add the dependencies they need. Please see <> for an exhaustive list of all `USE_GNOME` components and which other components they imply and their dependencies. Here is an example [.filename]#Makefile# for a GNOME port that uses many of the techniques outlined in this document. Please use it as a guide for creating new ports. [.programlisting] .... PORTNAME= regexxer DISTVERSION= 0.10 CATEGORIES= devel textproc gnome 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 USE_GNOME= gnomeprefix intlhack gtksourceviewmm3 GLIB_SCHEMAS= org.regexxer.gschema.xml .include .... [NOTE] ==== The `USE_GNOME` macro without any arguments does not add any dependencies to the port. `USE_GNOME` cannot be set after [.filename]#bsd.port.pre.mk#. ==== [[using-gnome-variables]] === Variables This section explains which macros are available and how they are used. Like they are used in the above example. The <> has a more in-depth explanation. `USE_GNOME` has to be set for these macros to be of use. `GLIB_SCHEMAS`:: List of all the glib schema files the port installs. The macro will add the files to the port plist and handle the registration of these files on install and deinstall. + The glib schema files are written in XML and end with the [.filename]#gschema.xml# extension. They are installed in the [.filename]#share/glib-2.0/schemas/# directory. These schema files contain all application config values with their default settings. The actual database used by the applications is built by glib-compile-schema, which is run by the `GLIB_SCHEMAS` macro. + [.programlisting] .... GLIB_SCHEMAS=foo.gschema.xml .... + [NOTE] ==== Do not add glib schemas to the [.filename]#pkg-plist#. If they are listed in [.filename]#pkg-plist#, they will not be registered and the applications might not work properly. ==== `GCONF_SCHEMAS`:: List all the gconf schema files. The macro will add the schema files to the port plist and will handle their registration on install and deinstall. + GConf is the XML-based database that virtually all GNOME applications use for storing their settings. These files are installed into the [.filename]#etc/gconf/schemas# directory. This database is defined by installed schema files that are used to generate [.filename]#%gconf.xml# key files. For each schema file installed by the port, there must be an entry in the [.filename]#Makefile#: + [.programlisting] .... GCONF_SCHEMAS=my_app.schemas my_app2.schemas my_app3.schemas .... + [NOTE] ==== Gconf schemas are listed in the `GCONF_SCHEMAS` macro rather than [.filename]#pkg-plist#. If they are listed in [.filename]#pkg-plist#, they will not be registered and the applications might not work properly. ==== `INSTALLS_OMF`:: Open Source Metadata Framework (OMF) files are commonly used by GNOME 2 applications. These files contain the application help file information, and require special processing by ScrollKeeper/rarian. To properly register OMF files when installing GNOME applications from packages, make sure that `omf` files are listed in `pkg-plist` and that the port [.filename]#Makefile# has `INSTALLS_OMF` defined: + [.programlisting] .... INSTALLS_OMF=yes .... + When set, [.filename]#bsd.gnome.mk# automatically scans [.filename]#pkg-plist# and adds appropriate `@exec` and `@unexec` directives for each [.filename]#.omf# to track in the OMF registration database. [[gnome-components]] == GNOME Components -For further help with a GNOME port, look at some of the link:https://www.FreeBSD.org/ports/gnome.html[existing ports] for examples. +For further help with a GNOME port, look at some of the link:https://ports.FreeBSD.org[existing ports] for examples. The link:https://www.FreeBSD.org/gnome/[FreeBSD GNOME page] has contact information if more help is needed. The components are divided into GNOME components that are currently in use and legacy components. If the component supports argument, they are listed between parenthesis in the description. The first is the default. "Both" is shown if the component defaults to adding to both build and run dependencies. [[gnome-components-list]] .GNOME Components [cols="1,1,1", options="header"] |=== | Component | Associated program | Description |`atk` |accessibility/atk |Accessibility toolkit (ATK) |`atkmm` |accessibility/atkmm |c++ bindings for atk |`cairo` |graphics/cairo |Vector graphics library with cross-device output support |`cairomm` |graphics/cairomm |c++ bindings for cairo |`dconf` |devel/dconf |Configuration database system (both, build, run) |`evolutiondataserver3` |databases/evolution-data-server |Data backends for the Evolution integrated mail/PIM suite |`gdkpixbuf2` |graphics/gdk-pixbuf2 |Graphics library for GTK+ |`glib20` |devel/glib20 |GNOME core library `glib20` |`glibmm` |devel/glibmm |c++ bindings for glib20 |`gnomecontrolcenter3` |sysutils/gnome-control-center |GNOME 3 Control Center |`gnomedesktop3` |x11/gnome-desktop |GNOME 3 desktop UI library |`gsound` |audio/gsound |GObject library for playing system sounds (both, build, run) |`gtk-update-icon-cache` |graphics/gtk-update-icon-cache |Gtk-update-icon-cache utility from the Gtk+ toolkit |`gtk20` |x11-toolkits/gtk20 |Gtk+ 2 toolkit |`gtk30` |x11-toolkits/gtk30 |Gtk+ 3 toolkit |`gtkmm20` |x11-toolkits/gtkmm20 |c++ bindings 2.0 for the gtk20 toolkit |`gtkmm24` |x11-toolkits/gtkmm24 |c++ bindings 2.4 for the gtk20 toolkit |`gtkmm30` |x11-toolkits/gtkmm30 |c++ bindings 3.0 for the gtk30 toolkit |`gtksourceview2` |x11-toolkits/gtksourceview2 |Widget that adds syntax highlighting to GtkTextView |`gtksourceview3` |x11-toolkits/gtksourceview3 |Text widget that adds syntax highlighting to the GtkTextView widget |`gtksourceviewmm3` |x11-toolkits/gtksourceviewmm3 |c++ bindings for the gtksourceview3 library |`gvfs` |devel/gvfs |GNOME virtual file system |`intltool` |textproc/intltool |Tool for internationalization (also see intlhack) |`introspection` |devel/gobject-introspection |Basic introspection bindings and tools to generate introspection bindings. Most of the time :build is enough, :both/:run is only need for applications that use introspection bindings. (both, build, run) |`libgda5` |databases/libgda5 |Provides uniform access to different kinds of data sources |`libgda5-ui` |databases/libgda5-ui |UI library from the libgda5 library |`libgdamm5` |databases/libgdamm5 |c++ bindings for the libgda5 library |`libgsf` |devel/libgsf |Extensible I/O abstraction for dealing with structured file formats |`librsvg2` |graphics/librsvg2 |Library for parsing and rendering SVG vector-graphic files |`libsigc++20` |devel/libsigc++20 |Callback Framework for C++ |`libxml++26` |textproc/libxml++26 |c++ bindings for the libxml2 library |`libxml2` |textproc/libxml2 |XML parser library (both, build, run) |`libxslt` |textproc/libxslt |XSLT C library (both, build, run) |`metacity` |x11-wm/metacity |Window manager from GNOME |`nautilus3` |x11-fm/nautilus |GNOME file manager |`pango` |x11-toolkits/pango |Open-source framework for the layout and rendering of i18n text |`pangomm` |x11-toolkits/pangomm |c++ bindings for the pango library |`py3gobject3` |devel/py3-gobject3 |Python 3, GObject 3.0 bindings |`pygobject3` |devel/py-gobject3 |Python 2, GObject 3.0 bindings |`vte3` |x11-toolkits/vte3 |Terminal widget with improved accessibility and I18N support |=== [[gnome-components-macro]] .GNOME Macro Components [cols="1,1", options="header"] |=== | Component | Description |`gnomeprefix` |Supply `configure` with some default locations. |`intlhack` |Same as intltool, but patches to make sure [.filename]#share/locale/# is used. Please only use when `intltool` alone is not enough. |`referencehack` |This macro is there to help splitting of the API or reference documentation into its own port. |=== [[gnome-components-legacy]] .GNOME Legacy Components [cols="1,1,1", options="header"] |=== | Component | Associated program | Description |`atspi` |accessibility/at-spi |Assistive Technology Service Provider Interface |`esound` |audio/esound |Enlightenment sound package |`gal2` |x11-toolkits/gal2 |Collection of widgets taken from GNOME 2 gnumeric |`gconf2` |devel/gconf2 |Configuration database system for GNOME 2 |`gconfmm26` |devel/gconfmm26 |c++ bindings for gconf2 |`gdkpixbuf` |graphics/gdk-pixbuf |Graphics library for GTK+ |`glib12` |devel/glib12 |glib 1.2 core library |`gnomedocutils` |textproc/gnome-doc-utils |GNOME doc utils |`gnomemimedata` |misc/gnome-mime-data |MIME and Application database for GNOME 2 |`gnomesharp20` |x11-toolkits/gnome-sharp20 |GNOME 2 interfaces for the .NET runtime |`gnomespeech` |accessibility/gnome-speech |GNOME 2 text-to-speech API |`gnomevfs2` |devel/gnome-vfs |GNOME 2 Virtual File System |`gtk12` |x11-toolkits/gtk12 |Gtk+ 1.2 toolkit |`gtkhtml3` |www/gtkhtml3 |Lightweight HTML rendering/printing/editing engine |`gtkhtml4` |www/gtkhtml4 |Lightweight HTML rendering/printing/editing engine |`gtksharp20` |x11-toolkits/gtk-sharp20 |GTK+ and GNOME 2 interfaces for the .NET runtime |`gtksourceview` |x11-toolkits/gtksourceview |Widget that adds syntax highlighting to GtkTextView |`libartgpl2` |graphics/libart_lgpl |Library for high-performance 2D graphics |`libbonobo` |devel/libbonobo |Component and compound document system for GNOME 2 |`libbonoboui` |x11-toolkits/libbonoboui |GUI frontend to the libbonobo component of GNOME 2 |`libgda4` |databases/libgda4 |Provides uniform access to different kinds of data sources |`libglade2` |devel/libglade2 |GNOME 2 glade library |`libgnome` |x11/libgnome |Libraries for GNOME 2, a GNU desktop environment |`libgnomecanvas` |graphics/libgnomecanvas |Graphics library for GNOME 2 |`libgnomekbd` |x11/libgnomekbd |GNOME 2 keyboard shared library |`libgnomeprint` |print/libgnomeprint |Gnome 2 print support library |`libgnomeprintui` |x11-toolkits/libgnomeprintui |Gnome 2 print support library |`libgnomeui` |x11-toolkits/libgnomeui |Libraries for the GNOME 2 GUI, a GNU desktop environment |`libgtkhtml` |www/libgtkhtml |Lightweight HTML rendering/printing/editing engine |`libgtksourceviewmm` |x11-toolkits/libgtksourceviewmm |c++ binding of GtkSourceView |`libidl` |devel/libIDL |Library for creating trees of CORBA IDL file |`libsigc++12` |devel/libsigc++12 |Callback Framework for C++ |`libwnck` |x11-toolkits/libwnck |Library used for writing pagers and taskslists |`libwnck3` |x11-toolkits/libwnck3 |Library used for writing pagers and taskslists |`orbit2` |devel/ORBit2 |High-performance CORBA ORB with support for the C language |`pygnome2` |x11-toolkits/py-gnome2 |Python bindings for GNOME 2 |`pygobject` |devel/py-gobject |Python 2, GObject 2.0 bindings |`pygtk2` |x11-toolkits/py-gtk2 |Set of Python bindings for GTK+ |`pygtksourceview` |x11-toolkits/py-gtksourceview |Python bindings for GtkSourceView 2 |`vte` |x11-toolkits/vte |Terminal widget with improved accessibility and I18N support |=== [[gnome-components-deprecated]] .Deprecated Components: Do Not Use [cols="1,1", options="header"] |=== | Component | Description |`pangox-compat` |pangox-compat has been deprecated and split off from the pango package. |=== [[using-qt]] == Using Qt [NOTE] ==== 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 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: [[using-qt-variables]] .Variables Provided to Ports That Use Qt [cols="1,1", frame="none"] |=== |`QMAKE` |Full path to `qmake` binary. |`LRELEASE` |Full path to `lrelease` utility. |`MOC` |Full path to `moc`. |`RCC` |Full path to `rcc`. |`UIC` |Full path to `uic`. |`QT_INCDIR` |Qt include directory. |`QT_LIBDIR` |Qt libraries path. |`QT_PLUGINDIR` |Qt plugins path. |=== [[qt-components]] === Component Selection 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`, 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 [cols="1,1", frame="none", options="header"] |=== | Name | Description |`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 |`charts` |Qt 5 charts module |`concurrent` |Qt multi-threading module |`connectivity` |Qt connectivity (Bluetooth/NFC) module |`core` |Qt core non-graphical module |`datavis3d` |Qt 5 3D data visualization module |`dbus` |Qt D-Bus inter-process communication module |`declarative` |Qt declarative framework for dynamic user interfaces |`designer` |Qt 5 graphical user interface designer |`diag` |Tool for reporting diagnostic information about Qt and its environment |`doc` |Qt 5 documentation |`examples` |Qt 5 examples sourcecode |`gamepad` |Qt 5 Gamepad Module |`graphicaleffects` |Qt Quick graphical effects |`gui` |Qt graphical user interface module |`help` |Qt online help integration module |`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 |`network` |Qt network module |`networkauth` |Qt network auth module |`opengl` |Qt 5-compatible OpenGL support module |`paths` |Command line client to QStandardPaths |`phonon4` |KDE multimedia framework |`pixeltool` |Qt 5 screen magnifier |`plugininfo` |Qt 5 plugin metadata dumper |`positioning` |Qt 6 positioning API from sources such as satellite, wifi or text files. |`printsupport` |Qt print support module |`qdbus` |Qt command-line interface to D-Bus |`qdbusviewer` |Qt 5 graphical interface to D-Bus |`qdoc` |Qt documentation generator |`qdoc-data` |QDoc configuration files |`qev` |Qt QWidget events introspection tool |`qmake` |Qt Makefile generator |`quickcontrols` |Set of controls for building complete interfaces in Qt Quick |`quickcontrols2` |Set of controls for building complete interfaces in Qt Quick |`remoteobjects` |Qt 5 SXCML module |`script` |Qt 4-compatible scripting module |`scripttools` |Qt Script additional components |`scxml` |Qt 5 SXCML module |`sensors` |Qt sensors module |`serialbus` |Qt functions to access industrial bus systems |`serialport` |Qt functions to access serial ports |`shadertools` |Qt 6 tools for the cross-platform Qt shader pipeline |`speech` |Accessibility features for Qt5 |`sql` |Qt SQL database integration module |`sql-ibase` |Qt InterBase/Firebird database plugin |`sql-mysql` |Qt MySQL database plugin |`sql-odbc` |Qt Open Database Connectivity plugin |`sql-pgsql` |Qt PostgreSQL database plugin |`sql-sqlite2` |Qt SQLite 2 database plugin |`sql-sqlite3` |Qt SQLite 3 database plugin |`sql-tds` |Qt TDS Database Connectivity database plugin |`svg` |Qt SVG support module |`testlib` |Qt unit testing module |`tools` |Qt 6 assorted tools |`translations` |Qt 6 translation module |`uiplugin` |Custom Qt widget plugin interface for Qt Designer |`uitools` |Qt Designer UI forms support module |`virtualkeyboard` |Qt 5 Virtual Keyboard Module |`wayland` |Qt 5 wrapper for Wayland |`webchannel` |Qt 5 library for integration of C++/QML with HTML/js clients |`webengine` |Qt 5 library to render web content |`webkit` |QtWebKit with a more modern WebKit code base |`websockets` |Qt implementation of WebSocket protocol |`websockets-qml` |Qt implementation of WebSocket protocol (QML bindings) |`webview` |Qt component for displaying web content |`widgets` |Qt C++ widgets module |`x11extras` |Qt platform-specific features for X11-based systems |`xml` |Qt SAX and DOM implementations |`xmlpatterns` |Qt support for XPath, XQuery, XSLT and XML Schema |=== To determine the libraries an application depends on, run `ldd` on the main executable after a successful compilation. [[using-qt-tools-list]] .Available Qt Tool Components [cols="1,1", frame="none", options="header"] |=== | Name | Description |`buildtools` |build tools (`moc`, `rcc`), needed for almost every Qt application. |`linguisttools` |localization tools: `lrelease`, `lupdate` |`qmake` |Makefile generator/build utility |=== [[using-qt-plugins-list]] .Available Qt Plugin Components [cols="1,1", frame="none", options="header"] |=== | Name | Description |`imageformats` |plugins for TGA, TIFF, and MNG image formats |=== [[qt5-components-example]] .Selecting Qt 5 Components [example] ==== In this example, the ported application uses the Qt 5 graphical user interface library, the Qt 5 core library, all of the Qt 5 code generation tools and Qt 5's Makefile generator. Since the `gui` library implies a dependency on the core library, `core` does not need to be specified. The Qt 5 code generation tools `moc`, `uic` and `rcc`, as well as the Makefile generator `qmake` are only needed at buildtime, thus they are specified with the `_build` suffix: [.programlisting] .... USES= qt:5 USE_QT= gui buildtools_build qmake_build .... ==== [[using-qmake]] === Using `qmake` If the application provides a qmake project file ([.filename]#*.pro#), define `USES= qmake` along with `USE_QT`. `USES= qmake` already implies a build dependency on qmake, therefore the qmake component can be omitted from `USE_QT`. Similar to <>, qmake supports out-of-source builds, which can be enabled by specifying the `outsource` argument (see <>). Also see <>. [[using-qmake-arguments]] .Possible Arguments for `USES= qmake` [cols="1,1", frame="none", options="header"] |=== | Variable | Description |`no_configure` |Do not add the configure target. This is implied by `HAS_CONFIGURE=yes` and `GNU_CONFIGURE=yes`. It is required when the build only needs the environment setup from `USES= qmake`, but otherwise runs `qmake` on its own. |`no_env` |Suppress modification of the configure and make environments. It is only required when `qmake` is used to configure the software and the build fails to understand the environment setup by `USES= qmake`. |`norecursive` |Do not pass the `-recursive` argument to `qmake`. |`outsource` |Perform an out-of-source build. |=== [[using-qmake-variables]] .Variables for Ports That Use `qmake` [cols="1,1", frame="none", options="header"] |=== | Variable | Description |`QMAKE_ARGS` |Port specific qmake flags to be passed to the `qmake` binary. |`QMAKE_ENV` |Environment variables to be set for the `qmake` binary. The default is `${CONFIGURE_ENV}`. |`QMAKE_SOURCE_PATH` |Path to qmake project files ([.filename]#.pro#). The default is `${WRKSRC}` if an out-of-source build is requested, empty otherwise. |=== When using `USES= qmake`, these settings are deployed: [.programlisting] .... CONFIGURE_ARGS+= --with-qt-includes=${QT_INCDIR} \ --with-qt-libraries=${QT_LIBDIR} \ --with-extra-libs=${LOCALBASE}/lib \ --with-extra-includes=${LOCALBASE}/include CONFIGURE_ENV+= QTDIR="${QT_PREFIX}" QMAKE="${QMAKE}" \ MOC="${MOC}" RCC="${RCC}" UIC="${UIC}" \ QMAKESPEC="${QMAKESPEC}" PLIST_SUB+= QT_INCDIR=${QT_INCDIR_REL} \ QT_LIBDIR=${QT_LIBDIR_REL} \ QT_PLUGINDIR=${QT_PLUGINDIR_REL} .... Some configure scripts do not support the arguments above. To suppress modification of `CONFIGURE_ENV` and `CONFIGURE_ARGS`, set `USES= qmake:no_env`. [[using-qmake-example]] .`USES= qmake` Example [example] ==== This snippet demonstrates the use of qmake for a Qt 5 port: [.programlisting] .... USES= qmake:outsource qt:5 USE_QT= buildtools_build .... ==== Qt applications are often written to be cross-platform and often X11/Unix is not the platform they are developed on, which in turn leads to certain loose ends, like: * _Missing additional include paths._ Many applications come with system tray icon support, but neglect to look for includes and/or libraries in the X11 directories. To add directories to `qmake`'s include and library search paths via the command line, use: + [.programlisting] .... QMAKE_ARGS+= INCLUDEPATH+=${LOCALBASE}/include \ LIBS+=-L${LOCALBASE}/lib .... * _Bogus installation paths._ Sometimes data such as icons or .desktop files are by default installed into directories which are not scanned by XDG-compatible applications. package:editors/texmaker[] is an example for this - look at [.filename]#patch-texmaker.pro# in the [.filename]#files# directory of that port for a template on how to remedy this directly in the `qmake` project file. [[using-kde]] == Using KDE [[kde5-variables]] === KDE Variable Definitions If the application depends on KDE, set `USES+=kde:5` and `USE_KDE` to the list of required components. `_build` and `_run` suffixes can be used to force components dependency type (for example, `baseapps_run`). If no suffix is set, a default dependency type will be used. To force both types, add the component twice with both suffixes (for example, `ecm_build ecm_run`). Available components are listed below (up-to-date components are also listed in [.filename]#/usr/ports/Mk/Uses/kde.mk#): [[using-kde-components]] .Available KDE Components [cols="1,1", frame="none", options="header"] |=== | Name | Description |`activities` |KF5 runtime and library to organize work in separate activities |`activities-stats` |KF5 statistics for activities |`activitymanagerd` |System service to manage user's activities, track the usage patterns |`akonadi` |Storage server for KDE-Pim |`akonadicalendar` |Akonadi Calendar Integration |`akonadiconsole` |Akonadi management and debugging console |`akonadicontacts` |Libraries and daemons to implement Contact Management in Akonadi |`akonadiimportwizard` |Import data from other mail clients to KMail |`akonadimime` |Libraries and daemons to implement basic email handling |`akonadinotes` |KDE library for accessing mail storages in MBox format |`akonadisearch` |Libraries and daemons to implement searching in Akonadi |`akregator` |A Feed Reader by KDE |`alarmcalendar` |KDE API for KAlarm alarms |`apidox` |KF5 API Documentation Tools |`archive` |KF5 library that provides classes for handling archive formats |`attica` |Open Collaboration Services API library KDE5 version |`attica5` |Open Collaboration Services API library KDE5 version |`auth` |KF5 abstraction to system policy and authentication features |`baloo` |KF5 Framework for searching and managing user metadata |`baloo-widgets` |BalooWidgets library |`baloo5` |KF5 Framework for searching and managing user metadata |`blog` |KDE API for weblogging access |`bookmarks` |KF5 library for bookmarks and the XBEL format |`breeze` |Plasma5 artwork, styles and assets for the Breeze visual style |`breeze-gtk` |Plasma5 Breeze visual style for Gtk |`breeze-icons` |Breeze icon theme for KDE |`calendarcore` |KDE calendar access library |`calendarsupport` |Calendar support libraries for KDEPim |`calendarutils` |KDE utility and user interface functions for accessing calendar |`codecs` |KF5 library for string manipulation |`completion` |KF5 text completion helpers and widgets |`config` |KF5 widgets for configuration dialogs |`configwidgets` |KF5 widgets for configuration dialogs |`contacts` |KDE api to manage contact information |`coreaddons` |KF5 addons to QtCore |`crash` |KF5 library to handle crash analysis and bug report from apps |`dbusaddons` |KF5 addons to QtDBus |`decoration` |Plasma5 library to create window decorations |`designerplugin` |KF5 integration of Frameworks widgets in Qt Designer/Creator |`discover` |Plasma5 package management tools |`dnssd` |KF5 abstraction to system DNSSD features |`doctools` |KF5 documentation generation from docbook |`drkonqi` |Plasma5 crash handler |`ecm` |Extra modules and scripts for CMake |`emoticons` |KF5 library to convert emoticons |`eventviews` |Event view libriares for KDEPim |`filemetadata` |KF5 library for extracting file metadata |`frameworkintegration` |KF5 workspace and cross-framework integration plugins |`gapi` |KDE based library to access google services |`globalaccel` |KF5 library to add support for global workspace shortcuts |`grantlee-editor` |Editor for Grantlee themes |`grantleetheme` |KDE PIM grantleetheme |`gravatar` |Library for gravatar support |`guiaddons` |KF5 addons to QtGui |`holidays` |KDE library for calendar holidays |`hotkeys` |Plasma5 library for hotkeys |`i18n` |KF5 advanced internationalization framework |`iconthemes` |KF5 library for handling icons in applications |`identitymanagement` |KDE pim identities |`idletime` |KF5 library for monitoring user activity |`imap` |KDE API for IMAP support |`incidenceeditor` |Incidence editor libriares for KDEPim |`infocenter` |Plasma5 utility providing system information |`init` |KF5 process launcher to speed up launching KDE applications |`itemmodels` |KF5 models for Qt Model/View system |`itemviews` |KF5 widget addons for Qt Model/View |`jobwidgets` |KF5 widgets for tracking KJob instance |`js` |KF5 library providing an ECMAScript interpreter |`jsembed` |KF5 library for binding JavaScript objects to QObjects |`kaddressbook` |KDE contact manager |`kalarm` |Personal alarm scheduler |`kalarm` |Personal alarm scheduler |`kate` |Basic editor framework for the KDE system |`kcmutils` |KF5 utilities for working with KCModules |`kde-cli-tools` |Plasma5 non-interactive system tools |`kde-gtk-config` |Plasma5 GTK2 and GTK3 configurator |`kdeclarative` |KF5 library providing integration of QML and KDE Frameworks |`kded` |KF5 extensible daemon for providing system level services |`kdelibs4support` |KF5 porting aid from KDELibs4 |`kdepim-addons` |KDE PIM addons |`kdepim-apps-libs` |KDE PIM mail related libraries |`kdepim-runtime5` |KDE PIM tools and services |`kdeplasma-addons` |Plasma5 addons to improve the Plasma experience |`kdesu` |KF5 integration with su for elevated privileges |`kdewebkit` |KF5 library providing integration of QtWebKit |`kgamma5` |Plasma5 monitor's gamma settings |`khtml` |KF5 KTHML rendering engine |`kimageformats` |KF5 library providing support for additional image formats |`kio` |KF5 resource and network access abstraction |`kirigami2` |QtQuick based components set |`kitinerary` |Data Model and Extraction System for Travel Reservation information |`kmail` |KDE mail client |`kmail` |KDE mail client |`kmail-account-wizard` |KDE mail account wizard |`kmenuedit` |Plasma5 menu editor |`knotes` |Popup notes |`kontact` |KDE Personal Information Manager |`kontact` |KDE Personal Information Manager |`kontactinterface` |KDE glue for embedding KParts into Kontact |`korganizer` |Calendar and scheduling Program |`kpimdav` |A DAV protocol implementation with KJobs |`kpkpass` |Library to deal with Apple Wallet pass files |`kross` |KF5 multi-language application scripting |`kscreen` |Plasma5 screen management library |`kscreenlocker` |Plasma5 secure lock screen architecture |`ksmtp` |Job-based library to send email through an SMTP server |`ksshaskpass` |Plasma5 ssh-add frontend |`ksysguard` |Plasma5 utility to track and control the running processes |`kwallet-pam` |Plasma5 KWallet PAM Integration |`kwayland-integration` |Integration plugins for a Wayland-based desktop |`kwin` |Plasma5 window manager |`kwrited` |Plasma5 daemon listening for wall and write messages |`ldap` |LDAP access API for KDE |`libkcddb` |KDE CDDB library |`libkcompactdisc` |KDE library for interfacing with audio CDs |`libkdcraw` |LibRaw interface for KDE |`libkdegames` |Libraries used by KDE games |`libkdepim` |KDE PIM Libraries |`libkeduvocdocument` |Library for reading and writing vocabulary files |`libkexiv2` |Exiv2 library interface for KDE |`libkipi` |KDE Image Plugin Interface |`libkleo` |Certificate manager for KDE |`libksane` |SANE library interface for KDE |`libkscreen` |Plasma5 screen management library |`libksieve` |Sieve libriares for KDEPim |`libksysguard` |Plasma5 library to track and control running processes |`mailcommon` |Common libriares for KDEPim |`mailimporter` |Import mbox files to KMail |`mailtransport` |KDE library to managing mail transport |`marble` |Virtual globe and world atlas for KDE |`mbox` |KDE library for accessing mail storages in MBox format |`mbox-importer` |Import mbox files to KMail |`mediaplayer` |KF5 plugin interface for media player features |`messagelib` |Library for handling messages |`milou` |Plasma5 Plasmoid for search |`mime` |Library for handling MIME data |`newstuff` |KF5 library for downloading application assets from the network |`notifications` |KF5 abstraction for system notifications |`notifyconfig` |KF5 configuration system for KNotify |`okular` |KDE universal document viewer |`oxygen` |Plasma5 Oxygen style |`oxygen-icons5` |The Oxygen icon theme for KDE |`package` |KF5 library to load and install packages |`parts` |KF5 document centric plugin system |`people` |KF5 library providing access to contacts |`pim-data-exporter` |Import and export KDE PIM settings |`pimcommon` |Common libriares for KDEPim |`pimtextedit` |KDE library for PIM-specific text editing utilities |`plasma-browser-integration` |Plasma5 components to integrate browsers into the desktop |`plasma-desktop` |Plasma5 plasma desktop |`plasma-framework` |KF5 plugin based UI runtime used to write user interfaces |`plasma-integration` |Qt Platform Theme integration plugins for the Plasma workspaces |`plasma-pa` |Plasma5 Plasma pulse audio mixer |`plasma-sdk` |Plasma5 applications useful for Plasma development |`plasma-workspace` |Plasma5 Plasma workspace |`plasma-workspace-wallpapers` |Plasma5 wallpapers |`plotting` |KF5 lightweight plotting framework |`polkit-kde-agent-1` |Plasma5 daemon providing a polkit authentication UI |`powerdevil` |Plasma5 tool to manage the power consumption settings |`prison` |API to produce barcodes |`pty` |KF5 pty abstraction |`purpose` |Offers available actions for a specific purpose |`qqc2-desktop-style` |Qt QuickControl2 style for KDE |`runner` |KF5 parallelized query system |`service` |KF5 advanced plugin and service introspection |`solid` |KF5 hardware integration and detection |`sonnet` |KF5 plugin-based spell checking library |`syndication` |KDE RSS feed handling library |`syntaxhighlighting` |KF5 syntax highlighting engine for structured text and code |`systemsettings` |Plasma5 system settings |`texteditor` |KF5 advanced embeddable text editor |`textwidgets` |KF5 advanced text editing widgets |`threadweaver` |KF5 addons to QtDBus |`tnef` |KDE API for the handling of TNEF data |`unitconversion` |KF5 library for unit conversion |`user-manager` |Plasma5 user manager |`wallet` |KF5 secure and unified container for user passwords |`wayland` |KF5 Client and Server library wrapper for the Wayland libraries |`widgetsaddons` |KF5 addons to QtWidgets |`windowsystem` |KF5 library for access to the windowing system |`xmlgui` |KF5 user configurable main windows |`xmlrpcclient` |KF5 interaction with XMLRPC services |=== [[kde5-components-example]] .`USE_KDE` Example [example] ==== This is a simple example for a KDE port. `USES= cmake` instructs the port to utilize CMake, a configuration tool widely used by KDE projects (see <> for detailed usage). `USE_KDE` brings dependency on KDE libraries. Required KDE components and other dependencies can be determined through the configure log. `USE_KDE` does not imply `USE_QT`. If a port requires some Qt components, specify them in `USE_QT`. [.programlisting] .... USES= cmake kde:5 qt:5 USE_KDE= ecm USE_QT= core buildtools_build qmake_build .... ==== [[using-lxqt]] == Using LXQt Applications depending on LXQt should set `USES+= lxqt` and set `USE_LXQT` to the list of required components from the table below [[using-lxqt-components]] .Available LXQt Components [cols="1,1", frame="none", options="header"] |=== | Name | Description |`buildtools` |Helpers for additional CMake modules |`libfmqt` |Libfm Qt bindings |`lxqt` |LXQt core library |`qtxdg` |Qt implementation of freedesktop.org XDG specifications |=== [[lxqt-components-example]] .`USE_LXQT` Example [example] ==== This is a simple example, `USE_LXQT` adds a dependency on LXQt libraries. Required LXQt components and other dependencies can be determined from the configure log. [.programlisting] .... USES= cmake lxqt qt:5 tar:xz USE_QT= core dbus widgets buildtools_build qmake_build USE_LXQT= buildtools libfmqt .... ==== [[using-java]] == Using Java [[java-variables]] === Variable Definitions If the port needs a Java(TM) Development Kit (JDK(TM)) to either build, run or even extract the distfile, then define `USE_JAVA`. There are several JDKs in the ports collection, from various vendors, and in several versions. If the port must use a particular version, specify it using the `JAVA_VERSION` variable. The most current version is package:java/openjdk18[], with package:java/openjdk17[], package:java/openjdk16[], package:java/openjdk15[], package:java/openjdk14[], package:java/openjdk13[], package:java/openjdk12[], package:java/openjdk11[], package:java/openjdk8[], and package:java/openjdk7[] also available. [[using-java-variables]] .Variables Which May be Set by Ports That Use Java [cols="1,1", frame="none", options="header"] |=== | Variable | Means |`USE_JAVA` |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: `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`). |`JAVA_VENDOR` |List of space-separated suitable JDK port vendors for the port (allowed values: `openjdk oracle`). |`JAVA_BUILD` |When set, add the selected JDK port to the build dependencies. |`JAVA_RUN` |When set, add the selected JDK port to the run dependencies. |`JAVA_EXTRACT` |When set, add the selected JDK port to the extract dependencies. |=== Below is the list of all settings a port will receive after setting `USE_JAVA`: [[using-java-variables2]] .Variables Provided to Ports That Use Java [cols="1,1", frame="none", options="header"] |=== | Variable | Value |`JAVA_PORT` |The name of the JDK port (for example, `java/openjdk6`). |`JAVA_PORT_VERSION` |The full version of the JDK port (for example, `1.6.0`). Only the first two digits of this version number are needed, use `${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}`. |`JAVA_PORT_OS` |The operating system used by the JDK port (for example, `'native'`). |`JAVA_PORT_VENDOR` |The vendor of the JDK port (for example, `'openjdk'`). |`JAVA_PORT_OS_DESCRIPTION` |Description of the operating system used by the JDK port (for example, `'Native'`). |`JAVA_PORT_VENDOR_DESCRIPTION` |Description of the vendor of the JDK port (for example, `'OpenJDK BSD Porting Team'`). |`JAVA_HOME` |Path to the installation directory of the JDK (for example, [.filename]#'/usr/local/openjdk6'#). |`JAVAC` |Path to the Java compiler to use (for example, [.filename]#'/usr/local/openjdk6/bin/javac'#). |`JAR` |Path to the `jar` tool to use (for example, [.filename]#'/usr/local/openjdk6/bin/jar'# or [.filename]#'/usr/local/bin/fastjar'#). |`APPLETVIEWER` |Path to the `appletviewer` utility (for example, [.filename]#'/usr/local/openjdk6/bin/appletviewer'#). |`JAVA` |Path to the `java` executable. Use this for executing Java programs (for example, [.filename]#'/usr/local/openjdk6/bin/java'#). |`JAVADOC` |Path to the `javadoc` utility program. |`JAVAH` |Path to the `javah` program. |`JAVAP` |Path to the `javap` program. |`JAVA_KEYTOOL` |Path to the `keytool` utility program. |`JAVA_N2A` |Path to the `native2ascii` tool. |`JAVA_POLICYTOOL` |Path to the `policytool` program. |`JAVA_SERIALVER` |Path to the `serialver` utility program. |`RMIC` |Path to the RMI stub/skeleton generator, `rmic`. |`RMIREGISTRY` |Path to the RMI registry program, `rmiregistry`. |`RMID` |Path to the RMI daemon program `rmid`. |`JAVA_CLASSES` |Path to the archive that contains the JDK class files, [.filename]#${JAVA_HOME}/jre/lib/rt.jar#. |=== Use the `java-debug` make target to get information for debugging the port. It will display the value of many of the previously listed variables. Additionally, these constants are defined so all Java ports may be installed in a consistent way: [[using-java-constants]] .Constants Defined for Ports That Use Java [cols="1,1", frame="none", options="header"] |=== | Constant | Value |`JAVASHAREDIR` |The base directory for everything related to Java. Default: [.filename]#${PREFIX}/share/java#. |`JAVAJARDIR` |The directory where JAR files is installed. Default: [.filename]#${JAVASHAREDIR}/classes#. |`JAVALIBDIR` |The directory where JAR files installed by other ports are located. Default: [.filename]#${LOCALBASE}/share/java/classes#. |=== The related entries are defined in both `PLIST_SUB` (documented in crossref:plist[plist-sub,Changing pkg-plist Based on Make Variables]) and `SUB_LIST`. [[java-building-with-ant]] === Building with Ant When the port is to be built using Apache Ant, it has to define `USE_ANT`. Ant is thus considered to be the sub-make command. When no `do-build` target is defined by the port, a default one will be set that runs Ant according to `MAKE_ENV`, `MAKE_ARGS` and `ALL_TARGET`. This is similar to the `USES= gmake` mechanism, which is documented in <>. [[java-best-practices]] === Best Practices When porting a Java library, the port has to install the JAR file(s) in [.filename]#${JAVAJARDIR}#, and everything else under [.filename]#${JAVASHAREDIR}/${PORTNAME}# (except for the documentation, see below). To reduce the packing file size, reference the JAR file(s) directly in the [.filename]#Makefile#. Use this statement (where [.filename]#myport.jar# is the name of the JAR file installed as part of the port): [.programlisting] .... PLIST_FILES+= ${JAVAJARDIR}/myport.jar .... When porting a Java application, the port usually installs everything under a single directory (including its JAR dependencies). The use of [.filename]#${JAVASHAREDIR}/${PORTNAME}# is strongly encouraged in this regard. It is up the porter to decide whether the port installs the additional JAR dependencies under this directory or uses the already installed ones (from [.filename]#${JAVAJARDIR}#). When porting a Java(TM) application that requires an application server such as package:www/tomcat7[] to run the service, it is quite common for a vendor to distribute a [.filename]#.war#. A [.filename]#.war# is a Web application ARchive and is extracted when called by the application. Avoid adding a [.filename]#.war# to [.filename]#pkg-plist#. It is not considered best practice. An application server will expand war archive, but not clean it up properly if the port is removed. A more desirable way of working with this file is to extract the archive, then install the files, and lastly add these files to [.filename]#pkg-plist#. [.programlisting] .... TOMCATDIR= ${LOCALBASE}/apache-tomcat-7.0 WEBAPPDIR= myapplication post-extract: @${MKDIR} ${WRKDIR}/${PORTDIRNAME} @${TAR} xf ${WRKDIR}/myapplication.war -C ${WRKDIR}/${PORTDIRNAME} do-install: cd ${WRKDIR} && \ ${INSTALL} -d -o ${WWWOWN} -g ${WWWGRP} ${TOMCATDIR}/webapps/${PORTDIRNAME} cd ${WRKDIR}/${PORTDIRNAME} && ${COPYTREE_SHARE} \* ${WEBAPPDIR}/${PORTDIRNAME} .... Regardless of the type of port (library or application), the additional documentation is installed in the crossref:makefiles[install-documentation,same location] as for any other port. The Javadoc tool is known to produce a different set of files depending on the version of the JDK that is used. For ports that do not enforce the use of a particular JDK, it is therefore a complex task to specify the packing list ([.filename]#pkg-plist#). This is one reason why porters are strongly encouraged to use `PORTDOCS`. Moreover, even if the set of files that will be generated by `javadoc` can be predicted, the size of the resulting [.filename]#pkg-plist# advocates for the use of `PORTDOCS`. The default value for `DATADIR` is [.filename]#${PREFIX}/share/${PORTNAME}#. It is a good idea to override `DATADIR` to [.filename]#${JAVASHAREDIR}/${PORTNAME}# for Java ports. Indeed, `DATADIR` is automatically added to `PLIST_SUB` (documented in crossref:plist[plist-sub,Changing pkg-plist Based on Make Variables]) so use `%%DATADIR%%` directly in [.filename]#pkg-plist#. As for the choice of building Java ports from source or directly installing them from a binary distribution, there is no defined policy at the time of writing. However, people from the https://www.freebsd.org/java/[FreeBSD Java Project] encourage porters to have their ports built from source whenever it is a trivial task. All the features that have been presented in this section are implemented in [.filename]#bsd.java.mk#. If the port needs more sophisticated Java support, please first have a look at the https://cgit.FreeBSD.org/ports/tree/Mk/bsd.java.mk[bsd.java.mk Git log] as it usually takes some time to document the latest features. Then, if the needed support that is lacking would be beneficial to many other Java ports, feel free to discuss it on the freebsd-java. Although there is a `java` category for PRs, it refers to the JDK porting effort from the FreeBSD Java project. Therefore, submit the Java port in the `ports` category as for any other port, unless the issue is related to either a JDK implementation or [.filename]#bsd.java.mk#. Similarly, there is a defined policy regarding the `CATEGORIES` of a Java port, which is detailed in crossref:makefiles[makefile-categories,Categorization]. [[using-php]] == Web Applications, Apache and PHP [[using-apache]] === Apache [[using-apache-variables]] .Variables for Ports That Use Apache [cols="1,1", frame="none"] |=== |`USE_APACHE` |The port requires Apache. Possible values: `yes` (gets any version), `22`, `24`, `22-24`, `22+`, etc. The default APACHE version is `22`. More details are available in [.filename]#ports/Mk/bsd.apache.mk# and at https://wiki.freebsd.org/Apache/[wiki.freebsd.org/Apache/]. |`APXS` |Full path to the `apxs` binary. Can be overridden in the port. |`HTTPD` |Full path to the `httpd` binary. Can be overridden in the port. |`APACHE_VERSION` |The version of present Apache installation (read-only variable). This variable is only available after inclusion of [.filename]#bsd.port.pre.mk#. Possible values: `22`, `24`. |`APACHEMODDIR` |Directory for Apache modules. This variable is automatically expanded in [.filename]#pkg-plist#. |`APACHEINCLUDEDIR` |Directory for Apache headers. This variable is automatically expanded in [.filename]#pkg-plist#. |`APACHEETCDIR` |Directory for Apache configuration files. This variable is automatically expanded in [.filename]#pkg-plist#. |=== [[using-apache-modules]] .Useful Variables for Porting Apache Modules [cols="1,1", frame="none"] |=== |`MODULENAME` |Name of the module. Default value is `PORTNAME`. Example: `mod_hello` |`SHORTMODNAME` |Short name of the module. Automatically derived from `MODULENAME`, but can be overridden. Example: `hello` |`AP_FAST_BUILD` |Use `apxs` to compile and install the module. |`AP_GENPLIST` |Also automatically creates a [.filename]#pkg-plist#. |`AP_INC` |Adds a directory to a header search path during compilation. |`AP_LIB` |Adds a directory to a library search path during compilation. |`AP_EXTRAS` |Additional flags to pass to `apxs`. |=== [[web-apps]] === Web Applications Web applications must be installed into [.filename]#PREFIX/www/appname#. This path is available both in [.filename]#Makefile# and in [.filename]#pkg-plist# as `WWWDIR`, and the path relative to `PREFIX` is available in [.filename]#Makefile# as `WWWDIR_REL`. The user and group of web server process are available as `WWWOWN` and `WWWGRP`, in case the ownership of some files needs to be changed. The default values of both are `www`. Use `WWWOWN?= myuser` and `WWWGRP?= mygroup` if the port needs different values. This allows the user to override them easily. [IMPORTANT] ==== Use `WWWOWN` and `WWWGRP` sparingly. Remember that every file the web server can write to is a security risk waiting to happen. ==== Do not depend on Apache unless the web app explicitly needs Apache. Respect that users may wish to run a web application on a web server other than Apache. [[php-variables]] === PHP PHP web applications declare their dependency on it with `USES=php`. See crossref:uses[uses-php,`php`] for more information. [[php-pear]] === PEAR Modules Porting PEAR modules is a very simple process. Add `USES=pear` to the port's [.filename]#Makefile#. The framework will install the relevant files in the right places and automatically generate the plist at install time. [[pear-makefile]] .Example Makefile for PEAR Class [example] ==== [.programlisting] .... PORTNAME= Date DISTVERSION= 1.4.3 CATEGORIES= devel www pear MAINTAINER= someone@example.org COMMENT= PEAR Date and Time Zone Classes WWW= https://pear.php.net/package/Date/ USES= pear .include .... ==== [TIP] ==== PEAR modules will automatically be flavorized using crossref:flavors[flavors-auto-php,PHP flavors]. ==== [NOTE] ==== If a non default `PEAR_CHANNEL` is used, the build and run-time dependencies will automatically be added. ==== [IMPORTANT] ==== PEAR modules do not need to defined `PKGNAMESUFFIX` it is automatically filled in using `PEAR_PKGNAMEPREFIX`. If a port needs to add to `PKGNAMEPREFIX`, it must also use `PEAR_PKGNAMEPREFIX` to differentiate between different flavors. ==== [[php-horde]] ==== Horde Modules In the same way, porting Horde modules is a simple process. Add `USES=horde` to the port's [.filename]#Makefile#. The framework will install the relevant files in the right places and automatically generate the plist at install time. The `USE_HORDE_BUILD` and `USE_HORDE_RUN` variables can be used to add buildtime and runtime dependencies on other Horde modules. See [.filename]#Mk/Uses/horde.mk# for a complete list of available modules. [[horde-Makefile]] .Example Makefile for Horde Module [example] ==== [.programlisting] .... PORTNAME= Horde_Core DISTVERSION= 2.14.0 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 SOCKETS_DESC= Depend on sockets PHP extension USES= horde USE_PHP= session USE_HORDE_BUILD= Horde_Role USE_HORDE_RUN= Horde_Role Horde_History Horde_Pack \ Horde_Text_Filter Horde_View KOLAB_USE= HORDE_RUN=Horde_Kolab_Server,Horde_Kolab_Session SOCKETS_USE= PHP=sockets .include .... ==== [TIP] ==== As Horde modules are also PEAR modules they will also automatically be flavorized using crossref:flavors[flavors-auto-php,PHP flavors]. ==== [[using-python]] == Using Python The Ports Collection supports parallel installation of multiple Python versions. Ports must use a correct `python` interpreter, according to the user-settable `PYTHON_VERSION`. Most prominently, this means replacing the path to `python` executable in scripts with the value of `PYTHON_CMD`. Ports that install files under `PYTHON_SITELIBDIR` must use the `pyXY-` package name prefix, so their package name embeds the version of Python they are installed into. [.programlisting] .... PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX} .... [[using-python-variables]] .Most Useful Variables for Ports That Use Python [cols="1,1", frame="none"] |=== |`USES=python` |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`. |`USE_PYTHON=autoplist` |Create the packaging list automatically. This also requires `USE_PYTHON=distutils` to be set. |`USE_PYTHON=concurrent` |The port will use an unique prefix, typically `PYTHON_PKGNAMEPREFIX` for certain directories, such as `EXAMPLESDIR` and `DOCSDIR` and also will append a suffix, the python version from `PYTHON_VER`, to binaries and scripts to be installed. This allows ports to be installed for different Python versions at the same time, which otherwise would install conflicting files. |`USE_PYTHON=flavors` |The port does not use distutils but still supports multiple Python versions. `FLAVORS` will be set to the supported Python versions. See crossref:flavors[flavors-auto-python,`USES`=python and Flavors] for more information. |`USE_PYTHON=optsuffix` |If the current Python version is not the default version, the port will gain `PKGNAMESUFFIX=${PYTHON_PKGNAMESUFFIX}`. Only useful with flavors. |`PYTHON_PKGNAMEPREFIX` |Used as a `PKGNAMEPREFIX` to distinguish packages for different Python versions. Example: `py27-` |`PYTHON_SITELIBDIR` |Location of the site-packages tree, that contains installation path of Python (usually `LOCALBASE`). `PYTHON_SITELIBDIR` can be very useful when installing Python modules. |`PYTHONPREFIX_SITELIBDIR` |The PREFIX-clean variant of PYTHON_SITELIBDIR. Always use `%%PYTHON_SITELIBDIR%%` in [.filename]#pkg-plist# when possible. The default value of `%%PYTHON_SITELIBDIR%%` is `lib/python%%PYTHON_VERSION%%/site-packages` |`PYTHON_CMD` |Python interpreter command line, including version number. |=== [[using-python-variables-helpers]] .Python Module Dependency Helpers [cols="1,1", frame="none"] |=== |`PYNUMERIC` |Dependency line for numeric extension. |`PYNUMPY` |Dependency line for the new numeric extension, numpy. (PYNUMERIC is deprecated by upstream vendor). |`PYXML` |Dependency line for XML extension (not needed for Python 2.0 and higher as it is also in base distribution). |`PY_ENUM34` |Conditional dependency on package:devel/py-enum34[] depending on the Python version. |`PY_ENUM_COMPAT` |Conditional dependency on package:devel/py-enum-compat[] depending on the Python version. |`PY_PATHLIB` |Conditional dependency on package:devel/py-pathlib[] depending on the Python version. |`PY_IPADDRESS` |Conditional dependency on package:net/py-ipaddress[] depending on the Python version. |`PY_FUTURES` |Conditional dependency on package:devel/py-futures[] depending on the Python version. |=== A complete list of available variables can be found in [.filename]#/usr/ports/Mk/Uses/python.mk#. [IMPORTANT] ==== All dependencies to Python ports using crossref:flavors[flavors-auto-python,Python flavors] (either with `USE_PYTHON=distutils` or `USE_PYTHON=flavors`) must have the Python flavor appended to their origin using `@${PY_FLAVOR}`. See <>. ==== [[python-Makefile]] .Makefile for a Simple Python Module [example] ==== [.programlisting] .... PORTNAME= sample DISTVERSION= 1.2.3 CATEGORIES= devel 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} USES= python USE_PYTHON= autoplist distutils .include .... ==== Some Python applications claim to have `DESTDIR` support (which would be required for staging) but it is broken (Mailman up to 2.1.16, for instance). This can be worked around by recompiling the scripts. This can be done, for example, in the `post-build` target. Assuming the Python scripts are supposed to reside in `PYTHONPREFIX_SITELIBDIR` after installation, this solution can be applied: [.programlisting] .... (cd ${STAGEDIR}${PREFIX} \ && ${PYTHON_CMD} ${PYTHON_LIBDIR}/compileall.py \ -d ${PREFIX} -f ${PYTHONPREFIX_SITELIBDIR:S;${PREFIX}/;;}) .... This recompiles the sources with a path relative to the stage directory, and prepends the value of `PREFIX` to the file name recorded in the byte-compiled output file by `-d`. `-f` is required to force recompilation, and the `:S;${PREFIX}/;;` strips prefixes from the value of `PYTHONPREFIX_SITELIBDIR` to make it relative to `PREFIX`. [[using-tcl]] == Using Tcl/Tk The Ports Collection supports parallel installation of multiple Tcl/Tk versions. Ports should try to support at least the default Tcl/Tk version and higher with `USES=tcl`. It is possible to specify the desired version of `tcl` by appending `:_xx_`, for example, `USES=tcl:85`. [[using-tcl-variables]] .The Most Useful Read-Only Variables for Ports That Use Tcl/Tk [cols="1,1", frame="none"] |=== |`TCL_VER` | chosen major.minor version of Tcl |`TCLSH` | full path of the Tcl interpreter |`TCL_LIBDIR` | path of the Tcl libraries |`TCL_INCLUDEDIR` | path of the Tcl C header files |`TK_VER` | chosen major.minor version of Tk |`WISH` | full path of the Tk interpreter |`TK_LIBDIR` | path of the Tk libraries |`TK_INCLUDEDIR` | path of the Tk C header files |=== 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-sdl]] == Using SDL `USE_SDL` is used to autoconfigure the dependencies for ports which use an SDL based library like package:devel/sdl12[] and package:graphics/sdl_image[]. These SDL libraries for version 1.2 are recognized: * sdl: package:devel/sdl12[] * console: package:devel/sdl_console[] * gfx: package:graphics/sdl_gfx[] * image: package:graphics/sdl_image[] * mixer: package:audio/sdl_mixer[] * mm: package:devel/sdlmm[] * net: package:net/sdl_net[] * pango: package:x11-toolkits/sdl_pango[] * sound: package:audio/sdl_sound[] * ttf: package:graphics/sdl_ttf[] These SDL libraries for version 2.0 are recognized: * sdl: package:devel/sdl20[] * gfx: package:graphics/sdl2_gfx[] * image: package:graphics/sdl2_image[] * mixer: package:audio/sdl2_mixer[] * net: package:net/sdl2_net[] * ttf: package:graphics/sdl2_ttf[] Therefore, if a port has a dependency on package:net/sdl_net[] and package:audio/sdl_mixer[], the syntax will be: [.programlisting] .... USE_SDL= net mixer .... The dependency package:devel/sdl12[], which is required by package:net/sdl_net[] and package:audio/sdl_mixer[], is automatically added as well. Using `USE_SDL` with entries for SDL 1.2, it will automatically: * Add a dependency on sdl12-config to `BUILD_DEPENDS` * Add the variable `SDL_CONFIG` to `CONFIGURE_ENV` * Add the dependencies of the selected libraries to `LIB_DEPENDS` Using `USE_SDL` with entries for SDL 2.0, it will automatically: * Add a dependency on sdl2-config to `BUILD_DEPENDS` * Add the variable `SDL2_CONFIG` to `CONFIGURE_ENV` * Add the dependencies of the selected libraries to `LIB_DEPENDS` [[using-wx]] == Using wxWidgets This section describes the status of the wxWidgets libraries in the ports tree and its integration with the ports system. [[wx-introduction]] === Introduction There are many versions of the wxWidgets libraries 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. The obvious disadvantage of this is that each application has to be modified to find the expected version. Fortunately, most of the applications call the `wx-config` script to determine the necessary compiler and linker flags. The script is named differently for every available version. Majority of applications respect an environment variable, or accept a configure argument, to specify which `wx-config` script to call. Otherwise they have to be patched. [[wx-version]] === Version Selection To make the port use a specific version of wxWidgets there are two variables available for defining (if only one is defined the other will be set to a default value): [[wx-ver-sel-table]] .Variables to Select wxWidgets Versions [cols="1,1,1", frame="none", options="header"] |=== | Variable | Description | Default value |`USE_WX` |List of versions the port can use |All available versions |`USE_WX_NOT` |List of versions the port cannot use |None |=== The available wxWidgets versions and the corresponding ports in the tree are: [[wx-widgets-versions-table]] .Available wxWidgets Versions [cols="1,1", frame="none", options="header"] |=== | Version | Port |`2.8` |package:x11-toolkits/wxgtk28[] |`3.0` |package:x11-toolkits/wxgtk30[] |=== The variables in <> can be set to one or more of these combinations separated by spaces: [[wx-widgets-versions-specification]] .wxWidgets Version Specifications [cols="1,1", frame="none", options="header"] |=== | Description | Example |Single version |`2.8` |Ascending range |`2.8+` |Descending range |`3.0-` |Full range (must be ascending) |`2.8-3.0` |=== There are also some variables to select the preferred versions from the available ones. They can be set to a list of versions, the first ones will have higher priority. [[wx-widgets-preferred-version]] .Variables to Select Preferred wxWidgets Versions [cols="1,1", frame="none", options="header"] |=== | Name | Designed for |`WANT_WX_VER` |the port |`WITH_WX_VER` |the user |=== [[wx-components]] === Component Selection There are other applications that, while not being wxWidgets libraries, are related to them. These applications can be specified in `WX_COMPS`. These components are available: [[wx-widgets-components-table]] .Available wxWidgets Components [cols="1,1,1", frame="none", options="header"] |=== | Name | Description | Version restriction |`wx` |main library |none |`contrib` |contributed libraries |`none` |`python` |wxPython (Python bindings) |`2.8-3.0` |=== The dependency type can be selected for each component by adding a suffix separated by a semicolon. If not present then a default type will be used (see <>). These types are available: [[wx-widgets-dependency-table]] .Available wxWidgets Dependency Types [cols="1,1", frame="none", options="header"] |=== | Name | Description |`build` |Component is required for building, equivalent to `BUILD_DEPENDS` |`run` |Component is required for running, equivalent to `RUN_DEPENDS` |`lib` |Component is required for building and running, equivalent to `LIB_DEPENDS` |=== The default values for the components are detailed in this table: [[wx-def-dep-types]] .Default wxWidgets Dependency Types [cols="1,1", frame="none", options="header"] |=== | Component | Dependency type |`wx` |`lib` |`contrib` |`lib` |`python` |`run` |`mozilla` |`lib` |`svg` |`lib` |=== [[wx-components-example]] .Selecting wxWidgets Components [example] ==== This fragment corresponds to a port which uses wxWidgets version `2.4` and its contributed libraries. [.programlisting] .... USE_WX= 2.8 WX_COMPS= wx contrib .... ==== [[wx-version-detection]] === Detecting Installed Versions To detect an installed version, define `WANT_WX`. If it is not set to a specific version then the components will have a version suffix. `HAVE_WX` will be filled after detection. [[wx-ver-det-example]] .Detecting Installed wxWidgets Versions and Components [example] ==== This fragment can be used in a port that uses wxWidgets if it is installed, or an option is selected. [.programlisting] .... WANT_WX= yes .include .if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.8) USE_WX= 2.8 CONFIGURE_ARGS+= --enable-wx .endif .... This fragment can be used in a port that enables wxPython support if it is installed or if an option is selected, in addition to wxWidgets, both version `2.8`. [.programlisting] .... USE_WX= 2.8 WX_COMPS= wx WANT_WX= 2.8 .include .if defined(WITH_WXPYTHON) || !empty(PORT_OPTIONS:MWXPYTHON) || !empty(HAVE_WX:Mpython) WX_COMPS+= python CONFIGURE_ARGS+= --enable-wxpython .endif .... ==== [[wx-defined-variables]] === Defined Variables These variables are available in the port (after defining one from <>). [[wx-widgets-variables]] .Variables Defined for Ports That Use wxWidgets [cols="1,1", frame="none", options="header"] |=== | Name | Description |`WX_CONFIG` |The path to the wxWidgets`wx-config` script (with different name) |`WXRC_CMD` |The path to the wxWidgets`wxrc` program (with different name) |`WX_VERSION` |The wxWidgets version that is going to be used (for example, `2.6`) |=== [[wx-premk]] === Processing in [.filename]#bsd.port.pre.mk# Define `WX_PREMK` to be able to use the variables right after including [.filename]#bsd.port.pre.mk#. [IMPORTANT] ==== When defining `WX_PREMK`, then the version, dependencies, components and defined variables will not change if modifying the wxWidgets port variables _after_ including [.filename]#bsd.port.pre.mk#. ==== [[wx-premk-example]] .Using wxWidgets Variables in Commands [example] ==== This fragment illustrates the use of `WX_PREMK` by running the `wx-config` script to obtain the full version string, assign it to a variable and pass it to the program. [.programlisting] .... USE_WX= 2.8 WX_PREMK= yes .include .if exists(${WX_CONFIG}) VER_STR!= ${WX_CONFIG} --release PLIST_SUB+= VERSION="${VER_STR}" .endif .... ==== [NOTE] ==== The wxWidgets variables can be safely used in commands when they are inside targets without the need of `WX_PREMK`. ==== [[wx-additional-config-args]] === Additional `configure` Arguments Some GNU `configure` scripts cannot find wxWidgets with just the `WX_CONFIG` environment variable set, requiring additional arguments. `WX_CONF_ARGS` can be used for provide them. [[wx-conf-args-values]] .Legal Values for `WX_CONF_ARGS` [cols="1,1", frame="none", options="header"] |=== | Possible value | Resulting argument |`absolute` |`--with-wx-config=${WX_CONFIG}` |`relative` |`--with-wx=${LOCALBASE} --with-wx-config=${WX_CONFIG:T}` |=== [[using-lua]] == Using Lua This section describes the status of the Lua libraries in the ports tree and its integration with the ports system. [[lua-introduction]] === Introduction There are many versions of the Lua 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. The obvious disadvantage of this is that each application has to be modified to find the expected version. But it can be solved by adding some additional flags to the compiler and linker. Applications that use Lua should normally build for just one version. However, loadable modules for Lua are built in a separate flavor for each Lua version that they support, and dependencies on such modules should specify the flavor using the `@${LUA_FLAVOR}` suffix on the port origin. [[lua-version]] === Version Selection A port using Lua should have a line of this form: [.programlisting] .... USES= lua .... If a specific version of Lua, or range of versions, is needed, it can be specified as a parameter in the form `XY` (which may be used multiple times), `XY+`, `-XY`, or `XY-ZA`. The default version of Lua as set via `DEFAULT_VERSIONS` will be used if it falls in the requested range, otherwise the closest requested version to the default will be used. For example: [.programlisting] .... USES= lua:52-53 .... Note that no attempt is made to adjust the version selection based on the presence of any already-installed Lua version. [NOTE] ==== The `XY+` form of version specification should not be used without careful consideration; the Lua API changes to some extent in every version, and configuration tools like CMake or Autoconf will often fail to work on future versions of Lua until updated to do so. ==== [[lua-version-config]] === Configuration and Compiler flags 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: * 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]] === Version Flavors A port which installs a Lua module (rather than an application that simply makes use of Lua) should build a separate flavor for each supported Lua version. This is done by adding the `module` parameter: [.programlisting] .... USES= lua:module .... A version number or range of versions can be specified as well; use a comma to separate parameters. Since each flavor must have a different package name, the variable `LUA_PKGNAMEPREFIX` is provided which will be set to an appropriate value; the intended usage is: [.programlisting] .... PKGNAMEPREFIX= ${LUA_PKGNAMEPREFIX} .... Module ports should normally install files only to `LUA_MODLIBDIR`, `LUA_MODSHAREDIR`, `LUA_DOCSDIR`, and `LUA_EXAMPLESDIR`, all of which are set up to refer to version-specific subdirectories. Installing any other files must be done with care to avoid conflicts between versions. A port (other than a Lua module) which wishes to build a separate package for each Lua version should use the `flavors` parameter: [.programlisting] .... 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`. 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`. [[lua-defined-variables]] === Defined Variables These variables are available in the port. [[using-lua-variables-ports]] .Variables Defined for Ports That Use Lua [cols="1,1", frame="none", options="header"] |=== | Name | Description |`LUA_VER` |The Lua version that is going to be used (for example, `5.4`) |`LUA_VER_STR` |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 |`LUA_BASE` |The prefix that should be used to locate Lua (and components) that are already installed |`LUA_PREFIX` |The prefix where Lua (and components) are to be installed by this port |`LUA_INCDIR` |The directory where Lua header files are installed |`LUA_LIBDIR` |The directory where Lua libraries are installed |`LUA_REFMODLIBDIR` |The directory where Lua module libraries ([.filename]#.so#) that are already installed are to be found |`LUA_REFMODSHAREDIR` |The directory where Lua modules ([.filename]#.lua#) that are already installed are to be found |`LUA_MODLIBDIR` |The directory where Lua module libraries ([.filename]#.so#) are to be installed by this port |`LUA_MODSHAREDIR` |The directory where Lua modules ([.filename]#.lua#) are to be installed by this port |`LUA_PKGNAMEPREFIX` |The package name prefix used by Lua modules |`LUA_CMD` |The name of the Lua interpreter (e.g. `lua54`) |`LUAC_CMD` |The name of the Lua compiler (e.g. `luac54`) |=== These additional variables are available for ports that specified the `module` parameter: [[using-lua-variables-modules]] .Variables Defined for Lua Module Ports [cols="1,1", frame="none", options="header"] |=== | Name | Description |`LUA_DOCSDIR` |the directory to which the module's documentation should be installed. |`LUA_EXAMPLESDIR` |the directory to which the module's example files should be installed. |=== [[lua-examples]] === Examples [[lua-app-Makefile]] .Makefile for an application using Lua [example] ==== This example shows how to reference a Lua module required at run time. Notice that the reference must specify a flavor. [.programlisting] .... PORTNAME= sample DISTVERSION= 1.2.3 CATEGORIES= whatever 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} USES= lua .include .... ==== [[lua-mod-Makefile]] .Makefile for a simple Lua module [example] ==== [.programlisting] .... PORTNAME= sample DISTVERSION= 1.2.3 CATEGORIES= whatever PKGNAMEPREFIX= ${LUA_PKGNAMEPREFIX} MAINTAINER= fred.bloggs@example.com COMMENT= Sample WWW= https://example.com/lua_sample/sample/ USES= lua:module DOCSDIR= ${LUA_DOCSDIR} .include .... ==== [[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 .... ==== [[using-iconv]] == Using `iconv` FreeBSD has a native `iconv` in the operating system. For software that needs `iconv`, define `USES=iconv`. When a port defines `USES=iconv`, these variables will be available: [.informaltable] [cols="1,1,1,1", frame="none", options="header"] |=== | Variable name | Purpose | Port iconv (when using WCHAR_T or //TRANSLIT extensions) | Base iconv |`ICONV_CMD` |Directory where the `iconv` binary resides |`${LOCALBASE}/bin/iconv` |[.filename]#/usr/bin/iconv# |`ICONV_LIB` |`ld` argument to link to [.filename]#libiconv# (if needed) |`-liconv` |(empty) |`ICONV_PREFIX` |Directory where the `iconv` implementation resides (useful for configure scripts) |`${LOCALBASE}` |[.filename]#/usr# |`ICONV_CONFIGURE_ARG` |Preconstructed configure argument for configure scripts |`--with-libiconv-prefix=${LOCALBASE}` |(empty) |`ICONV_CONFIGURE_BASE` |Preconstructed configure argument for configure scripts |`--with-libiconv=${LOCALBASE}` |(empty) |=== These two examples automatically populate the variables with the correct value for systems using package:converters/libiconv[] or the native `iconv` respectively: [[iconv-simple-use]] .Simple `iconv` Usage [example] ==== [.programlisting] .... USES= iconv LDFLAGS+= -L${LOCALBASE}/lib ${ICONV_LIB} .... ==== [[iconv-configure-use]] .`iconv` Usage with `configure` [example] ==== [.programlisting] .... USES= iconv CONFIGURE_ARGS+=${ICONV_CONFIGURE_ARG} .... ==== As shown above, `ICONV_LIB` is empty when a native `iconv` is present. This can be used to detect the native `iconv` and respond appropriately. Sometimes a program has an `ld` argument or search path hardcoded in a [.filename]#Makefile# or configure script. This approach can be used to solve that problem: [[iconv-reinplace]] .Fixing Hardcoded `-liconv` [example] ==== [.programlisting] .... USES= iconv post-patch: @${REINPLACE_CMD} -e 's/-liconv/${ICONV_LIB}/' ${WRKSRC}/Makefile .... ==== In some cases it is necessary to set alternate values or perform operations depending on whether there is a native `iconv`. [.filename]#bsd.port.pre.mk# must be included before testing the value of `ICONV_LIB`: [[iconv-conditional]] .Checking for Native `iconv` Availability [example] ==== [.programlisting] .... USES= iconv .include post-patch: .if empty(ICONV_LIB) # native iconv detected @${REINPLACE_CMD} -e 's|iconv||' ${WRKSRC}/Config.sh .endif .include .... ==== [[using-xfce]] == Using Xfce Ports that need Xfce libraries or applications set `USES=xfce`. Specific Xfce library and application dependencies are set with values assigned to `USE_XFCE`. They are defined in [.filename]#/usr/ports/Mk/Uses/xfce.mk#. The possible values are: .Values of `USE_XFCE` garcon:: package:sysutils/garcon[] libexo:: package:x11/libexo[] libgui:: package:x11-toolkits/libxfce4gui[] libmenu:: package:x11/libxfce4menu[] libutil:: package:x11/libxfce4util[] panel:: package:x11-wm/xfce4-panel[] thunar:: package:x11-fm/thunar[] xfconf:: package:x11/xfce4-conf[] [[use-xfce]] .`USES=xfce` Example [example] ==== [.programlisting] .... USES= xfce USE_XFCE= libmenu .... ==== [[use-xfce-gtk2]] .Using Xfce's Own GTK2 Widgets [example] ==== In this example, the ported application uses the GTK2-specific widgets package:x11/libxfce4menu[] and package:x11/xfce4-conf[]. [.programlisting] .... USES= xfce:gtk2 USE_XFCE= libmenu xfconf .... ==== [TIP] ==== Xfce components included this way will automatically include any dependencies they need. It is no longer necessary to specify the entire list. If the port only needs package:x11-wm/xfce4-panel[], use: [.programlisting] .... USES= xfce USE_XFCE= panel .... There is no need to list the components package:x11-wm/xfce4-panel[] needs itself like this: [.programlisting] .... USES= xfce USE_XFCE= libexo libmenu libutil panel .... However, Xfce components and non-Xfce dependencies of the port must be included explicitly. 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 Use one of the `USES` macros from <> to add a dependency on a database. [[using-databases-uses]] .Database `USES` Macros [cols="1,1", frame="none", options="header"] |=== | Database | USES Macro |Berkeley DB |crossref:uses[uses-bdb,`bdb`] |MariaDB, MySQL, Percona |crossref:uses[uses-mysql,`mysql`] |PostgreSQL |crossref:uses[uses-pgsql,`pgsql`] |SQLite |crossref:uses[uses-sqlite,`sqlite`] |=== [[using-databases-bdb-ex1]] .Using Berkeley DB 6 [example] ==== [.programlisting] .... USES= bdb:6 .... See crossref:uses[uses-bdb,`bdb`] for more information. ==== [[using-databases-mysql-ex1]] .Using MySQL [example] ==== When a port needs the MySQL client library add [.programlisting] .... USES= mysql .... See crossref:uses[uses-mysql,`mysql`] for more information. ==== [[using-databases-pgsql-ex1]] .Using PostgreSQL [example] ==== When a port needs the PostgreSQL server version 9.6 or later add [.programlisting] .... USES= pgsql:9.6+ WANT_PGSQL= server .... See crossref:uses[uses-pgsql,`pgsql`] for more information. ==== [[using-databases-sqlite-ex1]] .Using SQLite 3 [example] ==== [.programlisting] .... USES= sqlite:3 .... See crossref:uses[uses-sqlite,`sqlite`] for more information. ==== [[rc-scripts]] == Starting and Stopping Services (`rc` Scripts) [.filename]#rc.d# scripts are used to start services on system startup, and to give administrators a standard way of stopping, starting and restarting the service. Ports integrate into the system [.filename]#rc.d# framework. Details on its usage can be found in extref:{handbook}[the rc.d Handbook chapter, configtuning-rcd]. Detailed explanation of the available commands is provided in man:rc[8] and man:rc.subr[8]. Finally, there is extref:{rc-scripting}[an article] on practical aspects of [.filename]#rc.d# scripting. With a mythical port called _doorman_, which needs to start a _doormand_ daemon. Add the following to the [.filename]#Makefile#: [.programlisting] .... USE_RC_SUBR= doormand .... Multiple scripts may be listed and will be installed. Scripts must be placed in the [.filename]#files# subdirectory and a `.in` suffix must be added to their filename. Standard `SUB_LIST` expansions will be ran against this file. Use of the `%%PREFIX%%` and `%%LOCALBASE%%` expansions is strongly encouraged as well. More on `SUB_LIST` in crossref:pkg-files[using-sub-files,the relevant section]. As of FreeBSD 6.1-RELEASE, local [.filename]#rc.d# scripts (including those installed by ports) are included in the overall man:rcorder[8] of the base system. An example simple [.filename]#rc.d# script to start the doormand daemon: [.programlisting] .... #!/bin/sh # PROVIDE: doormand # REQUIRE: LOGIN # KEYWORD: shutdown # # Add these lines to /etc/rc.conf.local or /etc/rc.conf # to enable this service: # # doormand_enable (bool): Set to NO by default. # Set it to YES to enable doormand. # doormand_config (path): Set to %%PREFIX%%/etc/doormand/doormand.cf # by default. . /etc/rc.subr name=doormand rcvar=doormand_enable load_rc_config $name : ${doormand_enable:="NO"} : ${doormand_config="%%PREFIX%%/etc/doormand/doormand.cf"} command=%%PREFIX%%/sbin/${name} pidfile=/var/run/${name}.pid command_args="-p $pidfile -f $doormand_config" run_rc_command "$1" .... Unless there is a very good reason to start the service earlier, or it runs as a particular user (other than root), all ports scripts must use: [.programlisting] .... REQUIRE: LOGIN .... If the startup script launches a daemon that must be shutdown, the following will trigger a stop of the service on system shutdown: [.programlisting] .... KEYWORD: shutdown .... If the script is not starting a persistent service this is not necessary. For optional configuration elements the "=" style of default variable assignment is preferable to the ":=" style here, since the former sets a default value only if the variable is unset, and the latter sets one if the variable is unset _or_ null. A user might very well include something like: [.programlisting] .... doormand_flags="" .... in their [.filename]#rc.conf.local#, and a variable substitution using ":=" would inappropriately override the user's intention. The `_enable` variable is not optional, and must use the ":" for the default. [IMPORTANT] ==== Ports _must not_ start and stop their services when installing and deinstalling. Do not abuse the [.filename]#plist# keywords described in crossref:plist[plist-keywords-base-exec, "the @preexec command,@postexec command,@preunexec command,@postunexec command section"] by running commands that modify the currently running system, including starting or stopping services. ==== [[rc-scripts-checklist]] === Pre-Commit Checklist Before contributing a port with an [.filename]#rc.d# script, and more importantly, before committing one, please consult this checklist to be sure that it is ready. The package:devel/rclint[] port can check for most of these, but it is not a substitute for proper review. [.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. . 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`. . Make sure there is no `KEYWORD: FreeBSD` present. This has not been necessary nor desirable for years. It is also an indication that the new script was copy/pasted from an old script, so extra caution must be given to the review. . If the script uses an interpreted language like `perl`, `python`, or `ruby`, make certain that `command_interpreter` is set appropriately, for example, for Perl, by adding `PERL=${PERL}` to `SUB_LIST` and using `%%PERL%%`. Otherwise, + [source,shell] .... # service name stop .... + will probably not work properly. See man:service[8] for more information. . Have all occurrences of [.filename]#/usr/local# been replaced with `%%PREFIX%%`? . Do the default variable assignments come after `load_rc_config`? . Are there default assignments to empty strings? They should be removed, but double-check that the option is documented in the comments at the top of the file. . Are things that are set in variables actually used in the script? . Are options listed in the default _name_`_flags` things that are actually mandatory? If so, they must be in `command_args`. `-d` is a red flag (pardon the pun) here, since it is usually the option to "daemonize" the process, and therefore is actually mandatory. . `_name__flags` must never be included in `command_args` (and vice versa, although that error is less common). . Does the script execute any code unconditionally? This is frowned on. Usually these things must be dealt with through a `start_precmd`. . All boolean tests must use the `checkyesno` function. No hand-rolled tests for `[Yy][Ee][Ss]`, etc. . If there is a loop (for example, waiting for something to start) does it have a counter to terminate the loop? We do not want the boot to be stuck forever if there is an error. . Does the script create files or directories that need specific permissions, for example, a [.filename]#pid# that needs to be owned by the user that runs the process? Rather than the traditional man:touch[1]/man:chown[8]/man:chmod[1] routine, consider using man:install[1] with the proper command line arguments to do the whole procedure with one step. [[users-and-groups]] == Adding Users and Groups Some ports require a particular user account to be present, usually for daemons that run as that user. For these ports, choose a _unique_ UID from 50 to 999 and register it in [.filename]#ports/UIDs# (for users) and [.filename]#ports/GIDs# (for groups). The unique identification should be the same for users and groups. Please include a patch against these two files when requiring a new user or group to be created for the port. Then use `USERS` and `GROUPS` in [.filename]#Makefile#, and the user will be automatically created when installing the port. [.programlisting] .... USERS= pulse GROUPS= pulse pulse-access pulse-rt .... The current list of reserved UIDs and GIDs can be found in [.filename]#ports/UIDs# and [.filename]#ports/GIDs#. [[requiring-kernel-sources]] == Ports That Rely on Kernel Sources Some ports (such as kernel loadable modules) need the kernel source files so that the port can compile. Here is the correct way to determine if the user has them installed: [.programlisting] .... USES= kmod .... Apart from this check, the `kmod` feature takes care of most items that these ports need to take into account. [[go-libs]] == Go Libraries Ports must not package or install Go libs or source code. Go ports must fetch the required deps at the normal fetch time and should only install the programs and things users need, not the things Go developers would need. Ports should (in order of preference): * Use vendored dependencies included with the package source. * Fetch the versions of deps specified by upstream (in the case of go.mod, vendor.json or similar). * As a last resort (deps are not included nor versions specified exactly) fetch versions of dependencies available at the time of upstream development/release. [[haskell-libs]] == Haskell Libraries Just like in case of Go language, Ports must not package or install Haskell libraries. Haskell ports must link statically to their dependencies and fetch all distribution files on fetch stage. [[shell-completion]] == Shell Completion Files Many modern shells (including bash, fish, tcsh and zsh) support parameter and/or option tab-completion. This support usually comes from completion files, which contain the definitions for how tab completion will work for a certain command. Ports sometimes ship with their own completion files, or porters may have created them themselves. When available, completion files should always be installed. 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]] .Full shell completion file names [cols="1,1,1", frame="none"] |=== |`bash` |[.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/completions/${PORTNAME}.fish# | |`zsh` |[.filename]#${PREFIX}/share/zsh/site-functions/_${PORTNAME}# | |=== Do not register any dependencies on the shells themselves.