Attachment 244542 Details for Bug 273483 – signed-off .patch

[patch] signed-off .patch

273483.patch (text/plain), 10.80 KB, created by Graham Perrin on 2023-09-01 06:41:32 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Graham Perrin

Created: 2023-09-01 06:41:32 UTC

Size: 10.80 KB

patch

obsolete

>From: Graham Perrin <grahamperrin@gmail.com>
>Date: Fri, 1 Sep 2023 05:45:13 +0000
>Subject: [PATCH 1/3] Porter's Handbook: fix a link, be concise
>
>https://docs.freebsd.org/en/books/porters-handbook/book/#testing-debugging-ports
>
>Fix the recently introduced link to a debugging subsection of the FreeBSD
>Developers' Handbook. Apply the link to relevant words.
>
>Be concise: no need to repeat the word 'debugging'.
>
>https://bugs.freebsd.org/273483
>
>PR: 273483
>Fixes: 5ff4e8af631f [phb]: Add information on how to debug ports
>Signed-off-by: Graham Perrin <grahamperrin@gmail.com>
>---
> .../content/en/books/porters-handbook/testing/_index.adoc   | 6 +++---
> 1 file changed, 3 insertions(+), 3 deletions(-)
>
>diff --git a/documentation/content/en/books/porters-handbook/testing/_index.adoc b/documentation/content/en/books/porters-handbook/testing/_index.adoc
>index b4e88cfe4c..015229438b 100644
>--- a/documentation/content/en/books/porters-handbook/testing/_index.adoc
>+++ b/documentation/content/en/books/porters-handbook/testing/_index.adoc
>@@ -661,6 +661,6 @@ variables must be specified in poudriere's [.filename]#make.conf# and not in
> Refer to package:ports-mgmt/poudriere[] documentation for details.
> ====
> 
>-Please refer to the debugging information in the
>-extref:{developers-handbook}[Developer's Handbook, debugging] for more details
>-about the debugging tools available.
>+Please refer to the extref:{developers-handbook}tools/#debugging[debugging information in the
>+Developer's Handbook] for more details
>+about the tools available.
>-- 
>2.30.8
>
>
>From: Graham Perrin <grahamperrin@gmail.com>
>Date: Fri, 1 Sep 2023 05:55:45 +0000
>Subject: [PATCH 2/3] Porter's Handbook: testing: markup
>
>One sentence per line.
>
>Signed-off-by: Graham Perrin <grahamperrin@gmail.com>
>---
> .../porters-handbook/testing/_index.adoc      | 49 ++++++-------------
> 1 file changed, 15 insertions(+), 34 deletions(-)
>
>diff --git a/documentation/content/en/books/porters-handbook/testing/_index.adoc b/documentation/content/en/books/porters-handbook/testing/_index.adoc
>index 015229438b..fe23e1143f 100644
>--- a/documentation/content/en/books/porters-handbook/testing/_index.adoc
>+++ b/documentation/content/en/books/porters-handbook/testing/_index.adoc
>@@ -68,25 +68,20 @@ Also note that running a recent version of `portlint` (as specified in the next
> [[make-test]]
> == Running `make test`
> 
>-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.
>+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.
> 
> 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`.
>+This is usually just `test` but other names include `tests`, `check` or for specific cases things like `run_tests.py`.
> 
>-In addition to the `TEST_TARGET` variable the framework provides the following
>-variables to control the tests execution:
>+In addition to the `TEST_TARGET` variable the framework provides the following variables to control the tests execution:
> 
> * `TEST_WRKSRC` is the directory to do the tests in.
> * `TEST_ENV` contains additional variables to be passed to the test stage.
> * `TEST_ARGS` contains any extra arguments passed to  the test stage.
> 
>-Examples of use of these variables can be found in package:cad/xyce[],
>-package:www/libjwt[] and others.
>+Examples of use of these variables can be found in package:cad/xyce[], package:www/libjwt[] and others.
> 
> [NOTE]
> ====
>@@ -246,8 +241,7 @@ This development version is used for the official FreeBSD package builds, so it
> 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.
>+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.
> 
> [[testing-poudriere-setup]]
>@@ -295,18 +289,14 @@ Create the base jails which poudriere will use for building:
> # poudriere jail -c -j 131Ramd64 -v 13.1-RELEASE -a amd64
> ....
> 
>-Fetch a `13.1-RELEASE` for `amd64` from the FTP server given by `FREEBSD_HOST` in [.filename]#poudriere.conf#,
>-create the zfs file system `tank/poudriere/jails/131Ramd64`,
>-mount it on [.filename]#/poudriere/jails/131Ramd64# and extract the `13.1-RELEASE` tarballs into this file system.
>+Fetch a `13.1-RELEASE` for `amd64` from the FTP server given by `FREEBSD_HOST` in [.filename]#poudriere.conf#, create the zfs file system `tank/poudriere/jails/131Ramd64`, mount it on [.filename]#/poudriere/jails/131Ramd64# and extract the `13.1-RELEASE` tarballs into this file system.
> 
> [source,shell]
> ....
> # poudriere jail -c -j 12i386 -v stable/12 -a i386 -m git+https
> ....
> 
>-Create `tank/poudriere/jails/12i386`, mount it on [.filename]#/poudriere/jails/12i386#,
>-then check out the tip of the Git branch of `FreeBSD-12-STABLE` from `GIT_HOST` in [.filename]#poudriere.conf# or the default `git.freebsd.org` into [.filename]#/poudriere/jails/12i386/usr/src#,
>-then complete a `buildworld` and install it into [.filename]#/poudriere/jails/12i386#.
>+Create `tank/poudriere/jails/12i386`, mount it on [.filename]#/poudriere/jails/12i386#, then check out the tip of the Git branch of `FreeBSD-12-STABLE` from `GIT_HOST` in [.filename]#poudriere.conf# or the default `git.freebsd.org` into [.filename]#/poudriere/jails/12i386/usr/src#, then complete a `buildworld` and install it into [.filename]#/poudriere/jails/12i386#.
> 
> [NOTE]
> ====
>@@ -511,8 +501,7 @@ Testing dependent ports with non-default options can be accomplished using sets,
> 
> [TIP]
> ====
>-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.
>+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.
> ====
> 
> [[testing-poudriere-sets]]
>@@ -620,8 +609,7 @@ The command
> # poudriere distclean -p portstree
> ....
> 
>-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.
>+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:
> 
> [source,shell]
>@@ -634,19 +622,16 @@ To skip the prompt and remove all unused files unconditionally, the `-y` argumen
> 
> 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.
>+These helpers are limited since the way of debugging a port heavily depends on the technology used.
> The following variables help with debugging ports:
> 
> * `WITH_DEBUG`. If set, ports are built with debugging symbols.
> * `WITH_DEBUG_PORTS`. Specifies a list of ports to be built with `WITH_DEBUG` set.
> * `DEBUG_FLAGS`. Used to specify additional flags to `CFLAGS`. Defaults to `-g`.
> 
>-When `WITH_DEBUG` is set, either globally or for a list of ports, the resulting
>-binaries are not stripped.
>+When `WITH_DEBUG` is set, either globally or for a list of ports, the resulting binaries are not stripped.
> 
>-These variables can be specified in [.filename]#make.conf# or in the command
>-line:
>+These variables can be specified in [.filename]#make.conf# or in the command line:
> 
> [source,shell]
> ....
>@@ -655,12 +640,8 @@ line:
> 
> [NOTE]
> ====
>-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#.
>+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.
> ====
> 
>-Please refer to the extref:{developers-handbook}tools/#debugging[debugging information in the
>-Developer's Handbook] for more details
>-about the tools available.
>+Please refer to the extref:{developers-handbook}tools/#debugging[debugging information in the Developer's Handbook] for more details about the tools available.
>-- 
>2.30.8
>
>
>From: Graham Perrin <grahamperrin@gmail.com>
>Date: Fri, 1 Sep 2023 06:05:14 +0000
>Subject: [PATCH 3/3] Porter's Handbook: fix a {freebsd-ports} link
>
>https://docs.freebsd.org/en/books/porters-handbook/book/#testing-portlint
>
>Fixes: 989d921f5d4a Migrate doc to Hugo/AsciiDoctor
>Signed-off-by: Graham Perrin <grahamperrin@gmail.com>
>---
> .../content/en/books/porters-handbook/testing/_index.adoc       | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
>diff --git a/documentation/content/en/books/porters-handbook/testing/_index.adoc b/documentation/content/en/books/porters-handbook/testing/_index.adoc
>index fe23e1143f..45da48584e 100644
>--- a/documentation/content/en/books/porters-handbook/testing/_index.adoc
>+++ b/documentation/content/en/books/porters-handbook/testing/_index.adoc
>@@ -108,7 +108,7 @@ For a new port, `portlint -A` is the most thorough; for an existing port, `portl
> 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.
> pass:[]
>-When in doubt, the best thing to do is ask on {freebsd-ports}.
>+When in doubt, the best thing to do is ask on the {freebsd-ports}.
> pass:[]
> 
> [[testing-porttools]]
>-- 
>2.30.8
>

Flags:

grahamperrin: maintainer-approval? (doc)

Actions: View | Diff

Attachments on bug 273483: 244542 | 244543 | 244544