svn commit: r54691 - head/en_US.ISO8859-1/books/handbook/ports

[Mateusz Piotrowski]

Author: 0mp
Date: Wed Nov 18 10:32:32 2020
New Revision: 54691
URL: https://svnweb.freebsd.org/changeset/doc/54691

Log:
  Add a warning regarding mixing ports(7) and pkg(8) to install software
  
  I think it's something that has been missing from the handbook for a long
  time.
  
  Unfortunately, this patch does not explain all the subtleties of the ports
  framework (like, e.g., that ports create packages during the build process
  which are then installed via pkg). We should probably hint the reader about
  it somewhere, but that's something for another patch. What's important here
  is to warn new users about problems they might encounter.
  
  Also, add some examples of working with quarterly with Subversion.
  
  PR:		251195
  Submitted by:	Fred <fjs.usa01 gmail.com>

Modified:
  head/en_US.ISO8859-1/books/handbook/ports/chapter.xml

Modified: head/en_US.ISO8859-1/books/handbook/ports/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/ports/chapter.xml	Tue Nov 17 21:30:01 2020	(r54690)
+++ head/en_US.ISO8859-1/books/handbook/ports/chapter.xml	Wed Nov 18 10:32:32 2020	(r54691)
@@ -837,6 +837,24 @@ security/sudo</screen>
     <para>By default, the Ports Collection itself is stored as a
       subdirectory of <filename>/usr/ports</filename>.</para>
 
+    <warning>
+      <para>Before installing and using the Ports Collection, please
+	be aware that it is generally ill-advised to use the
+	Ports Collection in conjunction with the binary packages
+	provided via <application>pkg</application> to install
+	software.  <application>pkg</application>, by default,
+	tracks quarterly branch-releases of the ports
+	tree and not HEAD. Dependencies could be different for a port
+	in HEAD compared to its counterpart in a quarterly branch
+	release and this could result in conflicts between
+	dependencies installed by <application>pkg</application>
+	and those from the Ports Collection.
+	If the Ports Collection and <application>pkg</application>
+	must be used in conjunction, then be sure that your
+	Ports Collection and <application>pkg</application> are
+	on the same branch release of the ports tree.</para>
+    </warning>
+
     <para>Before an application can be compiled using a port, the
       Ports Collection must first be installed.  If it was not
       installed during the installation of &os;, use one of the
@@ -917,17 +935,31 @@ security/sudo</screen>
       </step>
 
       <step>
-	<para>Check out a copy of the ports tree:</para>
+	<para>Check out a copy of the HEAD branch of the ports
+	  tree:</para>
 
 	<screen>&prompt.root; <userinput>svn checkout https://svn.FreeBSD.org/ports/head /usr/ports</userinput></screen>
       </step>
 
       <step>
+	<para>Or, check out a copy of a quarterly branch:</para>
+
+	<screen>&prompt.root; <userinput>svn checkout https://svn.FreeBSD.org/ports/branches/2020Q3 /usr/ports</userinput></screen>
+      </step>
+
+      <step>
 	<para>As needed, update <filename>/usr/ports</filename> after
 	  the initial <application>Subversion</application>
 	  checkout:</para>
 
 	<screen>&prompt.root; <userinput>svn update /usr/ports</userinput></screen>
+      </step>
+
+      <step>
+	<para>As needed, switch <filename>/usr/ports</filename> to a
+	  different quarterly branch:</para>
+
+	<screen>&prompt.root; <userinput>svn switch http://svn.freebsd.org/ports/branches/2020Q4/ /usr/ports</userinput></screen>
       </step>
     </procedure>