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

Mateusz Piotrowski 0mp at
Wed Nov 18 10:32:33 UTC 2020

Author: 0mp
Date: Wed Nov 18 10:32:32 2020
New Revision: 54691

  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
  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>


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>
-	<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 /usr/ports</userinput></screen>
+	<para>Or, check out a copy of a quarterly branch:</para>
+	<screen>&prompt.root; <userinput>svn checkout /usr/ports</userinput></screen>
+      </step>
+      <step>
 	<para>As needed, update <filename>/usr/ports</filename> after
 	  the initial <application>Subversion</application>
 	<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 /usr/ports</userinput></screen>

More information about the svn-doc-all mailing list