NetBSD Problem Report #48741

From www@NetBSD.org  Sun Apr 13 02:08:34 2014
Return-Path: <www@NetBSD.org>
Received: from mail.netbsd.org (mail.netbsd.org [149.20.53.66])
	(using TLSv1 with cipher ECDHE-RSA-AES256-SHA (256/256 bits))
	(Client CN "mail.netbsd.org", Issuer "Postmaster NetBSD.org" (verified OK))
	by mollari.NetBSD.org (Postfix) with ESMTPS id AC80DA580D
	for <gnats-bugs@gnats.NetBSD.org>; Sun, 13 Apr 2014 02:08:34 +0000 (UTC)
Message-Id: <20140413020833.564E3A581B@mollari.NetBSD.org>
Date: Sun, 13 Apr 2014 02:08:33 +0000 (UTC)
From: dhgutteridge@sympatico.ca
Reply-To: dhgutteridge@sympatico.ca
To: gnats-bugs@NetBSD.org
Subject: Patch to improve BUILDING documentation
X-Send-Pr-Version: www-1.0

>Number:         48741
>Category:       toolchain
>Synopsis:       Patch to improve BUILDING documentation
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    toolchain-manager
>State:          closed
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Sun Apr 13 02:10:00 +0000 2014
>Closed-Date:    Fri Aug 08 05:43:34 +0000 2014
>Last-Modified:  Fri Aug 08 05:43:34 +0000 2014
>Originator:     David H. Gutteridge
>Release:        HEAD
>Organization:
>Environment:
n/a
>Description:
After that debacle with opening PRs about things I should've found
were already documented, I had a look at the BUILDING document to see
what I could add. (Embarrassment is an excellent motivator for me...)
I thought there could be more information supplied to hopefully
save someone else from confusion. Also, the list of arguments to
build particular targets was very out of date, so I tried my hand at
updating it, based on what's in the current build.sh script. I'm not
sure I got it right in all cases, but I put in every combination I
saw. I hope this helps.
>How-To-Repeat:
(1) Become confused while trying to build a userland.

Or

(2) Notice there are many options for different ARM machines (ABI,
endianness, architecture) and wonder how to enable them.
>Fix:
--- BUILDING.mdoc.orig	2014-04-09 10:17:48.000000000 -0400
+++ BUILDING.mdoc	2014-04-12 21:35:42.000000000 -0400
@@ -1487,6 +1487,12 @@
 .Sy MACHINE_ARCH
 to
 .Ar arch .
+Note some
+.Sy MACHINE
+values require the
+.Sy MACHINE_ARCH
+value to also be explicitly set. At present, these are:
+evbmips, evbsh3, and sbmips.
 .
 .It Fl B Ar buildid
 Set the value of
@@ -1623,24 +1629,72 @@
 .Sy MACHINE_ARCH .
 The following special cases for the
 .Ar mach
-argument are defined to set the listed values of
+argument are defined by setting the listed values of
 .Sy MACHINE
 and
 .Sy MACHINE_ARCH :
-.Bl -column "evbmips-el" "MACHINE" "MACHINE_ARCH" -offset indent
+.Bl -column "evbearmv6hf-el" "netwinder" "(not set, no default)" -offset indent
 .It Sy mach Ta Sy "MACHINE" Ta Sy "MACHINE_ARCH"
+.It algor Ta algor Ta (not set)
+.It algor64 Ta algor Ta mips64el
+.It arc Ta arc Ta (not set)
+.It arc64 Ta arc Ta mips64el
+.It cats Ta cats Ta (not set)
+.It ecats Ta cats Ta earmv4
+.It cobalt Ta cobalt Ta (not set)
+.It cobalt64 Ta cobalt Ta mips64el
 .It evbarm Ta evbarm Ta (not set)
-.It evbarm-eb Ta evbarm Ta armeb
 .It evbarm-el Ta evbarm Ta arm
-.It evbmips Ta evbmips Ta (not set)
+.It evbarm-eb Ta evbarm Ta armeb
+.It evbearm-el Ta evbarm Ta earm
+.It evbearm-eb Ta evbarm Ta earmeb
+.It evbearmhf-el Ta evbarm Ta earmhf
+.It evbearmhf-eb Ta evbarm Ta earmhfeb
+.It evbearmv4-el Ta evbarm Ta earmv4
+.It evbearmv4-eb Ta evbarm Ta earmv4eb
+.It evbearmv5-el Ta evbarm Ta earmv5
+.It evbearmv5-eb Ta evbarm Ta earmv5eb
+.It evbearmv6-el Ta evbarm Ta earmv6
+.It evbearmv6hf-el Ta evbarm Ta earmv6hf
+.It evbearmv6-eb Ta evbarm Ta earmv6eb
+.It evbearmv6hf-eb Ta evbarm Ta earmv6hfeb
+.It evbearmv7-el Ta evbarm Ta earmv7
+.It evbearmv7-eb Ta evbarm Ta earmv7eb
+.It evbearmv7hf-el Ta evbarm Ta earmv7hf
+.It evbearmv7hf-eb Ta evbarm Ta earmv7hfeb
+.It evbmips Ta evbmips Ta (not set, no default)
+.It evbmips64-eb Ta evbmips Ta mips64eb
+.It evbmips64-el Ta evbmips Ta mips64el
 .It evbmips-eb Ta evbmips Ta mipseb
 .It evbmips-el Ta evbmips Ta mipsel
-.It evbsh3 Ta evbsh3 Ta (not set)
+.It evbppc Ta evbppc Ta (not set)
+.It evbppc64 Ta evbppc Ta powerpc64
+.It evbsh3 Ta evbsh3 Ta (not set, no default)
 .It evbsh3-eb Ta evbsh3 Ta sh3eb
 .It evbsh3-el Ta evbsh3 Ta sh3el
