Date: Tue, 8 Jun 2004 03:13:51 -0500 (CDT) From: Mark Linimon <linimon@lonesome.com> To: FreeBSD-gnats-submit@FreeBSD.org Cc: portmgr@FreeBSD.org Subject: docs/67707: [patch] beginning of rework of Dependencies section of Porter's Handbook Message-ID: <200406080813.i588DpFD020980@lonesome.lonesome.com> Resent-Message-ID: <200406080820.i588KOU9075894@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 67707
>Category: docs
>Synopsis: [patch] beginning of rework of Dependencies section of Porter's Handbook
>Confidential: no
>Severity: non-critical
>Priority: medium
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Tue Jun 08 08:20:24 GMT 2004
>Closed-Date:
>Last-Modified:
>Originator: Mark Linimon
>Release: FreeBSD 4.9-PRERELEASE i386
>Organization:
Lonesome Dove Computing Services
>Environment:
System: FreeBSD lonesome.lonesome.com 4.9-PRERELEASE FreeBSD 4.9-PRERELEASE #3: Thu Jan 22 20:41:05 CST 2004 root@lonesome.lonesome.com:/usr/src/sys/compile/MULTIMEDIA i386
>Description:
The section on dependencies Makevars in the Porter's Handbook
is out of date, especially with respect to the WITH_*/WITHOUT_*
Makevars. Although this patch is incomplete, it is better than
what is there, and provides us a start.
Note: I've removed some of the GNOME text because AFAICT it is
just completely wrong now.
>How-To-Repeat:
(n/a)
>Fix:
The following is my suggested patch. I am going to assign this
PR to myself, pending portmgr@ approval of the content. (portmgr
is Cc:ed).
Index: book.sgml
===================================================================
RCS file: /home/FreeBSD/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.422
diff -u -r1.422 book.sgml
--- book.sgml 6 Jun 2004 16:23:23 -0000 1.422
+++ book.sgml 8 Jun 2004 07:59:07 -0000
@@ -3029,7 +3029,26 @@
<title><makevar>USE_<replaceable>*</replaceable></makevar></title>
<para>A number of variables exist in order to encapsulate common
- dependencies that many ports have.</para>
+ dependencies that many ports have. Although their use is
+ optional, they can help to reduce the verbosity of the port
+ <filename>Makefile</filename>s. Each of them is styled
+ as <makevar>USE_<replaceable>*</replaceable></makevar>. The
+ usage of these variables is restricted to the port
+ <filename>Makefile</filename>s and
+ <filename>ports/Mk/bsd.*.mk</filename> and is not designed
+ to encapsulate user-settable options — use
+ <makevar>WITH_<replaceable>*</replaceable></makevar> and
+ <makevar>WITHOUT_<replaceable>*</replaceable></makevar>
+ for that purpose.</para>
+
+ <note>
+ <para>It is <emphasis>always</emphasis> incorrect to set
+ any <makevar>USE_<replaceable>*</replaceable></makevar>
+ in <filename>/etc/make.conf</filename>. For instance,
+ setting <programlisting>USE_GCC=3.2</programlisting>
+ would adds a dependency on gcc32 for every port,
+ including gcc32 itself!</para>
+ </note>
<table frame="none">
<title>The <makevar>USE_<replaceable>*</replaceable></makevar>
@@ -3198,42 +3217,6 @@
intention will be clear.</para>
</sect2>
- <sect2>
- <title>Optional dependencies</title>
-
- <para>Some large applications can be built in a number of
- configurations, adding functionality if one of a number of
- libraries or applications is available. Since not all users
- want those libraries or applications, the ports system
- provides hooks that the port author can use to decide which
- configuration should be built. Supporting these properly will
- make users happy, and effectively provide 2 or more ports for the
- price of one.</para>
-
- <para>The easiest of these to use is
- <makevar>WITHOUT_X11</makevar>. If the port can be built both
- with and without X support, then it should normally be built
- with X support. If <makevar>WITHOUT_X11</makevar> is defined,
- then the version that does not have X support should be
- built.</para>
-
- <para>Various parts of GNOME have such knobs, though they are
- slightly more difficult to use. The variables to use in the
- <filename>Makefile</filename> are <makevar>WANT_*</makevar>
- and <makevar>HAVE_*</makevar>. If the application can be
- built both with or without one of the dependencies listed
- below, then the <filename>Makefile</filename> should set
- <makevar>WANT_PKG</makevar>, and should build the version that
- uses <makevar>PKG</makevar> if <makevar>HAVE_PKG</makevar>
- is defined.</para>
-
- <para>The <makevar>WANT_*</makevar> variables currently
- supported this way are <makevar>WANT_GLIB</makevar>,
- <makevar>WANT_GTK</makevar>, <makevar>WANT_ESOUND</makevar>,
- <makevar>WANT_IMLIB</makevar>, and
- <makevar>WANT_GNOME</makevar>.</para>
- </sect2>
-
<sect2>
<title>Circular dependencies are fatal</title>
@@ -3252,6 +3235,142 @@
can be quite slow on older machines, but you may be able to
save a large number of people—including yourself—
a lot of grief in the process.</para>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="makefile-options">
+ <title>Makefile Options</title>
+
+ <para>Some large applications can be built in a number of
+ configurations, adding functionality if one of a number of
+ libraries or applications is available. Examples include
+ choice of natural (human) language, GUI versus command-line,
+ or type of database to support. Since not all users
+ want those libraries or applications, the ports system
+ provides hooks that the port author can use to control which
+ configuration should be built. Supporting these properly will
+ make users happy, and effectively provide 2 or more ports for the
+ price of one.</para>
+
+ <sect2>
+ <title><makevar>WITH_<replaceable>*</replaceable></makevar> and
+ <makevar>WITHOUT_<replaceable>*</replaceable></makevar></title>
+
+ <para>These variables are designed to be set by the system
+ administrator. There are many that are standardized in
+ <filename>ports/Mk/bsd.*.mk</filename>; others are not,
+ which can be confusing. If you need to add such a
+ configuration variable, please consider using one of the
+ ones from the following list.</para>
+
+ <note>
+ <para>You should not assume that a
+ <makevar>WITH_<replaceable>*</replaceable></makevar>
+ necessarily has a corresponding
+ <makevar>WITHOUT_<replaceable>*</replaceable></makevar>
+ variable and vice versa. In general, the default is
+ simply assumed.</para>
+ </note>
+
+ <note>
+ <para>Unless otherwise specified, these variables are only
+ tested for being set or not set, rather than being set to
+ some kind of variable such as <literal>YES</literal> or
+ <literal>NO</literal>.</para>
+ </note>
+
+ <table frame="none">
+ <title>The <makevar>WITH_<replaceable>*</replaceable></makevar>
+ and <makevar>WITHOUT_<replaceable>*</replaceable></makevar>
+ variables</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Variable</entry>
+
+ <entry>Means</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><makevar>WITH_APACHE2</makevar></entry>
+
+ <entry>If set, use
+ <filename role="package">www/apache2</filename>
+ instead of the default of
+ <filename role="package">www/apache</filename>.</entry>
+ </row>
+
+ <row>
+ <entry><makevar>WITH_BERKELEY_DB</makevar></entry>
+
+ <entry>Define this variable to specify the ability to
+ use a variant of the Berkeley database package such as
+ <filename role="package">databases/db41</filename>.
+ An associated variable,
+ <entry><makevar>WITH_BDB_VER</makevar>, may be
+ set to values such as 2, 3, 4, 41 or 42.</entry>
+ </row>
+
+ <row>
+ <entry><makevar>WITHOUT_GETTEXT</makevar></entry>
+
+ <entry>If set, says that internationalization is not
+ needed, which can save compile time. By default,
+ internalization is used.</entry>
+ </row>
+
+ <row>
+ <entry><makevar>WITH_MYSQL</makevar></entry>
+
+ <entry>Define this variable to specify the ability to
+ use a variant of the MySQL database package such as
+ <filename role="package">databases/mysql40-server</filename>.
+ An associated variable,
+ <entry><makevar>WANT_MYSQL_VER</makevar>, may be
+ set to values such as 323, 40, 41, or 50.</entry>
+ </row>
+
+ <row>
+ <entry><makevar>WITH_OPENSSL_BASE</makevar></entry>
+
+ <entry>Use the version of OpenSSL in the base system.</entry>
+ </row>
+
+ <row>
+ <entry><makevar>WITH_OPENSSL_PORT</makevar></entry>
+
+ <entry>Use the version of OpenSSL from
+ <filename role="package">security/openssh</filename>,
+ overwriting the version that was originally installed
+ in the base system.</entry>
+ </row>
+
+ <row>
+ <entry><makevar>WITH_POSTGRESQL</makevar></entry>
+
+ <entry>Define this variable to specify the ability to
+ use a variant of the PostGreSQL database package such as
+ <filename role="package">databases/postgresql72</filename>.
+ </entry>
+ </row>
+
+ <row>
+ <entry><makevar>WITHOUT_X11</makevar></entry>
+
+ <entry>If the port can be built both with and without
+ X support, then it should normally be built with
+ with X support. If this variable is defined, then
+ then the version that does not have X support should
+ be built instead.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
</sect2>
</sect1>
>Release-Note:
>Audit-Trail:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200406080813.i588DpFD020980>