pkg-static Handbook vs. man page

indomitableMoron

indomitableMoron

Reading through the Handbook, specifically 26.2.3.2, there is a reference to `pkg-static upgrade -f` as being a necessary step after switching major versions. I typically like to know what switches that I'm throwing at the box do, so I checked `man pkg-static` to discover there is no mention of a -f switch.

What would be an appropriate next step to get that remedied? (I'm new the the FreeBSD project and am looking for ways to contribute, not that this is a significant thing, but its a start.)
 
It may not be obvious at first sight. The man page of pkg(8) does not contain the detailed information of its various commands as in:
pkg <options> <command> <flags>

A brief description of those various commands you'll find in the COMMANDS section. A detailed description you'll find in its respective man page for each (sub) command, such as pkg-upgrade(8); note the inserted dash. There you'll see the complete and detailed description, including the -f flag. Note that, as is mentioned at pkg-static(8), this statically linked variant has mostly the same functionality as pkg(8); the specific variant pkg-static isn't mentioned again at pkg-upgrade(8)

This "man page splitting" happens with more commands in an attempt to not having too long man pages; for example also with zfs(8). If you look at the SEE ALSO section at the end of a command of a man page, you'll find the references where you can find more information, in this case: pkg-upgrade(8)
 
man 7 pkg
Code: 
pkg [-46] bootstrap [-fy] [-r reponame]
           Attempt    to bootstrap and do not    forward    anything to pkg(8) af-
           ter it is installed.  With -4 and -6, pkg will  force  IPv4  or
           IPv6 respectively to fetch pkg(8) and its signatures as needed.
           If  the    -f  flag is specified, then pkg(8) will    be fetched and
           installed regardless if it is already  installed.   If  the  -y
           flag  is     specified,  no     confirmation will be asked when boot-
           strapping pkg(8).
There's pkg(7) which is part of the base and it's used to install pkg(8) from the port/package. After major upgrade your pkg(8) will be old with incompatible ABI for the new kernel so it must be reinstalled again via pkg(7).

pkg(7)

man.freebsd.org man.freebsd.org

To avoid backwards incompatibility issues, the actual pkg(8) tool is
not installed in the base system. The first time invoked, pkg will
bootstrap the real pkg(8) from a remote repository
Click to expand...
 
VladiBG said:
There's pkg(7) which is part of the base and it's used to install pkg(8) from the port/package. After major upgrade your pkg(8) will be old with incompatible ABI for the new kernel so it must be reinstalled again via pkg(7).
Click to expand...
Not exactly, the kernel by default includes compatibility with older FreeBSD releases. What's an issue is userspace ABI (changed shared libraries). That's what pkg-static solves, it's just the normal pkg(8) but linked statically (so it doesn't need any libs at runtime). pkg can also update/reinstall itself. Normally, you'll only ever need the base pkg(7) tool once ... before the real pkg(8) is first installed.
 
Erichans said:
This "man page splitting" happens with more commands in an attempt to not having too long man pages; for example also with zfs(8). If you look at the SEE ALSO section at the end of a command of a man page, you'll find the references where you can find more information, in this case: pkg-upgrade(8)
Click to expand...

Thanks for pointing out the splitting tactic for brevity; that makes sense (long man pages are the worst).

Just hoping to understand the delineations for what goes in 8 (or 1, or whatever) vs. section 7... In our specific example of pkg(8), there is a "SEE ALSO" section, but it makes no mention of pkg(7). In fairness to the docs, `apropos pkg` does list pkg(7) but (ironically?) not pkg(8). And again, in fairness, pkg(7) does reference pkg(8) in it's SEE ALSO section, so if you started at `apropos pkg` and worked your way very diligently through, you would end-up reading both man pages, but that seems a circuitous route to take.

From this noob's perspective, either pkg(8) and pkg(7) should show up in `apropos pkg`, or there should be a reference in pkg(8)'s SEE ALSO to pkg(7).

One might further argue that, as a convention, pkg(8) should be authoritative about the switches and their functions with pkg(7) being reserved for the more exhaustive walk-through of scenarios, configurations, etc.
 
zirias@ said:
Not exactly, the kernel by default includes compatibility with older FreeBSD releases. What's an issue is userspace ABI (changed shared libraries). That's what pkg-static solves, it's just the normal pkg(8) but linked statically (so it doesn't need any libs at runtime). pkg can also update/reinstall itself. Normally, you'll only ever need the base pkg(7) tool once ... before the real pkg(8) is first installed.
Click to expand...
This was a great explanation that was helpful, thank you.

For those wondering what "ABI" stands for, its "application binary interface", as explained in this thread. I had to look it up, so I figured others who were new to FreeBSD would not know either.
 
indomitableMoron said:
… there should be a reference in pkg(8)'s SEE ALSO to pkg(7). …
Click to expand...

Good idea, please report a bug.

In the meantime, from pkg(8) COMMANDS <https://man.freebsd.org/cgi/man.cgi?query=pkg&sektion=8&manpath=freebsd-ports#COMMANDS>:

bootstrapThis is for compatibility with the pkg(7) bootstrapper. If pkg is already installed, nothing is done.

If invoked with the -f flag an attempt will be made to reinstall pkg from remote repository.

indomitableMoron said:
apropos
Click to expand...

apropos(1)

This report might help to understand how things do, and don't, work with apropos:

273324 – Stem apropos results at man.freebsd.org

bugs.freebsd.org bugs.freebsd.org

Also FYI:

272906 – man.cgi: make apropos support filtering by section

bugs.freebsd.org bugs.freebsd.org
 
indomitableMoron said:
I had to look it up, so I figured others who were new to FreeBSD would not know either.
Click to expand...
If you are interested in writing good documentation here is what tools, I have found useful for creating my own notes: pkg install abiword, dia, xfce-screenshooter
  1. Abiword to write a document with using Numbered Headers for the Table of Contents creation.
  2. Dia, nice little simple Diagram editor. I noticed in my own learning a new topic or item. That strictly "plenty of words, full of descriptions", without a picture diagram, makes it hard to concentrate and focus on a picture foundation to learn what goes where. Visual picture diagrams help me learn and understand the concept, otherwise I get lost in the many words.
  3. xfce-screenshooter, A frame grabber that can select
    a.) Whole Desktop
    b.) Active Window
    c.) Area region. I use this the most

Here is an example that I created. YMMV. I could use some writing help to move contents around and make this flow better. I wanted to create package using the tools, but did not come across any docs except a couple pages. I did NOT need to compile with C and use a MAKE file. All I wanted to do was put 4 files into a single package and share with other GhostBSD, FreeBSD, & Linux users. So I studied, worked, tested and wrote down my results. Could expand with a simple set of test files, that a new user could install as a package, and then play with the package creation file to build the same package and learn the techniques in packaging. Fred
http://ghostbsdarm64.hopto.org/packages/Dead_Simple_Binary_Packaging_How_To_10_6C.pdf
http://ghostbsdarm64.hopto.org/packages/Dead_Simple_Binary_Packaging_How_to_10C.abw
 

Attachments

You must log in or register to reply here.
Back
Top