diff options
Diffstat (limited to 'documentation/content/en/books/porters-handbook/porting-dads/_index.po')
| -rw-r--r-- | documentation/content/en/books/porters-handbook/porting-dads/_index.po | 1157 |
1 files changed, 1157 insertions, 0 deletions
diff --git a/documentation/content/en/books/porters-handbook/porting-dads/_index.po b/documentation/content/en/books/porters-handbook/porting-dads/_index.po new file mode 100644 index 0000000000..346864fc55 --- /dev/null +++ b/documentation/content/en/books/porters-handbook/porting-dads/_index.po @@ -0,0 +1,1157 @@ +# 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 "" |