diff options
Diffstat (limited to 'documentation/content/en/books/porters-handbook/quick-porting/_index.po')
| -rw-r--r-- | documentation/content/en/books/porters-handbook/quick-porting/_index.po | 587 |
1 files changed, 587 insertions, 0 deletions
diff --git a/documentation/content/en/books/porters-handbook/quick-porting/_index.po b/documentation/content/en/books/porters-handbook/quick-porting/_index.po new file mode 100644 index 0000000000..4138e88be6 --- /dev/null +++ b/documentation/content/en/books/porters-handbook/quick-porting/_index.po @@ -0,0 +1,587 @@ +# 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: 2025-05-01 19:56-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/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 <bsd.port.mk>\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 "" |