# 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: 2026-02-22 15:58+0000\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/porters-handbook/porting-dads/_index.adoc:1 #, no-wrap msgid "A list of common dos and don'ts that are encountered during the FreeBSD porting process" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:1 #, no-wrap msgid "Chapter 13. Dos and Don'ts" msgstr "" #. type: Title = #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:14 #, no-wrap msgid "Dos and Don'ts" msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:54 #, no-wrap msgid "Introduction" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:60 msgid "" "Here is a list of common dos and don'ts that are encountered during the " "porting process. Check the port against this list, but also check ports in " "the https://bugs.FreeBSD.org/search/[PR database] that others have " "submitted. Submit any comments on ports as described in extref:" "{contributing}[Bug Reports and General Commentary, CONTRIB-GENERAL]. " "Checking ports in the PR database will both make it faster for us to commit " "them, and prove that you know what you are doing." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:62 #, no-wrap msgid "`WRKDIR`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:66 msgid "" "Do not write anything to files outside `WRKDIR`. `WRKDIR` is the only place " "that is guaranteed to be writable during the port build (see extref:" "{handbook}[ installing ports from a CDROM, PORTS-CD] for an example of " "building ports from a read-only tree). The [.filename]##pkg-*## files can " "be modified by crossref:pkg-files[pkg-names,redefining a variable] rather " "than overwriting the file." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:68 #, no-wrap msgid "`WRKDIRPREFIX`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:73 msgid "" "Make sure the port honors `WRKDIRPREFIX`. Most ports do not have to worry " "about this. In particular, when referring to a `WRKDIR` of another port, " "note that the correct location is [.filename]#${WRKDIRPREFIX}${PORTSDIR}/" "subdir/name/work# not [.filename]#${PORTSDIR}/subdir/name/work# or " "[.filename]#${.CURDIR}/../../subdir/name/work# or some such." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:75 #, no-wrap msgid "Differentiating Operating Systems and OS Versions" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:79 msgid "" "Some code needs modifications or conditional compilation based upon what " "version of FreeBSD Unix it is running under. The preferred way to tell " "FreeBSD versions apart are the `{freebsd-version}` and `{freebsd}` macros " "defined in https://cgit.freebsd.org/src/tree/sys/sys/param.h[sys/param.h]. " "If this file is not included add the code," msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:83 #, no-wrap msgid "#include \n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:86 msgid "to the proper place in the [.filename]#.c# file." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:89 msgid "" "`{freebsd}` is defined in all versions of FreeBSD as their major version " "number. For example, in FreeBSD 9.x, `{freebsd}` is defined to be `9`." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:97 #, no-wrap msgid "" "#if __FreeBSD__ >= 9\n" "# if __FreeBSD_version >= 901000\n" "\t /* 9.1+ release specific code here */\n" "# endif\n" "#endif\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:100 msgid "" "A complete list of `{freebsd-version}` values is available in " "crossref:versions[versions,__FreeBSD_version Values]." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:102 #, no-wrap msgid "Writing Something After bsd.port.mk" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:106 msgid "" "Do not write anything after the `.include ` line. It usually " "can be avoided by including [.filename]#bsd.port.pre.mk# somewhere in the " "middle of the [.filename]#Makefile# and [.filename]#bsd.port.post.mk# at the " "end." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:110 msgid "" "Include either the [.filename]#bsd.port.pre.mk#/" "[.filename]#bsd.port.post.mk# pair or [.filename]#bsd.port.mk# only; do not " "mix these two usages." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:113 msgid "" "[.filename]#bsd.port.pre.mk# only defines a few variables, which can be used " "in tests in the [.filename]#Makefile#, [.filename]#bsd.port.post.mk# defines " "the rest." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:115 msgid "" "Here are some important variables defined in [.filename]#bsd.port.pre.mk# " "(this is not the complete list, please read [.filename]#bsd.port.mk# for the " "complete list)." msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:120 #, no-wrap msgid "Variable" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:122 #, no-wrap msgid "Description" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:123 #, no-wrap msgid "`ARCH`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:125 #, no-wrap msgid "The architecture as returned by `uname -p` (for example, `i386`)" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:126 #, no-wrap msgid "`OPSYS`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:128 #, no-wrap msgid "The operating system type, as returned by `uname -s` (for example, `FreeBSD`)" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:129 #, no-wrap msgid "`OSREL`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:131 #, no-wrap msgid "The release version of the operating system (for example, `2.1.5` or `2.2.7`)" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:132 #, no-wrap msgid "`OSVERSION`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:134 #, no-wrap msgid "The numeric version of the operating system; the same as crossref:versions[versions,`{freebsd-version}`]." msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:135 #, no-wrap msgid "`LOCALBASE`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:137 #, no-wrap msgid "The base of the \"local\" tree (for example, `/usr/local`)" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:138 #, no-wrap msgid "`PREFIX`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:139 #, no-wrap msgid "Where the port installs itself (see crossref:testing[porting-prefix,more on `PREFIX`])." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:144 msgid "" "When `MASTERDIR` is needed, always define it before including " "[.filename]#bsd.port.pre.mk#." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:147 msgid "" "Here are some examples of things that can be added after " "[.filename]#bsd.port.pre.mk#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:154 #, no-wrap msgid "" "# no need to compile lang/perl5 if perl5 is already in system\n" ".if ${OSVERSION} > 300003\n" "BROKEN=\tperl is in system\n" ".endif\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:157 msgid "Always use tab instead of spaces after `BROKEN=`." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:159 #, no-wrap msgid "Use the `exec` Statement in Wrapper Scripts" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:164 msgid "" "If the port installs a shell script whose purpose is to launch another " "program, and if launching that program is the last action performed by the " "script, make sure to launch the program using the `exec` statement, for " "instance:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:169 #, no-wrap msgid "" "#!/bin/sh\n" "exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar \"$@\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:174 msgid "" "The `exec` statement replaces the shell process with the specified program. " "If `exec` is omitted, the shell process remains in memory while the program " "is executing, and needlessly consumes system resources." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:176 #, no-wrap msgid "Do Things Rationally" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:181 msgid "" "The [.filename]#Makefile# should do things in a simple and reasonable " "manner. Making it a couple of lines shorter or more readable is always " "better. Examples include using a make `.if` construct instead of a shell " "`if` construct, not redefining `do-extract` if redefining `EXTRACT*` is " "enough, and using `GNU_CONFIGURE` instead of `CONFIGURE_ARGS += --prefix=$" "{PREFIX}`." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:184 msgid "" "If a lot of new code is needed to do something, there may already be an " "implementation of it in [.filename]#bsd.port.mk#. While hard to read, there " "are a great many seemingly-hard problems for which [.filename]#bsd.port.mk# " "already provides a shorthand solution." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:186 #, no-wrap msgid "Respect Both `CC` and `CXX`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:192 msgid "" "The port must respect both `CC` and `CXX`. What we mean by this is that the " "port must not set the values of these variables absolutely, overriding " "existing values; instead, it may append whatever values it needs to the " "existing values. This is so that build options that affect all ports can be " "set globally." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:194 msgid "" "If the port does not respect these variables, please add `NO_PACKAGE=ignores " "either cc or cxx` to the [.filename]#Makefile#." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:197 msgid "" "Here is an example of a [.filename]#Makefile# respecting both `CC` and " "`CXX`. Note the `?=`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:201 #, no-wrap msgid "CC?= gcc\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:206 #, no-wrap msgid "CXX?= g++\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:209 msgid "Here is an example which respects neither `CC` nor `CXX`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:213 #, no-wrap msgid "CC= gcc\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:218 #, no-wrap msgid "CXX= g++\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:223 msgid "" "Both `CC` and `CXX` can be defined on FreeBSD systems in [.filename]#/etc/" "make.conf#. The first example defines a value if it was not previously set " "in [.filename]#/etc/make.conf#, preserving any system-wide definitions. The " "second example clobbers anything previously defined." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:225 #, no-wrap msgid "Respect `CFLAGS`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:231 msgid "" "The port must respect `CFLAGS`. What we mean by this is that the port must " "not set the value of this variable absolutely, overriding the existing " "value. Instead, it may append whatever values it needs to the existing " "value. This is so that build options that affect all ports can be set " "globally." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:233 msgid "" "If it does not, please add `NO_PACKAGE=ignores cflags` to the " "[.filename]#Makefile#." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:235 msgid "" "Here is an example of a [.filename]#Makefile# respecting `CFLAGS`. Note the " "`+=`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:239 #, no-wrap msgid "CFLAGS+= -Wall -Werror\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:242 msgid "Here is an example which does not respect `CFLAGS`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:246 #, no-wrap msgid "CFLAGS= -Wall -Werror\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:251 msgid "" "`CFLAGS` is defined on FreeBSD systems in [.filename]#/etc/make.conf#. The " "first example appends additional flags to `CFLAGS`, preserving any system-" "wide definitions. The second example clobbers anything previously defined." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:255 msgid "" "Remove optimization flags from the third party [.filename]##Makefile##s. " "The system `CFLAGS` contains system-wide optimization flags. An example " "from an unmodified [.filename]#Makefile#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:259 #, no-wrap msgid "CFLAGS= -O3 -funroll-loops -DHAVE_SOUND\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:262 msgid "" "Using system optimization flags, the [.filename]#Makefile# would look " "similar to this example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:266 #, no-wrap msgid "CFLAGS+= -DHAVE_SOUND\n" msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:269 #, no-wrap msgid "Verbose Build Logs" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:273 msgid "" "Make the port build system display all commands executed during the build " "stage. Complete build logs are crucial to debugging port problems." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:275 msgid "Non-informative build log example (bad):" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:281 #, no-wrap msgid "" " CC source1.o\n" " CC source2.o\n" " CCLD someprogram\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:284 msgid "Verbose build log example (good):" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:290 #, no-wrap msgid "" "cc -O2 -pipe -I/usr/local/include -c -o source1.o source1.c\n" "cc -O2 -pipe -I/usr/local/include -c -o source2.o source2.c\n" "cc -o someprogram source1.o source2.o -L/usr/local/lib -lsomelib\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:294 msgid "" "Some build systems such as CMake, ninja, and GNU configure are set up for " "verbose logging by the ports framework. In other cases, ports might need " "individual tweaks." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:296 #, no-wrap msgid "Feedback" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:300 msgid "" "Do send applicable changes and patches to the upstream maintainer for " "inclusion in the next release of the code. This makes updating to the next " "release that much easier." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:302 #, no-wrap msgid "README.html" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:306 msgid "" "[.filename]#README.html# is not part of the port, but generated by `make " "readme`. Do not include this file in patches or commits." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:310 msgid "" "If `make readme` fails, make sure that the default value of `ECHO_MSG` has " "not been modified by the port." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:313 #, no-wrap msgid "Marking a Port Not Installable with `BROKEN`, `FORBIDDEN`, or `IGNORE`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:320 msgid "" "In certain cases, users must be prevented from installing a port. There are " "several variables that can be used in a port's [.filename]#Makefile# to tell " "the user that the port cannot be installed. The value of these make " "variables will be the reason that is shown to users for why the port refuses " "to install itself. Please use the correct make variable. Each variable " "conveys radically different meanings, both to users and to automated systems " "that depend on [.filename]##Makefile##s, such as crossref:keeping-up[build-" "cluster,the ports build cluster], and crossref:keeping-" "up[freshports,FreshPorts]." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:322 #, no-wrap msgid "Variables" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:325 msgid "" "`BROKEN` is reserved for ports that currently do not compile, install, " "deinstall, or run correctly. Use it for ports where the problem is believed " "to be temporary." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:328 msgid "" "If instructed, the build cluster will still attempt to try to build them to " "see if the underlying problem has been resolved. (However, in general, the " "cluster is run without this.)" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:330 msgid "For instance, use `BROKEN` when a port:" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:332 msgid "does not compile" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:333 msgid "fails its configuration or installation process" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:334 msgid "installs files outside of [.filename]#${PREFIX}#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:335 msgid "" "does not remove all its files cleanly upon deinstall (however, it may be " "acceptable, and desirable, for the port to leave user-modified files behind)" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:336 msgid "has runtime issues on systems where it is supposed to run fine." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:338 msgid "" "`FORBIDDEN` is used for ports that contain a security vulnerability or " "induce grave concern regarding the security of a FreeBSD system with a given " "port installed (for example, a reputably insecure program or a program that " "provides easily exploitable services). Mark ports as `FORBIDDEN` as soon as " "a particular piece of software has a vulnerability and there is no released " "upgrade. Ideally upgrade ports as soon as possible when a security " "vulnerability is discovered so as to reduce the number of vulnerable FreeBSD " "hosts (we like being known for being secure), however sometimes there is a " "noticeable time gap between disclosure of a vulnerability and an updated " "release of the vulnerable software. Do not mark a port `FORBIDDEN` for any " "reason other than security." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:339 msgid "" "`IGNORE` is reserved for ports that must not be built for some other reason. " "Use it for ports where the problem is believed to be structural. The build " "cluster will not, under any circumstances, build ports marked as `IGNORE`. " "For instance, use `IGNORE` when a port:" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:341 msgid "does not work on the installed version of FreeBSD" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:342 msgid "" "has a distfile which may not be automatically fetched due to licensing " "restrictions" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:343 msgid "" "does not work with some other currently installed port (for instance, the " "port depends on package:www/drupal7[] but package:www/drupal8[] is installed)" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:348 msgid "" "If a port would conflict with a currently installed port (for example, if " "they install a file in the same place that performs a different function), " "crossref:makefiles[conflicts,use `CONFLICTS` instead]. `CONFLICTS` will set " "`IGNORE` by itself." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:351 #, no-wrap msgid "Implementation Notes" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:355 msgid "" "Do not quote the values of `BROKEN`, `IGNORE`, and related variables. Due " "to the way the information is shown to the user, the wording of messages for " "each variable differ:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:359 #, no-wrap msgid "BROKEN=\tfails to link with base -lcrypto\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:364 #, no-wrap msgid "IGNORE=\tunsupported on recent versions\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:367 msgid "resulting in this output from `make describe`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:371 #, no-wrap msgid "===> foobar-0.1 is marked as broken: fails to link with base -lcrypto.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:376 #, no-wrap msgid "===> foobar-0.1 is unsupported on recent versions.\n" msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:379 #, no-wrap msgid "Architectural Considerations" msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:382 #, no-wrap msgid "General Notes on Architectures" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:386 msgid "" "FreeBSD runs on many more processor architectures than just the well-known " "x86-based ones. Some ports have constraints which are particular to one or " "more of these architectures." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:388 msgid "For the list of supported architectures, run:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:392 #, no-wrap msgid "cd ${SRCDIR}; make targets\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:397 msgid "" "The values are shown in the form `TARGET`/`TARGET_ARCH`. The ports read-" "only makevar `ARCH` is set based on the value of `TARGET_ARCH`. Port " "[.filename]##Makefile##s should test the value of this Makevar." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:399 #, no-wrap msgid "Marking a Port as Architecture Neutral" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:402 msgid "" "Ports that do not have any architecture-dependent files or requirements are " "identified by setting `NO_ARCH=yes`." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:404 msgid "" "Packages built from such ports have their architecture string ending in `:*` " "(wildcard architecture) as opposed to, for example, `freebsd:13:x86:64` " "(amd64 architecture)." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:410 msgid "" "`NO_ARCH` is meant to indicate that there is no need to build a package for " "each of the supported architectures. The goal is to reduce the amount of " "resources spent on building and distributing the packages such as network " "bandwidth and disk space on mirrors and on distribution media. Currently, " "however, our package infrastructure (e.g., package managers, mirrors, and " "package builders) is not set up to fully benefit from `NO_ARCH`." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:413 #, no-wrap msgid "Marking a Port as Ignored Only On Certain Architectures" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:416 msgid "" "To mark a port as ``IGNORE``d only on certain architectures, there are two " "other convenience variables that will automatically set `IGNORE`: " "`ONLY_FOR_ARCHS` and `NOT_FOR_ARCHS`. Examples:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:420 #, no-wrap msgid "ONLY_FOR_ARCHS=\ti386 amd64\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:425 #, no-wrap msgid "NOT_FOR_ARCHS=\tia64 sparc64\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:429 msgid "" "A custom `IGNORE` message can be set using `ONLY_FOR_ARCHS_REASON` and " "`NOT_FOR_ARCHS_REASON`. Per architecture entries are possible with " "`ONLY_FOR_ARCHS_REASON_ARCH` and `NOT_FOR_ARCHS_REASON_ARCH`." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:432 msgid "" "If a port fetches i386 binaries and installs them, set `IA32_BINARY_PORT`. " "If this variable is set, [.filename]#/usr/lib32# must be present for IA32 " "versions of libraries and the kernel must support IA32 compatibility. If one " "of these two dependencies is not satisfied, `IGNORE` will be set " "automatically." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:434 #, no-wrap msgid "Cluster-Specific Considerations" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:437 msgid "" "Some ports attempt to tune themselves to the exact machine they are being " "built on by specifying `-march=native` to the compiler. This should be " "avoided: either list it under an off-by-default option, or delete it " "entirely." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:439 msgid "" "Otherwise, the default package produced by the build cluster might not run " "on every single machine of that `ARCH`." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:441 #, no-wrap msgid "Marking a Port for Removal with `DEPRECATED` or `EXPIRATION_DATE`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:445 msgid "" "Do remember that `BROKEN` and `FORBIDDEN` are to be used as a temporary " "resort if a port is not working. Permanently broken ports will be removed " "from the tree entirely." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:449 msgid "" "When it makes sense to do so, users can be warned about a pending port " "removal with `DEPRECATED` and `EXPIRATION_DATE`. The former is a string " "stating why the port is scheduled for removal; the latter is a string in ISO " "8601 format (YYYY-MM-DD). Both will be shown to the user." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:451 msgid "" "It is possible to set `DEPRECATED` without an `EXPIRATION_DATE` (for " "instance, recommending a newer version of the port), but the converse does " "not make any sense." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:457 msgid "" "When marking a port as `DEPRECATED`, if there are any alternative ports that " "can be used as a replacement for the one being deprecated, it is convenient " "to mention them in the commit message." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:462 msgid "" "There is no set policy on how much notice to give. Current practice seems " "to be one month for security-related issues and two months for build " "issues. This also gives any interested committers a little time to fix the " "problems." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:464 #, no-wrap msgid "Avoid Use of the `.error` Construct" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:468 msgid "" "The correct way for a [.filename]#Makefile# to signal that the port cannot " "be installed due to some external factor (for instance, the user has " "specified an illegal combination of build options) is to set a non-blank " "value to `IGNORE`. This value will be formatted and shown to the user by " "`make install`." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:474 msgid "" "It is a common mistake to use `.error` for this purpose. The problem with " "this is that many automated tools that work with the ports tree will fail in " "this situation. The most common occurrence of this is seen when trying to " "build [.filename]#/usr/ports/INDEX# (see crossref:testing[make-" "describe,Running `make describe`]). However, even more trivial commands " "such as `make maintainer` also fail in this scenario. This is not " "acceptable." msgstr "" #. type: Block title #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:476 #, no-wrap msgid "How to Avoid Using `.error`" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:481 msgid "" "The first of the next two [.filename]#Makefile# snippets will cause `make " "index` to fail, while the second one will not:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:485 #, no-wrap msgid ".error \"option is not supported\"\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:490 #, no-wrap msgid "IGNORE=option is not supported\n" msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:495 #, no-wrap msgid "Usage of sysctl" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:500 msgid "" "The usage of [.filename]#sysctl# is discouraged except in targets. This is " "because the evaluation of any ``makevar``s, such as used during `make " "index`, then has to run the command, further slowing down that process." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:502 msgid "" "Only use man:sysctl[8] through `SYSCTL`, as it contains the fully qualified " "path and can be overridden, if one has such a special need." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:504 #, no-wrap msgid "Rerolling Distfiles" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:509 msgid "" "Sometimes the authors of software change the content of released distfiles " "without changing the file's name. Verify that the changes are official and " "have been performed by the author. It has happened in the past that the " "distfile was silently altered on the download servers with the intent to " "cause harm or compromise end user security." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:512 msgid "" "Put the old distfile aside, download the new one, unpack them and compare " "the content with man:diff[1]. If there is nothing suspicious, update " "[.filename]#distinfo#." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:516 msgid "" "Be sure to summarize the differences in the PR and commit log, so that other " "people know that nothing bad has happened." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:519 msgid "Contact the authors of the software and confirm the changes with them." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:521 #, no-wrap msgid "Use POSIX Standards" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:525 msgid "" "FreeBSD ports generally expect POSIX compliance. Some software and build " "systems make assumptions based on a particular operating system or " "environment that can cause problems when used in a port." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:528 msgid "" "Do not use [.filename]#/proc# if there are any other ways of getting the " "information. For example, `setprogname(argv[0])` in `main()` and then " "man:getprogname[3] to know the executable name." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:530 msgid "Do not rely on behavior that is undocumented by POSIX." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:534 msgid "" "Do not record timestamps in the critical path of the application if it also " "works without. Getting timestamps may be slow, depending on the accuracy of " "timestamps in the OS. If timestamps are really needed, determine how " "precise they have to be and use an API which is documented to just deliver " "the needed precision." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:538 msgid "" "A number of simple syscalls (for example man:gettimeofday[2], man:getpid[2]) " "are much faster on Linux(R) than on any other operating system due to " "caching and the vsyscall performance optimizations. Do not rely on them " "being cheap in performance-critical applications. In general, try hard to " "avoid syscalls if possible." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:541 msgid "" "Do not rely on Linux(R)-specific socket behavior. In particular, default " "socket buffer sizes are different (call man:setsockopt[2] with `SO_SNDBUF` " "and `SO_RCVBUF`, and while Linux(R)'s man:send[2] blocks when the socket " "buffer is full, FreeBSD's will fail and set `ENOBUFS` in errno." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:543 msgid "" "If relying on non-standard behavior is required, encapsulate it properly " "into a generic API, do a check for the behavior in the configure stage, and " "stop if it is missing." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:545 msgid "" "Check the https://man.freebsd.org/cgi/man.cgi[man pages] to see if the " "function used is a POSIX interface (in the \"STANDARDS\" section of the man " "page)." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:548 msgid "" "Do not assume that [.filename]#/bin/sh# is bash. Ensure that a command line " "passed to man:system[3] will work with a POSIX compliant shell." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:550 msgid "" "A list of common bashisms is available https://wiki.ubuntu.com/" "DashAsBinSh[here]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:553 msgid "" "Check that headers are included in the POSIX or man page recommended way. " "For example, [.filename]#sys/types.h# is often forgotten, which is not as " "much of a problem for Linux(R) as it is for FreeBSD." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:555 #, no-wrap msgid "Miscellanea" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:559 msgid "" "Always double-check [.filename]#pkg-descr# and [.filename]#pkg-plist#. If " "reviewing a port and a better wording can be achieved, do so." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:560 msgid "" "Please be careful to note any legal issues! Do not let us illegally " "distribute software!" msgstr ""