Re: HOWTO articles for migrating from Linux to FreeBSD, especially for pkg?

On Mon, Oct 20, 2014 at 08:04:14PM -0400, Allan Jude wrote:

> > For instance, the page that talks about running buildworld and buildkernel
> > have some instructions that are evidently vestigal for root-on-ZFS people.
> 
> Which parts? Nothing about buildworld is really any different when using
> ZFS except maybe the way you mount /usr/obj with noatime etc.

https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html

In this case, after "shutdown now" it suggests turning off a readonly flag
that's not on, mounting everything despite nothing being unmounted, and
setting the kernel time zone despite that never seeming to be an issue.


> Can you be more specific? The documentation team likes to add 'quick start'
> sections to the often more complex sections, so that users looking to just
> get started can do so, and dig into the more advanced options once they
> have it working.

Sure.

https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/ports-poudriere.html

So, coming at it from scratch, the section has a quick description and notes
where to find a sample config file. Then it says "It may be convenient to put
poudriere datasets in an isolated tree mounted at /poudriere. Defaults for
the other configuration values are adequate." However, that's the first
appearance of the word "dataset" so I don't know what it is or why I want a
root-level mount for it.

Section 5.6.1 has an example invocation:

    poudriere jail -c -j 10amd64 -v 10.0-RELEASE

This might not catch everyone, but the formality of the jail name and the
version made me think that the jail name has to be of a certain strict form
to work. Maybe it doesn't? It's not entirely clear.

Then there's another example invocation:

    poudriere ports -c -p local

It's not altogether clear (to me at least) what this is doing as compared
with the -c -i -v invocataion. Again, I suspect I can spend enough time
reading docs to figure it out, but that completely negates the value of the
Handbook as a primary source for information.

After these two somewhat opaque examples, we're told "poudriere can build
ports with multiple configurations, in multiple jails, and from different
port trees" and "The basic configuration shown here puts a single jail-,
port-, and set-specific make.conf in /usr/local/etc/poudriere.d." This one
definitely got me, as it seems to suggest that things should live in
/usr/local/etc/poudriere.d, but it doesn't specify exactly where. I see
something now that I think I missed before, which is that the long string
"10amd64-local-workstation-pkglist" references bits of text from the first
two invocations, but the description of how the string is formulated is
somewhat opaque, depending to some extent on the still-undefined "set" which
I presume to mean the same thing as "dataset".

But, where do I go to find the built packages? I'm guessing at the moment
that I'd find them somewhere in /poudriere, but I'm not entirely clear on how
different architectures and sets and such are kept distinct... (I spun up a
large virtual machine to do a test build and try to observe where things went
afterwards, and at that I was still unclear on where, for instance, config
options were stored... Anyway, the build exhausted its eight gigs of RAM and
the OOM killer made a mess of things, and I haven't had a chance to revisit
the process.)

It's entirely possible that I'm just old and slow and that this stuff isn't
as unclear to me as it seems, but at the very least it's introducing new
concepts without defining them and then using them in combinations that don't
help the reader to understand how the combinations work. Part of this is
inconsistency in formatting - are all the italic bits freeform text that
doesn't matter, in the examples? It seems like some of them (FreeBSD version,
for example) can't be. Again, a dig through more docs would clarify it, but
if that's necessary then this Handbook section seems somewhat inadequate.



> One goal is to actually have the version of the ports tree that the most
> recent binary packages were built with available, so that users who use
> that would have 0 complications from mixing.

That would be useful.


> Also, there have been some proposed features for pkg to make it aware of
> which packages were installed from ports, and when 'pkg upgrade' runs, to
> rebuild those packages from ports with the same options, instead of
> installing the 'wrong' version from the binary packages, requiring the user
> to 'pkg lock' or 'pkg annotate' to avoid that.

Hm, I'm as yet unfamiliar with those two commands, but again, that sounds
pretty useful.


> Binary packages of libdvdcss are not built for legal reasons

I figured as much - Debian doesn't ship it at all, for comparison, leaving
the user in an even worse position. It was a cause of stress when I also had
"don't mix pkgs and ports" emblazoned across my vision.

Worth noting is that my world hasn't ended mixing the two, to the point where
I'm doing so fairly freely.


> Making config-recursive the default is infact a good idea, unless someone
> knows a reason it should not be.

To reiterate, I gave up on FreeBSD for a time because I didn't know about it,
during that period when there were no binary packages available at all. Other
than Gentoo users, *everyone* coming from Linux is going to be coming from a
distribution where binary packages are the default, with building source
packages a relatively rare occurance. The first time they're faced with, say,
building a big hunk of X and then finding their machine sitting at a
configure screen, waiting for their input, they *will* vomit.


> The pre-populated with every option version of rc.conf is
> /etc/defaults/rc.conf

Oh, hrm. So, my suggestion here would be having a comment in rc.conf by
default that mentions this.


> There was a project to better document the sysctl tunables, but it seems
> to have stalled.

Seems like that would be useful.


Oh, while I'm on random nits, I'm using the Realtek network card built into
my motherboard. It's a pretty common one, but it doesn't work quite right
with FreeBSD. I might have found a combination of options to get it to work
without periodic stalls or lock-ups (disable MSI and MSI-X, and set
dev.re.0.int_rx_mod=0) but it was frustrating enough at several points for me
to twitch and start looking for systemd-free Linux distributions, on the idea
that the interface just works there, before I settled down and remembered all
the reasons why I want to be running FreeBSD - of which there are many.

While this is worthy of a bug report once I know more, it also qualifies as a
mild docbug, because re(4) say, of dev.re.0.int_rx_mod:

    The following variables are available as both sysctl(8) variables and
    loader(8) tunables:

But, in fact, it doesn't work as a loader tunable. I mention it as it's on
the short list of things that really ticked me off and got me reading
Slackware docs.

If the goal is being friendly to people escaping Linux and systemd, one last
bit that would be useful is having a "dual booting" section that describes
how to add a FreeBSD chainloading entry to GRUB. I figured it out after a
while, and now of course I don't dual boot at all, Debian being wholly
expunged from my system, but having a clear path to dual-booting would lower
the barrier for people to test the waters.

Also in this vein would be making it possible to do a full install into a
portion of a disk, where right now the installer wants a whole disk, but this
goes beyond being a docbug and should be considered separately. (I'm not sure
that how I implemented chainloading would be easily accomplished on a single
disk split between Linux and FreeBSD either, FWIW.)

-- 
The creatures outside looked from pig to man, and from man to pig, and from pig
to man again; but already it was impossible to say which was which. - G. Orwell