From nobody Thu May 22 19:22:33 2025 X-Original-To: freebsd-current@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4b3J8b4Pjxz5x3hk for ; Thu, 22 May 2025 19:22:39 +0000 (UTC) (envelope-from resin-freebsd@g-cipher.net) Received: from g-cipher.net (leon.g-cipher.net [5.9.120.19]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4b3J8Y4VjGz3wtQ for ; Thu, 22 May 2025 19:22:37 +0000 (UTC) (envelope-from resin-freebsd@g-cipher.net) Authentication-Results: mx1.freebsd.org; dkim=none; spf=pass (mx1.freebsd.org: domain of resin-freebsd@g-cipher.net designates 5.9.120.19 as permitted sender) smtp.mailfrom=resin-freebsd@g-cipher.net; dmarc=none Received: (qmail 92891 invoked from network); 22 May 2025 14:22:35 -0500 Received: from unknown (HELO ?192.168.7.176?) (resin@unknown) by g-cipher.net with ESMTPS (TLS_AES_128_GCM_SHA256 encrypted); 22 May 2025 14:22:35 -0500 Message-ID: <2f6b255b-696c-44ed-9c32-b70daec0ff4f@g-cipher.net> Date: Thu, 22 May 2025 12:22:33 -0700 List-Id: Discussions about the use of FreeBSD-current List-Archive: https://lists.freebsd.org/archives/freebsd-current List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-current@FreeBSD.org MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: Updating build and jail manual pages to include missing or obscure information To: freebsd-current References: <2d6ef406-2a4e-4876-b784-e9ad5a0e11be@app.fastmail.com> Content-Language: en-US Cc: doc From: resin-freebsd@g-cipher.net In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit X-Rspamd-Queue-Id: 4b3J8Y4VjGz3wtQ X-Spamd-Bar: / X-Spamd-Result: default: False [0.63 / 15.00]; NEURAL_SPAM_LONG(0.96)[0.963]; NEURAL_HAM_SHORT(-0.49)[-0.493]; NEURAL_SPAM_MEDIUM(0.26)[0.262]; ONCE_RECEIVED(0.20)[]; R_SPF_ALLOW(-0.20)[+a:c]; MIME_GOOD(-0.10)[text/plain]; MIME_TRACE(0.00)[0:+]; RCVD_COUNT_ONE(0.00)[1]; ARC_NA(0.00)[]; FROM_NO_DN(0.00)[]; ASN(0.00)[asn:24940, ipnet:5.9.0.0/16, country:DE]; MID_RHS_MATCH_FROM(0.00)[]; R_DKIM_NA(0.00)[]; TO_MATCH_ENVRCPT_SOME(0.00)[]; FROM_EQ_ENVFROM(0.00)[]; RCPT_COUNT_TWO(0.00)[2]; TO_DN_ALL(0.00)[]; MLMMJ_DEST(0.00)[freebsd-current@freebsd.org]; DMARC_NA(0.00)[g-cipher.net]; RCVD_TLS_ALL(0.00)[] On 5/22/25 09:16, Lexi Winter wrote: > Warner Losh: >> On Thu, May 22, 2025, 7:40 AM Alexander Ziaee wrote: >>> There seems to be a rough consensus that we should remove the world and >>> kernel targets. >> I object to removing these. I do agree we should document other methods, >> but my spidt sense is this is still in use... > note that 'make world' already doesn't work unless you're using DESTDIR > (or you set a special make knob) so it shouldn't be documented as a way > of upgrading the system in general, e.g. in build(7). > > afaik, every invocation of 'make world' can be trivially replaced by > 'make buildworld installworld', but there may be some argument for > keeping it around for people who use it to build jails, for the sake > of muscle memory. Just to share my two cents: I think all available options should be documented in the manual.  It's a reference document, so it's there to give a complete view of the interface.  Instructions on anything other than the simplest use cases should be out of scope.  Long-form how-to articles are what the handbook is for.  A README file (i.e. UPDATING) is good as a quick start, but shouldn't be complete reference or point of truth.