From nobody@FreeBSD.org  Mon Feb  6 14:36:01 2012
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 27A6D106566B
	for <freebsd-gnats-submit@FreeBSD.org>; Mon,  6 Feb 2012 14:36:01 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from red.freebsd.org (red.freebsd.org [IPv6:2001:4f8:fff6::22])
	by mx1.freebsd.org (Postfix) with ESMTP id 150018FC0C
	for <freebsd-gnats-submit@FreeBSD.org>; Mon,  6 Feb 2012 14:36:01 +0000 (UTC)
Received: from red.freebsd.org (localhost [127.0.0.1])
	by red.freebsd.org (8.14.4/8.14.4) with ESMTP id q16Ea03L061692
	for <freebsd-gnats-submit@FreeBSD.org>; Mon, 6 Feb 2012 14:36:00 GMT
	(envelope-from nobody@red.freebsd.org)
Received: (from nobody@localhost)
	by red.freebsd.org (8.14.4/8.14.4/Submit) id q16Ea0qR061691;
	Mon, 6 Feb 2012 14:36:00 GMT
	(envelope-from nobody)
Message-Id: <201202061436.q16Ea0qR061691@red.freebsd.org>
Date: Mon, 6 Feb 2012 14:36:00 GMT
From: Peter Maloney <peter.maloney@brockmann-consult.de>
To: freebsd-gnats-submit@FreeBSD.org
Subject: handbook ports page does not suggest config-recursive which should be a standard suggestion as it saves huge time
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         164826
>Category:       docs
>Synopsis:       handbook ports page does not suggest config-recursive which should be a standard suggestion as it saves huge time
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    issyl0
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Feb 06 14:40:09 UTC 2012
>Closed-Date:    Wed Aug 29 14:38:59 UTC 2012
>Last-Modified:  Wed Aug 29 14:38:59 UTC 2012
>Originator:     Peter Maloney
>Release:        8.2-STABLE csup'd at 20110927
>Organization:
Brockmann Consult
>Environment:
FreeBSD bczfsvm1.bc.local 8.2-STABLE-20110927 FreeBSD 8.2-STABLE-20110927 #0: Thu Jan 26 12:07:29 UTC 2012     root@bcnas1bak.bc.local:/usr/obj/usr/src/sys/GENERIC  amd64
>Description:
Installing ports is very time consuming, and since they are probably used to
binary distribution systems, new users may be discouraged from using FreeBSD if
done wrong. The handbook does not suggest usage of "make config-recursive" to
speed things up. Instead it suggests only "make install", which means there
will be long pauses between user interaction. When there are many dependencies,
this makes building a single port a huge hassle.

eg.

cd /usr/ports/emulators/virtualbox-ose
make install
download... wait...
menu pops up:
        &#9484;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9488;
        &#9474;               Options for virtualbox-ose 3.2.12_1                  &#9474;
        &#9474; &#9484;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9488; &#9474;
        &#9474; &#9474;      [X] QT4             Build with QT4 Frontend               &#9474; &#9474;
        &#9474; &#9474;      [ ] DEBUG           Build with debugging symbols          &#9474; &#9474;
        &#9474; &#9474;      [X] GUESTADDITIONS  Build with Guest Additions            &#9474; &#9474;
        &#9474; &#9474;      [X] DBUS            Build with D-Bus and HAL support      &#9474; &#9474;
        &#9474; &#9474;      [ ] PULSEAUDIO      Build with PulseAudio                 &#9474; &#9474;
        &#9474; &#9474;      [X] X11             Build with X11 support                &#9474; &#9474;
        &#9474; &#9474;      [X] VDE             Build with VDE support                &#9474; &#9474;
        &#9474; &#9474;      [X] VNC             Build with VNC support                &#9474; &#9474;
        &#9474; &#9474;      [X] WEBSERVICE      Build Webservice                      &#9474; &#9474;
        &#9474; &#9474;      [X] NLS             Native language support               &#9474; &#9474;
        &#9474; &#9492;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9496; &#9474;
        &#9474;                                                                    &#9474;

User must hit "OK"
download... wait...
menu pops up:
        &#9474;                    Options for glib 2.26.1_1                       &#9474;
        &#9474; &#9484;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9488; &#9474;
        &#9474; &#9474;            [X] COLLATION_FIX  fix string collation             &#9474; &#9474;
        &#9474; &#9492;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9472;&#9496; &#9474;

