Received: by mail.netbsd.org (Postfix, from userid 605)
	id B00BE84E9A; Mon, 10 Sep 2018 12:10:55 +0000 (UTC)
Received: from localhost (localhost [127.0.0.1])
	by mail.netbsd.org (Postfix) with ESMTP id BE4F784E84
	for <pkgsrc-changes@NetBSD.org>; Mon, 10 Sep 2018 12:10:54 +0000 (UTC)
X-Virus-Scanned: amavisd-new at netbsd.org
Received: from mail.netbsd.org ([127.0.0.1])
	by localhost (mail.netbsd.org [127.0.0.1]) (amavisd-new, port 10025)
	with ESMTP id 6IQ6_z622Iw1 for <pkgsrc-changes@netbsd.org>;
	Mon, 10 Sep 2018 12:10:54 +0000 (UTC)
Received: from cvs.NetBSD.org (ivanova.NetBSD.org [IPv6:2001:470:a085:999:28c:faff:fe03:5984])
	by mail.netbsd.org (Postfix) with ESMTP id EE05A84E79
	for <pkgsrc-changes@NetBSD.org>; Mon, 10 Sep 2018 12:10:53 +0000 (UTC)
Received: by cvs.NetBSD.org (Postfix, from userid 500)
	id DAA6CFBF8; Mon, 10 Sep 2018 12:10:53 +0000 (UTC)
Content-Transfer-Encoding: 7bit
Content-Type: multipart/mixed; boundary="_----------=_1536581453132830"
MIME-Version: 1.0
Date: Mon, 10 Sep 2018 12:10:53 +0000
From: "Leonardo Taccari" <leot@netbsd.org>
Subject: CVS commit: pkgsrc/doc/guide/files
To: pkgsrc-changes@NetBSD.org
Reply-To: leot@netbsd.org
X-Mailer: log_accum
Message-Id: <20180910121053.DAA6CFBF8@cvs.NetBSD.org>
Sender: pkgsrc-changes-owner@NetBSD.org
List-Id: pkgsrc-changes.NetBSD.org
Precedence: bulk
List-Unsubscribe: <mailto:majordomo@NetBSD.org?subject=Unsubscribe%20pkgsrc-changes&body=unsubscribe%20pkgsrc-changes>

This is a multi-part message in MIME format.

--_----------=_1536581453132830
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
Content-Type: text/plain; charset="US-ASCII"

Module Name:	pkgsrc
Committed By:	leot
Date:		Mon Sep 10 12:10:53 UTC 2018

Modified Files:
	pkgsrc/doc/guide/files: fixes.xml

Log Message:
doc/guide: Reword CONFLICTS usage suggestions

Despite most CONFLICTS are automatically detected at package
installation time it is still a good idea to manually mark CONFLICTS
in order to fail as early as possible instead e.g. of failing at
package installation time after possibly installing several (maybe
not needed) dependencies.

Pointed out by discussion on pkgsrc-changes@ by <jperkin>:

 <https://mail-index.NetBSD.org/pkgsrc-changes/2018/09/09/msg180626.html>

Last two paragraphs from <jperkin>, thanks!

Also discussed with <wiz>, thanks!


To generate a diff of this commit:
cvs rdiff -u -r1.145 -r1.146 pkgsrc/doc/guide/files/fixes.xml

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


--_----------=_1536581453132830
Content-Disposition: inline
Content-Length: 3039
Content-Transfer-Encoding: binary
Content-Type: text/x-diff; charset=us-ascii

Modified files:

Index: pkgsrc/doc/guide/files/fixes.xml
diff -u pkgsrc/doc/guide/files/fixes.xml:1.145 pkgsrc/doc/guide/files/fixes.xml:1.146
--- pkgsrc/doc/guide/files/fixes.xml:1.145	Wed Sep  6 16:49:22 2017
+++ pkgsrc/doc/guide/files/fixes.xml	Mon Sep 10 12:10:53 2018
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.145 2017/09/06 16:49:22 wiz Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.146 2018/09/10 12:10:53 leot Exp $ -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
 <title>Making your package work</title>
@@ -427,31 +427,36 @@ DEPENDS+=       ImageMagick>=6.0:../../g
     installs the same set of files as another package in the pkgsrc
     tree or has the same <varname>PKGNAME</varname>.</para>
 
-    <para>These cases are handled automatically by the packaging tools
-    at package installation time and do not need to be handled
-    manually.</para>
-   
-    <para>In case the conflicts can not be recognized automatically
-    (e.g., packages using the same config file location but no other
-    shared files), you can set <varname>CONFLICTS</varname> to a
-    space-separated list of packages (including version string) your
-    package conflicts with.</para>
-
-    <para>For example, if both <filename role="pkg">foo/bar</filename>
-    and <filename role="pkg">foo/baz</filename>
-    use the same config file, you would set in
-    <filename>foo/bar/Makefile</filename>:</para>
-
-<programlisting>
-CONFLICTS=      baz-[0-9]*
-</programlisting>
-
-    <para>and in <filename>pkgsrc/foo/baz/Makefile</filename>:</para>
-
-<programlisting>
-CONFLICTS=      bar-[0-9]*
-</programlisting>
-
+    <para>For example, <filename role="pkg">x11/libXaw3d</filename>
+    and <filename role="pkg">x11/Xaw-Xpm</filename>
+    install the same shared library, thus you set in
+    <filename>pkgsrc/x11/libXaw3d/Makefile</filename>:</para>
+
+    <programlisting>
+CONFLICTS=      Xaw-Xpm-[0-9]*
+    </programlisting>
+
+    <para>and in <filename>pkgsrc/x11/Xaw-Xpm/Makefile</filename>:</para>
+
+    <programlisting>
+CONFLICTS=      libXaw3d-[0-9]*
+    </programlisting>
+
+    <para>&man.pkg.add.1 is able to detect attempts to install packages
+    that conflict with existing packages and abort. However, in many
+    situations this is too late in the process. Binary package managers
+    will not know about the conflict until they attempt to install the
+    package after already downloading it and all its dependencies.
+    Users may also waste time building a package and its dependencies
+    only to find out at the end that it conflicts with another package
+    they have installed.</para>
+ 
+    <para>To avoid these issues <varname>CONFLICTS</varname> entries
+    should be added in all cases where it is known that packages conflict
+    with each other.  These <varname>CONFLICTS</varname> entries are
+    exported in &man.pkg.summary.5 files and consumed by binary package
+    managers to inform users that packages cannot be installed onto
+    the target system.</para>
   </sect2>
 
 


--_----------=_1536581453132830--