Path: blob/main/documentation/content/en/books/porters-handbook/testing/_index.po
18099 views
# 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-11-08 16:17+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <[email protected]>\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/testing/_index.adoc:1 #, no-wrap msgid "Testing a FreeBSD Port" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/porters-handbook/testing/_index.adoc:1 #, no-wrap msgid "Chapter 10. Testing the Port" msgstr "" #. type: Title = #: documentation/content/en/books/porters-handbook/testing/_index.adoc:14 #, no-wrap msgid "Testing the Port" msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/testing/_index.adoc:52 #, no-wrap msgid "Running `make describe`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:57 msgid "" "Several of the FreeBSD port maintenance tools, such as man:portupgrade[1], " "rely on a database called [.filename]#/usr/ports/INDEX# which keeps track of " "such items as port dependencies. [.filename]#INDEX# is created by the top-" "level [.filename]#ports/Makefile# via `make index`, which descends into each " "port subdirectory and executes `make describe` there. Thus, if `make " "describe` fails in any port, no one can generate [.filename]#INDEX#, and " "many people will quickly become unhappy." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:62 msgid "" "It is important to be able to generate this file no matter what options are " "present in [.filename]#make.conf#, so please avoid doing things such as " "using `.error` statements when (for instance) a dependency is not " "satisfied. (See crossref:porting-dads[dads-dot-error,Avoid Use of the " "`.error` Construct].)" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:66 msgid "" "If `make describe` produces a string rather than an error message, " "everything is probably safe. See [.filename]#bsd.port.mk# for the meaning " "of the string produced." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:68 msgid "" "Also note that running a recent version of `portlint` (as specified in the " "next section) will cause `make describe` to be run automatically." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/testing/_index.adoc:70 #, no-wrap msgid "Running `make test`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:76 msgid "" "Even if the port builds fine, it is a good idea to ensure that the software " "correctly does what it is supposed to do. If the original upstream project " "provides tests along with the software, it is a good idea to run them and " "check everything works as expected." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:81 msgid "" "A port can enable tests automatically by using the `TEST_TARGET` variable. " "When set, this variable contains the name of the testing target of the " "port. This is usually just `test` but other names include `tests`, `check` " "or for specific cases things like `run_tests.py`." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:84 msgid "" "In addition to the `TEST_TARGET` variable the framework provides the " "following variables to control the tests execution:" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:86 msgid "`TEST_WRKSRC` is the directory to do the tests in." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:87 msgid "" "`TEST_ENV` contains additional variables to be passed to the test stage." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:88 msgid "`TEST_ARGS` contains any extra arguments passed to the test stage." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:91 msgid "" "Examples of use of these variables can be found in package:cad/xyce[], " "package:www/libjwt[] and others." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:95 msgid "Please make sure that tests do not break when updating a port." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/testing/_index.adoc:99 #, no-wrap msgid "Portclippy / Portfmt" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:102 msgid "Those tools come from package:ports-mgmt/portfmt[]." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:104 msgid "" "Portclippy is a linter that checks if variables in the [.filename]#Makefile# " "are in the correct order according to crossref:order[porting-order,Order of " "Variables in Port Makefiles]." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:106 msgid "Portfmt is a tool for automatically formatting [.filename]#Makefile#." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/testing/_index.adoc:108 #, no-wrap msgid "Portlint" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:113 msgid "" "Do check the port with crossref:quick-porting[porting-portlint,`portlint`] " "before submitting or committing it. `portlint` warns about many common " "errors, both functional and stylistic. For a new port, `portlint -A` is the " "most thorough; for an existing port, `portlint -C` is sufficient." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:117 msgid "" "Since `portlint` uses heuristics to try to figure out errors, it can produce " "false positive warnings. In addition, occasionally something that is " "flagged as a problem really cannot be done in any other way due to " "limitations in the ports framework. When in doubt, the best thing to do is " "ask on {freebsd-ports}." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/testing/_index.adoc:119 #, no-wrap msgid "Port Tools" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:122 msgid "" "The package:ports-mgmt/porttools[] program is part of the Ports Collection." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:128 msgid "" "`port` is the front-end script, which can help simplify the testing job. " "Whenever a new port or an update to an existing one needs testing, use `port " "test` to test the port, including the crossref:testing[testing-" "portlint,`portlint`] checking. This command also detects and lists any " "files that are not listed in [.filename]#pkg-plist#. For example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:132 #, no-wrap msgid "# port test /usr/ports/net/csup\n" msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/testing/_index.adoc:135 #, no-wrap msgid "`PREFIX` and `DESTDIR`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:140 msgid "" "`PREFIX` determines where the port will be installed. It defaults to " "[.filename]#/usr/local#, but can be set by the user to a custom path like " "[.filename]#/opt#. The port must respect the value of this variable." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:145 msgid "" "`DESTDIR`, if set by the user, determines the complete alternative " "environment, usually a jail or an installed system mounted somewhere other " "than [.filename]#/#. A port will actually install into [.filename]#DESTDIR/" "PREFIX#, and register with the package database in [.filename]#DESTDIR/var/" "db/pkg#. `DESTDIR` is handled automatically by the ports infrastructure " "with man:chroot[8]. There is no need for modifications or any extra care to " "write `DESTDIR`-compliant ports." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:148 msgid "" "The value of `PREFIX` will be set to `LOCALBASE` (defaulting to [.filename]#/" "usr/local#). If `USE_LINUX_PREFIX` is set, `PREFIX` will be `LINUXBASE` " "(defaulting to [.filename]#/compat/linux#)." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:152 msgid "" "Avoiding hard-coded [.filename]#/usr/local# paths in the source makes the " "port much more flexible and able to cater to the needs of other sites. " "Often, this can be accomplished by replacing occurrences of [.filename]#/usr/" "local# in the port's various [.filename]##Makefile##s with `${PREFIX}`. " "This variable is automatically passed down to every stage of the build and " "install processes." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:155 msgid "" "Make sure the application is not installing things in [.filename]#/usr/" "local# instead of `PREFIX`. A quick test for such hard-coded paths is:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:159 #, no-wrap msgid "% make clean; make package PREFIX=/var/tmp/`make -V PORTNAME`\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:162 msgid "" "If anything is installed outside of `PREFIX`, the package creation process " "will complain that it cannot find the files." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:164 msgid "" "In addition, it is worth checking the same with the stage directory support " "(see crossref:special[staging,Staging]):" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:168 #, no-wrap msgid "% make stage && make check-plist && make stage-qa && make package\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:171 msgid "" "`check-plist` checks for files missing from the plist, and files in the " "plist that are not installed by the port." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:172 msgid "" "`stage-qa` checks for common problems like bad shebang, symlinks pointing " "outside the stage directory, setuid files, and non-stripped libraries..." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:175 msgid "" "These tests will not find hard-coded paths inside the port's files, nor will " "it verify that `LOCALBASE` is being used to correctly refer to files from " "other ports. The temporarily installed port in [.filename]#/var/tmp/`make " "-V PORTNAME`# must be tested for proper operation to make sure there are no " "problems with paths." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:178 msgid "" "`PREFIX` must not be set explicitly in a port's [.filename]#Makefile#. " "Users installing the port may have set `PREFIX` to a custom location, and " "the port must respect that setting." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:182 msgid "" "Refer to programs and files from other ports with the variables mentioned " "above, not explicit pathnames. For instance, if the port requires a macro " "`PAGER` to have the full pathname of `less`, do not use a literal path of " "[.filename]#/usr/local/bin/less#. Instead, use `${LOCALBASE}`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:186 #, no-wrap msgid "-DPAGER=\\\"${LOCALBASE}/bin/less\\\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:189 msgid "" "The path with `LOCALBASE` is more likely to still work if the system " "administrator has moved the whole [.filename]#/usr/local# tree somewhere " "else." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:195 msgid "" "All these tests are done automatically when running `poudriere testport` or " "`poudriere bulk -t`. It is highly recommended that every ports contributor " "install and test their ports with it. See crossref:testing[testing-" "poudriere, poudriere] for more information." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/testing/_index.adoc:198 #, no-wrap msgid "poudriere" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:202 msgid "" "For a ports contributor, poudriere is one of the most important and helpful " "testing and build tools. Its main features include:" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:204 msgid "" "Bulk building of the entire ports tree, specific subsets of the ports tree, " "or a single port including its dependencies" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:205 msgid "Automatic packaging of build results" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:206 msgid "Generation of build log files per port" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:207 msgid "Providing a signed man:pkg[8] repository" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:208 msgid "" "Testing of port builds before submitting a patch to the FreeBSD bug tracker " "or committing to the ports tree" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:209 msgid "Testing for successful ports builds using different options" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:212 msgid "" "Because poudriere performs its building in a clean man:jail[8] environment " "and uses man:zfs[8] features, it has several advantages over traditional " "testing on the host system:" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:214 msgid "" "No pollution of the host environment: No leftover files, no accidental " "removals, no changes of existing configuration files." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:215 msgid "Verify [.filename]#pkg-plist# for missing or superfluous entries" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:216 msgid "" "Ports committers sometimes ask for a poudriere log alongside a patch " "submission to assess whether the patch is ready for integration into the " "ports tree" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:219 msgid "" "It is also quite straightforward to set up and use, has no dependencies, and " "will run on any supported FreeBSD release. This section shows how to " "install, configure, and run poudriere as part of the normal workflow of a " "ports contributor." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:224 msgid "" "The examples in this section show a default file layout, as standard in " "FreeBSD. Substitute any local changes accordingly. The ports tree, " "represented by `${PORTSDIR}`, is located in [.filename]#/usr/ports#. Both `$" "{LOCALBASE}` and `${PREFIX}` are [.filename]#/usr/local# by default." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/testing/_index.adoc:226 #, no-wrap msgid "Installing poudriere" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:230 msgid "" "poudriere is available in the ports tree in package:ports-mgmt/poudriere[]. " "It can be installed using man:pkg[8] or from ports:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:234 #, no-wrap msgid "# pkg install poudriere\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:237 msgid "or" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:241 #, no-wrap msgid "# make -C /usr/ports/ports-mgmt/poudriere install clean\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:252 msgid "" "There is also a work-in-progress version of poudriere which will eventually " "become the next release. It is available in package:ports-mgmt/poudriere-" "devel[]. This development version is used for the official FreeBSD package " "builds, so it is well tested. It often has newer interesting features. A " "ports committer will want to use the development version because it is what " "is used in production, and has all the new features that will make sure " "everything is exactly right. A contributor will not necessarily need those " "as the most important fixes are backported to released version. The main " "reason for the use of the development version to build the official package " "is because it is faster, in a way that will shorten a full build from 18 " "hours to 17 hours when using a high end 32 CPU server with 128GB of RAM. " "Those optimizations will not matter a lot when building ports on a desktop " "machine." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/testing/_index.adoc:254 #, no-wrap msgid "Setting Up poudriere" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:258 msgid "" "The port installs a default configuration file, [.filename]#/usr/local/etc/" "poudriere.conf#. Each parameter is documented in the configuration file." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:260 msgid "Here is a minimal example config file:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:267 #, no-wrap msgid "" "ZPOOL=zroot\n" "BASEFS=/usr/local/poudriere\n" "DISTFILES_CACHE=/usr/ports/distfiles\n" "RESOLV_CONF=/etc/resolv.conf\n" msgstr "" #. type: Labeled list #: documentation/content/en/books/porters-handbook/testing/_index.adoc:269 #, no-wrap msgid "`ZPOOL`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:272 msgid "" "The name of the ZFS storage pool which poudriere shall use. Must be listed " "in the output of `zpool status`." msgstr "" #. type: Labeled list #: documentation/content/en/books/porters-handbook/testing/_index.adoc:273 #, no-wrap msgid "`BASEFS`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:276 msgid "" "The root mount point for poudriere file systems. This entry will cause " "poudriere to mount `tank/poudriere` to `/poudriere`." msgstr "" #. type: Labeled list #: documentation/content/en/books/porters-handbook/testing/_index.adoc:277 #, no-wrap msgid "`DISTFILES_CACHE`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:282 msgid "" "Defines where distfiles are stored. In this example, poudriere and the host " "share the distfiles storage directory. This avoids downloading tarballs " "which are already present on the system. Please create this directory if it " "does not already exist so that poudriere can find it." msgstr "" #. type: Labeled list #: documentation/content/en/books/porters-handbook/testing/_index.adoc:283 #, no-wrap msgid "`RESOLV_CONF`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:288 msgid "" "Use the host [.filename]#/etc/resolv.conf# inside jails for DNS. This is " "needed so jails can resolve the URLs of distfiles when downloading. It is " "not needed when using a proxy. Refer to the default configuration file for " "proxy configuration." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/testing/_index.adoc:290 #, no-wrap msgid "Creating poudriere Jails" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:293 msgid "Create the base jails which poudriere will use for building:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:297 #, no-wrap msgid "# poudriere jail -c -j 143Ramd64 -v 14.3-RELEASE -a amd64\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:302 msgid "" "Fetch a `14.3-RELEASE` for `amd64` from the HTTPS server given by " "`FREEBSD_HOST` in [.filename]#poudriere.conf#, create the zfs file system " "`tank/poudriere/jails/143Ramd64`, mount it on [.filename]#/poudriere/jails/" "143Ramd64# and extract the `14.3-RELEASE` tarballs into this file system." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:306 #, no-wrap msgid "# poudriere jail -c -j 13i386 -v stable/13 -a i386 -m git+https\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:311 msgid "" "Create `tank/poudriere/jails/13i386`, mount it on [.filename]#/poudriere/" "jails/13i386#, then check out the tip of the Git branch of `FreeBSD-13-" "STABLE` from `GIT_HOST` in [.filename]#poudriere.conf# or the default " "`git.freebsd.org` into [.filename]#/poudriere/jails/13i386/usr/src#, then " "complete a `buildworld` and install it into [.filename]#/poudriere/jails/" "13i386#." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:317 msgid "" "While it is possible to build a newer version of FreeBSD on an older " "version, most of the time it will not run. For example, if a `stable/14` " "jail is needed, the host will have to run `stable/14` too. Running `14.3-" "RELEASE` is not enough." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:322 msgid "To create a poudriere jail for `16.0-CURRENT`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:326 #, no-wrap msgid "# poudriere jail -c -j 16amd64 -v main -a amd64 -m git+https\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:331 msgid "" "In order to run a `16.0-CURRENT` poudriere jail the host must be running " "`16.0-CURRENT`. In general, newer kernels can build and run older jails. " "For instance, a `16.0-CURRENT` kernel can build and run a `14.3-STABLE` if " "the `COMPAT_FREEBSD14` kernel option was compiled in (on by default in `16.0-" "CURRENT`[.filename]#GENERIC# kernel config)." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:334 msgid "" "A list of jails currently known to poudriere can be shown with `poudriere " "jail -l`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:341 #, no-wrap msgid "" "# poudriere jail -l\n" "JAILNAME VERSION ARCH METHOD\n" "143Ramd64 14.3-RELEASE amd64 http\n" "13i386 13.5-STABLE i386 git+https\n" msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/testing/_index.adoc:344 #, no-wrap msgid "Keeping poudriere Jails Updated" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:348 msgid "Managing updates is very straightforward. The command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:352 #, no-wrap msgid "# poudriere jail -u -j JAILNAME\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:357 msgid "" "updates the specified jail to the latest version available. For FreeBSD " "releases, update to the latest patchlevel with man:freebsd-update[8]. For " "FreeBSD versions built from source, update to the latest git revision in the " "branch." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:362 msgid "" "For jails employing a `git+*` method, it is helpful to add `-J " "_NumberOfParallelBuildJobs_` to speed up the build by increasing the number " "of parallel compile jobs used. For example, if the building machine has 6 " "CPUs, use:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:366 #, no-wrap msgid "# poudriere jail -u -J 6 -j JAILNAME\n" msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/testing/_index.adoc:371 #, no-wrap msgid "Setting Up Ports Trees for Use with poudriere" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:375 msgid "" "There are multiple ways to use ports trees in poudriere. The most " "straightforward way is to have poudriere create a default ports tree for " "itself, using link:{handbook}mirrors/#git[Git]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:379 #, no-wrap msgid "# poudriere ports -c -m git+https -B main\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:383 msgid "" "These commands create `tank/poudriere/ports/default`, mount it on " "[.filename]#/poudriere/ports/default#, and populate it using Git. Afterward " "it is included in the list of known ports trees:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:389 #, no-wrap msgid "" "# poudriere ports -l\n" "PORTSTREE METHOD TIMESTAMP PATH\n" "default git+https 2025-07-20 04:23:56 /poudriere/ports/default\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:396 msgid "" "Note that the \"default\" ports tree is special. Each of the build commands " "explained later will implicitly use this ports tree unless specifically " "specified otherwise. To use another tree, add `-p _treename_` to the " "commands." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:401 msgid "" "The best way to deal with local modifications for a ports contributor is to " "use link:{handbook}mirrors/#git[Git]. As with the creation of jails, it is " "possible to use a different method for creating the ports tree. To add an " "additional ports tree for testing local modifications and ports development, " "checking out the tree via git (as described above) is preferable." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/testing/_index.adoc:403 #, no-wrap msgid "Using Manually Managed Ports Trees with poudriere" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:407 msgid "" "Depending on the workflow, it can be extremely helpful to use ports trees " "which are maintained manually. For instance, if there is a local copy of " "the ports tree in [.filename]#/work/ports#, point poudriere to the location:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:411 #, no-wrap msgid "# poudriere ports -c -m null -M /work/ports -p development\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:414 msgid "This will be listed in the table of known trees:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:420 #, no-wrap msgid "" "# poudriere ports -l\n" "PORTSTREE METHOD TIMESTAMP PATH\n" "development null 2025-07-20 05:06:33 /work/ports\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:426 msgid "" "The dash or `null` in the `METHOD` column means that poudriere will not " "update or change this ports tree, ever. It is completely up to the user to " "maintain this tree, including all local modifications that may be used for " "testing new ports and submitting patches." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/testing/_index.adoc:429 #, no-wrap msgid "Keeping poudriere Ports Trees Updated" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:432 msgid "As straightforward as with jails described earlier:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:436 #, no-wrap msgid "# poudriere ports -u -p PORTSTREE\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:439 msgid "" "Will update the given _PORTSTREE_, one tree given by the output of " "`poudriere -l`, to the latest revision available on the official servers." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:444 msgid "" "Ports trees without a method, see crossref:testing[testing-poudriere-ports-" "tree-manual, Using Manually Managed Ports Trees with poudriere], cannot be " "updated like this and must be updated manually by the porter." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/testing/_index.adoc:447 #, no-wrap msgid "Testing Ports" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:450 msgid "" "After jails and ports trees have been set up, the result of a contributor's " "modifications to the ports tree can be tested." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:452 msgid "" "For example, local modifications to the package:www/firefox[] port located " "in [.filename]#/work/ports/www/firefox# can be tested in the previously " "created 14.3-RELEASE jail:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:456 #, no-wrap msgid "# poudriere testport -j 143Ramd64 -p development -o www/firefox\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:462 msgid "" "This will build all dependencies of Firefox. If a dependency has been built " "previously and is still up-to-date, the pre-built package is installed. If " "a dependency has no up-to-date package, one will be built with default " "options in a jail. Then Firefox itself is built." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:464 msgid "" "The complete build of every port is logged to [.filename]#/poudriere/data/" "logs/bulk/143Ri386-development/build-time/logs#." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:469 msgid "" "The directory name `143Ri386-development` is derived from the arguments to `-" "j` and `-p`, respectively. For convenience, a symbolic link [.filename]#/" "poudriere/data/logs/bulk/143Ri386-development/latest# is also maintained. " "The link points to the latest _build-time_ directory. Also in this " "directory is an [.filename]#index.html# for observing the build process with " "a web browser." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:472 msgid "" "By default, poudriere cleans up the jails and leaves log files in the " "directories mentioned above. To ease investigation, jails can be kept " "running after the build by adding `-i` to `testport`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:476 #, no-wrap msgid "# poudriere testport -j 143Ramd64 -p development -i -o www/firefox\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:483 msgid "" "After the build completes, and regardless of whether it was successful, a " "shell is provided within the jail. The shell is used to investigate " "further. poudriere can be told to leave the jail running after the build " "finishes with `-I`. poudriere will show the command to run when the jail is " "no longer needed. It is then possible to man:jexec[8] into it:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:497 #, no-wrap msgid "" "# poudriere testport -j 143Ramd64 -p development -I -o www/firefox\n" "[...]\n" "====>> Installing local Pkg repository to /usr/local/etc/pkg/repos\n" "====>> Leaving jail 143Ramd64-development-n running, mounted at /poudriere/data/.m/143Ramd64-development/ref for interactive run testing\n" "====>> To enter jail: jexec 143Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root\n" "====>> To stop jail: poudriere jail -k -j 143Ramd64 -p development\n" "# jexec 143Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root\n" "# [do some stuff in the jail]\n" "# exit\n" "# poudriere jail -k -j 143Ramd64 -p development\n" "====>> Umounting file systems\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:502 msgid "" "An integral part of the FreeBSD ports build infrastructure is the ability to " "tweak ports to personal preferences with options. These can be tested with " "poudriere as well. Adding the `-c`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:506 #, no-wrap msgid "# poudriere testport -j 143Ramd64 -c -o www/firefox\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:512 msgid "" "Presents the port configuration dialog before the port is built. The ports " "given after `-o` in the format `_category_/_portname_` will use the " "specified options, all dependencies will use the default options. Testing " "dependent ports with non-default options can be accomplished using sets, see " "crossref:testing[testing-poudriere-sets, Using Sets]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:517 msgid "" "When testing ports where [.filename]#pkg-plist# is altered during build " "depending on the selected options, it is recommended to perform a test run " "with all options selected _and_ one with all options deselected." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/testing/_index.adoc:520 #, no-wrap msgid "Using Sets" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:525 msgid "" "For all actions involving builds, a so-called _set_ can be specified using `-" "z _setname_`. A set refers to a fully independent build. This allows, for " "instance, usage of `testport` with non-standard options for the dependent " "ports." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:531 msgid "" "To use sets, poudriere expects an existing directory structure similar to " "`PORT_DBDIR`, defaults to [.filename]#/var/db/ports# in its configuration " "directory. This directory is then man:nullfs[5]-mounted into the jails " "where the ports and their dependencies are built. Usually a suitable " "starting point can be obtained by recursively copying the existing " "`PORT_DBDIR` to [.filename]#/usr/local/etc/poudriere.d/jailname-portname-" "setname-options#. This is described in detail in man:poudriere[8]. For " "instance, testing package:www/firefox[] in a specific set named `devset`, " "add the `-z devset` parameter to the `testport` command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:535 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:579 #, no-wrap msgid "# poudriere testport -j 143Ramd64 -p development -z devset -o www/firefox\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:538 msgid "This will look for the existence of these directories in this order:" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:540 msgid "" "[.filename]#/usr/local/etc/poudriere.d/143Ramd64-development-devset-options#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:541 msgid "[.filename]#/usr/local/etc/poudriere.d/143Ramd64-devset-options#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:542 msgid "[.filename]#/usr/local/etc/poudriere.d/143Ramd64-development-options#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:543 msgid "[.filename]#/usr/local/etc/poudriere.d/devset-options#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:544 msgid "[.filename]#/usr/local/etc/poudriere.d/development-options#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:545 msgid "[.filename]#/usr/local/etc/poudriere.d/143Ramd64-options#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:546 msgid "[.filename]#/usr/local/etc/poudriere.d/options#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:549 msgid "" "From this list, poudriere man:nullfs[5]-mounts the _first existing_ " "directory tree into the [.filename]#/var/db/ports# directory of the build " "jails. Hence, all custom options are used for all the ports during this run " "of `testport`." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:552 msgid "" "After the directory structure for a set is provided, the options for a " "particular port can be altered. For example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:556 #, no-wrap msgid "# poudriere options -c www/firefox -z devset\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:560 msgid "" "The configuration dialog for package:www/firefox[] is shown, and options can " "be edited. The selected options are saved to the `devset` set." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:566 msgid "" "poudriere is very flexible in the option configuration. poudriere can be " "set for particular jails, ports trees, and for multiple ports by one " "command. Refer to man:poudriere[8] for details." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/testing/_index.adoc:569 #, no-wrap msgid "Providing a Custom [.filename]#make.conf# File" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:575 msgid "" "Similar to using sets, poudriere will also use a custom " "[.filename]#make.conf# if it is provided. No special command line argument " "is necessary. Instead, poudriere looks for existing files matching a name " "scheme derived from the command line. For instance:" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:582 msgid "" "causes poudriere to check for the existence of these files in this order:" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:584 msgid "[.filename]#/usr/local/etc/poudriere.d/make.conf#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:585 msgid "[.filename]#/usr/local/etc/poudriere.d/devset-make.conf#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:586 msgid "[.filename]#/usr/local/etc/poudriere.d/development-make.conf#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:587 msgid "[.filename]#/usr/local/etc/poudriere.d/143Ramd64-make.conf#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:588 msgid "[.filename]#/usr/local/etc/poudriere.d/143Ramd64-development-make.conf#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:589 msgid "[.filename]#/usr/local/etc/poudriere.d/143Ramd64-devset-make.conf#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:590 msgid "" "[.filename]#/usr/local/etc/poudriere.d/143Ramd64-development-devset-" "make.conf#" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:594 msgid "" "Unlike with sets, all of the found files will be appended, _in that order_, " "into one [.filename]#make.conf# inside the build jails. It is hence " "possible to have general make variables, intended to affect all builds in " "[.filename]#/usr/local/etc/poudriere.d/make.conf#. Special variables, " "intended to affect only certain jails or sets can be set in specialised " "[.filename]#make.conf# files, such as [.filename]#/usr/local/etc/poudriere.d/" "143Ramd64-development-devset-make.conf#." msgstr "" #. type: Block title #: documentation/content/en/books/porters-handbook/testing/_index.adoc:596 #, no-wrap msgid "Using [.filename]#make.conf# to Change Default Perl" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:601 msgid "" "To build a set with a non default Perl version, for example, `5.20`, using a " "set named `perl5-20`, create a [.filename]#perl5-20-make.conf# with this " "line:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:605 #, no-wrap msgid "DEFAULT_VERSIONS+= perl=5.20\n" msgstr "" #. type: delimited block * 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:609 msgid "" "Note the use of `+=` so that if the variable is already set in the default " "[.filename]#make.conf# its content will not be overwritten." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/testing/_index.adoc:614 #, no-wrap msgid "Pruning no Longer Needed Distfiles" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:618 msgid "" "poudriere comes with a built-in mechanism to remove outdated distfiles that " "are no longer used by any port of a given tree. The command" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:622 #, no-wrap msgid "# poudriere distclean -p portstree\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:627 msgid "" "will scan the distfiles folder, `DISTFILES_CACHE` in " "[.filename]#poudriere.conf#, versus the ports tree given by the `-p " "_portstree_` argument and prompt for removal of those distfiles. To skip " "the prompt and remove all unused files unconditionally, the `-y` argument " "can be added:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:631 #, no-wrap msgid "# poudriere distclean -p portstree -y\n" msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/testing/_index.adoc:634 #, no-wrap msgid "Debugging ports" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:641 msgid "" "Sometimes things go wrong and the port fails at run time. The framework " "provides some facilities to help in debugging ports. These helpers are " "limited since the way of debugging a port heavily depends on the technology " "used. The following variables help with debugging ports:" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:643 msgid "`WITH_DEBUG`. If set, ports are built with debugging symbols." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:644 msgid "" "`WITH_DEBUG_PORTS`. Specifies a list of ports to be built with `WITH_DEBUG` " "set." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:645 msgid "" "`DEBUG_FLAGS`. Used to specify additional flags to `CFLAGS`. Defaults to `-" "g`." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:648 msgid "" "When `WITH_DEBUG` is set, either globally or for a list of ports, the " "resulting binaries are not stripped." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:651 msgid "" "These variables can be specified in [.filename]#make.conf# or in the command " "line:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:655 #, no-wrap msgid "# cd category/port && make -DWITH_DEBUG DEBUG_FLAGSS=\"-g -O0\"\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/testing/_index.adoc:663 msgid "" "If the port is built using package:ports-mgmt/poudriere[] the debugging " "variables must be specified in poudriere's [.filename]#make.conf# and not in " "[.filename]#/etc/make.conf#. Refer to package:ports-mgmt/poudriere[] " "documentation for details." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/testing/_index.adoc:667 msgid "" "Please refer to the debugging information in the extref:{developers-handbook}" "tools[Developer's Handbook, debugging] for more details about the debugging " "tools available." msgstr ""