# 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: 2025-05-01 19:56-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: YAML Front Matter: description #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:1 #, no-wrap msgid "How to quickly create a new FreeBSD Port" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:1 #, no-wrap msgid "Chapter 3. Quick Porting" msgstr "" #. type: Title = #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:14 #, no-wrap msgid "Quick Porting" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:53 msgid "" "This section describes how to quickly create a new port. For applications " "where this quick method is not adequate, the full \"Slow Porting\" process " "is described in crossref:slow-porting[slow-porting,Slow Porting]." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:55 msgid "" "First, get the original tarball and put it into `DISTDIR`, which defaults to " "[.filename]#/usr/ports/distfiles#." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:61 msgid "" "These steps assume that the software compiled out-of-the-box. In other " "words, absolutely no changes were required for the application to work on a " "FreeBSD system. If anything had to be changed, refer to crossref:slow-" "porting[slow-porting,Slow Porting]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:66 msgid "" "It is recommended to set the `DEVELOPER` man:make[1] variable in " "[.filename]#/etc/make.conf# before getting into porting." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:70 #, no-wrap msgid "# echo DEVELOPER=yes >> /etc/make.conf\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:73 msgid "" "This setting enables the \"developer mode\" that displays deprecation " "warnings and activates some further quality checks on calling `make`." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:76 #, no-wrap msgid "Writing the Makefile" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:79 msgid "The minimal [.filename]#Makefile# would look something like this:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:86 #, no-wrap msgid "" "PORTNAME=\toneko\n" "DISTVERSION=\t1.1b\n" "CATEGORIES=\tgames\n" "MASTER_SITES=\tftp://ftp.rediris.es/sites/ftp.freebsd.org/pub/FreeBSD/\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:90 #, no-wrap msgid "" "MAINTAINER=\tyouremail@example.com\n" "COMMENT=\tCat chasing a mouse all over the screen\n" "WWW=\t\thttp://www.daidouji.com/oneko/\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:92 #, no-wrap msgid ".include \n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:96 msgid "" "Try to figure it out. A more detailed example is shown in the " "crossref:porting-samplem[porting-samplem,sample Makefile] section." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:98 #, no-wrap msgid "Writing the Description Files" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:103 msgid "" "There are two description files that are required for any port, whether they " "actually package or not. They are [.filename]#pkg-descr# and " "[.filename]#pkg-plist#. Their [.filename]#pkg-# prefix distinguishes them " "from other files." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:105 #, no-wrap msgid "[.filename]#pkg-descr#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:109 msgid "" "This is a longer description of the port. One to a few paragraphs concisely " "explaining what the port does is sufficient." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:116 msgid "" "This is _not_ a manual or an in-depth description on how to use or compile " "the port! _Please be careful when copying from the [.filename]#README# or " "manpage_. Too often they are not a concise description of the port or are " "in an awkward format. For example, manpages have justified spacing, which " "looks particularly bad with monospaced fonts." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:118 msgid "" "On the other hand, the content of [.filename]#pkg-descr# must be longer than " "the crossref:makefiles[makefile-comment,`COMMENT` line from the Makefile]. " "It must explain in more depth what the port is all about." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:122 msgid "" "A well-written [.filename]#pkg-descr# describes the port completely enough " "that users would not have to consult the documentation or visit the website " "to understand what the software does, how it can be useful, or what " "particularly nice features it has. Mentioning certain requirements like a " "graphical toolkit, heavy dependencies, runtime environment, or " "implementation languages help users decide whether this port will work for " "them." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:126 msgid "" "The URL that used to be included as the last line of the [.filename]#pkg-" "descr# file has been moved to the [.filename]#Makefile#." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:129 #, no-wrap msgid "[.filename]#pkg-plist#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:134 msgid "" "This file lists all the files installed by the port. It is also called the " "\"packing list\" because the package is generated by packing the files " "listed here. The pathnames are relative to the installation prefix (usually " "[.filename]#/usr/local#)." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:136 msgid "Here is a small example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:145 #, no-wrap msgid "" "bin/oneko\n" "man/man1/oneko.1.gz\n" "lib/X11/app-defaults/Oneko\n" "lib/X11/oneko/cat1.xpm\n" "lib/X11/oneko/cat2.xpm\n" "lib/X11/oneko/mouse.xpm\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:148 msgid "" "Refer to the man:pkg-create[8] manual page for details on the packing list." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:155 msgid "" "It is recommended to keep all the filenames in this file sorted " "alphabetically. It will make verifying changes when upgrading the port much " "easier. The sorting should be applied after variable expansion takes " "place. The framework does this correctly when the package list is " "crossref:plist[plist-autoplist,generated automatically]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:161 msgid "" "Creating a packing list manually can be a very tedious task. If the port " "installs a large numbers of files, crossref:plist[plist-autoplist,creating " "the packing list automatically] might save time." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:166 msgid "" "There is only one case when [.filename]#pkg-plist# can be omitted from a " "port. If the port installs just a handful of files, list them in " "`PLIST_FILES`, within the port's [.filename]#Makefile#. For instance, we " "could get along without [.filename]#pkg-plist# in the above " "[.filename]#oneko# port by adding these lines to the [.filename]#Makefile#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:175 #, no-wrap msgid "" "PLIST_FILES=\tbin/oneko \\\n" "\t\tman/man1/oneko.1.gz \\\n" "\t\tlib/X11/app-defaults/Oneko \\\n" "\t\tlib/X11/oneko/cat1.xpm \\\n" "\t\tlib/X11/oneko/cat2.xpm \\\n" "\t\tlib/X11/oneko/mouse.xpm\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:182 msgid "" "Usage of `PLIST_FILES` should not be abused. When looking for the origin of " "a file, people usually try to grep through the [.filename]#pkg-plist# files " "in the ports tree. Listing files in `PLIST_FILES` in the " "[.filename]#Makefile# makes that search more difficult." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:187 msgid "" "If a port needs to create an empty directory, or creates directories outside " "of [.filename]#${PREFIX}# during installation, refer to crossref:plist[plist-" "dir-cleaning,Cleaning Up Empty Directories] for more information." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:193 msgid "" "As `PLIST_FILES` is a man:make[1] variable, any entry with spaces must be " "quoted. For example, if using keywords described in man:pkg-create[8] and " "crossref:plist[plist-keywords,Expanding Package List with Keywords], the " "entry must be quoted." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:197 #, no-wrap msgid "PLIST_FILES=\t\"@sample ${ETCDIR}/oneko.conf.sample\"\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:201 msgid "" "Later we will see how [.filename]#pkg-plist# and `PLIST_FILES` can be used " "to fulfill crossref:plist[plist,more sophisticated tasks]." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:203 #, no-wrap msgid "Creating the Checksum File" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:208 msgid "" "Just type `make makesum`. The ports framework will automatically generate " "[.filename]#distinfo#. Do not try to generate the file manually." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:210 #, no-wrap msgid "Testing the Port" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:214 msgid "" "Make sure that the port rules do exactly what is desired, including " "packaging up the port. These are the important points to verify:" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:216 msgid "" "[.filename]#pkg-plist# does not contain anything not installed by the port." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:217 msgid "" "[.filename]#pkg-plist# contains everything that is installed by the port." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:218 msgid "" "The port can be installed using the `install` target. This verifies that the " "install script works correctly." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:219 msgid "" "The port can be deinstalled properly using the `deinstall` target. This " "verifies that the deinstall script works correctly." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:220 msgid "" "The port only has access to network resources during the `fetch` target " "phase. This is important for package builders, such as package:ports-mgmt/" "poudriere[]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:221 msgid "" "Make sure that `make package` can be run as a normal user (that is, not as " "`root`). If that fails, the software may need to be patched. See also " "crossref:uses[uses-fakeroot,`fakeroot`] and crossref:uses[uses-" "uidfix,`uidfix`]." msgstr "" #. type: Block title #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:223 #, no-wrap msgid "Procedure: Recommended Test Ordering" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:225 msgid "`make stage`" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:226 msgid "`make stage-qa`" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:227 msgid "`make package`" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:228 msgid "`make install`" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:229 msgid "`make deinstall`" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:230 msgid "`make package` (as user)" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:232 msgid "Make certain no warnings are shown in any of the stages." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:235 msgid "" "Thorough automated testing can be done with package:ports-mgmt/poudriere[] " "from the Ports Collection, see crossref:testing[testing-poudriere,poudriere] " "for more information. It maintains `jails` where all of the steps shown " "above can be tested without affecting the state of the host system." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:237 #, no-wrap msgid "Checking the Port with `portlint`" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:242 msgid "" "Please use `portlint` to see if the port conforms to our guidelines. The " "package:ports-mgmt/portlint[] program is part of the ports collection. In " "particular, check that the crossref:porting-samplem[porting-" "samplem,Makefile] is in the right shape and the crossref:porting-" "pkgname[porting-pkgname,package] is named appropriately." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:246 msgid "" "Do not blindly follow the output of `portlint`. It is a static lint tool and " "sometimes gets things wrong." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:249 #, no-wrap msgid "Submitting the New Port" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:252 msgid "" "Before submitting the new port, read the crossref:porting-dads[porting-" "dads,DOs and DON'Ts] section." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:254 msgid "" "Once happy with the port, the only thing remaining is to put it in the main " "FreeBSD ports tree and make everybody else happy about it too." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:258 msgid "" "We do not need the [.filename]#work# directory or the " "[.filename]#pkgname.txz# package, so delete them now." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:262 msgid "" "Next, create a man:patch[1], file. Assuming the port is called `oneko` and " "is in the `games` category." msgstr "" #. type: Block title #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:264 #, no-wrap msgid "Creating a [.filename]#.diff# for a New Port" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:268 msgid "" "Add all the files with `git add .`, then review the diff with `git diff`. " "For example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:273 #, no-wrap msgid "" "% git add .\n" "% git diff --staged\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:277 msgid "" "Make sure that all required files are included, then commit the change to " "your local branch and generate a patch with `git format-patch`" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:282 #, no-wrap msgid "" "% git commit\n" "% git format-patch origin/main\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:286 msgid "" "Patch generated with `git format-patch` will include author identity and " "email addresses, making it easier for developers to apply (with `git am`) " "and give proper credit." msgstr "" #. type: delimited block * 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:290 msgid "" "To make it easier for committers to apply the patch on their working copy of " "the ports tree, please generate the [.filename]#.diff# from the base of your " "ports tree." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:297 msgid "" "Submit [.filename]#oneko.diff# with the https://bugs.freebsd.org/submit/[bug " "submission form]. Use product \"Ports & Packages\", component \"Individual " "Port(s)\", and follow the guidelines shown there. Add a short description " "of the program to the Description field of the PR (perhaps a short version " "of `COMMENT`), and remember to add [.filename]#oneko.diff# as an attachment." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:303 msgid "" "Giving a good description in the summary of the problem report makes the " "work of port committers and triagers a lot easier. The expected format for " "new ports is \"[NEW PORT] _category/portname short description of the " "port_\". Using this scheme makes it easier and faster to begin the work of " "committing the new port." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:308 msgid "" "After submitting the port, please be patient. The time needed to include a " "new port in FreeBSD can vary from a few days to a few months. A simple " "search form of the Problem Report database can be searched at https://" "bugs.freebsd.org/bugzilla/query.cgi[]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:310 msgid "" "To get a listing of _open_ port PRs, select _Open_ and _Ports & Packages_ in " "the search form, then click btn:[Search]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:313 msgid "" "After looking at the new port, we will reply if necessary, and commit it to " "the tree. The submitter's name will also be added to the list of extref:" "{contributors}[Additional FreeBSD Contributors, contrib-additional] and " "other files." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/quick-porting/_index.adoc:318 msgid "" "Previously it was possible to submit patches for new ports using a " "man:shar[1] file; this is no longer the case with the evolution of " "man:git[1]. Committers no longer accept man:shar[1] files as their use is " "prone to mistake and does not add the relevant entry in the category's " "[.filename]#Makefile#." msgstr ""