path: root/documentation/content/en/books/porters-handbook/porting-dads/_index.po

# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR The FreeBSD Project
# This file is distributed under the same license as the FreeBSD Documentation package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: FreeBSD Documentation VERSION\n"
"POT-Creation-Date: 2023-05-21 14:43-0300\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\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:13
#, no-wrap
msgid "Dos and Don'ts"
msgstr ""

#. type: Title ==
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:53
#, no-wrap
msgid "Introduction"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:59
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:61
#, no-wrap
msgid "`WRKDIR`"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:65
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:67
#, no-wrap
msgid "`WRKDIRPREFIX`"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:72
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:74
#, no-wrap
msgid "Differentiating Operating Systems and OS Versions"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:78
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:82
#, no-wrap
msgid "#include <sys/param.h>\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:85
msgid "to the proper place in the [.filename]#.c# file."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:88
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:96
#, 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:99
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:101
#, no-wrap
msgid "Writing Something After bsd.port.mk"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:105
msgid ""
"Do not write anything after the `.include <bsd.port.mk>` 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:109
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:112
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:114
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:119
#, no-wrap
msgid "Variable"
msgstr ""

#. type: Table
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:121
#, no-wrap
msgid "Description"
msgstr ""

#. type: Table
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:122
#, no-wrap
msgid "`ARCH`"
msgstr ""

#. type: Table
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:124
#, no-wrap
msgid "The architecture as returned by `uname -m` (for example, `i386`)"
msgstr ""

#. type: Table
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:125
#, no-wrap
msgid "`OPSYS`"
msgstr ""

#. type: Table
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:127
#, 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:128
#, no-wrap
msgid "`OSREL`"
msgstr ""

#. type: Table
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:130
#, 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:131
#, no-wrap
msgid "`OSVERSION`"
msgstr ""

#. type: Table
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:133
#, 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:134
#, no-wrap
msgid "`LOCALBASE`"
msgstr ""

#. type: Table
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:136
#, 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:137
#, no-wrap
msgid "`PREFIX`"
msgstr ""

#. type: Table
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:138
#, 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:143
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:146
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:153
#, 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:156
msgid "Always use tab instead of spaces after `BROKEN=`."
msgstr ""

#. type: Title ==
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:158
#, no-wrap
msgid "Use the `exec` Statement in Wrapper Scripts"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:163
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:168
#, 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:173
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:175
#, no-wrap
msgid "Do Things Rationally"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:180
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:183
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:185
#, no-wrap
msgid "Respect Both `CC` and `CXX`"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:191
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:193
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:196
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:200
#, no-wrap
msgid "CC?= gcc\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:205
#, no-wrap
msgid "CXX?= g++\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:208
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:212
#, no-wrap
msgid "CC= gcc\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:217
#, no-wrap
msgid "CXX= g++\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:222
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:224
#, no-wrap
msgid "Respect `CFLAGS`"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:230
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:232
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:234
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:238
#, no-wrap
msgid "CFLAGS+= -Wall -Werror\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:241
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:245
#, no-wrap
msgid "CFLAGS= -Wall -Werror\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:250
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:254
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:258
#, no-wrap
msgid "CFLAGS= -O3 -funroll-loops -DHAVE_SOUND\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:261
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:265
#, no-wrap
msgid "CFLAGS+= -DHAVE_SOUND\n"
msgstr ""

#. type: Title ==
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:268
#, no-wrap
msgid "Verbose Build Logs"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:272
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:274
msgid "Non-informative build log example (bad):"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:280
#, 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:283
msgid "Verbose build log example (good):"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:289
#, 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:293
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:295
#, no-wrap
msgid "Feedback"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:299
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:301
#, no-wrap
msgid "README.html"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:305
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:309
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:312
#, 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:319
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:321
#, no-wrap
msgid "Variables"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:324
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:327
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:329
msgid "For instance, use `BROKEN` when a port:"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:331
msgid "does not compile"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:332
msgid "fails its configuration or installation process"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:333
msgid "installs files outside of [.filename]#${PREFIX}#"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:334
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:335
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:337
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:338
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:340
msgid "does not work on the installed version of FreeBSD"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:341
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:342
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:347
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:350
#, no-wrap
msgid "Implementation Notes"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:354
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:358
#, 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:363
#, no-wrap
msgid "IGNORE=\tunsupported on recent versions\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:366
msgid "resulting in this output from `make describe`:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:370
#, 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:375
#, 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:378
#, no-wrap
msgid "Architectural Considerations"
msgstr ""

#. type: Title ===
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:381
#, no-wrap
msgid "General Notes on Architectures"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:385
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:387
msgid "For the list of supported architectures, run:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:391
#, no-wrap
msgid "cd ${SRCDIR}; make targets\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:396
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:398
#, no-wrap
msgid "Marking a Port as Architecture Neutral"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:401
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:403
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:409
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:412
#, 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:415
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:419
#, no-wrap
msgid "ONLY_FOR_ARCHS=\ti386 amd64\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:424
#, no-wrap
msgid "NOT_FOR_ARCHS=\tia64 sparc64\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:428
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:431
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:433
#, no-wrap
msgid "Cluster-Specific Considerations"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:436
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:438
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:440
#, 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:444
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:448
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:450
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:456
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:461
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:463
#, no-wrap
msgid "Avoid Use of the `.error` Construct"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:467
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:473
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:475
#, no-wrap
msgid "How to Avoid Using `.error`"
msgstr ""

#. type: delimited block = 4
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:480
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:484
#, no-wrap
msgid ".error \"option is not supported\"\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:489
#, no-wrap
msgid "IGNORE=option is not supported\n"
msgstr ""

#. type: Title ==
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:494
#, no-wrap
msgid "Usage of sysctl"
msgstr ""

#. type: delimited block = 4
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:499
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:501
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:503
#, no-wrap
msgid "Rerolling Distfiles"
msgstr ""

#. type: delimited block = 4
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:508
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:511
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:515
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:518
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:520
#, no-wrap
msgid "Use POSIX Standards"
msgstr ""

#. type: delimited block = 4
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:524
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:527
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:529
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:533
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:537
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:540
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:542
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:544
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:547
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:549
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:552
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:554
#, no-wrap
msgid "Miscellanea"
msgstr ""

#. type: delimited block = 4
#: documentation/content/en/books/porters-handbook/porting-dads/_index.adoc:558
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:559
msgid ""
"Please be careful to note any legal issues! Do not let us illegally "
"distribute software!"
msgstr ""