-.It sbmips Ta sbmips Ta (not set)
+.It hpcarm Ta hpcarm Ta (not set)
+.It hpcearm Ta hpcarm Ta earm
+.It iyonix Ta iyonix Ta (not set)
+.It eiyonix Ta iyonix Ta earm
+.It macppc Ta macppc Ta (not set)
+.It macppc64 Ta macppc Ta powerpc64
+.It netwinder Ta netwinder Ta (not set)
+.It enetwinder Ta netwinder Ta earmv4
+.It ofppc Ta ofppc Ta (not set)
+.It ofppc64 Ta ofppc Ta powerpc64
+.It pmax Ta pmax Ta (not set)
+.It pmax64 Ta pmax Ta mips64el
+.It sbmips Ta sbmips Ta (not set, no default)
+.It sbmips64-eb Ta sbmips Ta mips64eb
+.It sbmips64-el Ta sbmips Ta mips64el
 .It sbmips-eb Ta sbmips Ta mipseb
 .It sbmips-el Ta sbmips Ta mipsel
+.It sgimips Ta sgimips Ta (not set)
+.It sgimips64 Ta sgimips Ta mips64eb
+.It shark Ta shark Ta (not set)
+.It eshark Ta shark Ta earmv4
+.It zaurus Ta zaurus Ta (not set)
+.It ezaurus Ta zaurus Ta earm
 .El
 .
 .It Fl N Ar noiselevel
@@ -1703,6 +1757,25 @@
 it is determined by complex rules that are influenced
 by the values of several variables and
 by the location of the source directory.
+.Pp
+Note that placing the
+.Ar obj
+directory location outside of the default source tree hierarchy makes
+it easier to manually clear out old files in the event the
+.Dq cleandir
+operation is unable to do so. (See
+.Sy CAVEATS
+below.)
+.Pp
+Note also that use of one of
+.Fl M
+or
+.Fl O
+is the only means of building multiple machine architecture userlands
+from the same source tree without cleaning between builds (in which
+case, one would specify distinct
+.Ar obj
+locations for each).
 .It Fl o
 Set the value of
 .Sy MKOBJDIRS
@@ -1934,3 +2007,14 @@
 and re-worked to
 .Sy TOOLCHAIN_MISSING
 after that.
+.
+.Sh CAVEATS
+.
+After significant updates to third-party components in the source
+tree, the
+.Dq cleandir
+operation may be insufficient to clean out old files in object
+directories. Instead, one may have to manually remove the
+files. Consult the
+.Sy UPDATING
+file for notices concerning this.

>Release-Note:

>Audit-Trail:
From: "David H. Gutteridge" <dhgutteridge@sympatico.ca>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: toolchain/48741: Patch to improve BUILDING documentation
Date: Thu, 7 Aug 2014 08:38:44 -0400

 Part of the patch I'd submitted documenting the machine/machine arch/
 alias options is now out of date. It might still be useful to someone
 though, if nothing else to reduce the amount of typing they'd have to
 do...

 (The evbarm options are set out differently than the other ones, such
 that it might be necessary to add a fourth column to the table to
 show the default, but from a user's perspective, it's still fine to
 just supply "evbarm" and leave it at that, so I kept what might seem
 like a superflous line to show that, rather than create a four 
 column layout. Someone else's preference may differ...)

 Dave

State-Changed-From-To: open->feedback
State-Changed-By: apb@NetBSD.org
State-Changed-When: Thu, 07 Aug 2014 21:50:37 +0000
State-Changed-Why:
I applied parts of your patch, with small changes.
The updates to the list of MACHINE and MACHINE_ARCH values
is no longer necessary, because BUILDING defers to "build.sh list-arch"
for that information.
Thank you for the patch.
Please check whether all your concerns have been addressed.


From: "Alan Barrett" <apb@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc: 
Subject: PR/48741 CVS commit: src/doc
Date: Thu, 7 Aug 2014 21:45:27 +0000

 Module Name:	src
 Committed By:	apb
 Date:		Thu Aug  7 21:45:27 UTC 2014

 Modified Files:
 	src/doc: BUILDING.mdoc

 Log Message:
 Add advice about avoiding common pitfalls.

 This is taken from the patch in PR 48741, by David H. Gutteridge,
 but I made small changes to wording and markup.


 To generate a diff of this commit:
 cvs rdiff -u -r1.103 -r1.104 src/doc/BUILDING.mdoc

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

From: "David H. Gutteridge" <dhgutteridge@sympatico.ca>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: toolchain/48741 (Patch to improve BUILDING documentation)
Date: Fri, 8 Aug 2014 00:36:21 -0400

 On 2014-08-07, at 5:50 PM, apb@NetBSD.org wrote:
 > Synopsis: Patch to improve BUILDING documentation
 > 
 > State-Changed-From-To: open->feedback
 > State-Changed-By: apb@NetBSD.org
 > State-Changed-When: Thu, 07 Aug 2014 21:50:37 +0000
 > State-Changed-Why:
 > I applied parts of your patch, with small changes.
 > The updates to the list of MACHINE and MACHINE_ARCH values
 > is no longer necessary, because BUILDING defers to "build.sh list-arch"
 > for that information.
 > Thank you for the patch.
 > Please check whether all your concerns have been addressed.

 Yes, this PR can be closed now, thanks.

 Dave


State-Changed-From-To: feedback->closed
State-Changed-By: wiz@NetBSD.org
State-Changed-When: Fri, 08 Aug 2014 05:43:34 +0000
State-Changed-Why:
Confirmed fixed, thanks for the feedback!


>Unformatted:

Home	PR Database Search