Re: Updating build and jail manual pages to include missing or obscure information

On 5/22/25 12:27, Lexi Winter wrote:
> resin-freebsd@g-cipher.net:
>> Just to share my two cents: I think all available options should be
>> documented in the manual.
> i'm fine with having 'make world' documented somewhere, although such
> documentation should probably note that it's been deprecated for over
> 20 years.  i'm just saying it can't be documented as a way of upgrading
> the host system since it won't do that -- it will refuse to run unless
> DESTDIR is set, so it can upgrade jails, but not hosts.

Totally fair.

I'm still unclear on the deprecated status of the 'world' target.  Is it 
deprecated because it's dangerous for the running system?  It clearly 
has some guard rails to prevent accidents (DESTDIR or 
HISTORICAL_MAKE_WORLD must be set).  If it's truly deprecated then it 
shouldn't be used in the jail instructions. But it also has more 
functionality than buildworld + installworld because it has logic for 
optionally making pre-world and post-world targets.

Options I see are:

   * Declare the 'world' target deprecated only for updating, but fine 
for other uses

   * Declare the 'world' target deprecated for all uses; update the jail 
build instructions with a more verbose invocation.

   * Declare the 'world' target deprecated for all uses; add an alias 
for the same recipe that doesn't have any legacy meaning.