Bug 74231

Summary: Conflicting information on mergemaster -p
Product: Documentation Reporter: Brian Candler <B.Candler>
Component: Books & ArticlesAssignee: Giorgos Keramidas <keramida>
Status: Closed FIXED    
Severity: Affects Only Me    
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   

Description Brian Candler 2004-11-22 10:20:22 UTC 
The handbook gives inconsistent information about where 'mergemaster -p'
fits into the build/upgrade process.
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html

In section 19.4.1 its advice is the same as I find in /usr/src/Makefile:

# For individuals wanting to upgrade their sources (even if only a
# delta of a few days):
#
# 1.  `cd /usr/src'       (or to the directory containing your source tree).
# 2.  `make buildworld'
# 3.  `make buildkernel KERNCONF=YOUR_KERNEL_HERE'     (default is GENERIC).
# 4.  `make installkernel KERNCONF=YOUR_KERNEL_HERE'   (default is GENERIC).
# 5.  `reboot'        (in single user mode: boot -s from the loader prompt).
# 6.  `mergemaster -p'
# 7.  `make installworld'
# 8.  `mergemaster'
# 9.  `reboot'
#
# See src/UPDATING `COMMON ITEMS' for more complete information.

However in section 19.4.4 it says that mergemaster -p should be done earlier
in the process; and section 19.4.10 doesn't suggest doing mergemaster -p
there, which would be consistent with the initial advice.

19.4.4 describes the -p flag as "pre-buildworld". 'man mergemaster' says the
same, and also says it "compares only files known to be essential to the
success of {build|install}world". That implies it may need to be done before
make buildworld, as well or instead of before make installworld.

Fix: 

Make it clear where mergemaster -p should be done in the entire process:
is it ever required before buildworld, or only before installworld?
Comment 1 Giorgos Keramidas 2004-11-22 13:37:38 UTC 
On 2004-11-22 10:18, Brian Candler <b.candler@pobox.com> wrote:
>
> Make it clear where mergemaster -p should be done in the entire process:
> is it ever required before buildworld, or only before installworld?

AFAIK, mergemaster -p is only needed before installworld.  The makefile
`magic' of the build process is smart enough to handle the buildworld
stage without mergemaster's help.

I could be wrong, but I have been running mergemaster -p only before
installworld, while in single-user mode, for years now.  I don't recall
any problems with that.
Comment 2 Giorgos Keramidas freebsd_committer freebsd_triage 2004-12-23 00:41:15 UTC 
Responsible Changed
From-To: freebsd-doc->keramida

I'll handle this.
Comment 3 Giorgos Keramidas freebsd_committer freebsd_triage 2004-12-23 17:59:19 UTC 
State Changed
From-To: open->closed

I've just committed a couple of short paragraphs stating that mergemaster may 
have to be run twice.  Once before buildworld and once after installworld. 
Hopefully, this will reduce the potential for confusion regarding the -p 
option of mergemaster. 

The changes should show up online within the next 24 hours.  Thanks for 
submitting this problem report.
Comment 4 Brian Candler 2004-12-27 12:25:50 UTC 
On Thu, Dec 23, 2004 at 06:02:39PM +0000, Giorgos Keramidas wrote:
> Synopsis: Conflicting information on mergemaster -p
> 
> State-Changed-From-To: open->closed
> State-Changed-By: keramida
> State-Changed-When: Thu Dec 23 17:59:19 GMT 2004
> State-Changed-Why: 
> I've just committed a couple of short paragraphs stating that mergemaster may
> have to be run twice.  Once before buildworld and once after installworld.
> Hopefully, this will reduce the potential for confusion regarding the -p
> option of mergemaster.
> 
> The changes should show up online within the next 24 hours.  Thanks for
> submitting this problem report.
> 
> http://www.freebsd.org/cgi/query-pr.cgi?pr=74231

Thank you. However I think the inconsistency remains in the webpage between
the 'canonical way' and then the step-by-step instructions; this is because
section 19.4.1 says to run

# make buildworld
# make buildkernel
# make installkernel
# reboot
boot -s
# mergemaster -p
# make installworld
# mergemaster
# reboot

(note: mergemaster -p before make installworld), whereas sections
19.4.4-19.4.14 say that you should run

# mergemaster -p			# 19.4.4
# make buildworld			# 19.4.7.2
# make buildkernel KERNCONF=MYKERNEL	# 19.4.8
# make installkernel KERNCONF=MYKERNEL
# reboot				# 19.4.9
boot -s
# make installworld			# 19.4.10
# mergemaster				# 19.4.11
# shutdown -r now			# 19.4.14

(mergemaster -p before make buildworld).

Perhaps the simplest solution here is that paragraph 19.4.4 should be moved
so that it is between 19.4.9 and 19.4.10, so that the sequence is consistent
with that given in 19.4.1, and also with /usr/src/UPDATING.

Regards,

Brian.