From nobody Thu May 22 13:56:38 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 4b38wj1vYrz5whQ8 for ; Thu, 22 May 2025 13:56:53 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: from mail-pj1-x1030.google.com (mail-pj1-x1030.google.com [IPv6:2607:f8b0:4864:20::1030]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "WR4" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4b38wh4Wg1z3xB5 for ; Thu, 22 May 2025 13:56:52 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Authentication-Results: mx1.freebsd.org; none Received: by mail-pj1-x1030.google.com with SMTP id 98e67ed59e1d1-30e57a37294so7581940a91.2 for ; Thu, 22 May 2025 06:56:52 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bsdimp-com.20230601.gappssmtp.com; s=20230601; t=1747922211; x=1748527011; darn=freebsd.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=sBsfG/0tb5wRXzsS2oFe+PVxA54jxL/NkBLgl4RNld0=; b=EbI3aPxZrcdzLbPEGpTDt1lp/Pg8FjRn3oKCyA0NPrniijrNlx8A2RvGfw+pFwp5/l 87P7bDh0epQ+S9uxuVQogaz0ig7fFYZjrYfew67wASRIkhLHfwwIonaW146TL2Bolv9m 1m82QDhRp7E8n2JhSRW/Dko3ylL/ht+x9zj6/BkJzUf8WY79ioAkflrMPNXW1/oHer17 ODTgwd3gqHGX5gaJEP1HG7YJ95iFcJv4vbFGsRs5eZALGwY/3ZP5mblseUeCSt/jfZnl rv0h77vBONdOdTRqs2mJ18a2bUvjxE7/+hFHPQESIPye9VmPm8rl/1oPz0M3767Kqrs8 R4Mg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1747922211; x=1748527011; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=sBsfG/0tb5wRXzsS2oFe+PVxA54jxL/NkBLgl4RNld0=; b=P7ou8TKHr8COBjJZBsfOXhrySESQaKNH/fifaHijWCMMIafPWCejuDRXjBd3ZHKEK/ 76mV/tZXsXQIUYeMrYWbqZkj7py2nvgman8VyvAEKiKGBt7/zKffX/fyZ2EG5Amlk+1c yvefPD0nbozv7mFyr+ghJgUvW5202h1cBfCM4LnaXD2HrqBLLYlphJ93XcdOHjVvZfrF 1U0FBID4Pt82yAy3qmSiU+nVTzcLu1J3Getn9VmTT4zwX2I6glubp/KIHttgEBc3ILH4 vZCunMMpNNsqfRnSxDU/raKJjQT7pc9VIE0L3DWI6BivFDZNxmDpqTMPnxLRrlpqahC2 VJpg== X-Forwarded-Encrypted: i=1; AJvYcCWLkj7dp1NjnEBci0tj7ahjC6Z6Gr1sTfwWAsR+J4XRTqluLSHCMbq3wt+YefKf1Q76XLpdSeToIP8e6kv8NUY=@freebsd.org X-Gm-Message-State: AOJu0YxK5VPDlcc5e5mlXwosAnY+WDNqZ/3/f0RQLndFTt1odYkYg6sk pLW6PvdASoZkWdePK4Ib0TxC+C2DZMdBNwNd0MqUcm8P9A+DTVH/aKwsFP5YYVBCI/Zt+mghSCe y29boBHa93CCpDTyg7lViIEzQ2yKhoR6voSGby7ByzA== X-Gm-Gg: ASbGncun9pJ5Dxx7fzoO7o1DQTi/peSeiDMZq+FEpPhqOKY9tAnsKIcOMM3vgybh4uv GlckEqkHLmt7btRywaBTIvxIWSz5dT34ELUe84PHaD1xh56iUKIOAm7ZjBS17ur7GbEw+J6OvrW q8AHxu5TBKTpWiTos8cNgy1g6tp15wgyXBXR0YtssAhnhmzUgTpBzdIi5XVE8nDHHK3a+Ttn7PC GquvQ== X-Google-Smtp-Source: AGHT+IHeBv2tepc+udB8Pcl+YR03EpuuhM/PZsD+8CQFL5MREkQY1agx5BPQib6vmbqyBj8LIVWSU7M1oVyddyNirw8= X-Received: by 2002:a17:90b:52c8:b0:30e:382f:8b86 with SMTP id 98e67ed59e1d1-30e8312dc73mr41522466a91.15.1747922210969; Thu, 22 May 2025 06:56:50 -0700 (PDT) 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 References: <2d6ef406-2a4e-4876-b784-e9ad5a0e11be@app.fastmail.com> In-Reply-To: From: Warner Losh Date: Thu, 22 May 2025 07:56:38 -0600 X-Gm-Features: AX0GCFvhvL06QvmLtN1NW23rAQ4sVhS080HByVwLmA7ARXTTYgShOnqoMxtfSMU Message-ID: Subject: Re: Updating build and jail manual pages to include missing or obscure information To: Alexander Ziaee Cc: Dave Cottlehuber , freebsd-current , doc , emaste Content-Type: multipart/alternative; boundary="0000000000007aefaa0635b9da76" X-Rspamd-Queue-Id: 4b38wh4Wg1z3xB5 X-Rspamd-Pre-Result: action=no action; module=replies; Message is reply to one we originated X-Spamd-Result: default: False [-4.00 / 15.00]; REPLY(-4.00)[]; ASN(0.00)[asn:15169, ipnet:2607:f8b0::/32, country:US] X-Spamd-Bar: ---- --0000000000007aefaa0635b9da76 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Thu, May 22, 2025, 7:40=E2=80=AFAM Alexander Ziaee w= rote: > On 2025-05-22 02:05 -04:00 EDT, "Dave Cottlehuber" > wrote: > > On Tue, 20 May 2025, at 21:17, Billiam Crashkopf wrote: > >> Hello all, > >> > >> I recently had a bit of trouble finding the proper make targets to > build > >> and install the base FreeBSD system from source into an empty director= y > >> for use in a jail. I had scoured the build(7) manual trying to find > the > >> right workflow, but was unable to come up with a solution based solely > >> on the information available. After some discussion on the forum it wa= s > >> discovered that the answer was in fact in the jail(8) manual, under th= e > >> Examples section. However, the make targets listed in the jail(8) > >> manual are not documented in the build(7) manual. I'd like to open a > >> discussion around updating the documentation to make the correct > >> information easier to find. Specifically: > >> > >> * Should the 'world' and 'distribution' targets, and examples of > >> their use, be included in the build(7) manual? > > There seems to be a rough consensus that we should remove the world and > kernel targets. > > https://reviews.freebsd.org/D50276 > > I like them, the workflow listed in jail(8) is massively simpler and > faster than the current recommended workflow of building a pkgbase jail. > I object to removing these. I do agree we should document other methods, but my spidt sense is this is still in use... >> * Is the workflow listed in the jail(8) manual currently correct? > >> Should it cross-reference the build(7) manual? Is there a way to make > >> the information more discoverable? > > For a long time, build(7) said to read src/UPDATING. > I think for discoverability and maintainability, we should put all the > examples on build(7)ing the system in the examples section of build(7), a= nd > then reference that everywhere. > We recommended that to make sure people read the entries. So i wouldn't remove that, but it might make sense to trim but not remove it from UPDATING. Users only need to have more/vi working, and not man and all the things it calls. That will be much easier to maintain, and the documentation on the targets > and variables is already there. > We had a lot in Makefile to cope with a lot of churn in the early days. Plus having the docs with the code is quite helpful when trying to rebuild a system. Maybe things are settled enough we can move. Maybe the weight given to the rebuild the system can be reduced, but I worry that when things go wrong with an upgrade this may get in the way. >> * Is it worth adding these instructions, or a reference to them, to > >> the Handbook? > > I would like there to be a reference and not doc that will get stale. It > is very hard to maintain all the duplicated information. > Most of it should be in the handbook, despite the duplication. Especially the examples. The whole purpose of the handbook is to do the explaining, and a lot of the stuff in build(7) more properly belongs there.... snd that dynamic is another reason UPDATING and Makefile* have had a lot of this traditionally. I don't think it's as binary as you suggest. Warner Warner >> For reference, the original discussion is here: > >> > https://forums.freebsd.org/threads/installing-world-into-an-empty-jail.97= 866/ > >> > >> My intent is to file PRs for any changes and, if it would be helpful, > >> draft edits. > >> > >> Thanks, > >> > >> Bill > > > > Hi Bill > > > > yes to all of those I think. > > > > I believe Alex is doing some work in this area already, I'm happy > > to help as a reviewer btw despite my lack of knowledge of manpage > > macros. > > Hey, thanks for cc'ing me! Yes I am working on this; everyone is invited > and here's what I've got so far: > > https://reviews.freebsd.org/D48693 > > I have the manpage macros down; the issue is "what is the correct practic= e > that we want to be recommending?" and "what examples should we have or no= t > have?". > > Best, > Alex > --0000000000007aefaa0635b9da76 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


On Thu, May 22, 2025, 7:40=E2=80= =AFAM Alexander Ziaee <ziaee@freebs= d.org> wrote:
On 2025-05-22 = 02:05 -04:00 EDT, "Dave Cottlehuber" <dch@FreeBSD.org> wrot= e:
> On Tue, 20 May 2025, at 21:17, Billiam Crashkopf wrote:
>> Hello all,
>>
>> I recently had a bit of trouble finding the proper make targets to= build
>> and install the base FreeBSD system from source into an empty dire= ctory
>> for use in a jail.=C2=A0 I had scoured the build(7) manual trying = to find the
>> right workflow, but was unable to come up with a solution based so= lely
>> on the information available. After some discussion on the forum i= t was
>> discovered that the answer was in fact in the jail(8) manual, unde= r the
>> Examples section.=C2=A0 However, the make targets listed in the ja= il(8)
>> manual are not documented in the build(7) manual. =C2=A0 I'd l= ike to open a
>> discussion around updating the documentation to make the correct <= br> >> information easier to find.=C2=A0 Specifically:
>>
>>=C2=A0 =C2=A0 * Should the 'world' and 'distribution= 9; targets, and examples of
>> their use, be included in the build(7) manual?

There seems to be a rough consensus that we should remove the world and ker= nel targets.

https://reviews.freebsd.org/D50276

I like them, the workflow listed in jail(8) is massively simpler and faster= than the current recommended workflow of building a pkgbase jail.

I object = to removing these. I do agree we should document other methods, but my spid= t sense is this is still in use...

>>=C2=A0 =C2=A0 * Is the workflow listed in the jail(8) manual curren= tly correct?=C2=A0
>> Should it cross-reference the build(7) manual?=C2=A0 Is there a wa= y to make
>> the information more discoverable?

For a long time, build(7) said to read src/UPDATING.
I think for discoverability and maintainability, we should put all the exam= ples on build(7)ing the system in the examples section of build(7), and the= n reference that everywhere.
=
We recommended that to make sure people read th= e entries. So i wouldn't remove that, but it might make sense to trim b= ut not remove it from UPDATING. Users only need to have more/vi working, an= d not man and all the things it calls.

That will be much easier to maintain, and the documentation on the targets = and variables is already there.

We had a lot in Makefile to cope with a lot = of churn in the early days. Plus having the docs with the code is quite hel= pful when trying to rebuild a system. Maybe things are settled enough we ca= n move. Maybe the weight given to the rebuild the system can be reduced, bu= t I worry that when things go wrong with an upgrade this may get in the way= .


>>=C2=A0 =C2=A0 * Is it worth adding these instructions, or a referen= ce to them, to
>> the Handbook?

I would like there to be a reference and not doc that will get stale. It is= very hard to maintain all the duplicated information.

Most of it should be = in the handbook, despite the duplication. Especially the examples. The whol= e purpose of the handbook is to do the explaining, and a lot of the stuff i= n build(7) more properly belongs there.... snd that dynamic is another reas= on UPDATING and Makefile* have had a lot of this traditionally. I don't= think it's as binary as you suggest.

=
Warner

Warner

--0000000000007aefaa0635b9da76--