# Improvements to FreeBSD Handbook (portmaster)



## bugzeo (Aug 22, 2022)

Following this issue:
black screen when x starts after upgrade

Followed the handbook chapter 24:

```
# freebsd-update fetch
# freebsd-update install
# pkg-static upgrade -f
# portmaster -af
portmaster: Command not found.
```
Clearly the handbook needs to explain why portmaster is not included by default, since it's mentioned like the command comes with all default FreeBSD installs...


----------



## zirias@ (Aug 22, 2022)

Seriously? Right above, it reads


> Packages can be upgraded using `pkg upgrade`. To upgrade installed ports, use a utility such as ports-mgmt/portmaster.


So, portmaster is just _one_ tool enabling you to "manage" ports, and it's shown here as an example.

It's also pretty obvious you're not supposed to run _both_ commands, as one is for packages and the other one for ports.

I recommend you read Chapter 4 first.


----------



## bugzeo (Aug 22, 2022)

Which both commands are not supposed to be run together? Section "24.2.3.2. Upgrading Packages After a Major Version Upgrade" doesn't mention anything about that. Neither you nor the HandBook are much clear.


----------



## zirias@ (Aug 22, 2022)

Maybe it helps just reading all the text instead of blindly copying commands out of the black boxes... (and *again*, read Chapter 4 *first*, it will explain you you're not supposed to use *both* ports and packages)


----------



## bugzeo (Aug 22, 2022)

Dude, I've read the text. What happens if I have binaries and ports installed? Shouldn't I run both pkg upgrade and portmaster? Doesn't the system detect which ones need upgrading?


----------



## zirias@ (Aug 22, 2022)

bugzeo said:


> What happens if I have binaries and ports installed?


Then you left what's supported. Mixing them is possible for sure, but very much discouraged unless you already know *exactly* what you're doing.


----------



## bugzeo (Aug 22, 2022)

zirias@ said:


> Then you left what's supported. Mixing them is possible for sure, but very much discouraged unless you already know *exactly* what you're doing.


So, the idea that you should tell me is that I should use pre-compiled pkgs where possible and if not user ports. Probably the HandBook should mention something about this too...


----------



## zirias@ (Aug 22, 2022)

See the *fat warning* in Chapter 4 of the handbook. Normally, you start reading a handbook from the beginning, that's how it's supposed to be used.

In addition to that warning, when it comes to upgrading, you must be aware that ports ultimately build and install packages (although the actual package file is not created if you just install the port) and they are registered in the very same package database `pkg` is using. So, running a package upgrade will attempt to also upgrade whatever you installed from ports, but using official packages. It's a recipe for disaster.


----------



## zirias@ (Aug 22, 2022)

Just for completeness: There *is* an elegant way to have both, custom-configured ports and official packages, without any issues: Build your own package repository using ports-mgmt/poudriere-devel (and configure `pkg` to use this local repo instead of the official one). This version of poudriere has an option to fetch official packages and put them in your local repository. It's AFAIK not in the handbook, after all, it's still a "development" version (but works fine in my experience).


----------



## jmos (Aug 23, 2022)

bugzeo said:


> Followed the handbook chapter 24:
> 
> ```
> # freebsd-update fetch
> ...


If I'm reading chapter 24 it is different: Direct in front of the portmaster command there's written: "A rebuild of all installed applications can be accomplished with this command:". So, if you build (!) packages you can use f.e. a portmaster command. Have you build packages?

And only one paragraph in front of that sentence I can read: "Packages can be upgraded using `pkg upgrade`. To upgrade installed ports, use a utility such as ports-mgmt/portmaster." With a clear link to the portmaster port.

And if you don't know the difference between ports and packages: There's also a whole chapter about that topic, too.

The handbook is clear. Your post suggests a mess that isn't written there as copied here. And: Never ever copy commands without understanding what they are doing. Even not from the handbook.


----------



## richardtoohey2 (Aug 23, 2022)

I don't _think_ portmaster use is encouraged (use it myself, but know it's not smiled upon) - it's due for deprecation (before 14.x?)  So don't think it's meant to be too obviously documentated in case people start going down the obsolete path.


----------



## zirias@ (Aug 23, 2022)

richardtoohey2 said:


> I don't _think_ portmaster use is encouraged (use it myself, but know it's not smiled upon) - it's due for deprecation (before 14.x?)


Where did you read that? Seriously, I'd like to know about it, just out of curiosity. It can't be tied to a FreeBSD release though, it's a port itself. I personally don't see a reason to deprecate it... Maybe you're confusing it with portsnap(8), which is part of base (and also still in the handbook), needs extra server-side infrastructure and is of questionable value nowadays where you could just use `git`? (And still, it wasn't removed yet)

The only "issue" with portmaster is the same as with similar tools, everything is built on your running system. Problems (rarely) resulting from this (like version conflicts during upgrades, picking up "automagic" dependencies, ...) can't be 100% avoided and that's by design. That's why I would always recommend to build your own pkg repository with poudriere, even on a single machine. Building each and every port in its own clean jail is the most reliable way to do things. But AFAIK, for people who _want_ to use the ports tree directly, portmaster is still the recommended way to go...


----------



## richardtoohey2 (Aug 23, 2022)

Oops you are right, sorry!  Yes, I mixed it up with portsnap. I know portmaster has its detractors (and issues) but it works for me … but that’s nothing to do with this thread.

(Excuse me while I go and bang my head on the wall!)


----------



## jmos (Aug 23, 2022)

zirias@ said:


> The only "issue" with portmaster is the same as with similar tools, everything is built on your running system.


Portmaster can be used in a explicit jail, too. The pkg command itself offers everything to build up a repository from all in the jail installed packages, and to get a little more comfort I've wrote ascript (comparing the repository with the installed packages, remove old packages from the repository, add new ones, update the repositories meta file, fire up a small webserver etc.).


----------



## zirias@ (Aug 23, 2022)

jmos said:


> Portmaster can be used in a explicit jail, too.


Sure, but this jail can't be "cleaned" for every port you build. So this is in no way comparable.


----------



## jmos (Aug 23, 2022)

zirias@ said:


> Sure, but this jail can't be "cleaned" for every port you build. So this is in no way comparable.


I really don't get it… I can remove all ports and compile them again, I can tell portmaster to recompile all ports that a to update port is depending on (option "-t"), and I can also tell portmaster to recompile all ports that depend on a to build port (option "-R/-r").

So one or all ports can be compiled by having a complete fresh environment for it, and the dependencies of ports can be handled normally as well as upwards and downwards. Doing this in a jail separates everything from my main machines installation. What am I missing? Isn't that "cleaned for every port"?


----------



## zirias@ (Aug 23, 2022)

To get closer to "clean" builds, you would need to build each and every port starting with a jail without any ports/packages installed. And still, it wouldn't be the same. Ports have dependencies needed only at build time. Those will accumulate along a larger dependency tree. Once you reach your leaf port you actually intended to build, there will be a lot more stuff installed in your jail than needed to build just _this_ port.

Poudriere clones a new jail for every single port it builds, and populates it (from packages that were built before) with _only_ what this port needs. You can't "emulate" that behavior with portmaster. Otherwise, there would be no need for poudriere.


----------



## fscorrea (Sep 12, 2022)

jmos said:


> Never ever copy commands without understanding what they are doing. Even not from the handbook.


What's this lingering sensation I'm having that, if someone followed your actually, wise suggestion up there, this someone could mysteriously give up on FreeBSD if not on UNIX-like as a whole, Linux included...

TBH, I ignored this (other, the one about not mixing ports and packages) advice myself in the past sometimes still do. Of course, I'd take responsibility for whatever result from doing so alone, though.


----------



## jmos (Sep 14, 2022)

fscorrea said:


> What's this lingering sensation I'm having that, if someone followed your actually, wise suggestion up there, this someone could mysteriously give up on FreeBSD if not on UNIX-like as a whole, Linux included...


IMO: If your someone really doesn't want to go to the trouble of understanding the basic function of an unknown command before executing it, then perhaps this is also quite good. Or should we be concerned about every user who would be better off with another operating system?

The times when such users were recommended a "read mail real fast" are over. That was not fair dealing. My recommendation is honest and constructive, not destructive.


----------