User must hit "OK"
download... wait...
menu pops up

etc. etc. At least 12 times.

So it is better to instead do:
    make config-recursive
then do all the selections and "OK" in one batch, then
    make install clean

Please add that to the handbook.

>How-To-Repeat:
a new FreeBSD user reads http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/ports-using.html

Then they type the following commands:
# cd /usr/ports/emulators/virtualbox-ose
# make install clean
>Fix:
Add another note to handbook, right after "Note: You can save two extra steps
by just running make install clean instead of make, make install and make clean
as three separate steps."

[addthis]
When installing a port, using only "make install" from the beginning means
there will potentially be many waiting periods between user interaction. When
there are many dependencies, this sometimes makes building a single port a huge
hassle. To avoid this, first run "make config-recursive" to do the
configuration in one batch. Then run "make install [clean]" afterwards.
[/addthis]

Another alternative to the above handbook change would be to add a new target,
maybe named "install-recursive" that is the same as "make config-recursive
install", and add that in the handbook, replacing "install"

>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-ports-bugs->freebsd-doc 
Responsible-Changed-By: pav 
Responsible-Changed-When: Thu Feb 9 12:25:52 UTC 2012 
Responsible-Changed-Why:  
Is really a docs issue. 

Also, another viable alternative would be to point users to portmaster, which 
handles this internally. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=164826 
Responsible-Changed-From-To: freebsd-doc->eadler 
Responsible-Changed-By: eadler 
Responsible-Changed-When: Sat Mar 3 15:37:19 UTC 2012 
Responsible-Changed-Why:  
I'll take it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=164826 
Responsible-Changed-From-To: eadler->freebsd-doc 
Responsible-Changed-By: eadler 
Responsible-Changed-When: Wed Jul 25 06:49:23 UTC 2012 
Responsible-Changed-Why:  
I won't be getting to this any time soon 

http://www.freebsd.org/cgi/query-pr.cgi?pr=164826 
Responsible-Changed-From-To: freebsd-doc->issyl0 
Responsible-Changed-By: issyl0 
Responsible-Changed-When: Wed Aug 29 14:09:15 UTC 2012 
Responsible-Changed-Why:  
I'll take it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=164826 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/164826: commit references a PR
Date: Wed, 29 Aug 2012 14:29:12 +0000 (UTC)

 Author: issyl0
 Date: Wed Aug 29 14:29:03 2012
 New Revision: 39468
 URL: http://svn.freebsd.org/changeset/doc/39468
 
 Log:
   Add a note about make's config-recursive option to the ports chapter of
   the Handbook.
   
   PR:		docs/164826
   Approved by:	gjb (mentor)
 
 Modified:
   head/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
 
 Modified: head/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
 ==============================================================================
 --- head/en_US.ISO8859-1/books/handbook/ports/chapter.sgml	Wed Aug 29 05:59:54 2012	(r39467)
 +++ head/en_US.ISO8859-1/books/handbook/ports/chapter.sgml	Wed Aug 29 14:29:03 2012	(r39468)
 @@ -976,6 +976,18 @@ docbook                     =
  	    <command>make <maketarget>install</maketarget></command> and
  	    <command>make <maketarget>clean</maketarget></command>
  	    as three separate steps.</para>
 +
 +	  <para>When installing a port, using only <command>make
 +	      <maketarget>install</maketarget></command> from the
 +	    beginning means there will potentially be many waiting
 +	    periods between user interaction as the default behaviour
 +	    is to prompt the user for options.  When there are many
 +	    dependencies, this sometimes makes building a single port
 +	    a huge hassle.  To avoid this, first run <command>make
 +	      <maketarget>config-recursive</maketarget></command> to
 +	    do the configuration in one batch.  Then run
 +	    <command>make <maketarget>install
 +	      [clean]</maketarget></command> afterwards.</para>
  	</note>
  
  	<note>
 _______________________________________________
 svn-doc-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-doc-all
 To unsubscribe, send any mail to "svn-doc-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: open->closed 
State-Changed-By: issyl0 
State-Changed-When: Wed Aug 29 14:38:58 UTC 2012 
State-Changed-Why:  
Committed. Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=164826 
>Unformatted:
