Page MenuHomeFreeBSD

patches to Handbook ports section: part 3
Needs ReviewPublic

Authored by linimon on Jan 10 2017, 11:43 PM.


Group Reviewers
Doc Committers

This patch adds a section on ports-mgmt/synth, as taken from its pkg-descr. It also adds a table comparing and contrasting poudriere, portupgrade, portmaster, and synth.

Diff Detail

Lint Skipped
Unit Tests Skipped

Event Timeline

linimon retitled this revision from to patches to Handbook ports section: part 3.
linimon updated this object.
linimon edited the test plan for this revision. (Show Details)
linimon added reviewers: Doc Committers, wblock.

Terms like "newest" quickly become outdated in the Handbook. Maybe just "newer"?


Typo: s/packge/package/


Be consistent in capitalization here. Elsewhere, these are capitalized with <application> tags.


Try to avoid asides, they interrupt the train of thought.

"It is simple to learn and user-friendly, with a limited number of powerful options. It is extremely fast..."


'"drop-in" on' sounds like a visit. Also kind of unusual for non-native speakers. How about just "work on"? (Although I'm not sure that's accurate.)


"Clean" is unclear here. Can be taken to mean different things. Also, "finally safe" kind of disregards poudriere.


"Profile" has not been defined, and "system" is fuzzy, too. I think this is trying to say that the host system is used as a default template for the building of ports.


The way this is laid out kind of suggests that a new jail is the valuable feature. Rearrange, maybe, or maybe just not even mention a jail.


Passive->active: s/will show/shows/


We should be consistent with <application> tags for these names.


Please avoid semicolons, they are usually just sentence splices:
"Synth requires no preparation. It works"


"upon installation" makes it sound like it takes off running as soon as installed, but pretty sure that was not meant.


Shouldn't capitalize "to" here. igor would know for sure.


These are not literal strings, so those tags are not needed. They don't need to be capitalized, either.


Come to that, I'm not certain this paragraph is helping. When someone else edits this, is it still subjective? Or rather, isn't the whole book somewhat subjective?


I think align="left" is the default, but not sure.


Capitalize "Individual".


Probably should add "No dependencies".


This should probably be "Ruby required", same "required" for the later ones.


bapt said there was a way to do config dialogs, but I forget what it was.


Does x86 imply i386 and amd64? I'm not sure.


No blank line here.


No blank line here.


No blank line here, either.

first batch, the system isn't letting me comment more than this.


I agree. Maybe the sentence could be something like "The ports-mgmt/synth utility for upgrading ports was introduced in January, 2016". Maybe dates could be added to the other tools and the reader can calculate relative newness and that won't get obsolete.


poudriere doesn't build on a live system, it has a dedicated jail.
portmaster, portupgrade always use the host system and synth uses the host system by default, but it can also use a dedicated environment like poudriere does. So the "finally safe" comment is correct even with regard to poudriere because it doesn't apply to poudriere.

That being said, maybe there's a better way to say it.


It means it's available for use immediately after installation. I don't think anybody would assume it's launched upon installation because nothing else does that.


yes x86 is understood to mean both i386 and x86_64.

remaining comments-to-comments


Almost. It's saying the default configuration will use the host system to build ports as opposed to a dedicated jail. A profile is a configuration set, and there are unlimited number of profiles possible. This is how one would use synth to build packages for different releases of FreeBSD or even different architectures or even test out new configurations for -CURRENT (e.g. privatize libraries like ncurses or openssl and see the fallout on ports).


What it's trying to say, badly, is that for some people, poudriere's unconditional use of a dedicated jail is a bad thing. They need the packages built on the host environment which is apparently custom. Synth by default uses the host system which is a "pro" for some people, a "con" for others, and a wash for the remaining majority.

As a standalone comment, maybe one that doesn't affect documentation:

It's true that Ada is currently available on x86 only.
With a bit of work, and access to an appropriate machine, gcc6-aux could be expanded to ARM platform.
In theory it could be expanded to any of the tier 2 platforms with the possible exception of aarch64.
It's a matter of interest and resources. Bootstrapping a compiler is not trivial so I need some expressed interest and hardware.

It's unclear to mean which T2 are rising and which are falling. (I assume aarch64 is rising but unclear about the rest)