Bug 253179 - ports(7) man page description of 'packages' target is out of date
Summary: ports(7) man page description of 'packages' target is out of date
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Some People
Assignee: Daniel Ebdrup Jensen
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2021-02-02 15:32 UTC by Robert Watson
Modified: 2021-02-19 12:46 UTC (History)
3 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Robert Watson freebsd_committer 2021-02-02 15:32:34 UTC
In attempting to build packages locally, I read the documentation, and was confused by the following pieces of text from ports(7):

...
     package              Make a binary package for the port.  The port will
                          be installed if it has not already been.  The
                          package is a .tbz file that you can use to install
                          the port on other machines with pkg-add(8).  If the
                          directory specified by PACKAGES does not exist, the
                          package will be put into the current directory.  See
                          PKGREPOSITORY and PKGFILE.
...
     PACKAGES          Used only for the package target; the base directory
                       for the packages tree, normally packages/ in PORTSDIR.
                       If this directory exists, the package tree will be
                       (partially) constructed.  This directory does not have
                       to exist; if it does not, packages will be placed into
                       the current directory, or you can define one of

                       PKGREPOSITORY      Directory to put the package in.

                       PKGFILE            The full path to the package.
...

When I attempted to build a package, I was surprised not to find it in my current working directory (the root of the port), as I hadn't specified PACKAGES on the command line. It turns out that it is not in the current working directory, but in work/pkg relative to the current working directory. This probably needs updating.

When I ran find(1) to try and find the package, I was further surprised not to find any, having used the pattern '*.tbz' as suggested by the text "a .tbz file". In fact, ports are now .txz files.  This probably needs updating.
Comment 1 Mateusz Piotrowski freebsd_committer 2021-02-02 15:58:08 UTC
I'll take a look. Thanks for the report.
Comment 2 Mark Linimon freebsd_committer freebsd_triage 2021-02-02 16:23:39 UTC
I'm not yet set up to work on the new docs/src trees.
Comment 3 Mateusz Piotrowski freebsd_committer 2021-02-18 21:13:37 UTC
Return to the pool for the time being.
Comment 4 Daniel Ebdrup Jensen freebsd_committer 2021-02-18 21:40:58 UTC
Yoink.
Comment 5 Daniel Ebdrup Jensen freebsd_committer 2021-02-18 22:01:03 UTC
I opened review D28781, mostly because I wanted to ensure I got the phrasing correct.
Comment 6 commit-hook freebsd_committer 2021-02-19 12:45:30 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/src/commit/?id=248a47a4c2fb229ae815fa61875b3f62a2d6856c

commit 248a47a4c2fb229ae815fa61875b3f62a2d6856c
Author:     Daniel Ebdrup Jensen <debdrup@FreeBSD.org>
AuthorDate: 2021-02-18 21:50:54 +0000
Commit:     Daniel Ebdrup Jensen <debdrup@FreeBSD.org>
CommitDate: 2021-02-19 12:42:16 +0000

    ports(7): Update instructions for package target

    Packages default to ending up in a different location compared to the
    documentation, so catch up to the implementation by referring to the
    location where packages can usually be found if no environment variables
    have been set.

    While here, also update the mention of the file extension to match the
    txz format that packages use.

    PR:             253179, 224370
    Reported by:    rwatson, jeromer at fastmail dotnet

 share/man/man7/ports.7 | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)
Comment 7 Daniel Ebdrup Jensen freebsd_committer 2021-02-19 12:46:37 UTC
Thank you for your attention to detail. :)