diff options
Diffstat (limited to 'en_US.ISO8859-1/books/porters-handbook/book.xml')
| -rw-r--r-- | en_US.ISO8859-1/books/porters-handbook/book.xml | 3642 |
1 files changed, 1766 insertions, 1876 deletions
diff --git a/en_US.ISO8859-1/books/porters-handbook/book.xml b/en_US.ISO8859-1/books/porters-handbook/book.xml index 5f2709929a..f325a8ba76 100644 --- a/en_US.ISO8859-1/books/porters-handbook/book.xml +++ b/en_US.ISO8859-1/books/porters-handbook/book.xml @@ -1,22 +1,20 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd" [ <!ENTITY values.uses SYSTEM "uses.xml"> <!ENTITY values.versions SYSTEM "versions.xml"> ]> - <!-- The FreeBSD Documentation Project $FreeBSD$ --> - -<book lang='en'> - <bookinfo> - <title>FreeBSD Porter's Handbook</title> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>FreeBSD Porter's Handbook</title> + <authorgroup> - <corpauthor>The FreeBSD Documentation Project</corpauthor> + <author><orgname>The FreeBSD Documentation Project</orgname></author> </authorgroup> <pubdate>$FreeBSD$</pubdate> @@ -42,7 +40,7 @@ &legalnotice; - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.unix; &tm-attrib.sun; @@ -50,9 +48,9 @@ </legalnotice> <releaseinfo>$FreeBSD$</releaseinfo> - </bookinfo> + </info> - <chapter id="why-port"> + <chapter xml:id="why-port"> <title>Introduction</title> <para>The FreeBSD ports collection is the way almost everyone @@ -67,7 +65,7 @@ </chapter> - <chapter id="own-port"> + <chapter xml:id="own-port"> <title>Making a New Port Yourself</title> <para>So, you are interested in making your own port or @@ -86,7 +84,7 @@ <note> <para>Only a fraction of the variables - (<makevar><replaceable>VAR</replaceable></makevar>) that can + (<varname><replaceable>VAR</replaceable></varname>) that can be overridden are mentioned in this document. Most (if not all) are documented at the start of <filename>/usr/ports/Mk/bsd.port.mk</filename>; the others @@ -101,12 +99,12 @@ <para> Looking for something easy to start with? Take a look at the - <ulink url="http://wiki.freebsd.org/WantedPorts">list of - requested ports</ulink> and see if you can work on one (or + <link xlink:href="http://wiki.freebsd.org/WantedPorts">list of + requested ports</link> and see if you can work on one (or more).</para> </chapter> - <chapter id="quick-porting"> + <chapter xml:id="quick-porting"> <title>Quick Porting</title> <para>This section tells you how to quickly create a new port. In @@ -114,7 +112,7 @@ further on into the document.</para> <para>First, get the original tarball and put it into - <makevar>DISTDIR</makevar>, which defaults to + <varname>DISTDIR</varname>, which defaults to <filename>/usr/ports/distfiles</filename>.</para> <note> @@ -126,18 +124,18 @@ </note> <note> - <para>It is recommended to set the <makevar>DEVELOPER</makevar> + <para>It is recommended to set the <varname>DEVELOPER</varname> &man.make.1; variable in <filename>/etc/make.conf</filename> before getting into porting.</para> - <screen>&prompt.root; <userinput>echo DEVELOPER=yes >> /etc/make.conf</userinput></screen> + <screen>&prompt.root; <userinput>echo DEVELOPER=yes >> /etc/make.conf</userinput></screen> <para>This setting enables the <quote>developer mode</quote> that displays deprecation warnings and activates some further quality checks on calling the <command>make</command> command.</para> </note> - <sect1 id="porting-makefile"> + <sect1 xml:id="porting-makefile"> <title>Writing the <filename>Makefile</filename></title> <para>The minimal <filename>Makefile</filename> would look @@ -171,7 +169,7 @@ COMMENT= Cat chasing a mouse all over the screen section.</para> </sect1> - <sect1 id="porting-desc"> + <sect1 xml:id="porting-desc"> <title>Writing the Description Files</title> <para>There are two description files that are required for @@ -275,8 +273,8 @@ lib/X11/oneko/mouse.xpm <filename>pkg-plist</filename> can be omitted from a port. If the port installs just a handful of files, and perhaps directories, the files and directories may be listed in the - variables <makevar>PLIST_FILES</makevar> and - <makevar>PLIST_DIRS</makevar>, respectively, within the + variables <varname>PLIST_FILES</varname> and + <varname>PLIST_DIRS</varname>, respectively, within the port's <filename>Makefile</filename>. For instance, we could get along without <filename>pkg-plist</filename> in the above <filename>oneko</filename> port by adding the @@ -290,17 +288,17 @@ lib/X11/oneko/mouse.xpm lib/X11/oneko/mouse.xpm PLIST_DIRS= lib/X11/oneko</programlisting> - <para>Of course, <makevar>PLIST_DIRS</makevar> should be left + <para>Of course, <varname>PLIST_DIRS</varname> should be left unset if a port installs no directories of its own.</para> <note> <para>Several ports can share a common directory. In that - case, <makevar>PLIST_DIRS</makevar> should be replaced by - <makevar>PLIST_DIRSTRY</makevar> so that the directory is + case, <varname>PLIST_DIRS</varname> should be replaced by + <varname>PLIST_DIRSTRY</varname> so that the directory is removed only if empty, otherwise it is silently ignored. - <makevar>PLIST_DIRS</makevar> and - <makevar>PLIST_DIRSTRY</makevar> are equivalent to using + <varname>PLIST_DIRS</varname> and + <varname>PLIST_DIRSTRY</varname> are equivalent to using <literal>@dirrm</literal> and <literal>@dirrmtry</literal> in <filename>pkg-plist</filename>, as described in <xref linkend="plist-dir-cleaning"/>.</para> @@ -316,13 +314,13 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <filename>pkg-plist</filename>.</para> <para>Later we will see how <filename>pkg-plist</filename> - and <makevar>PLIST_FILES</makevar> can be used to fulfill + and <varname>PLIST_FILES</varname> can be used to fulfill <link linkend="plist">more sophisticated tasks</link>.</para> </sect2> </sect1> - <sect1 id="porting-checksum"> + <sect1 xml:id="porting-checksum"> <title>Creating the Checksum File</title> <para>Just type <command>make makesum</command>. The ports make @@ -332,13 +330,13 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <para>If a file fetched has its checksum changed regularly and you are certain the source is trusted (i.e., it comes from manufacturer CDs or documentation generated daily), you should - specify these files in the <makevar>IGNOREFILES</makevar> + specify these files in the <varname>IGNOREFILES</varname> variable. Then the checksum is not calculated for that file when you run <command>make makesum</command>, but set to <literal>IGNORE</literal>.</para> </sect1> - <sect1 id="porting-testing"> + <sect1 xml:id="porting-testing"> <title>Testing the Port</title> <para>You should make sure that the port rules do exactly what @@ -358,20 +356,20 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <listitem> <para>The port can be installed using the - <maketarget>install</maketarget> target. This verifies + <buildtarget>install</buildtarget> target. This verifies that the install script works correctly.</para> </listitem> <listitem> <para>The port can be deinstalled properly using the - <maketarget>deinstall</maketarget> target. This verifies + <buildtarget>deinstall</buildtarget> target. This verifies that the deinstall script works correctly.</para> </listitem> <listitem> <para>Make sure that <command>make package</command> can be run as a normal user (that is, not as - <username>root</username>). If that fails, + <systemitem class="username">root</systemitem>). If that fails, <literal>NEED_ROOT=yes</literal> must be added to the port <filename>Makefile</filename>.</para> </listitem> @@ -401,11 +399,11 @@ PLIST_DIRS= lib/X11/oneko</programlisting> </step> <step> - <para><command>pkg_add <replaceable>package-name</replaceable></command></para> + <para><command>pkg_add package-name</command></para> <para>Or, for users of <emphasis>pkg</emphasis>:</para> - <para><command>pkg add <replaceable>package-name</replaceable></command></para> + <para><command>pkg add package-name</command></para> </step> <step> @@ -416,20 +414,20 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <para>Make certain no warnings are shown in any of the stages.</para> - <para>Thorough automated testing can be done with <filename role="package">ports-mgmt/tinderbox</filename> or - <filename role="package">ports-mgmt/poudriere</filename> from the Ports Collection. + <para>Thorough automated testing can be done with <package>ports-mgmt/tinderbox</package> or + <package>ports-mgmt/poudriere</package> from the Ports Collection. These applications maintain <literal>jails</literal> where all of the steps shown above can be tested without affecting the state of the host system.</para> </sect1> - <sect1 id="porting-portlint"> + <sect1 xml:id="porting-portlint"> <title>Checking Your Port with <command>portlint</command></title> <para>Please use <command>portlint</command> to see if your port conforms to our guidelines. The - <filename role="package">ports-mgmt/portlint</filename> + <package>ports-mgmt/portlint</package> program is part of the ports collection. In particular, you may want to check if the <link linkend="porting-samplem">Makefile</link> is in the @@ -438,7 +436,7 @@ PLIST_DIRS= lib/X11/oneko</programlisting> appropriately.</para> </sect1> - <sect1 id="porting-submitting"> + <sect1 xml:id="porting-submitting"> <title>Submitting the New Port</title> <para>Before you submit the new port, make sure you have read @@ -458,16 +456,15 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <para>Include your <literal>oneko.shar</literal> file in a bug report and send it with the &man.send-pr.1; program (see - <ulink - url="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug - Reports and General Commentary</ulink> for more information + <link xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug + Reports and General Commentary</link> for more information about &man.send-pr.1;). Be sure to classify the bug report as category <literal>ports</literal> and class <literal>change-request</literal> (Do not mark the report <literal>confidential</literal>!). Also add a short description of the program you ported to the <quote>Description</quote> field of the PR (e.g., perhaps a - short version of the <makevar>COMMENT</makevar>), and add + short version of the <varname>COMMENT</varname>), and add the shar file to the <quote>Fix</quote> field.</para> <note> @@ -489,19 +486,17 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <para>After you have submitted your port, please be patient. Sometimes it can take a few months before a port is included in &os;, although it might only take a few days. You can - view the list of <ulink - url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports">ports - PRs waiting to be committed to &os;</ulink>.</para> + view the list of <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports">ports + PRs waiting to be committed to &os;</link>.</para> <para>Once we have looked at your port, we will get back to you if necessary, and put it in the tree. Your name will also - be added to the list of <ulink - url="&url.articles.contributors;/contrib-additional.html">Additional - FreeBSD Contributors</ulink> and other files.</para> + be added to the list of <link xlink:href="&url.articles.contributors;/contrib-additional.html">Additional + FreeBSD Contributors</link> and other files.</para> </sect1> </chapter> - <chapter id="slow"> + <chapter xml:id="slow"> <title>Slow Porting</title> <para>Ok, so it was not that simple, and the port required some @@ -509,7 +504,7 @@ PLIST_DIRS= lib/X11/oneko</programlisting> explain, step by step, how to modify it to get it to work with the ports paradigm.</para> - <sect1 id="slow-work"> + <sect1 xml:id="slow-work"> <title>How Things Work</title> <para>First, this is the sequence of events which occurs when @@ -524,44 +519,44 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <procedure> <step> - <para>The <maketarget>fetch</maketarget> target is run. The - <maketarget>fetch</maketarget> target is responsible for + <para>The <buildtarget>fetch</buildtarget> target is run. The + <buildtarget>fetch</buildtarget> target is responsible for making sure that the tarball exists locally in - <makevar>DISTDIR</makevar>. If - <maketarget>fetch</maketarget> cannot find the required - files in <makevar>DISTDIR</makevar> it will look up the - URL <makevar>MASTER_SITES</makevar>, which is set in the + <varname>DISTDIR</varname>. If + <buildtarget>fetch</buildtarget> cannot find the required + files in <varname>DISTDIR</varname> it will look up the + URL <varname>MASTER_SITES</varname>, which is set in the Makefile, as well as our FTP mirrors where we put distfiles as backup. It will then attempt to fetch the named distribution file with - <makevar>FETCH</makevar>, assuming that the requesting + <varname>FETCH</varname>, assuming that the requesting site has direct access to the Internet. If that succeeds, - it will save the file in <makevar>DISTDIR</makevar> for + it will save the file in <varname>DISTDIR</varname> for future use and proceed.</para> </step> <step> - <para>The <maketarget>extract</maketarget> target is run. + <para>The <buildtarget>extract</buildtarget> target is run. It looks for your port's distribution file (typically a <command>gzip</command>ped tarball) in - <makevar>DISTDIR</makevar> and unpacks it into a temporary - subdirectory specified by <makevar>WRKDIR</makevar> + <varname>DISTDIR</varname> and unpacks it into a temporary + subdirectory specified by <varname>WRKDIR</varname> (defaults to <filename>work</filename>).</para> </step> <step> - <para>The <maketarget>patch</maketarget> target is run. + <para>The <buildtarget>patch</buildtarget> target is run. First, any patches defined in - <makevar>PATCHFILES</makevar> are applied. Second, if any + <varname>PATCHFILES</varname> are applied. Second, if any patch files named - <filename>patch-<replaceable>*</replaceable></filename> - are found in <makevar>PATCHDIR</makevar> (defaults to the + <filename>patch-*</filename> + are found in <varname>PATCHDIR</varname> (defaults to the <filename>files</filename> subdirectory), they are applied at this time in alphabetical order.</para> </step> <step> - <para>The <maketarget>configure</maketarget> target is run. + <para>The <buildtarget>configure</buildtarget> target is run. This can do any one of many different things.</para> <orderedlist> @@ -571,9 +566,9 @@ PLIST_DIRS= lib/X11/oneko</programlisting> </listitem> <listitem> - <para>If <makevar>HAS_CONFIGURE</makevar> or - <makevar>GNU_CONFIGURE</makevar> is set, - <filename><makevar>WRKSRC</makevar>/configure</filename> + <para>If <varname>HAS_CONFIGURE</varname> or + <varname>GNU_CONFIGURE</varname> is set, + <filename>WRKSRC/configure</filename> is run.</para> </listitem> @@ -581,23 +576,22 @@ PLIST_DIRS= lib/X11/oneko</programlisting> </step> <step> - <para>The <maketarget>build</maketarget> target is run. + <para>The <buildtarget>build</buildtarget> target is run. This is responsible for descending into the port's private - working directory (<makevar>WRKSRC</makevar>) and building + working directory (<varname>WRKSRC</varname>) and building it.</para> </step> <step> - <para>The <maketarget>stage</maketarget> target is run. This + <para>The <buildtarget>stage</buildtarget> target is run. This puts the final set of built files into a temporary directory - (<makevar>STAGEDIR</makevar>, see <xref - linkend="staging"/>). The hierarchy of this directory + (<varname>STAGEDIR</varname>, see <xref linkend="staging"/>). The hierarchy of this directory mirrors that of the system on which the package will be installed.</para> </step> <step> - <para>The <maketarget>install</maketarget> target is run. + <para>The <buildtarget>install</buildtarget> target is run. This copies the files listed in the port's pkg-plist to the host system.</para> </step> @@ -605,19 +599,19 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <para>The above are the default actions. In addition, you can define targets - <maketarget>pre-<replaceable>something</replaceable></maketarget> + <buildtarget>pre-<replaceable>something</replaceable></buildtarget> or - <maketarget>post-<replaceable>something</replaceable></maketarget>, + <buildtarget>post-<replaceable>something</replaceable></buildtarget>, or put scripts with those names, in the <filename>scripts</filename> subdirectory, and they will be run before or after the default actions are done.</para> <para>For example, if you have a - <maketarget>post-extract</maketarget> target defined in your + <buildtarget>post-extract</buildtarget> target defined in your <filename>Makefile</filename>, and a file <filename>pre-build</filename> in the <filename>scripts</filename> subdirectory, the - <maketarget>post-extract</maketarget> target will be called + <buildtarget>post-extract</buildtarget> target will be called after the regular extraction actions, and the <filename>pre-build</filename> script will be executed before the default build rules are done. It is recommended that you @@ -627,46 +621,46 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <para>The default actions are done by the <filename>bsd.port.mk</filename> targets - <maketarget>do-<replaceable>something</replaceable></maketarget>. + <buildtarget>do-<replaceable>something</replaceable></buildtarget>. For example, the commands to extract a port are in the target - <maketarget>do-extract</maketarget>. If you are not happy + <buildtarget>do-extract</buildtarget>. If you are not happy with the default target, you can fix it by redefining the - <maketarget>do-<replaceable>something</replaceable></maketarget> + <buildtarget>do-<replaceable>something</replaceable></buildtarget> target in your <filename>Makefile</filename>.</para> <note> <para>The <quote>main</quote> targets (e.g., - <maketarget>extract</maketarget>, - <maketarget>configure</maketarget>, etc.) do nothing more + <buildtarget>extract</buildtarget>, + <buildtarget>configure</buildtarget>, etc.) do nothing more than make sure all the stages up to that one are completed and call the real targets or scripts, and they are not intended to be changed. If you want to fix the extraction, - fix <maketarget>do-extract</maketarget>, but never ever - change the way <maketarget>extract</maketarget> + fix <buildtarget>do-extract</buildtarget>, but never ever + change the way <buildtarget>extract</buildtarget> operates! Additionally, the target - <maketarget>post-deinstall</maketarget> is invalid and + <buildtarget>post-deinstall</buildtarget> is invalid and is not run by the ports infrastructure.</para> </note> <para>Now that you understand what goes on when the user types - <command>make <maketarget>install</maketarget></command>, let + <command>make install</command>, let us go through the recommended steps to create the perfect port.</para> </sect1> - <sect1 id="slow-sources"> + <sect1 xml:id="slow-sources"> <title>Getting the Original Sources</title> <para>Get the original sources (normally) as a compressed tarball - (<filename><replaceable>foo</replaceable>.tar.gz</filename> or - <filename><replaceable>foo</replaceable>.tar.bz2</filename>) - and copy it into <makevar>DISTDIR</makevar>. Always use + (<filename>foo.tar.gz</filename> or + <filename>foo.tar.bz2</filename>) + and copy it into <varname>DISTDIR</varname>. Always use <emphasis>mainstream</emphasis> sources when and where you can.</para> <para>You will need to set the variable - <makevar>MASTER_SITES</makevar> to reflect where the original + <varname>MASTER_SITES</varname> to reflect where the original tarball resides. You will find convenient shorthand definitions for most mainstream sites in <filename>bsd.sites.mk</filename>. Please use these @@ -684,20 +678,20 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <para>If you cannot find somewhere convenient and reliable to put the distfile we can <quote>house</quote> it ourselves on - <hostid>ftp.FreeBSD.org</hostid>; however, this is the + <systemitem>ftp.FreeBSD.org</systemitem>; however, this is the least-preferred solution. The distfile must be placed into <filename>~/public_distfiles/</filename> of someone's - <hostid>freefall</hostid> account. Ask the person who commits + <systemitem>freefall</systemitem> account. Ask the person who commits your port to do this. This person will also set - <makevar>MASTER_SITES</makevar> to - <makevar>MASTER_SITE_LOCAL</makevar> and - <makevar>MASTER_SITE_SUBDIR</makevar> to their - <hostid>freefall</hostid> username.</para> + <varname>MASTER_SITES</varname> to + <varname>MASTER_SITE_LOCAL</varname> and + <varname>MASTER_SITE_SUBDIR</varname> to their + <systemitem>freefall</systemitem> username.</para> <para>If your port's distfile changes all the time without any kind of version update by the author, consider putting the distfile on your home page and listing it as the first - <makevar>MASTER_SITES</makevar>. If you can, try to talk the + <varname>MASTER_SITES</varname>. If you can, try to talk the port author out of doing this; it really does help to establish some kind of source code control. Hosting your own version will prevent users from getting @@ -705,18 +699,18 @@ PLIST_DIRS= lib/X11/oneko</programlisting> reduce the workload of maintainers of our FTP site. Also, if there is only one master site for the port, it is recommended that you house a backup at your site and list it as the second - <makevar>MASTER_SITES</makevar>.</para> + <varname>MASTER_SITES</varname>.</para> <para>If your port requires some additional `patches' that are available on the Internet, fetch them too and put them in - <makevar>DISTDIR</makevar>. Do not worry if they come from a + <varname>DISTDIR</varname>. Do not worry if they come from a site other than where you got the main source tarball, we have a way to handle these situations (see the description of <link linkend="porting-patchfiles">PATCHFILES</link> below).</para> </sect1> - <sect1 id="slow-modifying"> + <sect1 xml:id="slow-modifying"> <title>Modifying the Port</title> <para>Unpack a copy of the tarball in a private directory and @@ -745,28 +739,28 @@ PLIST_DIRS= lib/X11/oneko</programlisting> </note> </sect1> - <sect1 id="slow-patch"> + <sect1 xml:id="slow-patch"> <title>Patching</title> <para>In the preparation of the port, files that have been added or changed can be picked up with a &man.diff.1; for later feeding to &man.patch.1;. Each patch you wish to apply should be saved into a file named - <filename>patch-<replaceable>*</replaceable></filename> where + <filename>patch-*</filename> where <replaceable>*</replaceable> indicates the pathname of the file that is patched, such as <filename>patch-Imakefile</filename> or <filename>patch-src-config.h</filename>. These files should - be stored in <makevar>PATCHDIR</makevar> (usually + be stored in <varname>PATCHDIR</varname> (usually <filename>files/</filename>, from where they will be automatically applied. All patches must be relative to - <makevar>WRKSRC</makevar> (generally the directory your port's + <varname>WRKSRC</varname> (generally the directory your port's tarball unpacks itself into, that being where the build is done). To make fixes and upgrades easier, you should avoid having more than one patch fix the same file (e.g., <filename>patch-file</filename> and <filename>patch-file2</filename> both changing - <filename><makevar>WRKSRC</makevar>/foobar.c</filename>). + <filename>WRKSRC/foobar.c</filename>). Note that if the path of a patched file contains an underscore (<literal>_</literal>) character, the patch needs to have two underscores instead in its name. For example, to patch a file @@ -817,7 +811,7 @@ PLIST_DIRS= lib/X11/oneko</programlisting> at all.</para> <para>If you had to delete a file, then you can do it in the - <maketarget>post-extract</maketarget> target rather than as + <buildtarget>post-extract</buildtarget> target rather than as part of the patch.</para> <para>Simple replacements can be performed directly from the @@ -840,7 +834,7 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <programlisting>USE_DOS2UNIX= util.c util.h</programlisting> <para>If you want to convert a group of files across - subdirectories, <makevar>DOS2UNIX_REGEX</makevar> can be used. + subdirectories, <varname>DOS2UNIX_REGEX</varname> can be used. Its argument is a <command>find</command> compatible regular expression. More on the format is in &man.re.format.7;. This option is useful for converting all files of a given @@ -853,13 +847,12 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> <para>If you want to create a patch file based off of an existing file, you can copy it with an <filename>.orig</filename> extension, and then modify the - original one. The <maketarget>makepatch</maketarget> target - will write out an appropriate patch file to the <filename - class="directory">files</filename> directory of the + original one. The <buildtarget>makepatch</buildtarget> target + will write out an appropriate patch file to the <filename>files</filename> directory of the port.</para> </sect1> - <sect1 id="slow-configure"> + <sect1 xml:id="slow-configure"> <title>Configuring</title> <para>Include any additional customization commands in your @@ -871,11 +864,11 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> <filename>post-configure</filename>.</para> </sect1> - <sect1 id="slow-user-input"> + <sect1 xml:id="slow-user-input"> <title>Handling User Input</title> <para>If your port requires user input to build, configure, or - install, you must set <makevar>IS_INTERACTIVE</makevar> in + install, you must set <varname>IS_INTERACTIVE</varname> in your <filename>Makefile</filename>. This will allow <quote>overnight builds</quote> to skip your port if the user sets the variable <envar>BATCH</envar> in his environment (and @@ -886,13 +879,13 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> <para>It is also recommended that if there are reasonable default answers to the questions, you check the - <makevar>PACKAGE_BUILDING</makevar> variable and turn off the + <varname>PACKAGE_BUILDING</varname> variable and turn off the interactive script when it is set. This will allow us to build the packages for CDROMs and FTP.</para> </sect1> </chapter> - <chapter id="makefile"> + <chapter xml:id="makefile"> <title>Configuring the Makefile</title> <para>Configuring the <filename>Makefile</filename> is pretty @@ -906,28 +899,28 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> <para>Now, consider the following problems in sequence as you design your new <filename>Makefile</filename>:</para> - <sect1 id="makefile-source"> + <sect1 xml:id="makefile-source"> <title>The Original Source</title> - <para>Does it live in <makevar>DISTDIR</makevar> as a standard + <para>Does it live in <varname>DISTDIR</varname> as a standard <command>gzip</command>ped tarball named something like <filename>foozolix-1.2.tar.gz</filename>? If so, you can go on to the next step. If not, you should look at overriding any - of the <makevar>DISTVERSION</makevar>, - <makevar>DISTNAME</makevar>, <makevar>EXTRACT_CMD</makevar>, - <makevar>EXTRACT_BEFORE_ARGS</makevar>, - <makevar>EXTRACT_AFTER_ARGS</makevar>, - <makevar>EXTRACT_SUFX</makevar>, or - <makevar>DISTFILES</makevar> variables, depending on how alien + of the <varname>DISTVERSION</varname>, + <varname>DISTNAME</varname>, <varname>EXTRACT_CMD</varname>, + <varname>EXTRACT_BEFORE_ARGS</varname>, + <varname>EXTRACT_AFTER_ARGS</varname>, + <varname>EXTRACT_SUFX</varname>, or + <varname>DISTFILES</varname> variables, depending on how alien a format your port's distribution file is.</para> <para>In the worst case, you can simply create your own - <maketarget>do-extract</maketarget> target to override the + <buildtarget>do-extract</buildtarget> target to override the default, though this should be rarely, if ever, necessary.</para> </sect1> - <sect1 id="makefile-naming"> + <sect1 xml:id="makefile-naming"> <title>Naming</title> <para>The first part of the port's <filename>Makefile</filename> @@ -935,36 +928,36 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> in the correct category.</para> <sect2> - <title><makevar>PORTNAME</makevar> and - <makevar>PORTVERSION</makevar></title> + <title><varname>PORTNAME</varname> and + <varname>PORTVERSION</varname></title> - <para>You should set <makevar>PORTNAME</makevar> to the - base name of your port, and <makevar>PORTVERSION</makevar> + <para>You should set <varname>PORTNAME</varname> to the + base name of your port, and <varname>PORTVERSION</varname> to the version number of the port.</para> </sect2> - <sect2 id="makefile-naming-revepoch"> - <title><makevar>PORTREVISION</makevar> and - <makevar>PORTEPOCH</makevar></title> + <sect2 xml:id="makefile-naming-revepoch"> + <title><varname>PORTREVISION</varname> and + <varname>PORTEPOCH</varname></title> <sect3> - <title><makevar>PORTREVISION</makevar></title> + <title><varname>PORTREVISION</varname></title> - <para>The <makevar>PORTREVISION</makevar> variable is a + <para>The <varname>PORTREVISION</varname> variable is a monotonically increasing value which is reset to 0 with - every increase of <makevar>PORTVERSION</makevar> (i.e., + every increase of <varname>PORTVERSION</varname> (i.e., every time a new official vendor release is made), and appended to the package name if non-zero. Changes to - <makevar>PORTREVISION</makevar> are used by automated + <varname>PORTREVISION</varname> are used by automated tools (e.g., &man.pkg.version.1;) to highlight the fact that a new package is available.</para> - <para><makevar>PORTREVISION</makevar> should be increased + <para><varname>PORTREVISION</varname> should be increased each time a change is made to the port which significantly affects the content or structure of the derived package.</para> - <para>Examples of when <makevar>PORTREVISION</makevar> + <para>Examples of when <varname>PORTREVISION</varname> should be bumped:</para> <itemizedlist> @@ -1000,14 +993,14 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> significant functional differences, i.e., changes to the distfile requiring a correction to <filename>distinfo</filename> with no corresponding - change to <makevar>PORTVERSION</makevar>, where a + change to <varname>PORTVERSION</varname>, where a <command>diff -ru</command> of the old and new versions shows non-trivial changes to the code.</para> </listitem> </itemizedlist> <para>Examples of changes which do not require a - <makevar>PORTREVISION</makevar> bump:</para> + <varname>PORTREVISION</varname> bump:</para> <itemizedlist> <listitem> @@ -1017,7 +1010,7 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> </listitem> <listitem> - <para>Changes to <makevar>MASTER_SITES</makevar> or + <para>Changes to <varname>MASTER_SITES</varname> or other functional changes to the port which do not affect the resulting package.</para> </listitem> @@ -1034,10 +1027,10 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> compilable where it was previously failing (as long as the changes do not introduce any functional change on any other platforms on which the port did previously - build). Since <makevar>PORTREVISION</makevar> + build). Since <varname>PORTREVISION</varname> reflects the content of the package, if the package was not previously buildable then there is no need to - increase <makevar>PORTREVISION</makevar> to mark a + increase <varname>PORTREVISION</varname> to mark a change.</para> </listitem> </itemizedlist> @@ -1049,11 +1042,11 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> at all), and weigh that against that fact that it will cause everyone who regularly updates their ports tree to be compelled to update. If yes, the - <makevar>PORTREVISION</makevar> should be bumped.</para> + <varname>PORTREVISION</varname> should be bumped.</para> </sect3> <sect3> - <title><makevar>PORTEPOCH</makevar></title> + <title><varname>PORTEPOCH</varname></title> <para>From time to time a software vendor or FreeBSD porter will do something silly and release a version of their @@ -1071,13 +1064,13 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> <command>pkg version -t</command>. For example:</para> <screen>&prompt.user; <userinput>pkg_version -t 0.031 0.29</userinput> -></screen> +></screen> <para>Or, for <application>pkgng</application> users:</para> <screen>&prompt.user; <userinput>pkg version -t 0.031 0.29</userinput> -></screen> +></screen> <para>The <literal>></literal> output indicates that version 0.031 is considered greater than version 0.29, @@ -1085,10 +1078,10 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> </tip> <para>In situations such as this, the - <makevar>PORTEPOCH</makevar> version should be increased. - If <makevar>PORTEPOCH</makevar> is nonzero it is appended + <varname>PORTEPOCH</varname> version should be increased. + If <varname>PORTEPOCH</varname> is nonzero it is appended to the package name as described in section 0 above. - <makevar>PORTEPOCH</makevar> must never be decreased or + <varname>PORTEPOCH</varname> must never be decreased or reset to zero, because that would cause comparison to a package from an earlier epoch to fail (i.e., the package would not be detected as out of date): the new version @@ -1099,15 +1092,15 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> greater than the implied suffix <literal>,0</literal> on the earlier package.</para> - <para>Dropping or resetting <makevar>PORTEPOCH</makevar> + <para>Dropping or resetting <varname>PORTEPOCH</varname> incorrectly leads to no end of grief; if you do not understand the above discussion, please keep after it until you do, or ask questions on the mailing lists.</para> - <para>It is expected that <makevar>PORTEPOCH</makevar> will + <para>It is expected that <varname>PORTEPOCH</varname> will not be used for the majority of ports, and that sensible - use of <makevar>PORTVERSION</makevar> can often preempt it + use of <varname>PORTVERSION</varname> can often preempt it becoming necessary if a future release of the software should change the version structure. However, care is needed by FreeBSD porters when a vendor release is made @@ -1120,14 +1113,14 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> <para>For example, if a snapshot release is made on the date 20000917, and the previous version of the software was version 1.2, the snapshot release should be given a - <makevar>PORTVERSION</makevar> of 1.2.20000917 or similar, + <varname>PORTVERSION</varname> of 1.2.20000917 or similar, not 20000917, so that the succeeding release, say 1.3, is still a numerically greater value.</para> </sect3> <sect3> - <title>Example of <makevar>PORTREVISION</makevar> and - <makevar>PORTEPOCH</makevar> Usage</title> + <title>Example of <varname>PORTREVISION</varname> and + <varname>PORTEPOCH</varname> Usage</title> <para>The <literal>gtkmumble</literal> port, version <literal>0.10</literal>, is committed to the ports @@ -1136,18 +1129,18 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> <programlisting>PORTNAME= gtkmumble PORTVERSION= 0.10</programlisting> - <para><makevar>PKGNAME</makevar> becomes + <para><varname>PKGNAME</varname> becomes <literal>gtkmumble-0.10</literal>.</para> <para>A security hole is discovered which requires a local - FreeBSD patch. <makevar>PORTREVISION</makevar> is bumped + FreeBSD patch. <varname>PORTREVISION</varname> is bumped accordingly.</para> <programlisting>PORTNAME= gtkmumble PORTVERSION= 0.10 PORTREVISION= 1</programlisting> - <para><makevar>PKGNAME</makevar> becomes + <para><varname>PKGNAME</varname> becomes <literal>gtkmumble-0.10_1</literal></para> <para>A new version is released by the vendor, numbered @@ -1157,72 +1150,72 @@ PORTREVISION= 1</programlisting> <quote>what comes after 0.9</quote> - oops, too late now). Since the new minor version <literal>2</literal> is numerically less than the previous version - <literal>10</literal>, the <makevar>PORTEPOCH</makevar> + <literal>10</literal>, the <varname>PORTEPOCH</varname> must be bumped to manually force the new package to be detected as <quote>newer</quote>. Since it is a new vendor release of the code, - <makevar>PORTREVISION</makevar> is reset to 0 (or removed + <varname>PORTREVISION</varname> is reset to 0 (or removed from the <filename>Makefile</filename>).</para> <programlisting>PORTNAME= gtkmumble PORTVERSION= 0.2 PORTEPOCH= 1</programlisting> - <para><makevar>PKGNAME</makevar> becomes + <para><varname>PKGNAME</varname> becomes <literal>gtkmumble-0.2,1</literal></para> <para>The next release is 0.3. Since - <makevar>PORTEPOCH</makevar> never decreases, the version + <varname>PORTEPOCH</varname> never decreases, the version variables are now:</para> <programlisting>PORTNAME= gtkmumble PORTVERSION= 0.3 PORTEPOCH= 1</programlisting> - <para><makevar>PKGNAME</makevar> becomes + <para><varname>PKGNAME</varname> becomes <literal>gtkmumble-0.3,1</literal></para> <note> - <para>If <makevar>PORTEPOCH</makevar> were reset to + <para>If <varname>PORTEPOCH</varname> were reset to <literal>0</literal> with this upgrade, someone who had installed the <literal>gtkmumble-0.10_1</literal> package would not detect the <literal>gtkmumble-0.3</literal> package as newer, since <literal>3</literal> is still numerically less than <literal>10</literal>. Remember, this is the whole - point of <makevar>PORTEPOCH</makevar> in the first + point of <varname>PORTEPOCH</varname> in the first place.</para> </note> </sect3> </sect2> <sect2> - <title><makevar>PKGNAMEPREFIX</makevar> and - <makevar>PKGNAMESUFFIX</makevar></title> - - <para>Two optional variables, <makevar>PKGNAMEPREFIX</makevar> - and <makevar>PKGNAMESUFFIX</makevar>, are combined with - <makevar>PORTNAME</makevar> and - <makevar>PORTVERSION</makevar> to form - <makevar>PKGNAME</makevar> as + <title><varname>PKGNAMEPREFIX</varname> and + <varname>PKGNAMESUFFIX</varname></title> + + <para>Two optional variables, <varname>PKGNAMEPREFIX</varname> + and <varname>PKGNAMESUFFIX</varname>, are combined with + <varname>PORTNAME</varname> and + <varname>PORTVERSION</varname> to form + <varname>PKGNAME</varname> as <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>. Make sure this conforms to our <link linkend="porting-pkgname">guidelines for a good package name</link>. In particular, you are <emphasis>not</emphasis> allowed to use a hyphen - (<literal>-</literal>) in <makevar>PORTVERSION</makevar>. + (<literal>-</literal>) in <varname>PORTVERSION</varname>. Also, if the package name has the <replaceable>language-</replaceable> or the <replaceable>-compiled.specifics</replaceable> part (see - below), use <makevar>PKGNAMEPREFIX</makevar> and - <makevar>PKGNAMESUFFIX</makevar>, respectively. Do not make - them part of <makevar>PORTNAME</makevar>.</para> + below), use <varname>PKGNAMEPREFIX</varname> and + <varname>PKGNAMESUFFIX</varname>, respectively. Do not make + them part of <varname>PORTNAME</varname>.</para> </sect2> <sect2> - <title><makevar>LATEST_LINK</makevar></title> + <title><varname>LATEST_LINK</varname></title> - <para><makevar>LATEST_LINK</makevar> is used during package + <para><varname>LATEST_LINK</varname> is used during package building to determine a shortened name to create links that can be used by <command>pkg_add -r</command>. This makes it possible to, for example, install the latest perl version by @@ -1234,16 +1227,16 @@ PORTEPOCH= 1</programlisting> present in the ports collection at the same time. Both the index build and the package build system need to be able to see them as different, independent ports, although they may - all have the same <makevar>PORTNAME</makevar>, - <makevar>PKGNAMEPREFIX</makevar>, and even - <makevar>PKGNAMESUFFIX</makevar>. In those cases, the - optional <makevar>LATEST_LINK</makevar> variable should be + all have the same <varname>PORTNAME</varname>, + <varname>PKGNAMEPREFIX</varname>, and even + <varname>PKGNAMESUFFIX</varname>. In those cases, the + optional <varname>LATEST_LINK</varname> variable should be set to a different value for all ports except the <quote>main</quote> one — see the <filename>lang/gcc46</filename> and <filename>lang/gcc</filename> ports, and the <filename>www/apache*</filename> family for examples of its - use. By setting <makevar>NO_LATEST_LINK</makevar>, no link + use. By setting <varname>NO_LATEST_LINK</varname>, no link will be generated, which may be an option for all but the <quote>main</quote> version. Note that how to choose a <quote>main</quote> version — @@ -1254,7 +1247,7 @@ PORTEPOCH= 1</programlisting> picked a <quote>main</quote> one.</para> </sect2> - <sect2 id="porting-pkgname"> + <sect2 xml:id="porting-pkgname"> <title>Package Naming Conventions</title> <para>The following are the conventions you should follow in @@ -1263,7 +1256,7 @@ PORTEPOCH= 1</programlisting> users are going to turn away if they hurt their eyes!</para> <para>The package name should look like - <filename><replaceable><optional>language<optional>_region</optional></optional>-name<optional><optional>-</optional>compiled.specifics</optional>-version.numbers</replaceable></filename>.</para> + <filename>language_region-name-compiled.specifics-version.numbers</filename>.</para> <para>The package name is defined as <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>. @@ -1289,7 +1282,7 @@ PORTEPOCH= 1</programlisting> French.</para> <para>The <replaceable>language-</replaceable> part should - be set in the <makevar>PKGNAMEPREFIX</makevar> + be set in the <varname>PKGNAMEPREFIX</varname> variable.</para> </listitem> @@ -1309,27 +1302,26 @@ PORTEPOCH= 1</programlisting> <listitem> <para>Make sure that the port's name and version are clearly separated and placed into the - <makevar>PORTNAME</makevar> and - <makevar>PORTVERSION</makevar> variables. The only - reason for <makevar>PORTNAME</makevar> to contain a + <varname>PORTNAME</varname> and + <varname>PORTVERSION</varname> variables. The only + reason for <varname>PORTNAME</varname> to contain a version part is if the upstream distribution is really named that way, as in the <filename>textproc/libxml2</filename> or <filename>japanese/kinput2-freewnn</filename> ports. - Otherwise, the <makevar>PORTNAME</makevar> should not + Otherwise, the <varname>PORTNAME</varname> should not contain any version-specific information. It is quite normal for several ports to have the same - <makevar>PORTNAME</makevar>, as the + <varname>PORTNAME</varname>, as the <filename>www/apache*</filename> ports do; in that case, different versions (and different index entries) are - distinguished by the <makevar>PKGNAMEPREFIX</makevar>, - <makevar>PKGNAMESUFFIX</makevar>, and - <makevar>LATEST_LINK</makevar> values.</para> + distinguished by the <varname>PKGNAMEPREFIX</varname>, + <varname>PKGNAMESUFFIX</varname>, and + <varname>LATEST_LINK</varname> values.</para> </listitem> <listitem> - <para>If the port can be built with different <link - linkend="makefile-masterdir">hardcoded defaults</link> + <para>If the port can be built with different <link linkend="makefile-masterdir">hardcoded defaults</link> (usually part of the directory name in a family of ports), the <replaceable>-compiled.specifics</replaceable> part @@ -1339,7 +1331,7 @@ PORTEPOCH= 1</programlisting> <para>The <replaceable>-compiled.specifics</replaceable> part should be set in the - <makevar>PKGNAMESUFFIX</makevar> variable.</para> + <varname>PKGNAMESUFFIX</varname> variable.</para> </listitem> <listitem> @@ -1364,16 +1356,16 @@ PORTEPOCH= 1</programlisting> looking at the version string. In particular, make sure version number components are always delimited by a period, and if the date is part of the string, use the - <literal>0.0.<replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal> + <literal>0.0.yyyy.mm.dd</literal> format, not - <literal><replaceable>dd</replaceable>.<replaceable>mm</replaceable>.<replaceable>yyyy</replaceable></literal> + <literal>dd.mm.yyyy</literal> or the non-Y2K compliant - <literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal> + <literal>yy.mm.dd</literal> format. It is important to prefix the version with <literal>0.0.</literal> in case a release with an actual version number is made, which would of course be numerically less than - <literal><replaceable>yyyy</replaceable></literal>.</para> + <literal>yyyy</literal>.</para> </listitem> </orderedlist> @@ -1386,10 +1378,10 @@ PORTEPOCH= 1</programlisting> <thead> <row> <entry>Distribution Name</entry> - <entry><makevar>PKGNAMEPREFIX</makevar></entry> - <entry><makevar>PORTNAME</makevar></entry> - <entry><makevar>PKGNAMESUFFIX</makevar></entry> - <entry><makevar>PORTVERSION</makevar></entry> + <entry><varname>PKGNAMEPREFIX</varname></entry> + <entry><varname>PORTNAME</varname></entry> + <entry><varname>PKGNAMESUFFIX</varname></entry> + <entry><varname>PORTVERSION</varname></entry> <entry>Reason</entry> </row> </thead> @@ -1517,23 +1509,23 @@ PORTEPOCH= 1</programlisting> version string to <literal>1.0</literal> (like the <literal>piewm</literal> example above). Otherwise, ask the original author or use the date string - (<literal>0.0.<replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) + (<literal>0.0.yyyy.mm.dd</literal>) as the version.</para> </sect2> </sect1> - <sect1 id="makefile-categories"> + <sect1 xml:id="makefile-categories"> <title>Categorization</title> <sect2> - <title><makevar>CATEGORIES</makevar></title> + <title><varname>CATEGORIES</varname></title> <para>When a package is created, it is put under <filename>/usr/ports/packages/All</filename> and links are made from one or more subdirectories of <filename>/usr/ports/packages</filename>. The names of these subdirectories are specified by the variable - <makevar>CATEGORIES</makevar>. It is intended to make life + <varname>CATEGORIES</varname>. It is intended to make life easier for the user when he is wading through the pile of packages on the FTP site or the CDROM. Please take a look at the <link linkend="porting-categories">current list of @@ -1548,7 +1540,7 @@ PORTEPOCH= 1</programlisting> discussion about how to pick the right categories.</para> </sect2> - <sect2 id="porting-categories"> + <sect2 xml:id="porting-categories"> <title>Current List of Categories</title> <para>Here is the current list of port categories. Those @@ -1560,7 +1552,7 @@ PORTEPOCH= 1</programlisting> <note> <para>For non-virtual categories, you will find a one-line - description in the <makevar>COMMENT</makevar> in that + description in the <varname>COMMENT</varname> in that subdirectory's <filename>Makefile</filename>.</para> </note> @@ -1578,63 +1570,62 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>accessibility</filename></entry> <entry>Ports to help disabled users.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>afterstep*</filename></entry> - <entry>Ports to support the <ulink - url="http://www.afterstep.org">AfterStep</ulink> + <entry>Ports to support the <link xlink:href="http://www.afterstep.org">AfterStep</link> window manager.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>arabic</filename></entry> <entry>Arabic language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>archivers</filename></entry> <entry>Archiving tools.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>astro</filename></entry> <entry>Astronomical ports.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>audio</filename></entry> <entry>Sound support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>benchmarks</filename></entry> <entry>Benchmarking utilities.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>biology</filename></entry> <entry>Biology-related software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>cad</filename></entry> <entry>Computer aided design tools.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>chinese</filename></entry> <entry>Chinese language support.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1647,20 +1638,20 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>converters</filename></entry> <entry>Character code converters.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>databases</filename></entry> <entry>Databases.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>deskutils</filename></entry> <entry>Things that used to be on the desktop before computers were invented.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1675,13 +1666,13 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>dns</filename></entry> <entry>DNS-related software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>docs*</filename></entry> <entry>Meta-ports for FreeBSD documentation.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1695,7 +1686,7 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>elisp*</filename></entry> <entry>Emacs-lisp ports.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1713,13 +1704,13 @@ PORTEPOCH= 1</programlisting> <entry><filename>finance</filename></entry> <entry>Monetary, financial and related applications.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>french</filename></entry> <entry>French language support.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1733,83 +1724,83 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>games</filename></entry> <entry>Games.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>geography*</filename></entry> <entry>Geography-related software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>german</filename></entry> <entry>German language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>gnome*</filename></entry> <entry>Ports from the - <ulink url="http://www.gnome.org">GNOME</ulink> + <link xlink:href="http://www.gnome.org">GNOME</link> Project.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>gnustep*</filename></entry> <entry>Software related to the GNUstep desktop environment.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>graphics</filename></entry> <entry>Graphics utilities.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>hamradio*</filename></entry> <entry>Software for amateur radio.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>haskell*</filename></entry> <entry>Software related to the Haskell language.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>hebrew</filename></entry> <entry>Hebrew language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>hungarian</filename></entry> <entry>Hungarian language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>ipv6*</filename></entry> <entry>IPv6 related software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>irc</filename></entry> <entry>Internet Relay Chat utilities.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>japanese</filename></entry> <entry>Japanese language support.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1826,59 +1817,59 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>kde*</filename></entry> <entry>Ports from the - <ulink url="http://www.kde.org">KDE</ulink> + <link xlink:href="http://www.kde.org">KDE</link> Project.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>kld*</filename></entry> <entry>Kernel loadable modules.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>korean</filename></entry> <entry>Korean language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>lang</filename></entry> <entry>Programming languages.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>linux*</filename></entry> <entry>Linux applications and support utilities.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>lisp*</filename></entry> <entry>Software related to the Lisp language.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>mail</filename></entry> <entry>Mail software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>math</filename></entry> <entry>Numerical computation software and other utilities for mathematics.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>mbone*</filename></entry> <entry>MBone applications.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1893,59 +1884,58 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>multimedia</filename></entry> <entry>Multimedia software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>net</filename></entry> <entry>Miscellaneous networking software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>net-im</filename></entry> <entry>Instant messaging software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>net-mgmt</filename></entry> <entry>Networking management software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>net-p2p</filename></entry> <entry>Peer to peer network applications.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>news</filename></entry> <entry>USENET news software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>palm</filename></entry> - <entry>Software support for the <ulink - url="http://www.palm.com/">Palm™</ulink> + <entry>Software support for the <link xlink:href="http://www.palm.com/">Palm™</link> series.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>parallel*</filename></entry> <entry>Applications dealing with parallelism in computing.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>pear*</filename></entry> <entry>Ports related to the Pear PHP framework.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1953,20 +1943,19 @@ PORTEPOCH= 1</programlisting> <entry>Ports that require <application>Perl</application> version 5 to run.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>plan9*</filename></entry> - <entry>Various programs from <ulink - url="http://www.cs.bell-labs.com/plan9dist/">Plan9</ulink>.</entry> - <entry></entry> + <entry>Various programs from <link xlink:href="http://www.cs.bell-labs.com/plan9dist/">Plan9</link>.</entry> + <entry/> </row> <row> <entry><filename>polish</filename></entry> <entry>Polish language support.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1978,7 +1967,7 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>portuguese</filename></entry> <entry>Portuguese language support.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1990,39 +1979,36 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>python*</filename></entry> - <entry>Software related to the <ulink - url="http://www.python.org/">Python</ulink> + <entry>Software related to the <link xlink:href="http://www.python.org/">Python</link> language.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>ruby*</filename></entry> - <entry>Software related to the <ulink - url="http://www.ruby-lang.org/">Ruby</ulink> + <entry>Software related to the <link xlink:href="http://www.ruby-lang.org/">Ruby</link> language.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>rubygems*</filename></entry> - <entry>Ports of <ulink - url="http://www.rubygems.org/">RubyGems</ulink> + <entry>Ports of <link xlink:href="http://www.rubygems.org/">RubyGems</link> packages.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>russian</filename></entry> <entry>Russian language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>scheme*</filename></entry> <entry>Software related to the Scheme language.</entry> - <entry></entry> + <entry/> </row> <row> @@ -2031,37 +2017,37 @@ PORTEPOCH= 1</programlisting> categories such as <filename>astro</filename>, <filename>biology</filename> and <filename>math</filename>.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>security</filename></entry> <entry>Security utilities.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>shells</filename></entry> <entry>Command line shells.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>spanish*</filename></entry> <entry>Spanish language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>sysutils</filename></entry> <entry>System utilities.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>tcl*</filename></entry> <entry>Ports that use Tcl to run.</entry> - <entry></entry> + <entry/> </row> <row> @@ -2074,26 +2060,26 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>tk*</filename></entry> <entry>Ports that use Tk to run.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>ukrainian</filename></entry> <entry>Ukrainian language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>vietnamese</filename></entry> <entry>Vietnamese language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>windowmaker*</filename></entry> <entry>Ports to support the WindowMaker window manager.</entry> - <entry></entry> + <entry/> </row> <row> @@ -2116,71 +2102,71 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>x11-clocks</filename></entry> <entry>X11 clocks.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>x11-drivers</filename></entry> <entry>X11 drivers.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>x11-fm</filename></entry> <entry>X11 file managers.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>x11-fonts</filename></entry> <entry>X11 fonts and font utilities.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>x11-servers</filename></entry> <entry>X11 servers.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>x11-themes</filename></entry> <entry>X11 themes.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>x11-toolkits</filename></entry> <entry>X11 toolkits.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>x11-wm</filename></entry> <entry>X11 window managers.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>xfce*</filename></entry> <entry>Ports related to the - <ulink url="http://www.xfce.org/">Xfce</ulink> + <link xlink:href="http://www.xfce.org/">Xfce</link> desktop environment.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>zope*</filename></entry> - <entry><ulink url="http://www.zope.org/">Zope</ulink> + <entry><link xlink:href="http://www.zope.org/">Zope</link> support.</entry> - <entry></entry> + <entry/> </row> </tbody> </tgroup> </informaltable> </sect2> - <sect2 id="choosing-categories"> + <sect2 xml:id="choosing-categories"> <title>Choosing the Right Category</title> <para>As many of the categories overlap, you often have to @@ -2201,7 +2187,7 @@ PORTEPOCH= 1</programlisting> <listitem> <para>Language specific categories always come first. For example, if your port installs Japanese X11 fonts, then - your <makevar>CATEGORIES</makevar> line would read + your <varname>CATEGORIES</varname> line would read <filename>japanese x11-fonts</filename>.</para> </listitem> @@ -2239,14 +2225,14 @@ PORTEPOCH= 1</programlisting> <listitem> <para>Ports which install loadable kernel modules should have the virtual category <filename>kld</filename> in - their <makevar>CATEGORIES</makevar> line.</para> + their <varname>CATEGORIES</varname> line.</para> </listitem> <listitem> <para><filename>misc</filename> should not appear with any other non-virtual category. If you have <literal>misc</literal> with something else in your - <makevar>CATEGORIES</makevar> line, that means you can + <varname>CATEGORIES</varname> line, that means you can safely delete <literal>misc</literal> and just put the port in that other subdirectory!</para> </listitem> @@ -2267,7 +2253,7 @@ PORTEPOCH= 1</programlisting> repository.</para> </sect2> - <sect2 id="proposing-categories"> + <sect2 xml:id="proposing-categories"> <title>Proposing a New Category</title> <para>As the Ports Collection has grown over time, various new @@ -2288,8 +2274,8 @@ PORTEPOCH= 1</programlisting> human languages), or preferably both.</para> <para>The rationale for this is that such a change creates a - <ulink url="&url.articles.committers-guide;/#ports"> fair - amount of work</ulink> for both the committers and also + <link xlink:href="&url.articles.committers-guide;/#ports"> fair + amount of work</link> for both the committers and also for all users who track changes to the Ports Collection. In addition, proposed category changes just naturally seem to attract controversy. (Perhaps this is because there is no @@ -2361,9 +2347,8 @@ PORTEPOCH= 1</programlisting> <step> <para>If that PR is approved, a committer will need to - follow the rest of the procedure that is <ulink - url="&url.articles.committers-guide;/article.html#PORTS"> - outlined in the Committer's Guide</ulink>.</para> + follow the rest of the procedure that is <link xlink:href="&url.articles.committers-guide;/article.html#PORTS"> + outlined in the Committer's Guide</link>.</para> </step> </procedure> @@ -2371,11 +2356,11 @@ PORTEPOCH= 1</programlisting> the above but much less involved, since no ports will actually have to move. In this case, the only patches to include in the PR would be those to add the new category to - the <makevar>CATEGORIES</makevar> of the affected + the <varname>CATEGORIES</varname> of the affected ports.</para> </sect2> - <sect2 id="proposing-reorg"> + <sect2 xml:id="proposing-reorg"> <title>Proposing Reorganizing All the Categories</title> <para>Occasionally someone proposes reorganizing the @@ -2391,7 +2376,7 @@ PORTEPOCH= 1</programlisting> </sect2> </sect1> - <sect1 id="makefile-distfiles"> + <sect1 xml:id="makefile-distfiles"> <title>The Distribution Files</title> <para>The second part of the <filename>Makefile</filename> @@ -2399,27 +2384,27 @@ PORTEPOCH= 1</programlisting> the port, and where they can be downloaded from.</para> <sect2> - <title><makevar>DISTVERSION/DISTNAME</makevar></title> + <title><varname>DISTVERSION/DISTNAME</varname></title> - <para><makevar>DISTNAME</makevar> is the name of the port as + <para><varname>DISTNAME</varname> is the name of the port as called by the authors of the software. - <makevar>DISTNAME</makevar> defaults to + <varname>DISTNAME</varname> defaults to <literal>${PORTNAME}-${PORTVERSION}</literal>, so override - it only if necessary. <makevar>DISTNAME</makevar> is only + it only if necessary. <varname>DISTNAME</varname> is only used in two places. First, the distribution file list - (<makevar>DISTFILES</makevar>) defaults to - <makevar>${DISTNAME}</makevar><makevar>${EXTRACT_SUFX}</makevar>. + (<varname>DISTFILES</varname>) defaults to + <varname>${DISTNAME}</varname><varname>${EXTRACT_SUFX}</varname>. Second, the distribution file is expected to extract into a - subdirectory named <makevar>WRKSRC</makevar>, which defaults + subdirectory named <varname>WRKSRC</varname>, which defaults to - <filename>work/<makevar>${DISTNAME}</makevar></filename>.</para> + <filename>work/${DISTNAME}</filename>.</para> <para>Some vendor's distribution names which do not fit into the <literal>${PORTNAME}-${PORTVERSION}</literal>-scheme can be handled automatically by setting - <makevar>DISTVERSION</makevar>. - <makevar>PORTVERSION</makevar> and - <makevar>DISTNAME</makevar> will be derived automatically, + <varname>DISTVERSION</varname>. + <varname>PORTVERSION</varname> and + <varname>DISTNAME</varname> will be derived automatically, but can of course be overridden. The following table lists some examples:</para> @@ -2427,8 +2412,8 @@ PORTEPOCH= 1</programlisting> <tgroup cols="2"> <thead> <row> - <entry><makevar>DISTVERSION</makevar></entry> - <entry><makevar>PORTVERSION</makevar></entry> + <entry><varname>DISTVERSION</varname></entry> + <entry><varname>PORTVERSION</varname></entry> </row> </thead> @@ -2457,33 +2442,33 @@ PORTEPOCH= 1</programlisting> </informaltable> <note> - <para><makevar>PKGNAMEPREFIX</makevar> and - <makevar>PKGNAMESUFFIX</makevar> do not affect - <makevar>DISTNAME</makevar>. Also note that if - <makevar>WRKSRC</makevar> is equal to - <filename>work/<makevar>${PORTNAME}-${PORTVERSION}</makevar></filename> + <para><varname>PKGNAMEPREFIX</varname> and + <varname>PKGNAMESUFFIX</varname> do not affect + <varname>DISTNAME</varname>. Also note that if + <varname>WRKSRC</varname> is equal to + <filename>work/${PORTNAME}-${PORTVERSION}</filename> while the original source archive is named something other than - <makevar>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</makevar>, - you should probably leave <makevar>DISTNAME</makevar> + <varname>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</varname>, + you should probably leave <varname>DISTNAME</varname> alone— you are better off defining - <makevar>DISTFILES</makevar> than having to set both - <makevar>DISTNAME</makevar> and <makevar>WRKSRC</makevar> - (and possibly <makevar>EXTRACT_SUFX</makevar>).</para> + <varname>DISTFILES</varname> than having to set both + <varname>DISTNAME</varname> and <varname>WRKSRC</varname> + (and possibly <varname>EXTRACT_SUFX</varname>).</para> </note> </sect2> <sect2> - <title><makevar>MASTER_SITES</makevar></title> + <title><varname>MASTER_SITES</varname></title> <para>Record the directory part of the FTP/HTTP-URL pointing - at the original tarball in <makevar>MASTER_SITES</makevar>. + at the original tarball in <varname>MASTER_SITES</varname>. Do not forget the trailing slash (<filename>/</filename>)!</para> <para>The <command>make</command> macros will try to use this specification for grabbing the distribution file with - <makevar>FETCH</makevar> if they cannot find it already on + <varname>FETCH</varname> if they cannot find it already on the system.</para> <para>It is recommended that you put multiple sites on this @@ -2496,12 +2481,12 @@ PORTEPOCH= 1</programlisting> <para>If the original tarball is part of one of the popular archives such as SourceForge, GNU, or Perl CPAN, you may be able refer to those sites in an easy compact form using - <makevar>MASTER_SITE_<replaceable>*</replaceable></makevar> - (e.g., <makevar>MASTER_SITE_SOURCEFORGE</makevar>, - <makevar>MASTER_SITE_GNU</makevar> and - <makevar>MASTER_SITE_PERL_CPAN</makevar>). Simply set - <makevar>MASTER_SITES</makevar> to one of these variables - and <makevar>MASTER_SITE_SUBDIR</makevar> to the path within + <varname>MASTER_SITE_<replaceable>*</replaceable></varname> + (e.g., <varname>MASTER_SITE_SOURCEFORGE</varname>, + <varname>MASTER_SITE_GNU</varname> and + <varname>MASTER_SITE_PERL_CPAN</varname>). Simply set + <varname>MASTER_SITES</varname> to one of these variables + and <varname>MASTER_SITE_SUBDIR</varname> to the path within the archive. Here is an example:</para> <programlisting>MASTER_SITES= ${MASTER_SITE_GNU} @@ -2534,7 +2519,7 @@ MASTER_SITE_SUBDIR= make</programlisting> MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting> <table frame="none"> - <title>Popular Magic <makevar>MASTER_SITES</makevar> + <title>Popular Magic <varname>MASTER_SITES</varname> Macros</title> <tgroup cols="2"> @@ -2547,68 +2532,68 @@ MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting> <tbody> <row> - <entry><makevar>APACHE_JAKARTA</makevar></entry> - <entry><makevar>/dist/jakarta/${PORTNAME:S,-,,/,}/source</makevar></entry> + <entry><varname>APACHE_JAKARTA</varname></entry> + <entry><varname>/dist/jakarta/${PORTNAME:S,-,,/,}/source</varname></entry> </row> <row> - <entry><makevar>BERLIOS</makevar></entry> - <entry><makevar>/${PORTNAME:L}</makevar></entry> + <entry><varname>BERLIOS</varname></entry> + <entry><varname>/${PORTNAME:L}</varname></entry> </row> <row> - <entry><makevar>CHEESESHOP</makevar></entry> - <entry><makevar>/packages/source/source/${DISTNAME:C/(.).*/\1/}/${DISTNAME:C/(.*)-[0-9].*/\1/}</makevar></entry> + <entry><varname>CHEESESHOP</varname></entry> + <entry><varname>/packages/source/source/${DISTNAME:C/(.).*/\1/}/${DISTNAME:C/(.*)-[0-9].*/\1/}</varname></entry> </row> <row> - <entry><makevar>DEBIAN</makevar></entry> - <entry><makevar>/debian/pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME}</makevar></entry> + <entry><varname>DEBIAN</varname></entry> + <entry><varname>/debian/pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME}</varname></entry> </row> <row> - <entry><makevar>GCC</makevar></entry> - <entry><makevar>/pub/gcc/releases/${DISTNAME}</makevar></entry> + <entry><varname>GCC</varname></entry> + <entry><varname>/pub/gcc/releases/${DISTNAME}</varname></entry> </row> <row> - <entry><makevar>GNOME</makevar></entry> - <entry><makevar>/pub/GNOME/sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}</makevar></entry> + <entry><varname>GNOME</varname></entry> + <entry><varname>/pub/GNOME/sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}</varname></entry> </row> <row> - <entry><makevar>GNU</makevar></entry> - <entry><makevar>/gnu/${PORTNAME}</makevar></entry> + <entry><varname>GNU</varname></entry> + <entry><varname>/gnu/${PORTNAME}</varname></entry> </row> <row> - <entry><makevar>MOZDEV</makevar></entry> - <entry><makevar>/pub/mozdev/${PORTNAME:L}</makevar></entry> + <entry><varname>MOZDEV</varname></entry> + <entry><varname>/pub/mozdev/${PORTNAME:L}</varname></entry> </row> <row> - <entry><makevar>PERL_CPAN</makevar></entry> - <entry><makevar>/pub/CPAN/modules/by-module/${PORTNAME:C/-.*//}</makevar></entry> + <entry><varname>PERL_CPAN</varname></entry> + <entry><varname>/pub/CPAN/modules/by-module/${PORTNAME:C/-.*//}</varname></entry> </row> <row> - <entry><makevar>PYTHON</makevar></entry> - <entry><makevar>/ftp/python/${PYTHON_PORTVERSION:C/rc[0-9]//}</makevar></entry> + <entry><varname>PYTHON</varname></entry> + <entry><varname>/ftp/python/${PYTHON_PORTVERSION:C/rc[0-9]//}</varname></entry> </row> <row> - <entry><makevar>RUBYFORGE</makevar></entry> - <entry><makevar>/${PORTNAME:L}</makevar></entry> + <entry><varname>RUBYFORGE</varname></entry> + <entry><varname>/${PORTNAME:L}</varname></entry> </row> <row> - <entry><makevar>SAVANNAH</makevar></entry> - <entry><makevar>/${PORTNAME:L}</makevar></entry> + <entry><varname>SAVANNAH</varname></entry> + <entry><varname>/${PORTNAME:L}</varname></entry> </row> <row> - <entry><makevar>SF</makevar></entry> - <entry><makevar>/project/${PORTNAME:L}/${PORTNAME:L}/${PORTVERSION}</makevar></entry> + <entry><varname>SF</varname></entry> + <entry><varname>/project/${PORTNAME:L}/${PORTNAME:L}/${PORTVERSION}</varname></entry> </row> </tbody> </tgroup> @@ -2616,11 +2601,11 @@ MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting> </sect2> <sect2> - <title><makevar>EXTRACT_SUFX</makevar></title> + <title><varname>EXTRACT_SUFX</varname></title> <para>If you have one distribution file, and it uses an odd suffix to indicate the compression mechanism, set - <makevar>EXTRACT_SUFX</makevar>.</para> + <varname>EXTRACT_SUFX</varname>.</para> <para>For example, if the distribution file was named <filename>foo.tgz</filename> instead of the more normal @@ -2629,24 +2614,24 @@ MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting> <programlisting>DISTNAME= foo EXTRACT_SUFX= .tgz</programlisting> - <para>The <makevar>USE_BZIP2</makevar>, - <makevar>USE_XZ</makevar> and - <makevar>USE_ZIP</makevar> variables automatically set - <makevar>EXTRACT_SUFX</makevar> to + <para>The <varname>USE_BZIP2</varname>, + <varname>USE_XZ</varname> and + <varname>USE_ZIP</varname> variables automatically set + <varname>EXTRACT_SUFX</varname> to <literal>.tar.bz2</literal>, <literal>.tar.xz</literal> or <literal>.zip</literal> as necessary. If neither of - these are set then <makevar>EXTRACT_SUFX</makevar> + these are set then <varname>EXTRACT_SUFX</varname> defaults to <literal>.tar.gz</literal>.</para> <note> <para>You never need to set both - <makevar>EXTRACT_SUFX</makevar> and - <makevar>DISTFILES</makevar>.</para> + <varname>EXTRACT_SUFX</varname> and + <varname>DISTFILES</varname>.</para> </note> </sect2> <sect2> - <title><makevar>DISTFILES</makevar></title> + <title><varname>DISTFILES</varname></title> <para>Sometimes the names of the files to be downloaded have no resemblance to the name of the port. For example, it @@ -2655,49 +2640,49 @@ EXTRACT_SUFX= .tgz</programlisting> be in several different archives, all of which must be downloaded.</para> - <para>If this is the case, set <makevar>DISTFILES</makevar> to + <para>If this is the case, set <varname>DISTFILES</varname> to be a space separated list of all the files that must be downloaded.</para> <programlisting>DISTFILES= source1.tar.gz source2.tar.gz</programlisting> - <para>If not explicitly set, <makevar>DISTFILES</makevar> + <para>If not explicitly set, <varname>DISTFILES</varname> defaults to <literal>${DISTNAME}${EXTRACT_SUFX}</literal>.</para> </sect2> <sect2> - <title><makevar>EXTRACT_ONLY</makevar></title> + <title><varname>EXTRACT_ONLY</varname></title> - <para>If only some of the <makevar>DISTFILES</makevar> must be + <para>If only some of the <varname>DISTFILES</varname> must be extracted—for example, one of them is the source code, while another is an uncompressed document—list the filenames that must be extracted in - <makevar>EXTRACT_ONLY</makevar>.</para> + <varname>EXTRACT_ONLY</varname>.</para> <programlisting>DISTFILES= source.tar.gz manual.html EXTRACT_ONLY= source.tar.gz</programlisting> <para>If <emphasis>none</emphasis> of the - <makevar>DISTFILES</makevar> should be uncompressed then set - <makevar>EXTRACT_ONLY</makevar> to the empty string.</para> + <varname>DISTFILES</varname> should be uncompressed then set + <varname>EXTRACT_ONLY</varname> to the empty string.</para> <programlisting>EXTRACT_ONLY=</programlisting> </sect2> - <sect2 id="porting-patchfiles"> - <title><makevar>PATCHFILES</makevar></title> + <sect2 xml:id="porting-patchfiles"> + <title><varname>PATCHFILES</varname></title> <para>If your port requires some additional patches that are - available by FTP or HTTP, set <makevar>PATCHFILES</makevar> - to the names of the files and <makevar>PATCH_SITES</makevar> + available by FTP or HTTP, set <varname>PATCHFILES</varname> + to the names of the files and <varname>PATCH_SITES</varname> to the URL of the directory that contains them (the format - is the same as <makevar>MASTER_SITES</makevar>).</para> + is the same as <varname>MASTER_SITES</varname>).</para> <para>If the patch is not relative to the top of the source - tree (i.e., <makevar>WRKSRC</makevar>) because it contains + tree (i.e., <varname>WRKSRC</varname>) because it contains some extra pathnames, set - <makevar>PATCH_DIST_STRIP</makevar> accordingly. For + <varname>PATCH_DIST_STRIP</varname> accordingly. For instance, if all the pathnames in the patch have an extra <literal>foozolix-1.0/</literal> in front of the filenames, then set <literal>PATCH_DIST_STRIP=-p1</literal>.</para> @@ -2708,15 +2693,15 @@ EXTRACT_ONLY= source.tar.gz</programlisting> <para>If the patch is distributed with some other files, such as documentation, in a <command>gzip</command>ped tarball, - you cannot just use <makevar>PATCHFILES</makevar>. If that + you cannot just use <varname>PATCHFILES</varname>. If that is the case, add the name and the location of the patch - tarball to <makevar>DISTFILES</makevar> and - <makevar>MASTER_SITES</makevar>. Then, use the - <makevar>EXTRA_PATCHES</makevar> variable to point to those + tarball to <varname>DISTFILES</varname> and + <varname>MASTER_SITES</varname>. Then, use the + <varname>EXTRA_PATCHES</varname> variable to point to those files and <filename>bsd.port.mk</filename> will automatically apply them for you. In particular, do <emphasis>not</emphasis> copy patch files into the - <makevar>PATCHDIR</makevar> directory—that directory + <varname>PATCHDIR</varname> directory—that directory may not be writable.</para> <note> @@ -2727,11 +2712,11 @@ EXTRACT_ONLY= source.tar.gz</programlisting> latter, take extra care not to overwrite something that already exists in that directory. Also, do not forget to add a command to remove the copied patch in the - <maketarget>pre-clean</maketarget> target.</para> + <buildtarget>pre-clean</buildtarget> target.</para> </note> </sect2> - <sect2 id="porting-master-sites-n"> + <sect2 xml:id="porting-master-sites-n"> <title>Multiple Distribution Files or Patches from Different Sites and Subdirectories (<literal>MASTER_SITES:n</literal>)</title> @@ -2746,8 +2731,8 @@ EXTRACT_ONLY= source.tar.gz</programlisting> mechanism as <literal>MASTER_SITES:n</literal>.</para> <para>A little background first. OpenBSD has a neat feature - inside the <makevar>DISTFILES</makevar> and - <makevar>PATCHFILES</makevar> variables which allows files + inside the <varname>DISTFILES</varname> and + <varname>PATCHFILES</varname> variables which allows files and patches to be postfixed with <literal>:n</literal> identifiers. Here, <literal>n</literal> can be both <literal>[0-9]</literal> and denote a group designation. @@ -2757,26 +2742,26 @@ EXTRACT_ONLY= source.tar.gz</programlisting> <para>In OpenBSD, distribution file <filename>alpha</filename> will be associated with variable - <makevar>MASTER_SITES0</makevar> instead of our common - <makevar>MASTER_SITES</makevar> and + <varname>MASTER_SITES0</varname> instead of our common + <varname>MASTER_SITES</varname> and <filename>beta</filename> with - <makevar>MASTER_SITES1</makevar>.</para> + <varname>MASTER_SITES1</varname>.</para> <para>This is a very interesting feature which can decrease that endless search for the correct download site.</para> - <para>Just picture 2 files in <makevar>DISTFILES</makevar> and - 20 sites in <makevar>MASTER_SITES</makevar>, the sites slow + <para>Just picture 2 files in <varname>DISTFILES</varname> and + 20 sites in <varname>MASTER_SITES</varname>, the sites slow as hell where <filename>beta</filename> is carried by all - sites in <makevar>MASTER_SITES</makevar>, and + sites in <varname>MASTER_SITES</varname>, and <filename>alpha</filename> can only be found in the 20th site. It would be such a waste to check all of them if the maintainer knew this beforehand, would it not? Not a good start for that lovely weekend!</para> <para>Now that you have the idea, just imagine more - <makevar>DISTFILES</makevar> and more - <makevar>MASTER_SITES</makevar>. Surely our + <varname>DISTFILES</varname> and more + <varname>MASTER_SITES</varname>. Surely our <quote>distfiles survey meister</quote> would appreciate the relief to network strain that this would bring.</para> @@ -2807,9 +2792,9 @@ EXTRACT_ONLY= source.tar.gz</programlisting> sites.</para> <para>To support this, each entry in - <makevar>DISTFILES</makevar> may be followed by a colon + <varname>DISTFILES</varname> may be followed by a colon and a <quote>tag name</quote>. Each site listed in - <makevar>MASTER_SITES</makevar> is then followed by a + <varname>MASTER_SITES</varname> is then followed by a colon, and the tag that indicates which distribution files should be downloaded from this site.</para> @@ -2818,11 +2803,9 @@ EXTRACT_ONLY= source.tar.gz</programlisting> and <filename>source2.tar.gz</filename>, which must be downloaded from two different sites. The port's <filename>Makefile</filename> would include lines like - <xref - linkend="ports-master-sites-n-example-simple-use-one-file-per-site"/>.</para> + <xref linkend="ports-master-sites-n-example-simple-use-one-file-per-site"/>.</para> - <example - id="ports-master-sites-n-example-simple-use-one-file-per-site"> + <example xml:id="ports-master-sites-n-example-simple-use-one-file-per-site"> <title>Simplified Use of <literal>MASTER_SITES:n</literal> with One File Per Site</title> @@ -2836,13 +2819,11 @@ DISTFILES= source1.tar.gz:source1 \ Continuing the previous example, suppose that there was a third distfile, <filename>source3.tar.gz</filename>, that should be downloaded from - <hostid>ftp.example2.com</hostid>. The + <systemitem>ftp.example2.com</systemitem>. The <filename>Makefile</filename> would then be written like - <xref - linkend="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"/>.</para> + <xref linkend="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"/>.</para> - <example - id="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"> + <example xml:id="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"> <title>Simplified Use of <literal>MASTER_SITES:n</literal> with More Than One File Per Site</title> @@ -2866,7 +2847,7 @@ DISTFILES= source1.tar.gz:source1 \ <orderedlist> <listitem> <para>Elements can be postfixed with - <literal>:<replaceable>n</replaceable></literal> where + <literal>:n</literal> where <replaceable>n</replaceable> is <literal>[^:,]+</literal>, i.e., <replaceable>n</replaceable> could conceptually be any @@ -2882,11 +2863,9 @@ DISTFILES= source1.tar.gz:source1 \ postfixing purposes since they yield special meaning: <literal>default</literal>, <literal>all</literal> and <literal>ALL</literal> (they are used internally in - item <xref - linkend="porting-master-sites-n-what-changes-in-port-targets"/>). + item <xref linkend="porting-master-sites-n-what-changes-in-port-targets"/>). Furthermore, <literal>DEFAULT</literal> is a special - purpose word (check item <xref - linkend="porting-master-sites-n-DEFAULT-group"/>).</para> + purpose word (check item <xref linkend="porting-master-sites-n-DEFAULT-group"/>).</para> </listitem> <listitem> @@ -2896,15 +2875,14 @@ DISTFILES= source1.tar.gz:source1 \ <literal>m</literal> and so forth.</para> </listitem> - <listitem id="porting-master-sites-n-DEFAULT-group"> + <listitem xml:id="porting-master-sites-n-DEFAULT-group"> <para>Elements without a postfix are groupless, i.e., they all belong to the special group <literal>DEFAULT</literal>. If you postfix any elements with <literal>DEFAULT</literal>, you are just being redundant unless you want to have an element belonging to both <literal>DEFAULT</literal> and other - groups at the same time (check item <xref - linkend="porting-master-sites-n-comma-operator"/>).</para> + groups at the same time (check item <xref linkend="porting-master-sites-n-comma-operator"/>).</para> <para>The following examples are equivalent but the first one is preferred:</para> @@ -2922,7 +2900,7 @@ DISTFILES= source1.tar.gz:source1 \ will be simply that, repeated elements.</para> </listitem> - <listitem id="porting-master-sites-n-comma-operator"> + <listitem xml:id="porting-master-sites-n-comma-operator"> <para>When you want an element to belong to several groups at the same time, you can use the comma operator (<literal>,</literal>).</para> @@ -2948,32 +2926,32 @@ DISTFILES= source1.tar.gz:source1 \ <listitem> <para>All sites within a given group are sorted - according to <makevar>MASTER_SORT_AWK</makevar>. All - groups within <makevar>MASTER_SITES</makevar> and - <makevar>PATCH_SITES</makevar> are sorted as + according to <varname>MASTER_SORT_AWK</varname>. All + groups within <varname>MASTER_SITES</varname> and + <varname>PATCH_SITES</varname> are sorted as well.</para> </listitem> - <listitem id="porting-master-sites-n-group-semantics"> + <listitem xml:id="porting-master-sites-n-group-semantics"> <para>Group semantics can be used in any of the - following variables <makevar>MASTER_SITES</makevar>, - <makevar>PATCH_SITES</makevar>, - <makevar>MASTER_SITE_SUBDIR</makevar>, - <makevar>PATCH_SITE_SUBDIR</makevar>, - <makevar>DISTFILES</makevar>, and - <makevar>PATCHFILES</makevar> according to the + following variables <varname>MASTER_SITES</varname>, + <varname>PATCH_SITES</varname>, + <varname>MASTER_SITE_SUBDIR</varname>, + <varname>PATCH_SITE_SUBDIR</varname>, + <varname>DISTFILES</varname>, and + <varname>PATCHFILES</varname> according to the following syntax:</para> <orderedlist> <listitem> - <para>All <makevar>MASTER_SITES</makevar>, - <makevar>PATCH_SITES</makevar>, - <makevar>MASTER_SITE_SUBDIR</makevar> and - <makevar>PATCH_SITE_SUBDIR</makevar> elements must + <para>All <varname>MASTER_SITES</varname>, + <varname>PATCH_SITES</varname>, + <varname>MASTER_SITE_SUBDIR</varname> and + <varname>PATCH_SITE_SUBDIR</varname> elements must be terminated with the forward slash <literal>/</literal> character. If any elements belong to any groups, the group postfix - <literal>:<replaceable>n</replaceable></literal> + <literal>:n</literal> must come right after the terminator <literal>/</literal>. The <literal>MASTER_SITES:n</literal> mechanism relies @@ -2985,24 +2963,21 @@ DISTFILES= source1.tar.gz:source1 \ <literal>n</literal>. For compatibility purposes, since the <literal>/</literal> terminator was not required before in both - <makevar>MASTER_SITE_SUBDIR</makevar> and - <makevar>PATCH_SITE_SUBDIR</makevar> elements, if + <varname>MASTER_SITE_SUBDIR</varname> and + <varname>PATCH_SITE_SUBDIR</varname> elements, if the postfix immediate preceding character is not a <literal>/</literal> then <literal>:n</literal> will be considered a valid part of the element instead of a group postfix even if an element is postfixed with <literal>:n</literal>. See both - <xref - linkend="ports-master-sites-n-example-detailed-use-master-site-subdir"/> - and <xref - linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para> + <xref linkend="ports-master-sites-n-example-detailed-use-master-site-subdir"/> + and <xref linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para> - <example - id="ports-master-sites-n-example-detailed-use-master-site-subdir"> + <example xml:id="ports-master-sites-n-example-detailed-use-master-site-subdir"> <title>Detailed Use of <literal>MASTER_SITES:n</literal> in - <makevar>MASTER_SITE_SUBDIR</makevar></title> + <varname>MASTER_SITE_SUBDIR</varname></title> <programlisting>MASTER_SITE_SUBDIR= old:n new/:NEW</programlisting> @@ -3020,8 +2995,7 @@ DISTFILES= source1.tar.gz:source1 \ </itemizedlist> </example> - <example - id="ports-master-sites-n-example-detailed-use-complete-example-master-sites"> + <example xml:id="ports-master-sites-n-example-detailed-use-complete-example-master-sites"> <title>Detailed Use of <literal>MASTER_SITES:n</literal> with Comma Operator, Multiple Files, Multiple Sites and @@ -3052,7 +3026,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ <itemizedlist> <listitem> - <para><makevar>MASTER_SITE_OVERRIDE</makevar></para> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> </listitem> <listitem> @@ -3076,7 +3050,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ </listitem> <listitem> - <para><makevar>MASTER_SITE_BACKUP</makevar></para> + <para><varname>MASTER_SITE_BACKUP</varname></para> </listitem> </itemizedlist> </listitem> @@ -3089,7 +3063,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ <itemizedlist> <listitem> - <para><makevar>MASTER_SITE_OVERRIDE</makevar></para> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> </listitem> <listitem> @@ -3113,7 +3087,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ </listitem> <listitem> - <para><makevar>MASTER_SITE_BACKUP</makevar></para> + <para><varname>MASTER_SITE_BACKUP</varname></para> </listitem> </itemizedlist> </listitem> @@ -3124,7 +3098,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ <itemizedlist> <listitem> - <para><makevar>MASTER_SITE_OVERRIDE</makevar></para> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> </listitem> <listitem> @@ -3132,7 +3106,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ </listitem> <listitem> - <para><makevar>MASTER_SITE_BACKUP</makevar></para> + <para><varname>MASTER_SITE_BACKUP</varname></para> </listitem> </itemizedlist> </listitem> @@ -3143,7 +3117,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ <itemizedlist> <listitem> - <para><makevar>MASTER_SITE_OVERRIDE</makevar></para> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> </listitem> <listitem> @@ -3167,7 +3141,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ </listitem> <listitem> - <para><makevar>MASTER_SITE_BACKUP</makevar></para> + <para><varname>MASTER_SITE_BACKUP</varname></para> </listitem> </itemizedlist> </listitem> @@ -3178,11 +3152,11 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ <itemizedlist> <listitem> - <para><makevar>MASTER_SITE_OVERRIDE</makevar></para> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> </listitem> <listitem> - <para><makevar>MASTER_SITE_BACKUP</makevar></para> + <para><varname>MASTER_SITE_BACKUP</varname></para> </listitem> </itemizedlist> </listitem> @@ -3193,7 +3167,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ <itemizedlist> <listitem> - <para><makevar>MASTER_SITE_OVERRIDE</makevar></para> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> </listitem> <listitem> @@ -3201,7 +3175,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ </listitem> <listitem> - <para><makevar>MASTER_SITE_BACKUP</makevar></para> + <para><varname>MASTER_SITE_BACKUP</varname></para> </listitem> </itemizedlist> </listitem> @@ -3214,16 +3188,14 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ <listitem> <para>How do I group one of the special variables from <filename>bsd.sites.mk</filename>, e.g., - <makevar>MASTER_SITE_SOURCEFORGE</makevar>?</para> + <varname>MASTER_SITE_SOURCEFORGE</varname>?</para> - <para>See <xref - linkend="ports-master-sites-n-example-detailed-use-master-site-sourceforge"/>.</para> + <para>See <xref linkend="ports-master-sites-n-example-detailed-use-master-site-sourceforge"/>.</para> - <example - id="ports-master-sites-n-example-detailed-use-master-site-sourceforge"> + <example xml:id="ports-master-sites-n-example-detailed-use-master-site-sourceforge"> <title>Detailed Use of <literal>MASTER_SITES:n</literal> with - <makevar>MASTER_SITE_SOURCEFORGE</makevar></title> + <varname>MASTER_SITE_SOURCEFORGE</varname></title> <programlisting>MASTER_SITES= http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/} DISTFILES= something.tar.gz:sourceforge</programlisting> @@ -3231,24 +3203,22 @@ DISTFILES= something.tar.gz:sourceforge</programlisting> <para><filename>something.tar.gz</filename> will be fetched from all sites within - <makevar>MASTER_SITE_SOURCEFORGE</makevar>.</para> + <varname>MASTER_SITE_SOURCEFORGE</varname>.</para> </listitem> <listitem> - <para>How do I use this with <makevar>PATCH*</makevar> + <para>How do I use this with <varname>PATCH*</varname> variables?</para> <para>All examples were done with - <makevar>MASTER*</makevar> variables but they work - exactly the same for <makevar>PATCH*</makevar> ones as - can be seen in <xref - linkend="ports-master-sites-n-example-detailed-use-patch-sites"/>.</para> + <varname>MASTER*</varname> variables but they work + exactly the same for <varname>PATCH*</varname> ones as + can be seen in <xref linkend="ports-master-sites-n-example-detailed-use-patch-sites"/>.</para> - <example - id="ports-master-sites-n-example-detailed-use-patch-sites"> + <example xml:id="ports-master-sites-n-example-detailed-use-patch-sites"> <title>Simplified Use of <literal>MASTER_SITES:n</literal> with - <makevar>PATCH_SITES</makevar></title> + <varname>PATCH_SITES</varname></title> <programlisting>PATCH_SITES= http://site1/ http://site2/:test PATCHFILES= patch1:test</programlisting> @@ -3265,66 +3235,62 @@ PATCHFILES= patch1:test</programlisting> <para>All current ports remain the same. The <literal>MASTER_SITES:n</literal> feature code is only activated if there are elements postfixed with - <literal>:<replaceable>n</replaceable></literal> like + <literal>:n</literal> like elements according to the aforementioned syntax rules, - especially as shown in item <xref - linkend="porting-master-sites-n-group-semantics"/>.</para> + especially as shown in item <xref linkend="porting-master-sites-n-group-semantics"/>.</para> </listitem> - <listitem - id="porting-master-sites-n-what-changes-in-port-targets"> + <listitem xml:id="porting-master-sites-n-what-changes-in-port-targets"> <para>The port targets remain the same: - <maketarget>checksum</maketarget>, - <maketarget>makesum</maketarget>, - <maketarget>patch</maketarget>, - <maketarget>configure</maketarget>, - <maketarget>build</maketarget>, etc. With the obvious - exceptions of <maketarget>do-fetch</maketarget>, - <maketarget>fetch-list</maketarget>, - <maketarget>master-sites</maketarget> and - <maketarget>patch-sites</maketarget>.</para> + <buildtarget>checksum</buildtarget>, + <buildtarget>makesum</buildtarget>, + <buildtarget>patch</buildtarget>, + <buildtarget>configure</buildtarget>, + <buildtarget>build</buildtarget>, etc. With the obvious + exceptions of <buildtarget>do-fetch</buildtarget>, + <buildtarget>fetch-list</buildtarget>, + <buildtarget>master-sites</buildtarget> and + <buildtarget>patch-sites</buildtarget>.</para> <itemizedlist> <listitem> - <para><maketarget>do-fetch</maketarget>: deploys the + <para><buildtarget>do-fetch</buildtarget>: deploys the new grouping postfixed - <makevar>DISTFILES</makevar> and - <makevar>PATCHFILES</makevar> with their matching + <varname>DISTFILES</varname> and + <varname>PATCHFILES</varname> with their matching group elements within both - <makevar>MASTER_SITES</makevar> and - <makevar>PATCH_SITES</makevar> which use matching + <varname>MASTER_SITES</varname> and + <varname>PATCH_SITES</varname> which use matching group elements within both - <makevar>MASTER_SITE_SUBDIR</makevar> and - <makevar>PATCH_SITE_SUBDIR</makevar>. Check <xref - linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para> + <varname>MASTER_SITE_SUBDIR</varname> and + <varname>PATCH_SITE_SUBDIR</varname>. Check <xref linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para> </listitem> <listitem> - <para><maketarget>fetch-list</maketarget>: works - like old <maketarget>fetch-list</maketarget> with + <para><buildtarget>fetch-list</buildtarget>: works + like old <buildtarget>fetch-list</buildtarget> with the exception that it groups just like - <maketarget>do-fetch</maketarget>.</para> + <buildtarget>do-fetch</buildtarget>.</para> </listitem> <listitem> - <para><maketarget>master-sites</maketarget> and - <maketarget>patch-sites</maketarget>: + <para><buildtarget>master-sites</buildtarget> and + <buildtarget>patch-sites</buildtarget>: (incompatible with older versions) only return the elements of group <literal>DEFAULT</literal>; in fact, they execute targets - <maketarget>master-sites-default</maketarget> and - <maketarget>patch-sites-default</maketarget> + <buildtarget>master-sites-default</buildtarget> and + <buildtarget>patch-sites-default</buildtarget> respectively.</para> <para>Furthermore, using target either - <maketarget>master-sites-all</maketarget> or - <maketarget>patch-sites-all</maketarget> is + <buildtarget>master-sites-all</buildtarget> or + <buildtarget>patch-sites-all</buildtarget> is preferred to directly checking either - <maketarget>MASTER_SITES</maketarget> or - <maketarget>PATCH_SITES</maketarget>. Also, + <buildtarget>MASTER_SITES</buildtarget> or + <buildtarget>PATCH_SITES</buildtarget>. Also, directly checking is not guaranteed to work in any - future versions. Check item <xref - linkend="porting-master-sites-n-new-port-targets-master-sites-all"/> + future versions. Check item <xref linkend="porting-master-sites-n-new-port-targets-master-sites-all"/> for more information on these new port targets.</para> </listitem> @@ -3337,41 +3303,40 @@ PATCHFILES= patch1:test</programlisting> <orderedlist> <listitem> <para>There are - <maketarget>master-sites-<replaceable>n</replaceable></maketarget> + <buildtarget>master-sites-<replaceable>n</replaceable></buildtarget> and - <maketarget>patch-sites-<replaceable>n</replaceable></maketarget> + <buildtarget>patch-sites-<replaceable>n</replaceable></buildtarget> targets which will list the elements of the respective group <replaceable>n</replaceable> - within <makevar>MASTER_SITES</makevar> and - <makevar>PATCH_SITES</makevar> respectively. For + within <varname>MASTER_SITES</varname> and + <varname>PATCH_SITES</varname> respectively. For instance, both - <maketarget>master-sites-DEFAULT</maketarget> and - <maketarget>patch-sites-DEFAULT</maketarget> will + <buildtarget>master-sites-DEFAULT</buildtarget> and + <buildtarget>patch-sites-DEFAULT</buildtarget> will return the elements of group <literal>DEFAULT</literal>, - <maketarget>master-sites-test</maketarget> and - <maketarget>patch-sites-test</maketarget> of group + <buildtarget>master-sites-test</buildtarget> and + <buildtarget>patch-sites-test</buildtarget> of group <literal>test</literal>, and thereon.</para> </listitem> - <listitem - id="porting-master-sites-n-new-port-targets-master-sites-all"> + <listitem xml:id="porting-master-sites-n-new-port-targets-master-sites-all"> <para>There are new targets - <maketarget>master-sites-all</maketarget> and - <maketarget>patch-sites-all</maketarget> which do + <buildtarget>master-sites-all</buildtarget> and + <buildtarget>patch-sites-all</buildtarget> which do the work of the old - <maketarget>master-sites</maketarget> and - <maketarget>patch-sites</maketarget> ones. They + <buildtarget>master-sites</buildtarget> and + <buildtarget>patch-sites</buildtarget> ones. They return the elements of all groups as if they all belonged to the same group with the caveat that it lists as many - <makevar>MASTER_SITE_BACKUP</makevar> and - <makevar>MASTER_SITE_OVERRIDE</makevar> as there + <varname>MASTER_SITE_BACKUP</varname> and + <varname>MASTER_SITE_OVERRIDE</varname> as there are groups defined within either - <makevar>DISTFILES</makevar> or - <makevar>PATCHFILES</makevar>; respectively for - <maketarget>master-sites-all</maketarget> and - <maketarget>patch-sites-all</maketarget>.</para> + <varname>DISTFILES</varname> or + <varname>PATCHFILES</varname>; respectively for + <buildtarget>master-sites-all</buildtarget> and + <buildtarget>patch-sites-all</buildtarget>.</para> </listitem> </orderedlist> </listitem> @@ -3380,53 +3345,52 @@ PATCHFILES= patch1:test</programlisting> </sect2> <sect2> - <title><makevar>DIST_SUBDIR</makevar></title> + <title><varname>DIST_SUBDIR</varname></title> <para>Do not let your port clutter <filename>/usr/ports/distfiles</filename>. If your port requires a lot of files to be fetched, or contains a file that has a name that might conflict with other ports (e.g., <filename>Makefile</filename>), set - <makevar>DIST_SUBDIR</makevar> to the name of the port + <varname>DIST_SUBDIR</varname> to the name of the port (<literal>${PORTNAME}</literal> or <literal>${PKGNAMEPREFIX}${PORTNAME}</literal> should work - fine). This will change <makevar>DISTDIR</makevar> from the + fine). This will change <varname>DISTDIR</varname> from the default <filename>/usr/ports/distfiles</filename> to - <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>, + <filename>/usr/ports/distfiles/DIST_SUBDIR</filename>, and in effect puts everything that is required for your port into that subdirectory.</para> <para>It will also look at the subdirectory with the same name on the backup master site at <filename>ftp.FreeBSD.org</filename>. (Setting - <makevar>DISTDIR</makevar> explicitly in your - <makevar>Makefile</makevar> will not accomplish this, so - please use <makevar>DIST_SUBDIR</makevar>.)</para> + <varname>DISTDIR</varname> explicitly in your + <varname>Makefile</varname> will not accomplish this, so + please use <varname>DIST_SUBDIR</varname>.)</para> <note> <para>This does not affect the - <makevar>MASTER_SITES</makevar> you define in your + <varname>MASTER_SITES</varname> you define in your <filename>Makefile</filename>.</para> </note> </sect2> <sect2> - <title><makevar>ALWAYS_KEEP_DISTFILES</makevar></title> + <title><varname>ALWAYS_KEEP_DISTFILES</varname></title> <para>If your port uses binary distfiles and has a license that requires that the source code is provided with packages distributed in binary form, e.g., GPL, - <makevar>ALWAYS_KEEP_DISTFILES</makevar> will instruct the + <varname>ALWAYS_KEEP_DISTFILES</varname> will instruct the &os; build cluster to keep a copy of the files specified in - <makevar>DISTFILES</makevar>. Users of these ports will + <varname>DISTFILES</varname>. Users of these ports will generally not need these files, so it is a good idea to only - add the source distfiles to <makevar>DISTFILES</makevar> - when <makevar>PACKAGE_BUILDING</makevar> is defined.</para> + add the source distfiles to <varname>DISTFILES</varname> + when <varname>PACKAGE_BUILDING</varname> is defined.</para> - <example - id="ports-master-sites-n-example-always-keep-distfiles"> + <example xml:id="ports-master-sites-n-example-always-keep-distfiles"> <title>Use of - <makevar>ALWAYS_KEEP_DISTFILES</makevar></title> + <varname>ALWAYS_KEEP_DISTFILES</varname></title> <programlisting>.if defined(PACKAGE_BUILDING) DISTFILES+= <replaceable>foo.tar.gz</replaceable> @@ -3434,23 +3398,23 @@ ALWAYS_KEEP_DISTFILES= yes .endif</programlisting> </example> - <para>When adding extra files to <makevar>DISTFILES</makevar>, + <para>When adding extra files to <varname>DISTFILES</varname>, make sure you also add them to <filename>distinfo</filename>. Also, the additional files - will normally be extracted into <makevar>WRKDIR</makevar> as + will normally be extracted into <varname>WRKDIR</varname> as well, which for some ports may lead to undesirable side effects and require special handling.</para> </sect2> </sect1> - <sect1 id="makefile-maintainer"> - <title><makevar>MAINTAINER</makevar></title> + <sect1 xml:id="makefile-maintainer"> + <title><varname>MAINTAINER</varname></title> <para>Set your mail-address here. Please. <!-- smiley --><emphasis>:-)</emphasis></para> <para>Note that only a single address without the comment part - is allowed as a <makevar>MAINTAINER</makevar> value. The + is allowed as a <varname>MAINTAINER</varname> value. The format used should be <literal>user@hostname.domain</literal>. Please do not include any descriptive text such as your real name in this entry—that merely confuses @@ -3459,9 +3423,8 @@ ALWAYS_KEEP_DISTFILES= yes <para>The maintainer is responsible for keeping the port up to date, and ensuring the port works correctly. For a detailed description of the responsibilities of a port - maintainer, refer to the <ulink - url="&url.articles.contributing-ports;/maintain-port.html">The - challenge for port maintainers</ulink> section.</para> + maintainer, refer to the <link xlink:href="&url.articles.contributing-ports;/maintain-port.html">The + challenge for port maintainers</link> section.</para> <para>Changes to the port will be sent to the maintainer of a port for review and approval before being committed. If the @@ -3489,8 +3452,8 @@ ALWAYS_KEEP_DISTFILES= yes maintainership for security reasons.</para> </sect1> - <sect1 id="makefile-comment"> - <title><makevar>COMMENT</makevar></title> + <sect1 xml:id="makefile-comment"> + <title><varname>COMMENT</varname></title> <para>This is a one-line description of the port. Please respect the following rules:</para> @@ -3542,20 +3505,20 @@ ALWAYS_KEEP_DISTFILES= yes <filename>Makefile</filename>.</para> </sect1> - <sect1 id="makefile-portscout"> - <title><makevar>PORTSCOUT</makevar></title> + <sect1 xml:id="makefile-portscout"> + <title><varname>PORTSCOUT</varname></title> <para><application>Portscout</application> is an automated distfile check utility for the &os; Ports Collection, described in detail in <xref linkend="distfile-survey"/>.</para> - <para>The <makevar>PORTSCOUT</makevar> variable defines + <para>The <varname>PORTSCOUT</varname> variable defines special conditions within which the <application>Portscout</application> distfile scanner should be restricted.</para> - <para>Situations where the <makevar>PORTSCOUT</makevar> + <para>Situations where the <varname>PORTSCOUT</varname> variable should be set include:</para> <itemizedlist> @@ -3584,7 +3547,7 @@ ALWAYS_KEEP_DISTFILES= yes <para>When URLs listing the available versions differ from the download URLs. For example, to limit distfile version checks to the download page for the - <filename role="package">databases/pgtune</filename> + <package>databases/pgtune</package> port, add:</para> <programlisting>PORTSCOUT= site:http://pgfoundry.org/frs/?group_id=1000416</programlisting> @@ -3592,7 +3555,7 @@ ALWAYS_KEEP_DISTFILES= yes </itemizedlist> </sect1> - <sect1 id="makefile-depend"> + <sect1 xml:id="makefile-depend"> <title>Dependencies</title> <para>Many ports depend on other ports. This is a very @@ -3606,7 +3569,7 @@ ALWAYS_KEEP_DISTFILES= yes behavior of dependencies.</para> <sect2> - <title><makevar>LIB_DEPENDS</makevar></title> + <title><varname>LIB_DEPENDS</varname></title> <para>This variable specifies the shared libraries this port depends on. It is a list of @@ -3624,19 +3587,19 @@ ALWAYS_KEEP_DISTFILES= yes it is not found.</para> <para>The dependency is checked twice, once from within the - <maketarget>extract</maketarget> target and then from within - the <maketarget>install</maketarget> target. Also, the name + <buildtarget>extract</buildtarget> target and then from within + the <buildtarget>install</buildtarget> target. Also, the name of the dependency is put into the package so that &man.pkg.add.1; will automatically install it if it is not on the user's system.</para> </sect2> <sect2> - <title><makevar>RUN_DEPENDS</makevar></title> + <title><varname>RUN_DEPENDS</varname></title> <para>This variable specifies executables or files this port depends on during run-time. It is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> tuples where <replaceable>path</replaceable> is the name of the executable or file, <replaceable>dir</replaceable> is the directory in which to find it in case it is not @@ -3679,16 +3642,16 @@ ALWAYS_KEEP_DISTFILES= yes </note> <para>The dependency is checked from within the - <maketarget>install</maketarget> target. Also, the name of + <buildtarget>install</buildtarget> target. Also, the name of the dependency is put into the package so that &man.pkg.add.1; will automatically install it if it is not on the user's system. The <replaceable>target</replaceable> part can be omitted if it is the same as - <makevar>DEPENDS_TARGET</makevar>.</para> + <varname>DEPENDS_TARGET</varname>.</para> <para>A quite common situation is when - <makevar>RUN_DEPENDS</makevar> is literally the same as - <makevar>BUILD_DEPENDS</makevar>, especially if ported + <varname>RUN_DEPENDS</varname> is literally the same as + <varname>BUILD_DEPENDS</varname>, especially if ported software is written in a scripted language or if it requires the same build and run-time environment. In this case, it is both tempting and intuitive to directly @@ -3698,18 +3661,18 @@ ALWAYS_KEEP_DISTFILES= yes <para>However, such assignment can pollute run-time dependencies with entries not defined in the port's original - <makevar>BUILD_DEPENDS</makevar>. This happens because of + <varname>BUILD_DEPENDS</varname>. This happens because of &man.make.1;'s lazy evaluation of variable assignment. Consider a <filename>Makefile</filename> with - <makevar>USE_<replaceable>*</replaceable></makevar> + <varname>USE_<replaceable>*</replaceable></varname> variables, which are processed by <filename>ports/Mk/bsd.*.mk</filename> to augment initial build dependencies. For example, <literal>USES= gmake</literal> adds - <filename role="package">devel/gmake</filename> to - <makevar>BUILD_DEPENDS</makevar>. To prevent such + <package>devel/gmake</package> to + <varname>BUILD_DEPENDS</varname>. To prevent such additional dependencies from polluting - <makevar>RUN_DEPENDS</makevar>, take care to assign with + <varname>RUN_DEPENDS</varname>, take care to assign with expansion, i.e., expand the value before assigning it to the variable:</para> @@ -3717,12 +3680,12 @@ ALWAYS_KEEP_DISTFILES= yes </sect2> <sect2> - <title><makevar>BUILD_DEPENDS</makevar></title> + <title><varname>BUILD_DEPENDS</varname></title> <para>This variable specifies executables or files this port - requires to build. Like <makevar>RUN_DEPENDS</makevar>, it + requires to build. Like <varname>RUN_DEPENDS</varname>, it is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> tuples. For example,</para> <programlisting>BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting> @@ -3736,18 +3699,18 @@ ALWAYS_KEEP_DISTFILES= yes <note> <para><quote>build</quote> here means everything from extraction to compilation. The dependency is checked from - within the <maketarget>extract</maketarget> target. The + within the <buildtarget>extract</buildtarget> target. The <replaceable>target</replaceable> part can be omitted if - it is the same as <makevar>DEPENDS_TARGET</makevar></para> + it is the same as <varname>DEPENDS_TARGET</varname></para> </note> </sect2> <sect2> - <title><makevar>FETCH_DEPENDS</makevar></title> + <title><varname>FETCH_DEPENDS</varname></title> <para>This variable specifies executables or files this port requires to fetch. Like the previous two, it is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> tuples. For example,</para> <programlisting>FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting> @@ -3758,17 +3721,17 @@ ALWAYS_KEEP_DISTFILES= yes tree to build and install it if it is not found.</para> <para>The dependency is checked from within the - <maketarget>fetch</maketarget> target. The + <buildtarget>fetch</buildtarget> target. The <replaceable>target</replaceable> part can be omitted if it - is the same as <makevar>DEPENDS_TARGET</makevar>.</para> + is the same as <varname>DEPENDS_TARGET</varname>.</para> </sect2> <sect2> - <title><makevar>EXTRACT_DEPENDS</makevar></title> + <title><varname>EXTRACT_DEPENDS</varname></title> <para>This variable specifies executables or files this port requires for extraction. Like the previous, it is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> tuples. For example,</para> <programlisting>EXTRACT_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting> @@ -3780,25 +3743,25 @@ ALWAYS_KEEP_DISTFILES= yes found.</para> <para>The dependency is checked from within the - <maketarget>extract</maketarget> target. The + <buildtarget>extract</buildtarget> target. The <replaceable>target</replaceable> part can be omitted if it - is the same as <makevar>DEPENDS_TARGET</makevar>.</para> + is the same as <varname>DEPENDS_TARGET</varname>.</para> <note> <para>Use this variable only if the extraction does not already work (the default assumes <command>gzip</command>) and cannot be made to work using - <makevar>USE_ZIP</makevar> or <makevar>USE_BZIP2</makevar> + <varname>USE_ZIP</varname> or <varname>USE_BZIP2</varname> described in <xref linkend="use-vars"/>.</para> </note> </sect2> <sect2> - <title><makevar>PATCH_DEPENDS</makevar></title> + <title><varname>PATCH_DEPENDS</varname></title> <para>This variable specifies executables or files this port requires to patch. Like the previous, it is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> tuples. For example,</para> <programlisting>PATCH_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract</programlisting> @@ -3807,13 +3770,13 @@ ALWAYS_KEEP_DISTFILES= yes subdirectory of your ports tree to extract it.</para> <para>The dependency is checked from within the - <maketarget>patch</maketarget> target. The + <buildtarget>patch</buildtarget> target. The <replaceable>target</replaceable> part can be omitted if it - is the same as <makevar>DEPENDS_TARGET</makevar>.</para> + is the same as <varname>DEPENDS_TARGET</varname>.</para> </sect2> - <sect2 id="uses"> - <title><makevar>USES</makevar></title> + <sect2 xml:id="uses"> + <title><varname>USES</varname></title> <para>There several parameters exist for defining different kind of features and dependencies that the port in question @@ -3822,33 +3785,32 @@ ALWAYS_KEEP_DISTFILES= yes <programlisting>USES= feature[:arguments]</programlisting> - <para>For the complete list of such values, please see <xref - linkend="uses-values"/>.</para> + <para>For the complete list of such values, please see <xref linkend="uses-values"/>.</para> <warning> - <para><makevar>USES</makevar> cannot be assigned after + <para><varname>USES</varname> cannot be assigned after inclusion of <filename>bsd.port.pre.mk</filename>.</para> </warning> </sect2> - <sect2 id="use-vars"> - <title><makevar>USE_<replaceable>*</replaceable></makevar></title> + <sect2 xml:id="use-vars"> + <title><varname>USE_<replaceable>*</replaceable></varname></title> <para>Several variables exist to define common dependencies shared by many ports. Their use is optional, but helps to reduce the verbosity of the port <filename>Makefile</filename>s. Each of them is styled as - <makevar>USE_<replaceable>*</replaceable></makevar>. + <varname>USE_<replaceable>*</replaceable></varname>. These variables may be used only in the port <filename>Makefile</filename>s and <filename>ports/Mk/bsd.*.mk</filename>. They are not meant for user-settable options — use - <makevar>PORT_OPTIONS</makevar> for that purpose.</para> + <varname>PORT_OPTIONS</varname> for that purpose.</para> <note> <para>It is <emphasis>always</emphasis> incorrect to set any - <makevar>USE_<replaceable>*</replaceable></makevar> in + <varname>USE_<replaceable>*</replaceable></varname> in <filename>/etc/make.conf</filename>. For instance, setting</para> @@ -3861,7 +3823,7 @@ ALWAYS_KEEP_DISTFILES= yes <table frame="none"> <title>The - <makevar>USE_<replaceable>*</replaceable></makevar> + <varname>USE_<replaceable>*</replaceable></varname> Variables</title> <tgroup cols="2"> @@ -3874,19 +3836,19 @@ ALWAYS_KEEP_DISTFILES= yes <tbody> <row> - <entry><makevar>USE_BZIP2</makevar></entry> + <entry><varname>USE_BZIP2</varname></entry> <entry>The port's tarballs are compressed with <command>bzip2</command>.</entry> </row> <row> - <entry><makevar>USE_ZIP</makevar></entry> + <entry><varname>USE_ZIP</varname></entry> <entry>The port's tarballs are compressed with <command>zip</command>.</entry> </row> <row> - <entry><makevar>USE_GCC</makevar></entry> + <entry><varname>USE_GCC</varname></entry> <entry>The port requires GCC (<command>gcc</command> or <command>g++</command>) to build. Some ports need any GCC version, some require modern, recent @@ -3903,8 +3865,8 @@ ALWAYS_KEEP_DISTFILES= yes <literal>4.6+</literal>. The GCC from the base system is used when it satisfies the requested version, otherwise an appropriate compiler in built - from the port, and the <makevar>CC</makevar> and - <makevar>CXX</makevar> variables are adjusted + from the port, and the <varname>CC</varname> and + <varname>CXX</varname> variables are adjusted accordingly.</entry> </row> </tbody> @@ -3941,11 +3903,11 @@ ALWAYS_KEEP_DISTFILES= yes <title>Minimal Version of a Dependency</title> <para>A minimal version of a dependency can be specified in - any <makevar>*_DEPENDS</makevar> variable except - <makevar>LIB_DEPENDS</makevar> using the following + any <varname>*_DEPENDS</varname> variable except + <varname>LIB_DEPENDS</varname> using the following syntax:</para> - <programlisting>p5-Spiffy>=0.26:${PORTSDIR}/devel/p5-Spiffy</programlisting> + <programlisting>p5-Spiffy>=0.26:${PORTSDIR}/devel/p5-Spiffy</programlisting> <para>The first field contains a dependent package name, which must match the entry in the package database, a comparison @@ -3958,26 +3920,26 @@ ALWAYS_KEEP_DISTFILES= yes <para>As mentioned above, the default target to call when a dependency is required is - <maketarget>DEPENDS_TARGET</maketarget>. It defaults to + <buildtarget>DEPENDS_TARGET</buildtarget>. It defaults to <literal>install</literal>. This is a user variable; it is never defined in a port's <filename>Makefile</filename>. If your port needs a special way to handle a dependency, use the <literal>:target</literal> part of the - <makevar>*_DEPENDS</makevar> variables instead of redefining - <makevar>DEPENDS_TARGET</makevar>.</para> + <varname>*_DEPENDS</varname> variables instead of redefining + <varname>DEPENDS_TARGET</varname>.</para> <para>When you type <command>make clean</command>, its dependencies are automatically cleaned too. If you do not wish this to happen, define the variable - <makevar>NOCLEANDEPENDS</makevar> in your environment. This + <varname>NOCLEANDEPENDS</varname> in your environment. This may be particularly desirable if the port has something that takes a long time to rebuild in its dependency list, such as KDE, GNOME or Mozilla.</para> <para>To depend on another port unconditionally, use the - variable <makevar>${NONEXISTENT}</makevar> as the first - field of <makevar>BUILD_DEPENDS</makevar> or - <makevar>RUN_DEPENDS</makevar>. Use this only when you need + variable <varname>${NONEXISTENT}</varname> as the first + field of <varname>BUILD_DEPENDS</varname> or + <varname>RUN_DEPENDS</varname>. Use this only when you need to get the source of the other port. You can often save compilation time by specifying the target too. For instance</para> @@ -4012,8 +3974,7 @@ ALWAYS_KEEP_DISTFILES= yes <title>Problems Caused by Automatic Dependencies</title> <para>Dependencies must be declared either explicitly or by - using the <link - linkend="makefile-options">OPTIONS framework</link>. + using the <link linkend="makefile-options">OPTIONS framework</link>. Using other methods like automatic detection complicates indexing, which causes problems for port and package management.</para> @@ -4059,45 +4020,45 @@ LIB_DEPENDS= bar:${PORTSDIR}/foo/bar packages.</para> </sect2> - <sect2 id="use-want"> - <title><makevar>USE_</makevar> and - <makevar>WANT_</makevar></title> + <sect2 xml:id="use-want"> + <title><varname>USE_</varname> and + <varname>WANT_</varname></title> - <para><makevar>USE_</makevar> variables are set by the port + <para><varname>USE_</varname> variables are set by the port maintainer to define software on which this port depends. A port that needs Firefox would set</para> <programlisting>USE_FIREFOX= yes</programlisting> - <para>Some <makevar>USE_</makevar> variables can accept + <para>Some <varname>USE_</varname> variables can accept version numbers or other parameters. For example, a port that requires Apache 2.2 would set</para> <programlisting>USE_APACHE= 22</programlisting> <para>For more control over dependencies in some cases, - <makevar>WANT_</makevar> variables are available to more + <varname>WANT_</varname> variables are available to more precisely specify what is needed. For example, consider the - <filename role="package">mail/squirrelmail</filename> port. + <package>mail/squirrelmail</package> port. This port needs some PHP modules, which are listed in the - <makevar>USE_PHP</makevar> variable:</para> + <varname>USE_PHP</varname> variable:</para> <programlisting>USE_PHP= session mhash gettext mbstring pcre openssl xml</programlisting> <para>Those modules may be available in CLI or web versions, so the web version is selected with a - <makevar>WANT_</makevar> variable:</para> + <varname>WANT_</varname> variable:</para> <programlisting>WANT_PHP_WEB= yes</programlisting> - <para>Available <makevar>USE_</makevar> and - <makevar>WANT_</makevar> variables are defined in the files + <para>Available <varname>USE_</varname> and + <varname>WANT_</varname> variables are defined in the files in <filename>/usr/ports/Mk</filename>.</para> </sect2> </sect1> - <sect1 id="makefile-masterdir"> - <title><makevar>MASTERDIR</makevar></title> + <sect1 xml:id="makefile-masterdir"> + <title><varname>MASTERDIR</varname></title> <para>If your port needs to build slightly different versions of packages by having a variable (for instance, resolution, or @@ -4107,10 +4068,9 @@ LIB_DEPENDS= bar:${PORTSDIR}/foo/bar you only need a very short <filename>Makefile</filename> in all but one of the directories if you use variables cleverly. In the sole <filename>Makefile</filename>, you can use - <makevar>MASTERDIR</makevar> to specify the directory where + <varname>MASTERDIR</varname> to specify the directory where the rest of the files are. Also, use a variable as part of - <link - linkend="porting-pkgname"><makevar>PKGNAMESUFFIX</makevar></link> + <link linkend="porting-pkgname"><varname>PKGNAMESUFFIX</varname></link> so the packages will have different names.</para> <para>This will be best demonstrated by an example. This is @@ -4130,7 +4090,7 @@ RESOLUTION?= 300 @${FALSE} .endif</programlisting> - <para><filename role="package">japanese/xdvi300</filename> also + <para><package>japanese/xdvi300</package> also has all the regular patches, package files, etc. If you type <command>make</command> there, it will take the default value for the resolution (300) and build the port normally.</para> @@ -4146,10 +4106,10 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <para>(<filename>xdvi240/Makefile</filename> and <filename>xdvi400/Makefile</filename> are similar). The - <makevar>MASTERDIR</makevar> definition tells + <varname>MASTERDIR</varname> definition tells <filename>bsd.port.mk</filename> that the regular set of - subdirectories like <makevar>FILESDIR</makevar> and - <makevar>SCRIPTDIR</makevar> are to be found under + subdirectories like <varname>FILESDIR</varname> and + <varname>SCRIPTDIR</varname> are to be found under <filename>xdvi300</filename>. The <literal>RESOLUTION=118</literal> line will override the <literal>RESOLUTION=300</literal> line in @@ -4157,35 +4117,35 @@ MASTERDIR= ${.CURDIR}/../xdvi300 built with resolution set to 118.</para> </sect1> - <sect1 id="makefile-manpages"> + <sect1 xml:id="makefile-manpages"> <title>Man Pages</title> <para>If your port anchors its man tree somewhere other than - <makevar>PREFIX</makevar>, you can use - <makevar>MANDIRS</makevar> to specify those directories. Note + <varname>PREFIX</varname>, you can use + <varname>MANDIRS</varname> to specify those directories. Note that the files corresponding to manual pages should be placed in <filename>pkg-plist</filename> along with the rest of the files. - The purpose of <makevar>MANDIRS</makevar> is to enable automatic + The purpose of <varname>MANDIRS</varname> is to enable automatic compression of manual pages, therefore the file names should be suffixed with <filename>.gz</filename>.</para> </sect1> - <sect1 id="makefile-info"> + <sect1 xml:id="makefile-info"> <title>Info Files</title> <para>If your package needs to install GNU info files, they - should be listed in the <makevar>INFO</makevar> variable + should be listed in the <varname>INFO</varname> variable (without the trailing <literal>.info</literal>), one entry per document. These files are assumed to be installed to - <filename><makevar>PREFIX</makevar>/<makevar>INFO_PATH</makevar></filename>. - You can change <makevar>INFO_PATH</makevar> if your package + <filename>PREFIX/INFO_PATH</filename>. + You can change <varname>INFO_PATH</varname> if your package uses a different location. However, this is not recommended. These entries contain just the path relative to - <filename><makevar>PREFIX</makevar>/<makevar>INFO_PATH</makevar></filename>. - For example, <filename role="package">lang/gcc34</filename> + <filename>PREFIX/INFO_PATH</filename>. + For example, <package>lang/gcc34</package> installs info files to - <filename><makevar>PREFIX</makevar>/<makevar>INFO_PATH</makevar>/gcc34</filename>, - and <makevar>INFO</makevar> will be something like + <filename>PREFIX/INFO_PATH/gcc34</filename>, + and <varname>INFO</varname> will be something like this:</para> <programlisting>INFO= gcc34/cpp gcc34/cppinternals gcc34/g77 ...</programlisting> @@ -4196,7 +4156,7 @@ MASTERDIR= ${.CURDIR}/../xdvi300 registration.</para> </sect1> - <sect1 id="makefile-options"> + <sect1 xml:id="makefile-options"> <title>Makefile Options</title> <para>Many applications can be built with optional or differing @@ -4212,26 +4172,25 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <title>Knobs</title> <sect3> - <title><makevar>WITH_<replaceable>*</replaceable></makevar> + <title><varname>WITH_<replaceable>*</replaceable></varname> and - <makevar>WITHOUT_<replaceable>*</replaceable></makevar></title> + <varname>WITHOUT_<replaceable>*</replaceable></varname></title> <para>These variables are designed to be set by the system administrator. There are many that are standardized in - the <ulink - url="http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>ports/KNOBS</filename></ulink> + the <link xlink:href="http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>ports/KNOBS</filename></link> file.</para> <para>When creating a port, do not make knob names specific to a given application. For example in Avahi port, use - <makevar>WITHOUT_MDNS</makevar> instead of - <makevar>WITHOUT_AVAHI_MDNS</makevar>.</para> + <varname>WITHOUT_MDNS</varname> instead of + <varname>WITHOUT_AVAHI_MDNS</varname>.</para> <note> <para>You should not assume that a - <makevar>WITH_<replaceable>*</replaceable></makevar> + <varname>WITH_<replaceable>*</replaceable></varname> necessarily has a corresponding - <makevar>WITHOUT_<replaceable>*</replaceable></makevar> + <varname>WITHOUT_<replaceable>*</replaceable></varname> variable and vice versa. In general, the default is simply assumed.</para> </note> @@ -4245,8 +4204,8 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <table frame="none"> <title>Common - <makevar>WITH_<replaceable>*</replaceable></makevar> and - <makevar>WITHOUT_<replaceable>*</replaceable></makevar> + <varname>WITH_<replaceable>*</replaceable></varname> and + <varname>WITHOUT_<replaceable>*</replaceable></varname> Variables</title> <tgroup cols="2"> @@ -4259,16 +4218,15 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <tbody> <row> - <entry><makevar>WITH_OPENSSL_BASE</makevar></entry> + <entry><varname>WITH_OPENSSL_BASE</varname></entry> <entry>Use the version of OpenSSL in the base system.</entry> </row> <row> - <entry><makevar>WITH_OPENSSL_PORT</makevar></entry> + <entry><varname>WITH_OPENSSL_PORT</varname></entry> <entry>Installs the version of OpenSSL from - <filename - role="package">security/openssl</filename>, even + <package>security/openssl</package>, even if the base is up to date.</entry> </row> </tbody> @@ -4282,45 +4240,44 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <para>Porters should use like-named knobs, both for the benefit of end-users and to help keep the number of knob names down. A list of popular knob names can be - found in the <ulink - url="http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>KNOBS</filename></ulink> + found in the <link xlink:href="http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>KNOBS</filename></link> file.</para> <para>Knob names should reflect what the knob is and does. When a port has a lib-prefix in the - <makevar>PORTNAME</makevar> the lib-prefix should be + <varname>PORTNAME</varname> the lib-prefix should be dropped in knob naming.</para> </sect3> </sect2> <sect2> - <title><makevar>OPTIONS</makevar></title> + <title><varname>OPTIONS</varname></title> <sect3> <title>Background</title> - <para>The <makevar>OPTIONS_*</makevar> variables give the + <para>The <varname>OPTIONS_*</varname> variables give the user installing the port a dialog showing the available options, and then saves those options to - <filename>/var/db/ports/<makevar>${UNIQUENAME}</makevar>/options</filename>. + <filename>/var/db/ports/${UNIQUENAME}/options</filename>. The next time the port is built, the options are reused.</para> <para>When the user runs <command>make config</command> (or runs <command>make build</command> for the first time), the framework checks for - <filename>/var/db/ports/<makevar>${UNIQUENAME}</makevar>/options</filename>. + <filename>/var/db/ports/${UNIQUENAME}/options</filename>. If that file does not exist, the values of - <makevar>OPTIONS_*</makevar> are used, and a dialog box is + <varname>OPTIONS_*</varname> are used, and a dialog box is displayed where the options can be enabled or disabled. Then the <filename>options</filename> file is saved and the configured variables are used when building the port.</para> <para>If a new version of the port adds new - <makevar>OPTIONS</makevar>, the dialog will be presented + <varname>OPTIONS</varname>, the dialog will be presented to the user with the saved values of old - <makevar>OPTIONS</makevar> prefilled.</para> + <varname>OPTIONS</varname> prefilled.</para> <para><command>make showconfig</command> shows the saved configuration. Use <command>make rmconfig</command> @@ -4330,13 +4287,13 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <sect3> <title>Syntax</title> - <para><makevar>OPTIONS_DEFINE</makevar> contains a list of - <makevar>OPTIONS</makevar> to be used. These are + <para><varname>OPTIONS_DEFINE</varname> contains a list of + <varname>OPTIONS</varname> to be used. These are independent of each other and are not grouped:</para> <programlisting>OPTIONS_DEFINE= OPT1 OPT2</programlisting> - <para>Once defined, <makevar>OPTIONS</makevar> are + <para>Once defined, <varname>OPTIONS</varname> are described (optional, but strongly recommended):</para> <programlisting>OPT1_DESC= Describe OPT1 @@ -4349,7 +4306,7 @@ OPT6_DESC= Describe OPT6</programlisting> <tip> <para><filename>ports/Mk/bsd.options.desc.mk</filename> has descriptions for many common - <makevar>OPTIONS</makevar>; there is usually no need + <varname>OPTIONS</varname>; there is usually no need to override these.</para> </tip> @@ -4366,21 +4323,21 @@ OPT6_DESC= Describe OPT6</programlisting> much more helpful.</para> </tip> - <para><makevar>OPTIONS</makevar> can be grouped as radio + <para><varname>OPTIONS</varname> can be grouped as radio choices, where only one choice from each group is allowed:</para> <programlisting>OPTIONS_SINGLE= SG1 OPTIONS_SINGLE_SG1= OPT3 OPT4</programlisting> - <para><makevar>OPTIONS</makevar> can be grouped as radio + <para><varname>OPTIONS</varname> can be grouped as radio choices, where none or only one choice from each group is allowed:</para> <programlisting>OPTIONS_RADIO= RG1 OPTIONS_RADIO_RG1= OPT7 OPT8</programlisting> - <para><makevar>OPTIONS</makevar> can also be grouped as + <para><varname>OPTIONS</varname> can also be grouped as <quote>multiple-choice</quote> lists, where <emphasis>at least one</emphasis> option must be enabled:</para> @@ -4388,23 +4345,23 @@ OPTIONS_RADIO_RG1= OPT7 OPT8</programlisting> <programlisting>OPTIONS_MULTI= MG1 OPTIONS_MULTI_MG1= OPT5 OPT6</programlisting> - <para><makevar>OPTIONS</makevar> can also be grouped as + <para><varname>OPTIONS</varname> can also be grouped as <quote>multiple-choice</quote> lists, where none or any option can be enabled:</para> <programlisting>OPTIONS_GROUP= GG1 OPTIONS_GROUP_GG1= OPT9 OPT10</programlisting> - <para><makevar>OPTIONS</makevar> are unset by default, + <para><varname>OPTIONS</varname> are unset by default, unless they are listed in - <makevar>OPTIONS_DEFAULT</makevar>:</para> + <varname>OPTIONS_DEFAULT</varname>:</para> <programlisting>OPTIONS_DEFAULT= OPT1 OPT3 OPT6</programlisting> - <para><makevar>OPTIONS</makevar> definitions must appear + <para><varname>OPTIONS</varname> definitions must appear before the inclusion of <filename>bsd.port.options.mk</filename>. The - <makevar>PORT_OPTIONS</makevar> variable can only be + <varname>PORT_OPTIONS</varname> variable can only be tested after the inclusion of <filename>bsd.port.options.mk</filename>. Inclusion of <filename>bsd.port.pre.mk</filename> can be used instead, @@ -4413,10 +4370,10 @@ OPTIONS_GROUP_GG1= OPT9 OPT10</programlisting> But be aware that some variables will not work as expected after the inclusion of <filename>bsd.port.pre.mk</filename>, typically some - <makevar>USE_*</makevar> flags.</para> + <varname>USE_*</varname> flags.</para> - <example id="ports-options-simple-use"> - <title>Simple Use of <makevar>OPTIONS</makevar></title> + <example xml:id="ports-options-simple-use"> + <title>Simple Use of <varname>OPTIONS</varname></title> <programlisting>OPTIONS_DEFINE= FOO BAR FOO_DESC= Enable option foo @@ -4439,17 +4396,17 @@ RUN_DEPENDS+= bar:${PORTSDIR}/bar/bar .include <bsd.port.mk></programlisting> </example> - <example id ="ports-options-check-unset"> + <example xml:id="ports-options-check-unset"> <title>Check for Unset Port - <makevar>OPTIONS</makevar></title> + <varname>OPTIONS</varname></title> <programlisting>.if ! ${PORT_OPTIONS:MEXAMPLES} CONFIGURE_ARGS+=--without-examples .endif</programlisting> </example> - <example id="ports-options-practical-use"> - <title>Practical Use of <makevar>OPTIONS</makevar></title> + <example xml:id="ports-options-practical-use"> + <title>Practical Use of <varname>OPTIONS</varname></title> <programlisting>OPTIONS_DEFINE= EXAMPLES @@ -4521,9 +4478,9 @@ CONFIGURE_ARGS+= --without-examples <note> <para>There is no need to add these to - <makevar>OPTIONS_DEFAULT</makevar>. To have them show + <varname>OPTIONS_DEFAULT</varname>. To have them show up in the options selection dialog, however, they must - be added to <makevar>OPTIONS_DEFINE</makevar>.</para> + be added to <varname>OPTIONS_DEFINE</varname>.</para> </note> </sect3> </sect2> @@ -4536,7 +4493,7 @@ CONFIGURE_ARGS+= --without-examples Explicitly disable optional features you do not wish to be used by passing respective <literal>--without-xxx</literal> or <literal>--disable-xxx</literal> in - <makevar>CONFIGURE_ARGS</makevar>.</para> + <varname>CONFIGURE_ARGS</varname>.</para> <example> <title>Wrong Handling of an Option</title> @@ -4592,10 +4549,10 @@ CONFIGURE_ARGS+= --disable-foo <para>There are some macros to help simplify conditional values which differ based on the options set.</para> - <para>If <makevar>OPTIONS_SUB</makevar> is set to + <para>If <varname>OPTIONS_SUB</varname> is set to <literal>yes</literal> then each of the options added - to <makevar>OPTIONS_DEFINE</makevar> will be added to - <makevar>PLIST_SUB</makevar>, for example:</para> + to <varname>OPTIONS_DEFINE</varname> will be added to + <varname>PLIST_SUB</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 OPTIONS_SUB= yes</programlisting> @@ -4612,11 +4569,11 @@ PLIST_SUB+= OPT1="" PLIST_SUB+= OPT1="@comment " .endif</programlisting> - <para>If <makevar>X_CONFIGURE_ENABLE</makevar> is set then + <para>If <varname>X_CONFIGURE_ENABLE</varname> is set then <literal>--enable-${X_CONFIGURE_ENABLE}</literal> or <literal>--disable-${X_CONFIGURE_ENABLE}</literal> will be - added to <makevar>CONFIGURE_ARGS</makevar> depending on the - value of the option<makevar>X</makevar>, for example:</para> + added to <varname>CONFIGURE_ARGS</varname> depending on the + value of the option<varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_ENABLE= test</programlisting> @@ -4633,11 +4590,11 @@ CONFIGURE_ARGS+= --enable-test CONFIGURE_ARGS+= --disable-test .endif</programlisting> - <para>If <makevar>X_CONFIGURE_WITH</makevar> is set then + <para>If <varname>X_CONFIGURE_WITH</varname> is set then <literal>--with-${X_CONFIGURE_WITH}</literal> or <literal>--without-${X_CONFIGURE_WITH}</literal> will - be added to <makevar>CONFIGURE_ARGS</makevar> depending - on the status of the option <makevar>X</makevar>, + be added to <varname>CONFIGURE_ARGS</varname> depending + on the status of the option <varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 @@ -4655,9 +4612,9 @@ CONFIGURE_ARGS+= --with-test CONFIGURE_ARGS+= --without-test .endif</programlisting> - <para>If <makevar>X_CONFIGURE_ON</makevar> is set then its - value will be appended to <makevar>CONFIGURE_ARGS</makevar> - depending on the status of the option <makevar>X</makevar>, + <para>If <varname>X_CONFIGURE_ON</varname> is set then its + value will be appended to <varname>CONFIGURE_ARGS</varname> + depending on the status of the option <varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 @@ -4673,9 +4630,9 @@ OPT1_CONFIGURE_ON= --add-test</programlisting> CONFIGURE_ARGS+= --add-test .endif</programlisting> - <para>If <makevar>X_CONFIGURE_OFF</makevar> is set then its - value will be appended to <makevar>CONFIGURE_ARGS</makevar> - depending on the status of the option <makevar>X</makevar>, + <para>If <varname>X_CONFIGURE_OFF</varname> is set then its + value will be appended to <varname>CONFIGURE_ARGS</varname> + depending on the status of the option <varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 @@ -4689,9 +4646,9 @@ OPT1_CONFIGURE_OFF= --no-test</programlisting> CONFIGURE_ARGS+= --no-test .endif</programlisting> - <para>If <makevar>X_CMAKE_ON</makevar> is set then its value - will be appended to <makevar>CMAKE_ARGS</makevar> depending - on the status of the option <makevar>X</makevar>, for + <para>If <varname>X_CMAKE_ON</varname> is set then its value + will be appended to <varname>CMAKE_ARGS</varname> depending + on the status of the option <varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 @@ -4707,9 +4664,9 @@ OPT1_CMAKE_ON= -DTEST:BOOL=true</programlisting> CMAKE_ARGS+= -DTEST:BOOL=true .endif</programlisting> - <para>If <makevar>X_CMAKE_OFF</makevar> is set then its value - will be appended to <makevar>CMAKE_ARGS</makevar> depending - on the status of the option <makevar>X</makevar>, for + <para>If <varname>X_CMAKE_OFF</varname> is set then its value + will be appended to <varname>CMAKE_ARGS</varname> depending + on the status of the option <varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 @@ -4729,82 +4686,82 @@ CMAKE_ARGS+= -DTEST:BOOL=false <itemizedlist> <listitem> - <para><makevar>ALL_TARGET</makevar></para> + <para><varname>ALL_TARGET</varname></para> </listitem> <listitem> - <para><makevar>CATEGORIES</makevar></para> + <para><varname>CATEGORIES</varname></para> </listitem> <listitem> - <para><makevar>CFLAGS</makevar></para> + <para><varname>CFLAGS</varname></para> </listitem> <listitem> - <para><makevar>CPPFLAGS</makevar></para> + <para><varname>CPPFLAGS</varname></para> </listitem> <listitem> - <para><makevar>CXXFLAGS</makevar></para> + <para><varname>CXXFLAGS</varname></para> </listitem> <listitem> - <para><makevar>CONFIGURE_ENV</makevar></para> + <para><varname>CONFIGURE_ENV</varname></para> </listitem> <listitem> - <para><makevar>DISTFILES</makevar></para> + <para><varname>DISTFILES</varname></para> </listitem> <listitem> - <para><makevar>EXTRA_PATCHES</makevar></para> + <para><varname>EXTRA_PATCHES</varname></para> </listitem> <listitem> - <para><makevar>INSTALL_TARGET</makevar></para> + <para><varname>INSTALL_TARGET</varname></para> </listitem> <listitem> - <para><makevar>LDFLAGS</makevar></para> + <para><varname>LDFLAGS</varname></para> </listitem> <listitem> - <para><makevar>MAKE_ARGS</makevar></para> + <para><varname>MAKE_ARGS</varname></para> </listitem> <listitem> - <para><makevar>MAKE_ENV</makevar></para> + <para><varname>MAKE_ENV</varname></para> </listitem> <listitem> - <para><makevar>PATCH_SITES</makevar></para> + <para><varname>PATCH_SITES</varname></para> </listitem> <listitem> - <para><makevar>PATCHFILES</makevar></para> + <para><varname>PATCHFILES</varname></para> </listitem> <listitem> - <para><makevar>PLIST_FILES</makevar></para> + <para><varname>PLIST_FILES</varname></para> </listitem> <listitem> - <para><makevar>PLIST_DIRS</makevar></para> + <para><varname>PLIST_DIRS</varname></para> </listitem> <listitem> - <para><makevar>PLIST_DIRSTRY</makevar></para> + <para><varname>PLIST_DIRSTRY</varname></para> </listitem> <listitem> - <para><makevar>USES</makevar></para> + <para><varname>USES</varname></para> </listitem> </itemizedlist> - <para>If <makevar>X_ABOVEVARIABLE</makevar> is defined then + <para>If <varname>X_ABOVEVARIABLE</varname> is defined then its value will be appended to - <makevar>ABOVEVARIABLE</makevar> depending on the status of - the option <makevar>X</makevar>, for example:</para> + <varname>ABOVEVARIABLE</varname> depending on the status of + the option <varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 OPT1_USES= gmake @@ -4825,38 +4782,38 @@ CFLAGS+= -DTEST <itemizedlist> <listitem> - <para><makevar>PKG_DEPENDS</makevar></para> + <para><varname>PKG_DEPENDS</varname></para> </listitem> <listitem> - <para><makevar>EXTRACT_DEPENDS</makevar></para> + <para><varname>EXTRACT_DEPENDS</varname></para> </listitem> <listitem> - <para><makevar>PATCH_DEPENDS</makevar></para> + <para><varname>PATCH_DEPENDS</varname></para> </listitem> <listitem> - <para><makevar>FETCH_DEPENDS</makevar></para> + <para><varname>FETCH_DEPENDS</varname></para> </listitem> <listitem> - <para><makevar>BUILD_DEPENDS</makevar></para> + <para><varname>BUILD_DEPENDS</varname></para> </listitem> <listitem> - <para><makevar>LIB_DEPENDS</makevar></para> + <para><varname>LIB_DEPENDS</varname></para> </listitem> <listitem> - <para><makevar>RUN_DEPENDS</makevar></para> + <para><varname>RUN_DEPENDS</varname></para> </listitem> </itemizedlist> - <para>If <makevar>X_ABOVEVARIABLE</makevar> is defined then + <para>If <varname>X_ABOVEVARIABLE</varname> is defined then its value will be appended to - <makevar>ABOVEVARIABLE</makevar> depending on the status - of the option <makevar>X</makevar>, for example:</para> + <varname>ABOVEVARIABLE</varname> depending on the status + of the option <varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 OPT1_LIB_DEPENDS= liba.so:${PORTSDIR}/devel/a</programlisting> @@ -4873,12 +4830,12 @@ LIB_DEPENDS+= liba.so:${PORTSDIR}/devel/a </sect2> </sect1> - <sect1 id="makefile-wrkdir"> + <sect1 xml:id="makefile-wrkdir"> <title>Specifying the Working Directory</title> <para>Each port is extracted in to a working directory, which must be writable. The ports system defaults to having the - <makevar>DISTFILES</makevar> unpack in to a directory called + <varname>DISTFILES</varname> unpack in to a directory called <literal>${DISTNAME}</literal>. In other words, if you have set:</para> @@ -4893,7 +4850,7 @@ PORTVERSION= 1.0</programlisting> is not the case.</para> <sect2> - <title><makevar>WRKSRC</makevar></title> + <title><varname>WRKSRC</varname></title> <para>The variable lists the name of the directory that is created when the application's distfiles are extracted. If @@ -4909,59 +4866,59 @@ PORTVERSION= 1.0</programlisting> </sect2> <sect2> - <title><makevar>NO_WRKSUBDIR</makevar></title> + <title><varname>NO_WRKSUBDIR</varname></title> <para>If the port does not extract in to a subdirectory at all - then you should set <makevar>NO_WRKSUBDIR</makevar> to + then you should set <varname>NO_WRKSUBDIR</varname> to indicate that.</para> <programlisting>NO_WRKSUBDIR= yes</programlisting> </sect2> </sect1> - <sect1 id="conflicts"> + <sect1 xml:id="conflicts"> <title>Conflict Handling</title> <para>There are three different variables to register a conflict - between packages and ports: <makevar>CONFLICTS</makevar>, - <makevar>CONFLICTS_INSTALL</makevar> and - <makevar>CONFLICTS_BUILD</makevar>.</para> + between packages and ports: <varname>CONFLICTS</varname>, + <varname>CONFLICTS_INSTALL</varname> and + <varname>CONFLICTS_BUILD</varname>.</para> <note> <para>The conflict variables automatically set the variable - <makevar>IGNORE</makevar>, which is more fully documented + <varname>IGNORE</varname>, which is more fully documented in <xref linkend="dads-noinstall"/>.</para> </note> <para>When removing one of several conflicting ports, it is - advisable to retain the <makevar>CONFLICTS</makevar> entries + advisable to retain the <varname>CONFLICTS</varname> entries in those other ports for a few months to cater for users who only update once in a while.</para> <sect2> - <title><makevar>CONFLICTS_INSTALL</makevar></title> + <title><varname>CONFLICTS_INSTALL</varname></title> <para>If your package cannot coexist with other packages (because of file conflicts, runtime incompatibilities, etc.), list the other package names in the - <makevar>CONFLICTS_INSTALL</makevar> variable. You can use + <varname>CONFLICTS_INSTALL</varname> variable. You can use shell globs like <literal>*</literal> and <literal>?</literal> here. Package names should be enumerated the same way they appear in <filename>/var/db/pkg</filename>. Please make sure that - <makevar>CONFLICTS_INSTALL</makevar> does not match this + <varname>CONFLICTS_INSTALL</varname> does not match this port's package itself. Otherwise enforcing its installation - with <makevar>FORCE_PKG_REGISTER</makevar> will no longer + with <varname>FORCE_PKG_REGISTER</varname> will no longer work. The CONFLICTS_INSTALL check is done after the build stage and prior to the install stage.</para> </sect2> <sect2> - <title><makevar>CONFLICTS_BUILD</makevar></title> + <title><varname>CONFLICTS_BUILD</varname></title> <para>If your port cannot be built if a certain port is already installed, list the other port names in the - <makevar>CONFLICTS_BUILD</makevar> variable. You can use + <varname>CONFLICTS_BUILD</varname> variable. You can use shell globs like <literal>*</literal> and <literal>?</literal> here. Package names should be enumerated the same way they appear in @@ -4971,37 +4928,37 @@ PORTVERSION= 1.0</programlisting> </sect2> <sect2> - <title><makevar>CONFLICTS</makevar></title> + <title><varname>CONFLICTS</varname></title> <para>If your port cannot be built if a certain port is already installed and the resulting package cannot coexist with the other package, list the other package name in the - <makevar>CONFLICTS</makevar> variable. You can use shell + <varname>CONFLICTS</varname> variable. You can use shell globs like <literal>*</literal> and <literal>?</literal> here. Packages names should be enumerated the same way they appear in <filename>/var/db/pkg</filename>. Please make - sure that <makevar>CONFLICTS_INSTALL</makevar> does not + sure that <varname>CONFLICTS_INSTALL</varname> does not match this port's package itself. Otherwise enforcing its - installation with <makevar>FORCE_PKG_REGISTER</makevar> will + installation with <varname>FORCE_PKG_REGISTER</varname> will no longer work. The CONFLICTS check is done prior to the build stage and prior to the install stage.</para> </sect2> </sect1> - <sect1 id="install"> + <sect1 xml:id="install"> <title>Installing Files</title> - <sect2 id="install-macros"> - <title><makevar>INSTALL_*</makevar> Macros</title> + <sect2 xml:id="install-macros"> + <title><varname>INSTALL_*</varname> Macros</title> <para>Use the macros provided in <filename>bsd.port.mk</filename> to ensure correct modes of - files in the port's <maketarget>*-install</maketarget> targets. + files in the port's <buildtarget>*-install</buildtarget> targets. Set ownership directly in <filename>pkg-plist</filename> with the corresponding entries, such as <literal>@owner - <replaceable>owner</replaceable></literal> and <literal>@group - <replaceable>group</replaceable></literal>. These + owner</literal> and <literal>@group + group</literal>. These operators work until being overridden, or until the end of <filename>pkg-plist</filename>, so do not forget to reset them after they are no longer needed. The default @@ -5010,35 +4967,35 @@ PORTVERSION= 1.0</programlisting> <itemizedlist> <listitem> - <para><makevar>INSTALL_PROGRAM</makevar> is a command to + <para><varname>INSTALL_PROGRAM</varname> is a command to install binary executables.</para> </listitem> <listitem> - <para><makevar>INSTALL_SCRIPT</makevar> is a command to + <para><varname>INSTALL_SCRIPT</varname> is a command to install executable scripts.</para> </listitem> <listitem> - <para><makevar>INSTALL_LIB</makevar> is a command to + <para><varname>INSTALL_LIB</varname> is a command to install shared libraries.</para> </listitem> <listitem> - <para><makevar>INSTALL_KLD</makevar> is a command to + <para><varname>INSTALL_KLD</varname> is a command to install kernel loadable modules. Some architectures do not like having the modules stripped, so use this command instead of - <makevar>INSTALL_PROGRAM</makevar>.</para> + <varname>INSTALL_PROGRAM</varname>.</para> </listitem> <listitem> - <para><makevar>INSTALL_DATA</makevar> is a command to + <para><varname>INSTALL_DATA</varname> is a command to install sharable data.</para> </listitem> <listitem> - <para><makevar>INSTALL_MAN</makevar> is a command to + <para><varname>INSTALL_MAN</varname> is a command to install manpages and other documentation (it does not compress anything).</para> </listitem> @@ -5048,22 +5005,22 @@ PORTVERSION= 1.0</programlisting> command with all the appropriate flags.</para> </sect2> - <sect2 id="install-strip"> + <sect2 xml:id="install-strip"> <title>Stripping Binaries and Shared Libraries</title> <para>Do not strip binaries manually unless you have to. All binaries should be stripped, but the - <makevar>INSTALL_PROGRAM</makevar> macro will install and + <varname>INSTALL_PROGRAM</varname> macro will install and strip a binary at the same time (see the next section). The - <makevar>INSTALL_LIB</makevar> macro does the same thing to + <varname>INSTALL_LIB</varname> macro does the same thing to shared libraries.</para> <para>If you need to strip a file, but wish to use neither - <makevar>INSTALL_PROGRAM</makevar> nor - <makevar>INSTALL_LIB</makevar> macros, - <makevar>${STRIP_CMD}</makevar> will strip your program or + <varname>INSTALL_PROGRAM</varname> nor + <varname>INSTALL_LIB</varname> macros, + <varname>${STRIP_CMD}</varname> will strip your program or shared library. This is typically done within the - <maketarget>post-install</maketarget> target. For + <buildtarget>post-install</buildtarget> target. For example:</para> <programlisting>post-install: @@ -5076,30 +5033,30 @@ PORTVERSION= 1.0</programlisting> stripped program; it will instead exit cleanly.</para> </sect2> - <sect2 id="install-copytree"> + <sect2 xml:id="install-copytree"> <title>Installing a Whole Tree of Files</title> <para>Sometimes, a large number of files must be installed while preserving their hierarchical organization. For example, copying over a whole directory tree from - <makevar>WRKSRC</makevar> to a target directory under - <makevar>PREFIX</makevar>. Note that - <makevar>PREFIX</makevar>, <makevar>EXAMPLESDIR</makevar>, - <makevar>DATADIR</makevar>, and other path varialbes must always be - prepended with <makevar>STAGEDIR</makevar> to respect + <varname>WRKSRC</varname> to a target directory under + <varname>PREFIX</varname>. Note that + <varname>PREFIX</varname>, <varname>EXAMPLESDIR</varname>, + <varname>DATADIR</varname>, and other path varialbes must always be + prepended with <varname>STAGEDIR</varname> to respect staging (see <xref linkend="staging"/>).</para> <para>Two macros exist for this situation. The advantage of using these macros instead of <command>cp</command> is that they guarantee proper file ownership and permissions on target files. The first macro, - <makevar>COPYTREE_BIN</makevar>, will set all the installed + <varname>COPYTREE_BIN</varname>, will set all the installed files to be executable, thus being suitable for installing - into <filename><makevar>PREFIX</makevar>/bin</filename>. - The second macro, <makevar>COPYTREE_SHARE</makevar>, does + into <filename>PREFIX/bin</filename>. + The second macro, <varname>COPYTREE_SHARE</varname>, does not set executable permissions on files, and is therefore suitable for installing files under - <filename><makevar>PREFIX</makevar>/share</filename> + <filename>PREFIX/share</filename> target.</para> <programlisting>post-install: @@ -5117,11 +5074,11 @@ PORTVERSION= 1.0</programlisting> <para>And this example will install the data of summer months to the <filename>summer</filename> subdirectory of a - <filename><makevar>DATADIR</makevar></filename>.</para> + <filename>DATADIR</filename>.</para> <para>Additional <command>find</command> arguments can be passed via the third argument to the - <makevar>COPYTREE_*</makevar> macros. For example, to + <varname>COPYTREE_*</varname> macros. For example, to install all files from the first example except Makefiles, one can use the following command.</para> @@ -5133,34 +5090,33 @@ PORTVERSION= 1.0</programlisting> <para>These macros do not add the installed files to <filename>pkg-plist</filename>. They must be added manually. For optional documentation - (<makevar>PORTDOCS</makevar>, see <xref - linkend="install-documentation"/>) and examples - (<makevar>PORTEXAMPLES</makevar>), the + (<varname>PORTDOCS</varname>, see <xref linkend="install-documentation"/>) and examples + (<varname>PORTEXAMPLES</varname>), the <literal>%%PORTDOCS%%</literal> or <literal>%%PORTEXAMPLES%%</literal> prefixes must be prepended in <filename>pkg-plist</filename>.</para> </sect2> - <sect2 id="install-documentation"> + <sect2 xml:id="install-documentation"> <title>Install Additional Documentation</title> <para>If your software has some documentation other than the standard man and info pages that you think is useful for the user, install it under - <filename><makevar>PREFIX</makevar>/share/doc</filename>. + <filename>PREFIX/share/doc</filename>. This can be done, like the previous item, in the - <maketarget>post-install</maketarget> target.</para> + <buildtarget>post-install</buildtarget> target.</para> <para>Create a new directory for your port. The directory name should reflect what the port is. This usually means - <makevar>PORTNAME</makevar>. However, if you think the user + <varname>PORTNAME</varname>. However, if you think the user might want different versions of the port to be installed at the same time, you can use the whole - <makevar>PKGNAME</makevar>.</para> + <varname>PKGNAME</varname>.</para> <para>Since only the files listed in <filename>pkg-plist</filename> are installed, it is safe to - always install documentation to <makevar>STAGEDIR</makevar> + always install documentation to <varname>STAGEDIR</varname> (see <xref linkend="staging"/>). Hence <literal>.if</literal> blocks are only needed when the installed files are large enough to cause significant I/O overhead.</para> @@ -5175,53 +5131,53 @@ PORTVERSION= 1.0</programlisting> <itemizedlist> <listitem> - <para><makevar>DATADIR</makevar> gets expanded to - <filename><makevar>PREFIX</makevar>/share/<makevar>PORTNAME</makevar></filename>.</para> + <para><varname>DATADIR</varname> gets expanded to + <filename>PREFIX/share/PORTNAME</filename>.</para> </listitem> <listitem> - <para><makevar>DATADIR_REL</makevar> gets expanded to - <filename>share/<makevar>PORTNAME</makevar></filename>.</para> + <para><varname>DATADIR_REL</varname> gets expanded to + <filename>share/PORTNAME</filename>.</para> </listitem> <listitem> - <para><makevar>DOCSDIR</makevar> gets expanded to - <filename><makevar>PREFIX</makevar>/share/doc/<makevar>PORTNAME</makevar></filename>.</para> + <para><varname>DOCSDIR</varname> gets expanded to + <filename>PREFIX/share/doc/PORTNAME</filename>.</para> </listitem> <listitem> - <para><makevar>DOCSDIR_REL</makevar> gets expanded to - <filename>share/doc/<makevar>PORTNAME</makevar></filename>.</para> + <para><varname>DOCSDIR_REL</varname> gets expanded to + <filename>share/doc/PORTNAME</filename>.</para> </listitem> <listitem> - <para><makevar>EXAMPLESDIR</makevar> gets expanded to - <filename><makevar>PREFIX</makevar>/share/examples/<makevar>PORTNAME</makevar></filename>.</para> + <para><varname>EXAMPLESDIR</varname> gets expanded to + <filename>PREFIX/share/examples/PORTNAME</filename>.</para> </listitem> <listitem> - <para><makevar>EXAMPLESDIR_REL</makevar> gets expanded to - <filename>share/examples/<makevar>PORTNAME</makevar></filename>.</para> + <para><varname>EXAMPLESDIR_REL</varname> gets expanded to + <filename>share/examples/PORTNAME</filename>.</para> </listitem> </itemizedlist> <note> <para>The <literal>DOCS</literal> option only controls additional documentation installed in - <makevar>DOCSDIR</makevar>. It does not apply to standard + <varname>DOCSDIR</varname>. It does not apply to standard man pages and info pages. Things installed in - <makevar>DATADIR</makevar> and - <makevar>EXAMPLESDIR</makevar> are controlled by + <varname>DATADIR</varname> and + <varname>EXAMPLESDIR</varname> are controlled by <literal>DATA</literal> and <literal>EXAMPLES</literal> options, respectively.</para> </note> <para>These variables are exported to - <makevar>PLIST_SUB</makevar>. Their values will appear + <varname>PLIST_SUB</varname>. Their values will appear there as pathnames relative to - <filename><makevar>PREFIX</makevar></filename> if possible. + <filename>PREFIX</filename> if possible. That is, - <filename>share/doc/<makevar>PORTNAME</makevar></filename> + <filename>share/doc/PORTNAME</filename> will be substituted for <literal>%%DOCSDIR%%</literal> in the packing list by default, and so on. (See more on <filename>pkg-plist</filename> substitution @@ -5238,31 +5194,31 @@ PORTVERSION= 1.0</programlisting> <para>As an alternative to enumerating the documentation files in <filename>pkg-plist</filename>, a port can set the - variable <makevar>PORTDOCS</makevar> to a list of file names + variable <varname>PORTDOCS</varname> to a list of file names and shell glob patterns to add to the final packing list. - The names will be relative to <makevar>DOCSDIR</makevar>. - Therefore, a port that utilizes <makevar>PORTDOCS</makevar> + The names will be relative to <varname>DOCSDIR</varname>. + Therefore, a port that utilizes <varname>PORTDOCS</varname> and uses a non-default location for its documentation should - set <makevar>DOCSDIR</makevar> accordingly. If a directory - is listed in <makevar>PORTDOCS</makevar> or matched by a + set <varname>DOCSDIR</varname> accordingly. If a directory + is listed in <varname>PORTDOCS</varname> or matched by a glob pattern from this variable, the entire subtree of contained files and directories will be registered in the final packing list. If the <literal>DOCS</literal> option has been unset then files and directories listed in - <makevar>PORTDOCS</makevar> would not be installed or added + <varname>PORTDOCS</varname> would not be installed or added to port packing list. Installing the documentation at - <makevar>PORTDOCS</makevar> as shown above remains up to the + <varname>PORTDOCS</varname> as shown above remains up to the port itself. A typical example of utilizing - <makevar>PORTDOCS</makevar> looks as follows:</para> + <varname>PORTDOCS</varname> looks as follows:</para> <programlisting>PORTDOCS= README.* ChangeLog docs/*</programlisting> <note> - <para>The equivalents of <makevar>PORTDOCS</makevar> for - files installed under <makevar>DATADIR</makevar> and - <makevar>EXAMPLESDIR</makevar> are - <makevar>PORTDATA</makevar> and - <makevar>PORTEXAMPLES</makevar>, respectively.</para> + <para>The equivalents of <varname>PORTDOCS</varname> for + files installed under <varname>DATADIR</varname> and + <varname>EXAMPLESDIR</varname> are + <varname>PORTDATA</varname> and + <varname>PORTEXAMPLES</varname>, respectively.</para> <para>You can also use the <filename>pkg-message</filename> file to display messages upon installation. See @@ -5273,11 +5229,11 @@ PORTVERSION= 1.0</programlisting> </note> </sect2> - <sect2 id="install-subdirs"> - <title>Subdirectories Under <makevar>PREFIX</makevar></title> + <sect2 xml:id="install-subdirs"> + <title>Subdirectories Under <varname>PREFIX</varname></title> <para>Try to let the port put things in the right - subdirectories of <makevar>PREFIX</makevar>. Some ports + subdirectories of <varname>PREFIX</varname>. Some ports lump everything and put it in the subdirectory with the port's name, which is incorrect. Also, many ports put everything except binaries, header files and manual pages in @@ -5293,39 +5249,38 @@ PORTVERSION= 1.0</programlisting> <filename>/usr</filename> pretty much apply to <filename>/usr/local</filename> too. The exception are ports dealing with USENET <quote>news</quote>. They may use - <filename><makevar>PREFIX</makevar>/news</filename> as a + <filename>PREFIX/news</filename> as a destination for their files.</para> </sect2> </sect1> </chapter> - <chapter id="special"> + <chapter xml:id="special"> <title>Special Considerations</title> <para>There are some more things you have to take into account when you create a port. This section explains the most common of those.</para> - <sect1 id="staging"> + <sect1 xml:id="staging"> <title>Staging</title> <para><filename>bsd.port.mk</filename> expects ports to work with a <quote>stage directory</quote>. This means that a port should not install files directly to the regular destination directories (that is, under - <makevar>PREFIX</makevar>, for example) but instead into a + <varname>PREFIX</varname>, for example) but instead into a separate directory from which the package is then built. In many cases, this does not require root privileges, making it possible to build packages as an unprivileged user. With staging, the port is built and installed into the stage - directory, <makevar>STAGEDIR</makevar>. A package is created + directory, <varname>STAGEDIR</varname>. A package is created from the stage directory and then installed on the system. Automake tools refer to - this concept as <makevar>DESTDIR</makevar>, but in &os;, - <makevar>DESTDIR</makevar> has a different meaning (see <xref - linkend="porting-prefix"/>).</para> + this concept as <varname>DESTDIR</varname>, but in &os;, + <varname>DESTDIR</varname> has a different meaning (see <xref linkend="porting-prefix"/>).</para> <para>When a port still requires system-wide privileges in order - to run the <maketarget>package</maketarget> target, this + to run the <buildtarget>package</buildtarget> target, this line must be added to the <filename>Makefile</filename>:</para> @@ -5341,19 +5296,19 @@ PORTVERSION= 1.0</programlisting> <programlisting>NO_MTREE= yes</programlisting> <para>Staging is enabled by prepending the - <makevar>STAGEDIR</makevar> variable to paths used in - the <maketarget>pre-install</maketarget>, - <maketarget>do-install</maketarget>, and - <maketarget>post-install</maketarget> targets (see the examples + <varname>STAGEDIR</varname> variable to paths used in + the <buildtarget>pre-install</buildtarget>, + <buildtarget>do-install</buildtarget>, and + <buildtarget>post-install</buildtarget> targets (see the examples through the book). Typically, this includes - <makevar>PREFIX</makevar>, <makevar>ETCDIR</makevar>, - <makevar>DATADIR</makevar>, <makevar>EXAMPLESDIR</makevar>, - <makevar>MANPREFIX</makevar>, <makevar>DOCSDIR</makevar>, and so on. + <varname>PREFIX</varname>, <varname>ETCDIR</varname>, + <varname>DATADIR</varname>, <varname>EXAMPLESDIR</varname>, + <varname>MANPREFIX</varname>, <varname>DOCSDIR</varname>, and so on. Directories should be created as part of the - <maketarget>post-install</maketarget> target. Avoid using + <buildtarget>post-install</buildtarget> target. Avoid using absolute paths whenever possible.</para> - <para>When creating a symlink, <makevar>STAGEDIR</makevar> should + <para>When creating a symlink, <varname>STAGEDIR</varname> should be prepended to the target path only. For example:</para> <programlisting>${LN} -sf libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so</programlisting> @@ -5366,10 +5321,9 @@ PORTVERSION= 1.0</programlisting> Relative paths are less fragile, and often much shorter.</para> <para>Ports that install kernel modules must prepend the - <makevar>STAGEDIR</makevar> variable to - their default destination, <filename - class="directory">/boot/modules</filename>. Then the - <maketarget>pre-install</maketarget> target can be used to handle + <varname>STAGEDIR</varname> variable to + their default destination, <filename>/boot/modules</filename>. Then the + <buildtarget>pre-install</buildtarget> target can be used to handle the creation of this directory:</para> <programlisting>pre-install: @@ -5377,8 +5331,8 @@ PORTVERSION= 1.0</programlisting> <para>&man.kldxref.8; should not be run when installing to the temporary staging directory. To prevent this, define - the<makevar>NO_XREF</makevar> variable and add it - to <makevar>MAKE_ENV</makevar> in the port's + the<varname>NO_XREF</varname> variable and add it + to <varname>MAKE_ENV</varname> in the port's <filename>Makefile</filename>:</para> <programlisting>MAKE_ENV+= KMODDIR=/boot/modules NO_XREF=yes</programlisting> @@ -5391,16 +5345,16 @@ PORTVERSION= 1.0</programlisting> @exec kldxref /boot/modules</programlisting> </sect1> - <sect1 id="porting-shlibs"> + <sect1 xml:id="porting-shlibs"> <title>Shared Libraries</title> <para>If your port installs one or more shared libraries, define - a <makevar>USE_LDCONFIG</makevar> make variable, which will + a <varname>USE_LDCONFIG</varname> make variable, which will instruct a <filename>bsd.port.mk</filename> to run <literal>${LDCONFIG} -m</literal> on the directory where the new library is installed (usually - <filename><makevar>PREFIX</makevar>/lib</filename>) during - <maketarget>post-install</maketarget> target to register it + <filename>PREFIX/lib</filename>) during + <buildtarget>post-install</buildtarget> target to register it into the shared library cache. This variable, when defined, will also facilitate addition of an appropriate <literal>@exec /sbin/ldconfig -m</literal> and @@ -5413,11 +5367,11 @@ PORTVERSION= 1.0</programlisting> <programlisting>USE_LDCONFIG= yes</programlisting> <para>If you need, you can override the default directory by - setting the <makevar>USE_LDCONFIG</makevar> value to a list of + setting the <varname>USE_LDCONFIG</varname> value to a list of directories into which shared libraries are to be installed. For example if your port installs shared libraries into - <filename><makevar>PREFIX</makevar>/lib/foo</filename> and - <filename><makevar>PREFIX</makevar>/lib/bar</filename> + <filename>PREFIX/lib/foo</filename> and + <filename>PREFIX/lib/bar</filename> directories you could use the following in your <filename>Makefile</filename>:</para> @@ -5426,14 +5380,14 @@ PORTVERSION= 1.0</programlisting> <para>Please double-check, often this is not necessary at all or can be avoided through <literal>-rpath</literal> or setting <envar>LD_RUN_PATH</envar> during linking (see - <filename role="package">lang/moscow_ml</filename> for an + <package>lang/moscow_ml</package> for an example), or through a shell-wrapper which sets - <makevar>LD_LIBRARY_PATH</makevar> before invoking the binary, - like <filename role="package">www/seamonkey</filename> + <varname>LD_LIBRARY_PATH</varname> before invoking the binary, + like <package>www/seamonkey</package> does.</para> <para>When installing 32-bit libraries on 64-bit system, use - <makevar>USE_LDCONFIG32</makevar> instead.</para> + <varname>USE_LDCONFIG32</varname> instead.</para> <para>Try to keep shared library version numbers in the <filename>libfoo.so.0</filename> format. Our runtime linker @@ -5442,11 +5396,11 @@ PORTVERSION= 1.0</programlisting> <para>When the major library version number increments in the update to the new port version, all other ports that link to the affected library should have their - <makevar>PORTREVISION</makevar> incremented, to force + <varname>PORTREVISION</varname> incremented, to force recompilation with the new library version.</para> </sect1> - <sect1 id="porting-restrictions"> + <sect1 xml:id="porting-restrictions"> <title>Ports with Distribution Restrictions</title> <para>Licenses vary, and some of them place restrictions on how @@ -5466,7 +5420,7 @@ PORTVERSION= 1.0</programlisting> following sections can be set.</para> <sect2> - <title><makevar>NO_PACKAGE</makevar></title> + <title><varname>NO_PACKAGE</varname></title> <para>This variable indicates that we may not generate a binary package of the application. For instance, the @@ -5474,39 +5428,39 @@ PORTVERSION= 1.0</programlisting> prohibit distribution of packages created from patched sources.</para> - <para>However, the port's <makevar>DISTFILES</makevar> may be + <para>However, the port's <varname>DISTFILES</varname> may be freely mirrored on FTP/HTTP. They may also be distributed on a CD-ROM (or similar media) unless - <makevar>NO_CDROM</makevar> is set as well.</para> + <varname>NO_CDROM</varname> is set as well.</para> - <para><makevar>NO_PACKAGE</makevar> should also be used if the + <para><varname>NO_PACKAGE</varname> should also be used if the binary package is not generally useful, and the application should always be compiled from the source code. For example, if the application has configuration information that is site specific hard coded in to it at compile time, - set <makevar>NO_PACKAGE</makevar>.</para> + set <varname>NO_PACKAGE</varname>.</para> - <para><makevar>NO_PACKAGE</makevar> should be set to a string + <para><varname>NO_PACKAGE</varname> should be set to a string describing the reason why the package should not be generated.</para> </sect2> <sect2> - <title><makevar>NO_CDROM</makevar></title> + <title><varname>NO_CDROM</varname></title> <para>This variable alone indicates that, although we are allowed to generate binary packages, we may put neither - those packages nor the port's <makevar>DISTFILES</makevar> + those packages nor the port's <varname>DISTFILES</varname> onto a CD-ROM (or similar media) for resale. However, the - binary packages and the port's <makevar>DISTFILES</makevar> + binary packages and the port's <varname>DISTFILES</varname> will still be available via FTP/HTTP.</para> <para> If this variable is set along with - <makevar>NO_PACKAGE</makevar>, then only the port's - <makevar>DISTFILES</makevar> will be available, and only via + <varname>NO_PACKAGE</varname>, then only the port's + <varname>DISTFILES</varname> will be available, and only via FTP/HTTP.</para> - <para><makevar>NO_CDROM</makevar> should be set to a string + <para><varname>NO_CDROM</varname> should be set to a string describing the reason why the port cannot be redistributed on CD-ROM. For instance, this should be used if the port's license is for <quote>non-commercial</quote> use @@ -5514,45 +5468,45 @@ PORTVERSION= 1.0</programlisting> </sect2> <sect2> - <title><makevar>NOFETCHFILES</makevar></title> + <title><varname>NOFETCHFILES</varname></title> - <para>Files defined in the <makevar>NOFETCHFILES</makevar> + <para>Files defined in the <varname>NOFETCHFILES</varname> variable are not fetchable from any of the - <makevar>MASTER_SITES</makevar>. An example of such a file + <varname>MASTER_SITES</varname>. An example of such a file is when the file is supplied on CD-ROM by the vendor.</para> <para>Tools which check for the availability of these files - on the <makevar>MASTER_SITES</makevar> should ignore these + on the <varname>MASTER_SITES</varname> should ignore these files and not report about them.</para> </sect2> <sect2> - <title><makevar>RESTRICTED</makevar></title> + <title><varname>RESTRICTED</varname></title> <para>Set this variable alone if the application's license permits neither mirroring the application's - <makevar>DISTFILES</makevar> nor distributing the binary + <varname>DISTFILES</varname> nor distributing the binary package in any way.</para> - <para><makevar>NO_CDROM</makevar> or - <makevar>NO_PACKAGE</makevar> should not be set along with - <makevar>RESTRICTED</makevar> since the latter variable + <para><varname>NO_CDROM</varname> or + <varname>NO_PACKAGE</varname> should not be set along with + <varname>RESTRICTED</varname> since the latter variable implies the former ones.</para> - <para><makevar>RESTRICTED</makevar> should be set to a string + <para><varname>RESTRICTED</varname> should be set to a string describing the reason why the port cannot be redistributed. Typically, this indicates that the port contains proprietary software and that the user will need to manually download - the <makevar>DISTFILES</makevar>, possibly after registering + the <varname>DISTFILES</varname>, possibly after registering for the software or agreeing to accept the terms of an <acronym>EULA</acronym>.</para> </sect2> <sect2> - <title><makevar>RESTRICTED_FILES</makevar></title> + <title><varname>RESTRICTED_FILES</varname></title> - <para>When <makevar>RESTRICTED</makevar> or - <makevar>NO_CDROM</makevar> is set, this variable defaults + <para>When <varname>RESTRICTED</varname> or + <varname>NO_CDROM</varname> is set, this variable defaults to <literal>${DISTFILES} ${PATCHFILES}</literal>, otherwise it is empty. If only some of the distribution files are restricted, then set this variable to list them.</para> @@ -5581,10 +5535,10 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep </sect2> </sect1> - <sect1 id="building"> + <sect1 xml:id="building"> <title>Building Mechanisms</title> - <sect2 id="parallel-builds"> + <sect2 xml:id="parallel-builds"> <title>Building Ports in Parallel</title> <para>The &os; ports framework supports parallel building @@ -5593,7 +5547,7 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep their available <acronym>CPU</acronym> power, allowing port builds to be faster and more effective.</para> - <para>This is achieved by passing <makevar>-jX</makevar> flag + <para>This is achieved by passing <varname>-jX</varname> flag to &man.make.1; running on vendor code. Unfortunately, not all ports handle parallel building well. Therefore it is required to explicitly enable this feature by adding @@ -5603,15 +5557,15 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep <para>Another option for controlling this feature from the maintainer's point of view is the - <makevar>MAKE_JOBS_UNSAFE=yes</makevar> variable. It is + <varname>MAKE_JOBS_UNSAFE=yes</varname> variable. It is used when a port is known to be broken with - <makevar>-jX</makevar> and a user forces the use of multi + <varname>-jX</varname> and a user forces the use of multi processor compilations for all ports in <filename>/etc/make.conf</filename> with the <literal>FORCE_MAKE_JOBS=yes</literal> variable.</para> </sect2> - <sect2 id="using-make"> + <sect2 xml:id="using-make"> <title><command>make</command>, <command>gmake</command>, and <command>imake</command></title> @@ -5632,13 +5586,13 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep <tbody> <row> - <entry><makevar>USES= gmake</makevar></entry> + <entry><varname>USES= gmake</varname></entry> <entry>The port requires <command>gmake</command> to build.</entry> </row> <row> - <entry><makevar>GMAKE</makevar></entry> + <entry><varname>GMAKE</varname></entry> <entry>The full path for <command>gmake</command> if it is not in the <envar>PATH</envar>.</entry> </row> @@ -5656,18 +5610,18 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep flag is a problem for your port, set <literal>XMKMF=xmkmf</literal>. If the port uses <application>imake</application> but does not understand the - <maketarget>install.man</maketarget> target, + <buildtarget>install.man</buildtarget> target, <literal>NO_INSTALL_MANPAGES=yes</literal> should be set.</para> <para>If your port's source <filename>Makefile</filename> has - something else than <maketarget>all</maketarget> as the main - build target, set <makevar>ALL_TARGET</makevar> accordingly. - Same goes for <maketarget>install</maketarget> and - <makevar>INSTALL_TARGET</makevar>.</para> + something else than <buildtarget>all</buildtarget> as the main + build target, set <varname>ALL_TARGET</varname> accordingly. + Same goes for <buildtarget>install</buildtarget> and + <varname>INSTALL_TARGET</varname>.</para> </sect2> - <sect2 id="using-configure"> + <sect2 xml:id="using-configure"> <title><command>configure</command> Script</title> <para>If your port uses the <command>configure</command> @@ -5679,9 +5633,9 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep --infodir=${PREFIX}/${INFO_PATH} --mandir=${MANPREFIX}/man --build=${CONFIGURE_TARGET}</literal>), set those - extra arguments in <makevar>CONFIGURE_ARGS</makevar>. Extra + extra arguments in <varname>CONFIGURE_ARGS</varname>. Extra environment variables can be passed using - <makevar>CONFIGURE_ENV</makevar> variable.</para> + <varname>CONFIGURE_ENV</varname> variable.</para> <table frame="none"> <title>Variables for Ports That Use @@ -5697,32 +5651,32 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep <tbody> <row> - <entry><makevar>GNU_CONFIGURE</makevar></entry> + <entry><varname>GNU_CONFIGURE</varname></entry> <entry>The port uses <command>configure</command> script to prepare build.</entry> </row> <row> - <entry><makevar>HAS_CONFIGURE</makevar></entry> - <entry>Same as <makevar>GNU_CONFIGURE</makevar>, + <entry><varname>HAS_CONFIGURE</varname></entry> + <entry>Same as <varname>GNU_CONFIGURE</varname>, except default configure target is not added to - <makevar>CONFIGURE_ARGS</makevar>.</entry> + <varname>CONFIGURE_ARGS</varname>.</entry> </row> <row> - <entry><makevar>CONFIGURE_ARGS</makevar></entry> + <entry><varname>CONFIGURE_ARGS</varname></entry> <entry>Additional arguments passed to <command>configure</command> script.</entry> </row> <row> - <entry><makevar>CONFIGURE_ENV</makevar></entry> + <entry><varname>CONFIGURE_ENV</varname></entry> <entry>Additional environment variables to be set for <command>configure</command> script run.</entry> </row> <row> - <entry><makevar>CONFIGURE_TARGET</makevar></entry> + <entry><varname>CONFIGURE_TARGET</varname></entry> <entry>Override default configure target. Default value is <literal>${MACHINE_ARCH}-portbld-freebsd${OSREL}</literal>.</entry> @@ -5732,7 +5686,7 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep </table> </sect2> - <sect2 id="using-cmake"> + <sect2 xml:id="using-cmake"> <title>Using <command>cmake</command></title> <para>For ports that use <application>CMake</application>, @@ -5754,30 +5708,30 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep <tbody> <row> - <entry><makevar>CMAKE_ARGS</makevar></entry> + <entry><varname>CMAKE_ARGS</varname></entry> <entry>Port specific <application>CMake</application> flags to be passed to the <command>cmake</command> binary.</entry> </row> <row> - <entry><makevar>CMAKE_BUILD_TYPE</makevar></entry> + <entry><varname>CMAKE_BUILD_TYPE</varname></entry> <entry>Type of build (<application>CMake</application> predefined build profiles). Default is <literal>Release</literal>, or <literal>Debug</literal> if - <makevar>WITH_DEBUG</makevar> is set.</entry> + <varname>WITH_DEBUG</varname> is set.</entry> </row> <row> - <entry><makevar>CMAKE_ENV</makevar></entry> + <entry><varname>CMAKE_ENV</varname></entry> <entry>Environment variables to be set for <command>cmake</command> binary. Default is <literal>${CONFIGURE_ENV}</literal>.</entry> </row> <row> - <entry><makevar>CMAKE_SOURCE_PATH</makevar></entry> + <entry><varname>CMAKE_SOURCE_PATH</varname></entry> <entry>Path to the source directory. Default is <literal>${WRKSRC}</literal>.</entry> </row> @@ -5793,19 +5747,19 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep <literal>Release</literal> profiles respect system <literal>*FLAGS</literal>, <literal>RelWithDebInfo</literal> and <literal>MinSizeRel</literal> will set - <makevar>CFLAGS</makevar> to <literal>-O2 -g</literal> and + <varname>CFLAGS</varname> to <literal>-O2 -g</literal> and <literal>-Os -DNDEBUG</literal> correspondingly. The - lower-cased value of <makevar>CMAKE_BUILD_TYPE</makevar> is - exported to the <makevar>PLIST_SUB</makevar> and should be + lower-cased value of <varname>CMAKE_BUILD_TYPE</varname> is + exported to the <varname>PLIST_SUB</varname> and should be used if port installs <literal>*.cmake</literal> files depending on the build type (see - <filename role="package">deskutils/strigi</filename> for an + <package>deskutils/strigi</package> for an example). Please note that some projects may define their own build profiles and/or force particular build type by setting <literal>CMAKE_BUILD_TYPE</literal> in <filename>CMakeLists.txt </filename> files. In order to make a port for such a project respect - <makevar>CFLAGS</makevar> and <makevar>WITH_DEBUG</makevar>, + <varname>CFLAGS</varname> and <varname>WITH_DEBUG</varname>, the <literal>CMAKE_BUILD_TYPE</literal> definitions must be removed from those files.</para> @@ -5813,20 +5767,20 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep support an out-of-source method of building. The out-of-source build for a port can be requested by using the <literal>:outsource</literal> suffix. When enabled, - <makevar>CONFIGURE_WRKSRC</makevar>, - <makevar>BUILD_WRKSRC</makevar> and - <makevar>INSTALL_WRKSRC</makevar> will be set to + <varname>CONFIGURE_WRKSRC</varname>, + <varname>BUILD_WRKSRC</varname> and + <varname>INSTALL_WRKSRC</varname> will be set to <literal>${WRKDIR}/.build</literal> and this directory will be used to keep all files generated during configuration and build stages, leaving the source directory intact.</para> - <example id="using-cmake-example"> + <example xml:id="using-cmake-example"> <title><literal>USES= cmake</literal> Example</title> <para>The following snippet demonstrates the use of <application>CMake</application> for a port. - <makevar>CMAKE_SOURCE_PATH</makevar> is not usually + <varname>CMAKE_SOURCE_PATH</varname> is not usually required, but can be set when the sources are not located in the top directory, or if only a subset of the project is intended to be built by the port.</para> @@ -5836,7 +5790,7 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> </example> </sect2> - <sect2 id="using-scons"> + <sect2 xml:id="using-scons"> <title>Using <command>scons</command></title> <para>If your port uses <application>SCons</application>, @@ -5856,27 +5810,27 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <tbody> <row> - <entry><makevar>SCONS_ARGS</makevar></entry> + <entry><varname>SCONS_ARGS</varname></entry> <entry>Port specific SCons flags passed to the SCons environment.</entry> </row> <row> - <entry><makevar>SCONS_BUILDENV</makevar></entry> + <entry><varname>SCONS_BUILDENV</varname></entry> <entry>Variables to be set in system environment.</entry> </row> <row> - <entry><makevar>SCONS_ENV</makevar></entry> + <entry><varname>SCONS_ENV</varname></entry> <entry>Variables to be set in SCons environment.</entry> </row> <row> - <entry><makevar>SCONS_TARGET</makevar></entry> + <entry><varname>SCONS_TARGET</varname></entry> <entry>Last argument passed to SCons, similar to - <makevar>MAKE_TARGET</makevar>.</entry> + <varname>MAKE_TARGET</varname>.</entry> </row> </tbody> </tgroup> @@ -5884,8 +5838,8 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <para>To make third party <filename>SConstruct</filename> respect everything that is passed to SCons in - <makevar>SCONS_ENV</makevar> (that is, most importantly, - <makevar>CC/CXX/CFLAGS/CXXFLAGS</makevar>), patch the + <varname>SCONS_ENV</varname> (that is, most importantly, + <varname>CC/CXX/CFLAGS/CXXFLAGS</varname>), patch the <filename>SConstruct</filename> so build <literal>Environment</literal> is constructed like this:</para> @@ -5898,10 +5852,10 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> </sect2> </sect1> - <sect1 id="using-autotools"> + <sect1 xml:id="using-autotools"> <title>Using GNU Autotools</title> - <sect2 id="using-autotools-introduction"> + <sect2 xml:id="using-autotools-introduction"> <title>Introduction</title> <para>The various GNU autotools provide an abstraction @@ -5938,7 +5892,7 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <literal>devel/autotools</literal> port.</para> </sect2> - <sect2 id="using-libtool"> + <sect2 xml:id="using-libtool"> <title><command>libtool</command></title> <para>Shared libraries using the GNU building framework @@ -5953,11 +5907,11 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <programlisting>USE_AUTOTOOLS= libtool:<replaceable>version</replaceable>[:env]</programlisting> <para>With no additional operations, - <literal>libtool:<replaceable>version</replaceable></literal> + <literal>libtool:version</literal> tells the building framework to patch the configure script with the system-installed copy of <command>libtool</command>. The - <makevar>GNU_CONFIGURE</makevar> is implied. Further, a + <varname>GNU_CONFIGURE</varname> is implied. Further, a number of make and shell variables will be assigned for onward use by the port. See <filename>bsd.autotools.mk</filename> for details.</para> @@ -5965,15 +5919,15 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <para>With the <literal>:env</literal> operation, only the environment will be set up.</para> - <para>Finally, <makevar>LIBTOOLFLAGS</makevar> and - <makevar>LIBTOOLFILES</makevar> can be optionally set to + <para>Finally, <varname>LIBTOOLFLAGS</varname> and + <varname>LIBTOOLFILES</varname> can be optionally set to override the most likely arguments to, and files patched by, <command>libtool</command>. Most ports are unlikely to need this. See <filename>bsd.autotools.mk</filename> for further details.</para> </sect2> - <sect2 id="using-libltdl"> + <sect2 xml:id="using-libltdl"> <title><command>libltdl</command></title> <para>Some ports make use of the <command>libltdl</command> @@ -5986,15 +5940,15 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <programlisting>USE_AUTOTOOLS= libltdl:<replaceable>version</replaceable></programlisting> <para>Currently, all this does is to bring in a - <makevar>LIB_DEPENDS</makevar> on the appropriate + <varname>LIB_DEPENDS</varname> on the appropriate <command>libltdl</command> port, and is provided as a convenience function to help eliminate any dependencies on the autotools ports outside of the - <makevar>USE_AUTOTOOLS</makevar> framework. There are no + <varname>USE_AUTOTOOLS</varname> framework. There are no optional operations for this tool.</para> </sect2> - <sect2 id="using-autoconf"> + <sect2 xml:id="using-autoconf"> <title><command>autoconf</command> and <command>autoheader</command></title> @@ -6013,7 +5967,7 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <programlisting>USE_AUTOTOOLS= autoheader:<replaceable>version</replaceable></programlisting> <para>which also implies the use of - <literal>autoconf:<replaceable>version</replaceable></literal>.</para> + <literal>autoconf:version</literal>.</para> <para>Similarly to <command>libtool</command>, the inclusion of the optional <literal>:env</literal> operation simply @@ -6022,14 +5976,14 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> out.</para> <para>The additional optional variables - <makevar>AUTOCONF_ARGS</makevar> and - <makevar>AUTOHEADER_ARGS</makevar> can be overridden by the + <varname>AUTOCONF_ARGS</varname> and + <varname>AUTOHEADER_ARGS</varname> can be overridden by the port <filename>Makefile</filename> if specifically requested. As with the <command>libtool</command> equivalents, most ports are unlikely to need this.</para> </sect2> - <sect2 id="using-automake"> + <sect2 xml:id="using-automake"> <title><command>automake</command> and <command>aclocal</command></title> @@ -6060,7 +6014,7 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <programlisting>USE_AUTOTOOLS= aclocal:<replaceable>version</replaceable></programlisting> <para>which also implies the use of - <literal>automake:<replaceable>version</replaceable></literal>.</para> + <literal>automake:version</literal>.</para> <para>Similarly to <command>libtool</command> and <command>autoconf</command>, the inclusion of the optional @@ -6072,14 +6026,14 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <command>autoheader</command>, both <command>automake</command> and <command>aclocal</command> have optional argument variables, - <makevar>AUTOMAKE_ARGS</makevar> and - <makevar>ACLOCAL_ARGS</makevar> respectively, which may be + <varname>AUTOMAKE_ARGS</varname> and + <varname>ACLOCAL_ARGS</varname> respectively, which may be overridden by the port <filename>Makefile</filename> if required.</para> </sect2> </sect1> - <sect1 id="using-gettext"> + <sect1 xml:id="using-gettext"> <title>Using GNU <literal>gettext</literal></title> <sect2> @@ -6088,7 +6042,7 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <para>If your port requires <literal>gettext</literal>, set <literal>USES= gettext</literal>, and your port will inherit a dependency on - <filename role="package">devel/gettext</filename>. Other + <package>devel/gettext</package>. Other values for <literal>gettext</literal> usage are listed in <xref linkend="uses-values"/>.</para> @@ -6121,7 +6075,7 @@ GNU_CONFIGURE= yes</programlisting> through passing <option>--disable-nls</option> to <command>configure</command>. In that case, your port should use <literal>gettext</literal> conditionally, - depending on the status of the <makevar>NLS</makevar> + depending on the status of the <varname>NLS</varname> option. For ports of low to medium complexity, you can rely on the following idiom:</para> @@ -6172,37 +6126,36 @@ PLIST_SUB+= NLS="@comment " <para>There is a point to note about installing message catalog files. The target directories for them, which reside under - <filename><makevar>LOCALBASE</makevar>/share/locale</filename>, + <filename>LOCALBASE/share/locale</filename>, should rarely be created and removed by a port. The most popular languages have their respective directories listed in - <filename><makevar>PORTSDIR</makevar>/Templates/BSD.local.dist</filename>. + <filename>PORTSDIR/Templates/BSD.local.dist</filename>. The directories for many other languages are governed by the - <filename role="package">devel/gettext</filename> port. + <package>devel/gettext</package> port. Consult its <filename>pkg-plist</filename> and see whether the port is going to install a message catalog file for a unique language.</para> </sect2> </sect1> - <sect1 id="using-perl"> + <sect1 xml:id="using-perl"> <title>Using <application>Perl</application></title> - <para>If <makevar>MASTER_SITES</makevar> is set to - <makevar>MASTER_SITE_PERL_CPAN</makevar>, then the preferred - value of <makevar>MASTER_SITE_SUBDIR</makevar> is the + <para>If <varname>MASTER_SITES</varname> is set to + <varname>MASTER_SITE_PERL_CPAN</varname>, then the preferred + value of <varname>MASTER_SITE_SUBDIR</varname> is the top-level hierarchy name. For example, the recommended value for <literal>p5-Module-Name</literal> is <literal>Module</literal>. The top-level hierarchy can be - examined at <ulink - url="http://cpan.org/modules/by-module/">cpan.org</ulink>. + examined at <link xlink:href="http://cpan.org/modules/by-module/">cpan.org</link>. This keeps the port working when the author of the module changes.</para> <para>The exception to this rule is when the relevant directory does not exist or the distfile does not exist in that directory. In such case, using author's id as - <makevar>MASTER_SITE_SUBDIR</makevar> is allowed.</para> + <varname>MASTER_SITE_SUBDIR</varname> is allowed.</para> <para>All of the tunable knobs below accept either <literal>YES</literal> or a version string like @@ -6230,25 +6183,25 @@ PLIST_SUB+= NLS="@comment " <tbody> <row> - <entry><makevar>USE_PERL5</makevar></entry> + <entry><varname>USE_PERL5</varname></entry> <entry>The port uses Perl 5 to build and run.</entry> </row> <row> - <entry><makevar>USE_PERL5_BUILD</makevar></entry> + <entry><varname>USE_PERL5_BUILD</varname></entry> <entry>The port uses Perl 5 to build.</entry> </row> <row> - <entry><makevar>USE_PERL5_RUN</makevar></entry> + <entry><varname>USE_PERL5_RUN</varname></entry> <entry>The port uses Perl 5 to run.</entry> </row> <row> - <entry><makevar>PERL</makevar></entry> + <entry><varname>PERL</varname></entry> <entry>The full path of the Perl 5 interpreter, either in the system or installed from a port, but without the version number. Use this if you need to @@ -6257,15 +6210,15 @@ PLIST_SUB+= NLS="@comment " </row> <row> - <entry><makevar>PERL_CONFIGURE</makevar></entry> + <entry><varname>PERL_CONFIGURE</varname></entry> <entry>Configure using Perl's MakeMaker. It implies - <makevar>USE_PERL5</makevar>.</entry> + <varname>USE_PERL5</varname>.</entry> </row> <row> - <entry><makevar>PERL_MODBUILD</makevar></entry> + <entry><varname>PERL_MODBUILD</varname></entry> <entry>Configure, build and install using Module::Build. - It implies <makevar>PERL_CONFIGURE</makevar>.</entry> + It implies <varname>PERL_CONFIGURE</varname>.</entry> </row> </tbody> </tgroup> @@ -6280,36 +6233,36 @@ PLIST_SUB+= NLS="@comment " <tbody> <row> - <entry><makevar>PERL_VERSION</makevar></entry> + <entry><varname>PERL_VERSION</varname></entry> <entry>The full version of Perl installed (e.g., <literal>5.8.9</literal>).</entry> </row> <row> - <entry><makevar>PERL_LEVEL</makevar></entry> + <entry><varname>PERL_LEVEL</varname></entry> <entry>The installed Perl version as an integer of the form <literal>MNNNPP</literal> (e.g., <literal>500809</literal>).</entry> </row> <row> - <entry><makevar>PERL_ARCH</makevar></entry> + <entry><varname>PERL_ARCH</varname></entry> <entry>Where Perl stores architecture dependent libraries. Defaults to <literal>${ARCH}-freebsd</literal>.</entry> </row> <row> - <entry><makevar>PERL_PORT</makevar></entry> + <entry><varname>PERL_PORT</varname></entry> <entry>Name of the Perl port that is installed (e.g., <literal>perl5</literal>).</entry> </row> <row> - <entry><makevar>SITE_PERL</makevar></entry> + <entry><varname>SITE_PERL</varname></entry> <entry>Directory name where site specific Perl packages go. This value is - added to <makevar>PLIST_SUB</makevar>.</entry> + added to <varname>PLIST_SUB</varname>.</entry> </row> </tbody> </tgroup> @@ -6317,7 +6270,7 @@ PLIST_SUB+= NLS="@comment " <note> <para>Ports of Perl modules which do not have an official - website should link to <hostid>cpan.org</hostid> in the WWW + website should link to <systemitem>cpan.org</systemitem> in the WWW line of <filename>pkg-descr</filename>. The preferred URL form is <literal>http://search.cpan.org/dist/Module-Name/</literal> @@ -6334,14 +6287,14 @@ PLIST_SUB+= NLS="@comment " is shown in the example below.</para> </note> - <example id="use-perl-dependency-example"> + <example xml:id="use-perl-dependency-example"> <title>Perl Dependency Example</title> <programlisting>p5-IO-Tee>=0.64:${PORTSDIR}/devel/p5-IO-Tee</programlisting> </example> <para>For Perl ports that install manual pages, the macro - <makevar>PERL5_MAN<replaceable>x</replaceable></makevar> (where + <varname>PERL5_MAN<replaceable>x</replaceable></varname> (where <replaceable>x</replaceable> ranges from <literal>1</literal> to <literal>9</literal>) can be used inside <filename>pkg-plist</filename>. For example,</para> @@ -6353,15 +6306,15 @@ PLIST_SUB+= NLS="@comment " <programlisting>%%PERL5_MAN3%%/AnyEvent::I3.3.gz</programlisting> </sect1> - <sect1 id="using-x11"> + <sect1 xml:id="using-x11"> <title>Using X11</title> - <sect2 id="x11-variables"> + <sect2 xml:id="x11-variables"> <title>X.Org Components</title> <para>The X11 implementation available in The Ports Collection is X.Org. If your application depends on X components, set - <makevar>USE_XORG</makevar> to the list of required + <varname>USE_XORG</varname> to the list of required components. Available components, at the time of writing, are:</para> @@ -6385,14 +6338,14 @@ PLIST_SUB+= NLS="@comment " <para>The Mesa Project is an effort to provide free OpenGL implementation. You can specify a dependency on various - components of this project with <makevar>USE_GL</makevar> + components of this project with <varname>USE_GL</varname> variable. Valid options are: <literal>glut, glu, glw, glew, gl</literal> and <literal>linux</literal>. For backwards compatibility, the value of <literal>yes</literal> maps to <literal>glu</literal>.</para> - <example id="use-xorg-example"> + <example xml:id="use-xorg-example"> <title>USE_XORG Example</title> <programlisting>USE_XORG= xrender xft xkbfile xt xaw @@ -6405,12 +6358,12 @@ USE_GL= glu</programlisting> <tgroup cols="2"> <tbody> <row> - <entry><makevar>USES= imake</makevar></entry> + <entry><varname>USES= imake</varname></entry> <entry>The port uses <command>imake</command>.</entry> </row> <row> - <entry><makevar>XMKMF</makevar></entry> + <entry><varname>XMKMF</varname></entry> <entry>Set to the path of <command>xmkmf</command> if not in the <envar>PATH</envar>. Defaults to <literal>xmkmf -a</literal>.</entry> @@ -6419,7 +6372,7 @@ USE_GL= glu</programlisting> </tgroup> </table> - <example id="using-x11-vars"> + <example xml:id="using-x11-vars"> <title>Using X11-Related Variables</title> <programlisting># Use some X11 libraries @@ -6427,20 +6380,20 @@ USE_XORG= x11 xpm</programlisting> </example> </sect2> - <sect2 id="x11-motif"> + <sect2 xml:id="x11-motif"> <title>Ports That Require Motif</title> <para>If your port requires a Motif library, define - <makevar>USES= motif</makevar> in the + <varname>USES= motif</varname> in the <filename>Makefile</filename>. Default Motif implementation is - <filename role="package">x11-toolkits/open-motif</filename>. + <package>x11-toolkits/open-motif</package>. Users can choose - <filename role="package">x11-toolkits/lesstif</filename> - instead by setting <makevar>WANT_LESSTIF</makevar> + <package>x11-toolkits/lesstif</package> + instead by setting <varname>WANT_LESSTIF</varname> variable.</para> - <para>The <makevar>MOTIFLIB</makevar> variable will be set by + <para>The <varname>MOTIFLIB</varname> variable will be set by <filename>bsd.port.mk</filename> to reference the appropriate Motif library. Please patch the source of your port to use <literal>${MOTIFLIB}</literal> wherever @@ -6467,7 +6420,7 @@ USE_XORG= x11 xpm</programlisting> </listitem> </itemizedlist> - <para>Note that <makevar>MOTIFLIB</makevar> (usually) expands + <para>Note that <varname>MOTIFLIB</varname> (usually) expands to <literal>-L/usr/local/lib -lXm</literal> or <literal>/usr/local/lib/libXm.a</literal>, so there is no need to add <literal>-L</literal> or <literal>-l</literal> @@ -6479,7 +6432,7 @@ USE_XORG= x11 xpm</programlisting> <para>If your port installs fonts for the X Window System, put them in - <filename><makevar>LOCALBASE</makevar>/lib/X11/fonts/local</filename>.</para> + <filename>LOCALBASE/lib/X11/fonts/local</filename>.</para> </sect2> <sect2> @@ -6495,12 +6448,11 @@ USE_XORG= x11 xpm</programlisting> <programlisting>USES= display</programlisting> </sect2> - <sect2 id="desktop-entries"> + <sect2 xml:id="desktop-entries"> <title>Desktop Entries</title> - <para>Desktop entries (<ulink - url="http://standards.freedesktop.org/desktop-entry-spec/latest/">a - Freedesktop standard</ulink>) provide a way to + <para>Desktop entries (<link xlink:href="http://standards.freedesktop.org/desktop-entry-spec/latest/">a + Freedesktop standard</link>) provide a way to automatically adjust desktop features when a new program is installed, without requiring user intervention. For example, newly-installed programs automatically appear in @@ -6522,32 +6474,31 @@ USE_XORG= x11 xpm</programlisting> <filename>*.desktop</filename> files should include those files in <filename>pkg-plist</filename> and install them in the - <filename><makevar>$LOCALBASE</makevar>/share/applications</filename> - directory. The <link - linkend="install-macros"><makevar>INSTALL_DATA</makevar> + <filename>$LOCALBASE/share/applications</filename> + directory. The <link linkend="install-macros"><varname>INSTALL_DATA</varname> macro</link> is useful for installing these files.</para> </sect3> - <sect3 id="updating-desktop-database"> + <sect3 xml:id="updating-desktop-database"> <title>Updating Desktop Database</title> <para>If a port has a MimeType entry in its - <filename><replaceable>portname</replaceable>.desktop</filename>, + <filename>portname.desktop</filename>, the desktop database must be updated after install and - deinstall. To do this, define <makevar>USES</makevar>= + deinstall. To do this, define <varname>USES</varname>= desktop-file-utils.</para> </sect3> - <sect3 id="desktop-entries-macro"> + <sect3 xml:id="desktop-entries-macro"> <title>Creating Desktop Entries with the - <makevar>DESKTOP_ENTRIES</makevar> Macro</title> + <varname>DESKTOP_ENTRIES</varname> Macro</title> <para>Desktop entries can be easily created for applications - by using the <makevar>DESKTOP_ENTRIES</makevar> variable. + by using the <varname>DESKTOP_ENTRIES</varname> variable. A file named - <filename><replaceable>name</replaceable>.desktop</filename> + <filename>name.desktop</filename> will be created, installed, and added to the <filename>pkg-plist</filename> automatically. Syntax is:</para> @@ -6555,9 +6506,8 @@ USE_XORG= x11 xpm</programlisting> <programlisting>DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify</programlisting> <para>The list of possible categories is available on the - <ulink - url="http://standards.freedesktop.org/menu-spec/latest/apa.html">Freedesktop - website</ulink>. <makevar>StartupNotify</makevar> + <link xlink:href="http://standards.freedesktop.org/menu-spec/latest/apa.html">Freedesktop + website</link>. <varname>StartupNotify</varname> indicates whether the application is compatible with <emphasis>startup notifications</emphasis>. These are typically a graphic indicator like a clock that appear at @@ -6567,7 +6517,7 @@ USE_XORG= x11 xpm</programlisting> after it has started. Programs that are not compatible with startup notifications would never clear the indicator (potentially confusing and infuriating the user), and - should have <makevar>StartupNotify</makevar> set to + should have <varname>StartupNotify</varname> set to <literal>false</literal> so the indicator is not shown at all.</para> @@ -6582,21 +6532,20 @@ USE_XORG= x11 xpm</programlisting> </sect2> </sect1> - <sect1 id="using-gnome"> + <sect1 xml:id="using-gnome"> <title>Using GNOME</title> <para>The FreeBSD/GNOME project uses its own set of variables to define which GNOME components a particular port uses. A - <ulink - url="http://www.FreeBSD.org/gnome/docs/porting.html">comprehensive - list of these variables</ulink> exists within the + <link xlink:href="http://www.FreeBSD.org/gnome/docs/porting.html">comprehensive + list of these variables</link> exists within the FreeBSD/GNOME project's homepage.</para> </sect1> - <sect1 id="using-qt"> + <sect1 xml:id="using-qt"> <title>Using Qt</title> - <sect2 id="qt-common"> + <sect2 xml:id="qt-common"> <title>Ports That Require Qt</title> <table frame="none"> @@ -6605,7 +6554,7 @@ USE_XORG= x11 xpm</programlisting> <tgroup cols="2"> <tbody> <row> - <entry><makevar>USE_QT_VER</makevar></entry> + <entry><varname>USE_QT_VER</varname></entry> <entry>The port uses the Qt toolkit. The only possible value is <literal>3</literal>. Appropriate parameters are passed to @@ -6614,7 +6563,7 @@ USE_XORG= x11 xpm</programlisting> </row> <row> - <entry><makevar>USE_QT4</makevar></entry> + <entry><varname>USE_QT4</varname></entry> <entry>Specify tool and library dependencies for ports that use Qt 4. See <link linkend="qt4-components">Qt 4 component @@ -6622,41 +6571,41 @@ USE_XORG= x11 xpm</programlisting> </row> <row> - <entry><makevar>QT_PREFIX</makevar></entry> + <entry><varname>QT_PREFIX</varname></entry> <entry>Set to the path where Qt installed to (read-only variable).</entry> </row> <row> - <entry><makevar>MOC</makevar></entry> + <entry><varname>MOC</varname></entry> <entry>Set to the path of <command>moc</command> (read-only variable). Default set according to - <makevar>USE_QT_VER</makevar> value.</entry> + <varname>USE_QT_VER</varname> value.</entry> </row> <row> - <entry><makevar>QTCPPFLAGS</makevar></entry> + <entry><varname>QTCPPFLAGS</varname></entry> <entry>Additional compiler flags passed via - <makevar>CONFIGURE_ENV</makevar> for Qt toolkit. + <varname>CONFIGURE_ENV</varname> for Qt toolkit. Default set according to - <makevar>USE_QT_VER</makevar>.</entry> + <varname>USE_QT_VER</varname>.</entry> </row> <row> - <entry><makevar>QTCFGLIBS</makevar></entry> + <entry><varname>QTCFGLIBS</varname></entry> <entry>Additional libraries for linking passed via - <makevar>CONFIGURE_ENV</makevar> for Qt toolkit. + <varname>CONFIGURE_ENV</varname> for Qt toolkit. Default set according to - <makevar>USE_QT_VER</makevar>.</entry> + <varname>USE_QT_VER</varname>.</entry> </row> <row> - <entry><makevar>QTNONSTANDARD</makevar></entry> + <entry><varname>QTNONSTANDARD</varname></entry> <entry>Suppress modification of - <makevar>CONFIGURE_ENV</makevar>, - <makevar>CONFIGURE_ARGS</makevar>, - <makevar>CPPFLAGS</makevar> and - <makevar>MAKE_ENV</makevar>.</entry> + <varname>CONFIGURE_ENV</varname>, + <varname>CONFIGURE_ARGS</varname>, + <varname>CPPFLAGS</varname> and + <varname>MAKE_ENV</varname>.</entry> </row> </tbody> </tgroup> @@ -6669,44 +6618,44 @@ USE_XORG= x11 xpm</programlisting> <tgroup cols="2"> <tbody> <row> - <entry><makevar>UIC</makevar></entry> + <entry><varname>UIC</varname></entry> <entry>Set to the path of <command>uic</command> (read-only variable).</entry> </row> <row> - <entry><makevar>QMAKE</makevar></entry> + <entry><varname>QMAKE</varname></entry> <entry>Set to the path of <command>qmake</command> (read-only variable).</entry> </row> <row> - <entry><makevar>QMAKESPEC</makevar></entry> + <entry><varname>QMAKESPEC</varname></entry> <entry>Set to the path of configuration file for <command>qmake</command> (read-only variable).</entry> </row> <row> - <entry><makevar>QMAKEFLAGS</makevar></entry> + <entry><varname>QMAKEFLAGS</varname></entry> <entry>Additional flags for <command>qmake</command>.</entry> </row> <row> - <entry><makevar>QT_INCDIR</makevar></entry> + <entry><varname>QT_INCDIR</varname></entry> <entry>Set to Qt 4 include directories (read-only variable).</entry> </row> <row> - <entry><makevar>QT_LIBDIR</makevar></entry> + <entry><varname>QT_LIBDIR</varname></entry> <entry>Set to Qt 4 libraries path (read-only variable).</entry> </row> <row> - <entry><makevar>QT_PLUGINDIR</makevar></entry> + <entry><varname>QT_PLUGINDIR</varname></entry> <entry>Set to Qt 4 plugins path (read-only variable).</entry> </row> @@ -6714,7 +6663,7 @@ USE_XORG= x11 xpm</programlisting> </tgroup> </table> - <para>When <makevar>USE_QT_VER</makevar> is set to + <para>When <varname>USE_QT_VER</varname> is set to <literal>3</literal>, some useful settings are passed to the <command>configure</command> script:</para> @@ -6726,7 +6675,7 @@ CONFIGURE_ENV+= MOC="${MOC}" LIBS="${QTCFGLIBS}" \ QTDIR="${QT_PREFIX}" KDEDIR="${KDE_PREFIX}" CPPFLAGS+= ${QTCPPFLAGS}</programlisting> - <para>If <makevar>USE_QT4</makevar> is set, the following + <para>If <varname>USE_QT4</varname> is set, the following settings are deployed:</para> <programlisting>CONFIGURE_ARGS+= --with-qt-includes=${QT_INCDIR} \ @@ -6742,11 +6691,11 @@ PLIST_SUB+= QT_INCDIR_REL=${QT_INCDIR_REL} \ QT_PLUGINDIR_REL=${QT_PLUGINDIR_REL}</programlisting> </sect2> - <sect2 id="qt4-components"> + <sect2 xml:id="qt4-components"> <title>Component Selection (Qt 4.x Only)</title> <para>Individual Qt 4 tool and library dependencies must be - specified in the <makevar>USE_QT4</makevar> variable. Every + specified in the <varname>USE_QT4</varname> variable. Every component can be suffixed by either <literal>_build</literal> or <literal>_run</literal>, the suffix indicating whether the component should be depended @@ -6758,7 +6707,7 @@ PLIST_SUB+= QT_INCDIR_REL=${QT_INCDIR_REL} \ should be specified with the <literal>_run</literal> suffix. The most commonly used components are listed below (all available components are listed in - <makevar>_USE_QT4_ALL</makevar> in + <varname>_USE_QT4_ALL</varname> in <filename>/usr/ports/Mk/bsd.qt.mk</filename>):</para> <table frame="none"> @@ -6894,7 +6843,7 @@ PLIST_SUB+= QT_INCDIR_REL=${QT_INCDIR_REL} \ </tgroup> </table> - <example id="qt4-components-example"> + <example xml:id="qt4-components-example"> <title>Selecting Qt 4 Components</title> <para>In this example, the ported application uses the Qt 4 @@ -6913,7 +6862,7 @@ PLIST_SUB+= QT_INCDIR_REL=${QT_INCDIR_REL} \ </example> </sect2> - <sect2 id="qt-additional"> + <sect2 xml:id="qt-additional"> <title>Additional Considerations</title> <para>If the application does not provide a @@ -6929,12 +6878,12 @@ do-configure: <para>Note the similarity to the <command>qmake</command> line from the provided <filename>BUILD.sh</filename> script. - Passing <makevar>CONFIGURE_ENV</makevar> ensures + Passing <varname>CONFIGURE_ENV</varname> ensures <command>qmake</command> will see the - <makevar>QMAKESPEC</makevar> variable, without which it + <varname>QMAKESPEC</varname> variable, without which it cannot work. <command>qmake</command> generates standard Makefiles, so it is not necessary to write our own - <maketarget>build</maketarget> target.</para> + <buildtarget>build</buildtarget> target.</para> <para>Qt applications often are written to be cross-platform and often X11/Unix is not the platform they are developed @@ -6960,7 +6909,7 @@ do-configure: Sometimes data such as icons or .desktop files are by default installed into directories which are not scanned by XDG-compatible applications. - <filename role="package">editors/texmaker</filename> is + <package>editors/texmaker</package> is an example for this - look at <filename>patch-texmaker.pro</filename> in the <filename>files</filename> directory of that port for a @@ -6971,14 +6920,14 @@ do-configure: </sect2> </sect1> - <sect1 id="using-kde"> + <sect1 xml:id="using-kde"> <title>Using KDE</title> - <sect2 id="kde4-variables"> + <sect2 xml:id="kde4-variables"> <title>KDE 4 Variable Definitions</title> <para>If your application depends on KDE 4.x, set - <makevar>USE_KDE4</makevar> to the list of required + <varname>USE_KDE4</varname> to the list of required components. <literal>_build</literal> and <literal>_run</literal> suffixes can be used to force components dependency type (e.g., @@ -7128,7 +7077,7 @@ do-configure: </row> <row> - <entry>smokekde<literal></literal></entry> + <entry>smokekde<literal/></entry> <entry>KDE SMOKE libraries</entry> </row> </tbody> @@ -7136,32 +7085,32 @@ do-configure: </table> <para>KDE 4.x ports are installed into - <makevar>KDE4_PREFIX</makevar>, which is + <varname>KDE4_PREFIX</varname>, which is <filename>/usr/local/kde4</filename> currently. This is achieved by specifying the <literal>kdeprefix</literal> component, which overrides the default - <makevar>PREFIX</makevar>. The ports however respect any - <makevar>PREFIX</makevar> set via <envar>MAKEFLAGS</envar> + <varname>PREFIX</varname>. The ports however respect any + <varname>PREFIX</varname> set via <envar>MAKEFLAGS</envar> environment variable and/or <command>make</command> arguments.</para> - <example id="kde4-components-example"> - <title><makevar>USE_KDE4</makevar> Example</title> + <example xml:id="kde4-components-example"> + <title><varname>USE_KDE4</varname> Example</title> <para>This is a simple example for a KDE 4 port. <literal>USES= cmake:outsource</literal> instructs the port to utilize <application>CMake</application>, a configuration tool widely used by KDE 4 projects (see <xref linkend="using-cmake"/> for detailed usage). - <makevar>USE_KDE4</makevar> brings dependency on KDE + <varname>USE_KDE4</varname> brings dependency on KDE libraries and makes port using <command>automoc4</command> at build stage. Required KDE components and other dependencies can be determined through configure log. - <makevar>USE_KDE4</makevar> does not imply - <makevar>USE_QT4</makevar>. If a port requires some + <varname>USE_KDE4</varname> does not imply + <varname>USE_QT4</varname>. If a port requires some Qt 4 components, they should be specified in - <makevar>USE_QT4</makevar>.</para> + <varname>USE_QT4</varname>.</para> <programlisting>USES= cmake:outsource USE_KDE4= kdelibs kdeprefix automoc4 @@ -7170,22 +7119,22 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </sect2> </sect1> - <sect1 id="using-java"> + <sect1 xml:id="using-java"> <title>Using Java</title> - <sect2 id="java-variables"> + <sect2 xml:id="java-variables"> <title>Variable Definitions</title> <para>If your port needs a Java™ Development Kit (JDK™) to either build, run or even extract the distfile, then it should define - <makevar>USE_JAVA</makevar>.</para> + <varname>USE_JAVA</varname>.</para> <para>There are several JDKs in the ports collection, from various vendors, and in several versions. If your port must use one of these versions, you can define which one. The most current version, and &os; default is - <filename role="package">java/openjdk6</filename>.</para> + <package>java/openjdk6</package>.</para> <table frame="none"> <title>Variables Which May be Set by Ports That Use @@ -7201,13 +7150,13 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <tbody> <row> - <entry><makevar>USE_JAVA</makevar></entry> + <entry><varname>USE_JAVA</varname></entry> <entry>Should be defined for the remaining variables to have any effect.</entry> </row> <row> - <entry><makevar>JAVA_VERSION</makevar></entry> + <entry><varname>JAVA_VERSION</varname></entry> <entry>List of space-separated suitable Java versions for the port. An optional <literal>"+"</literal> allows you to specify a range of versions (allowed @@ -7216,14 +7165,14 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </row> <row> - <entry><makevar>JAVA_OS</makevar></entry> + <entry><varname>JAVA_OS</varname></entry> <entry>List of space-separated suitable JDK port operating systems for the port (allowed values: <literal>native linux</literal>).</entry> </row> <row> - <entry><makevar>JAVA_VENDOR</makevar></entry> + <entry><varname>JAVA_VENDOR</varname></entry> <entry>List of space-separated suitable JDK port vendors for the port (allowed values: <literal>freebsd bsdjava sun @@ -7231,21 +7180,21 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </row> <row> - <entry><makevar>JAVA_BUILD</makevar></entry> + <entry><varname>JAVA_BUILD</varname></entry> <entry>When set, it means that the selected JDK port should be added to the build dependencies of the port.</entry> </row> <row> - <entry><makevar>JAVA_RUN</makevar></entry> + <entry><varname>JAVA_RUN</varname></entry> <entry>When set, it means that the selected JDK port should be added to the run dependencies of the port.</entry> </row> <row> - <entry><makevar>JAVA_EXTRACT</makevar></entry> + <entry><varname>JAVA_EXTRACT</varname></entry> <entry>When set, it means that the selected JDK port should be added to the extract dependencies of the port.</entry> @@ -7255,7 +7204,7 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </table> <para>Below is the list of all settings a port will receive - after setting <makevar>USE_JAVA</makevar>:</para> + after setting <varname>USE_JAVA</varname>:</para> <table frame="none"> <title>Variables Provided to Ports That Use Java</title> @@ -7270,60 +7219,60 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <tbody> <row> - <entry><makevar>JAVA_PORT</makevar></entry> + <entry><varname>JAVA_PORT</varname></entry> <entry>The name of the JDK port (e.g., <literal>'java/openjdk6'</literal>).</entry> </row> <row> - <entry><makevar>JAVA_PORT_VERSION</makevar></entry> + <entry><varname>JAVA_PORT_VERSION</varname></entry> <entry>The full version of the JDK port (e.g., <literal>'1.6.0'</literal>). If you only need the first two digits of this version number, use - <makevar>${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}</makevar>.</entry> + <varname>${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}</varname>.</entry> </row> <row> - <entry><makevar>JAVA_PORT_OS</makevar></entry> + <entry><varname>JAVA_PORT_OS</varname></entry> <entry>The operating system used by the JDK port (e.g., <literal>'native'</literal>).</entry> </row> <row> - <entry><makevar>JAVA_PORT_VENDOR</makevar></entry> + <entry><varname>JAVA_PORT_VENDOR</varname></entry> <entry>The vendor of the JDK port (e.g., <literal>'openjdk'</literal>).</entry> </row> <row> - <entry><makevar>JAVA_PORT_OS_DESCRIPTION</makevar></entry> + <entry><varname>JAVA_PORT_OS_DESCRIPTION</varname></entry> <entry>Description of the operating system used by the JDK port (e.g., <literal>'Native'</literal>).</entry> </row> <row> - <entry><makevar>JAVA_PORT_VENDOR_DESCRIPTION</makevar></entry> + <entry><varname>JAVA_PORT_VENDOR_DESCRIPTION</varname></entry> <entry>Description of the vendor of the JDK port (e.g., <literal>'OpenJDK BSD Porting Team'</literal>).</entry> </row> <row> - <entry><makevar>JAVA_HOME</makevar></entry> + <entry><varname>JAVA_HOME</varname></entry> <entry>Path to the installation directory of the JDK (e.g., <filename>'/usr/local/openjdk6'</filename>).</entry> </row> <row> - <entry><makevar>JAVAC</makevar></entry> + <entry><varname>JAVAC</varname></entry> <entry>Path to the Java compiler to use (e.g., <filename>'/usr/local/openjdk6/bin/javac'</filename>).</entry> </row> <row> - <entry><makevar>JAR</makevar></entry> + <entry><varname>JAR</varname></entry> <entry>Path to the <command>jar</command> tool to use (e.g., <filename>'/usr/local/openjdk6/bin/jar'</filename> @@ -7332,81 +7281,81 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </row> <row> - <entry><makevar>APPLETVIEWER</makevar></entry> + <entry><varname>APPLETVIEWER</varname></entry> <entry>Path to the <command>appletviewer</command> utility (e.g., <filename>'/usr/local/openjdk6/bin/appletviewer'</filename>).</entry> </row> <row> - <entry><makevar>JAVA</makevar></entry> + <entry><varname>JAVA</varname></entry> <entry>Path to the <command>java</command> executable. Use this for executing Java programs (e.g., <filename>'/usr/local/openjdk6/bin/java'</filename>).</entry> </row> <row> - <entry><makevar>JAVADOC</makevar></entry> + <entry><varname>JAVADOC</varname></entry> <entry>Path to the <command>javadoc</command> utility program.</entry> </row> <row> - <entry><makevar>JAVAH</makevar></entry> + <entry><varname>JAVAH</varname></entry> <entry>Path to the <command>javah</command> program.</entry> </row> <row> - <entry><makevar>JAVAP</makevar></entry> + <entry><varname>JAVAP</varname></entry> <entry>Path to the <command>javap</command> program.</entry> </row> <row> - <entry><makevar>JAVA_KEYTOOL</makevar></entry> + <entry><varname>JAVA_KEYTOOL</varname></entry> <entry>Path to the <command>keytool</command> utility program.</entry> </row> <row> - <entry><makevar>JAVA_N2A</makevar></entry> + <entry><varname>JAVA_N2A</varname></entry> <entry>Path to the <command>native2ascii</command> tool.</entry> </row> <row> - <entry><makevar>JAVA_POLICYTOOL</makevar></entry> + <entry><varname>JAVA_POLICYTOOL</varname></entry> <entry>Path to the <command>policytool</command> program.</entry> </row> <row> - <entry><makevar>JAVA_SERIALVER</makevar></entry> + <entry><varname>JAVA_SERIALVER</varname></entry> <entry>Path to the <command>serialver</command> utility program.</entry> </row> <row> - <entry><makevar>RMIC</makevar></entry> + <entry><varname>RMIC</varname></entry> <entry>Path to the RMI stub/skeleton generator, <command>rmic</command>.</entry> </row> <row> - <entry><makevar>RMIREGISTRY</makevar></entry> + <entry><varname>RMIREGISTRY</varname></entry> <entry>Path to the RMI registry program, <command>rmiregistry</command>.</entry> </row> <row> - <entry><makevar>RMID</makevar></entry> + <entry><varname>RMID</varname></entry> <entry>Path to the RMI daemon program <command>rmid</command>.</entry> </row> <row> - <entry><makevar>JAVA_CLASSES</makevar></entry> + <entry><varname>JAVA_CLASSES</varname></entry> <entry>Path to the archive that contains the JDK class files, <filename>${JAVA_HOME}/jre/lib/rt.jar</filename>.</entry> @@ -7435,21 +7384,21 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <tbody> <row> - <entry><makevar>JAVASHAREDIR</makevar></entry> + <entry><varname>JAVASHAREDIR</varname></entry> <entry>The base directory for everything related to Java. Default: <filename>${PREFIX}/share/java</filename>.</entry> </row> <row> - <entry><makevar>JAVAJARDIR</makevar></entry> + <entry><varname>JAVAJARDIR</varname></entry> <entry>The directory where JAR files should be installed. Default: <filename>${JAVASHAREDIR}/classes</filename>.</entry> </row> <row> - <entry><makevar>JAVALIBDIR</makevar></entry> + <entry><varname>JAVALIBDIR</varname></entry> <entry>The directory where JAR files installed by other ports are located. Default: <filename>${LOCALBASE}/share/java/classes</filename>.</entry> @@ -7459,26 +7408,26 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </table> <para>The related entries are defined in both - <makevar>PLIST_SUB</makevar> (documented in + <varname>PLIST_SUB</varname> (documented in <xref linkend="plist-sub"/>) and - <makevar>SUB_LIST</makevar>.</para> + <varname>SUB_LIST</varname>.</para> </sect2> - <sect2 id="java-building-with-ant"> + <sect2 xml:id="java-building-with-ant"> <title>Building with Ant</title> <para>When the port is to be built using Apache Ant, it has to - define <makevar>USE_ANT</makevar>. Ant is thus considered + define <varname>USE_ANT</varname>. Ant is thus considered to be the sub-make command. When no <literal>do-build</literal> target is defined by the port, a default one will be set that simply runs Ant according to - <makevar>MAKE_ENV</makevar>, <makevar>MAKE_ARGS</makevar> - and <makevar>ALL_TARGET</makevar>. This is similar to the - <makevar>USES= gmake</makevar> mechanism, which is + <varname>MAKE_ENV</varname>, <varname>MAKE_ARGS</varname> + and <varname>ALL_TARGET</varname>. This is similar to the + <varname>USES= gmake</varname> mechanism, which is documented in <xref linkend="building"/>.</para> </sect2> - <sect2 id="java-best-practices"> + <sect2 xml:id="java-best-practices"> <title>Best Practices</title> <para>When porting a Java library, your port should install @@ -7514,18 +7463,18 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> particular JDK, it is therefore a complex task to specify the packing list (<filename>pkg-plist</filename>). This is one reason why porters are strongly encouraged to use the - <makevar>PORTDOCS</makevar> macro. Moreover, even if you + <varname>PORTDOCS</varname> macro. Moreover, even if you can predict the set of files that will be generated by <command>javadoc</command>, the size of the resulting <filename>pkg-plist</filename> advocates for the use of - <makevar>PORTDOCS</makevar>.</para> + <varname>PORTDOCS</varname>.</para> - <para>The default value for <makevar>DATADIR</makevar> is + <para>The default value for <varname>DATADIR</varname> is <filename>${PREFIX}/share/${PORTNAME}</filename>. It is a - good idea to override <makevar>DATADIR</makevar> to + good idea to override <varname>DATADIR</varname> to <filename>${JAVASHAREDIR}/${PORTNAME}</filename> for Java - ports. Indeed, <makevar>DATADIR</makevar> is automatically - added to <makevar>PLIST_SUB</makevar> (documented in + ports. Indeed, <varname>DATADIR</varname> is automatically + added to <varname>PLIST_SUB</varname> (documented in <xref linkend="plist-sub"/>) so you may use <literal>%%DATADIR%%</literal> directly in <filename>pkg-plist</filename>.</para> @@ -7534,16 +7483,15 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> directly installing them from a binary distribution, there is no defined policy at the time of writing. However, people from the - <ulink url="http://www.freebsd.org/java/">&os; Java - Project</ulink> encourage porters to have their ports + <link xlink:href="http://www.freebsd.org/java/">&os; Java + Project</link> encourage porters to have their ports built from source whenever it is a trivial task.</para> <para>All the features that have been presented in this section are implemented in <filename>bsd.java.mk</filename>. If you ever think that your port needs more sophisticated - Java support, please first have a look at the <ulink - url="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=markup">bsd.java.mk - SVN log</ulink> as it usually takes some time + Java support, please first have a look at the <link xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=markup">bsd.java.mk + SVN log</link> as it usually takes some time to document the latest features. Then, if you think the support you are lacking would be beneficial to many other Java ports, feel free to discuss it on the &a.java;.</para> @@ -7557,15 +7505,15 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <filename>bsd.java.mk</filename>.</para> <para>Similarly, there is a defined policy regarding the - <makevar>CATEGORIES</makevar> of a Java port, which is + <varname>CATEGORIES</varname> of a Java port, which is detailed in <xref linkend="makefile-categories"/>.</para> </sect2> </sect1> - <sect1 id="using-php"> + <sect1 xml:id="using-php"> <title>Web Applications, Apache and PHP</title> - <sect2 id="using-apache"> + <sect2 xml:id="using-apache"> <title>Apache</title> <table frame="none"> @@ -7575,7 +7523,7 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <tbody> <row> - <entry><makevar>USE_APACHE</makevar></entry> + <entry><varname>USE_APACHE</varname></entry> <entry>The port requires Apache. Possible values: <literal>yes</literal> (gets any version), <literal>22</literal>, <literal>24</literal>, @@ -7583,24 +7531,23 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> etc. The default APACHE version is <literal>22</literal>. More details are available in <filename>ports/Mk/bsd.apache.mk</filename> and - at <ulink - url="http://wiki.freebsd.org/Apache/">wiki.freebsd.org/Apache/</ulink>.</entry> + at <link xlink:href="http://wiki.freebsd.org/Apache/">wiki.freebsd.org/Apache/</link>.</entry> </row> <row> - <entry><makevar>APXS</makevar></entry> + <entry><varname>APXS</varname></entry> <entry>Full path to the <command>apxs</command> binary. Can be overridden in your port.</entry> </row> <row> - <entry><makevar>HTTPD</makevar></entry> + <entry><varname>HTTPD</varname></entry> <entry>Full path to the <command>httpd</command> binary. Can be overridden in your port.</entry> </row> <row> - <entry><makevar>APACHE_VERSION</makevar></entry> + <entry><varname>APACHE_VERSION</varname></entry> <entry>The version of present Apache installation (read-only variable). This variable is only available after inclusion of @@ -7610,21 +7557,21 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </row> <row> - <entry><makevar>APACHEMODDIR</makevar></entry> + <entry><varname>APACHEMODDIR</varname></entry> <entry>Directory for Apache modules. This variable is automatically expanded in <filename>pkg-plist</filename>.</entry> </row> <row> - <entry><makevar>APACHEINCLUDEDIR</makevar></entry> + <entry><varname>APACHEINCLUDEDIR</varname></entry> <entry>Directory for Apache headers. This variable is automatically expanded in <filename>pkg-plist</filename>.</entry> </row> <row> - <entry><makevar>APACHEETCDIR</makevar></entry> + <entry><varname>APACHEETCDIR</varname></entry> <entry>Directory for Apache configuration files. This variable is automatically expanded in <filename>pkg-plist</filename>.</entry> @@ -7640,46 +7587,46 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <tbody> <row> - <entry><makevar>MODULENAME</makevar></entry> + <entry><varname>MODULENAME</varname></entry> <entry>Name of the module. Default value is - <makevar>PORTNAME</makevar>. Example: + <varname>PORTNAME</varname>. Example: <literal>mod_hello</literal></entry> </row> <row> - <entry><makevar>SHORTMODNAME</makevar></entry> + <entry><varname>SHORTMODNAME</varname></entry> <entry>Short name of the module. Automatically - derived from <makevar>MODULENAME</makevar>, but can + derived from <varname>MODULENAME</varname>, but can be overridden. Example: <literal>hello</literal></entry> </row> <row> - <entry><makevar>AP_FAST_BUILD</makevar></entry> + <entry><varname>AP_FAST_BUILD</varname></entry> <entry>Use <command>apxs</command> to compile and install the module.</entry> </row> <row> - <entry><makevar>AP_GENPLIST</makevar></entry> + <entry><varname>AP_GENPLIST</varname></entry> <entry>Also automatically creates a <filename>pkg-plist</filename>.</entry> </row> <row> - <entry><makevar>AP_INC</makevar></entry> + <entry><varname>AP_INC</varname></entry> <entry>Adds a directory to a header search path during compilation.</entry> </row> <row> - <entry><makevar>AP_LIB</makevar></entry> + <entry><varname>AP_LIB</varname></entry> <entry>Adds a directory to a library search path during compilation.</entry> </row> <row> - <entry><makevar>AP_EXTRAS</makevar></entry> + <entry><varname>AP_EXTRAS</varname></entry> <entry>Additional flags to pass to <command>apxs</command>.</entry> </row> @@ -7688,20 +7635,20 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </table> </sect2> - <sect2 id="web-apps"> + <sect2 xml:id="web-apps"> <title>Web Applications</title> <para>Web applications should be installed into - <filename><makevar>PREFIX</makevar>/www/<replaceable>appname</replaceable></filename>. + <filename>PREFIX/www/appname</filename>. For your convenience, this path is available both in <filename>Makefile</filename> and in - <filename>pkg-plist</filename> as <makevar>WWWDIR</makevar>, - and the path relative to <makevar>PREFIX</makevar> is + <filename>pkg-plist</filename> as <varname>WWWDIR</varname>, + and the path relative to <varname>PREFIX</varname> is available in <filename>Makefile</filename> as - <makevar>WWWDIR_REL</makevar>.</para> + <varname>WWWDIR_REL</varname>.</para> <para>The user and group of web server process are available - as <makevar>WWWOWN</makevar> and <makevar>WWWGRP</makevar>, + as <varname>WWWOWN</varname> and <varname>WWWGRP</varname>, in case you need to change the ownership of some files. The default values of both are <literal>www</literal>. If you want different values for your port, use @@ -7713,7 +7660,7 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> app on different web server than Apache.</para> </sect2> - <sect2 id="php-variables"> + <sect2 xml:id="php-variables"> <title>PHP</title> <table frame="none"> @@ -7722,7 +7669,7 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <tgroup cols="2"> <tbody> <row> - <entry><makevar>USE_PHP</makevar></entry> + <entry><varname>USE_PHP</varname></entry> <entry>The port requires PHP. The value <literal>yes</literal> adds a dependency on PHP. The list of required PHP extensions can be specified @@ -7731,7 +7678,7 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </row> <row> - <entry><makevar>DEFAULT_PHP_VER</makevar></entry> + <entry><varname>DEFAULT_PHP_VER</varname></entry> <entry>Selects which major version of PHP will be installed as a dependency when no PHP is installed yet. Default is <literal>5</literal>. Possible @@ -7740,53 +7687,53 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </row> <row> - <entry><makevar>IGNORE_WITH_PHP</makevar></entry> + <entry><varname>IGNORE_WITH_PHP</varname></entry> <entry>The port does not work with PHP of the given version. Possible values: <literal>4</literal>, <literal>5</literal></entry> </row> <row> - <entry><makevar>USE_PHPIZE</makevar></entry> + <entry><varname>USE_PHPIZE</varname></entry> <entry>The port will be built as a PHP extension.</entry> </row> <row> - <entry><makevar>USE_PHPEXT</makevar></entry> + <entry><varname>USE_PHPEXT</varname></entry> <entry>The port will be treated as a PHP extension, including installation and registration in the extension registry.</entry> </row> <row> - <entry><makevar>USE_PHP_BUILD</makevar></entry> + <entry><varname>USE_PHP_BUILD</varname></entry> <entry>Set PHP as a build dependency.</entry> </row> <row> - <entry><makevar>WANT_PHP_CLI</makevar></entry> + <entry><varname>WANT_PHP_CLI</varname></entry> <entry>Want the CLI (command line) version of PHP.</entry> </row> <row> - <entry><makevar>WANT_PHP_CGI</makevar></entry> + <entry><varname>WANT_PHP_CGI</varname></entry> <entry>Want the CGI version of PHP.</entry> </row> <row> - <entry><makevar>WANT_PHP_MOD</makevar></entry> + <entry><varname>WANT_PHP_MOD</varname></entry> <entry>Want the Apache module version of PHP.</entry> </row> <row> - <entry><makevar>WANT_PHP_SCR</makevar></entry> + <entry><varname>WANT_PHP_SCR</varname></entry> <entry>Want the CLI or the CGI version of PHP.</entry> </row> <row> - <entry><makevar>WANT_PHP_WEB</makevar></entry> + <entry><varname>WANT_PHP_WEB</varname></entry> <entry>Want the Apache module or the CGI version of PHP.</entry> </row> @@ -7800,10 +7747,10 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <para>Porting PEAR modules is a very simple process.</para> - <para>Use the variables <makevar>FILES</makevar>, - <makevar>TESTS</makevar>, <makevar>DATA</makevar>, - <makevar>SQLS</makevar>, <makevar>SCRIPTFILES</makevar>, - <makevar>DOCS</makevar> and <makevar>EXAMPLES</makevar> to + <para>Use the variables <varname>FILES</varname>, + <varname>TESTS</varname>, <varname>DATA</varname>, + <varname>SQLS</varname>, <varname>SCRIPTFILES</varname>, + <varname>DOCS</varname> and <varname>EXAMPLES</varname> to list the files you want to install. All listed files will be automatically installed into the appropriate locations and added to <filename>pkg-plist</filename>.</para> @@ -7813,7 +7760,7 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> on the last line of the <filename>Makefile</filename>.</para> - <example id="pear-makefile"> + <example xml:id="pear-makefile"> <title>Example Makefile for PEAR Class</title> <programlisting>PORTNAME= Date @@ -7844,19 +7791,19 @@ _DOCSDIR= . </sect2> </sect1> - <sect1 id="using-python"> + <sect1 xml:id="using-python"> <title>Using Python</title> <para>The Ports Collection supports parallel installation of multiple Python versions. Ports should make sure to use a correct <command>python</command> interpreter, according to - the user-settable <makevar>PYTHON_VERSION</makevar> variable. + the user-settable <varname>PYTHON_VERSION</varname> variable. Most prominently, this means replacing the path to <command>python</command> executable in scripts with the value - of <makevar>PYTHON_CMD</makevar> variable.</para> + of <varname>PYTHON_CMD</varname> variable.</para> <para>Ports that install files under - <makevar>PYTHON_SITELIBDIR</makevar> should use the + <varname>PYTHON_SITELIBDIR</varname> should use the <literal>pyXY-</literal> package name prefix, so their package name embeds the version of Python they are installed into.</para> @@ -7869,7 +7816,7 @@ _DOCSDIR= . <tgroup cols="2"> <tbody> <row> - <entry><makevar>USE_PYTHON</makevar></entry> + <entry><varname>USE_PYTHON</varname></entry> <entry>The port needs Python. Minimal required version can be specified with values such as <literal>2.6+</literal>. Version ranges can also be @@ -7878,35 +7825,35 @@ _DOCSDIR= . </row> <row> - <entry><makevar>USE_PYDISTUTILS</makevar></entry> + <entry><varname>USE_PYDISTUTILS</varname></entry> <entry>Use Python distutils for configuring, compiling and installing. This is required when the port comes with <filename>setup.py</filename>. This overrides - the <maketarget>do-build</maketarget> and - <maketarget>do-install</maketarget> targets and may - also override <maketarget>do-configure</maketarget> if - <makevar>GNU_CONFIGURE</makevar> is not + the <buildtarget>do-build</buildtarget> and + <buildtarget>do-install</buildtarget> targets and may + also override <buildtarget>do-configure</buildtarget> if + <varname>GNU_CONFIGURE</varname> is not defined.</entry> </row> <row> - <entry><makevar>PYTHON_PKGNAMEPREFIX</makevar></entry> - <entry>Used as a <makevar>PKGNAMEPREFIX</makevar> to + <entry><varname>PYTHON_PKGNAMEPREFIX</varname></entry> + <entry>Used as a <varname>PKGNAMEPREFIX</varname> to distinguish packages for different Python versions. Example: <literal>py24-</literal></entry> </row> <row> - <entry><makevar>PYTHON_SITELIBDIR</makevar></entry> + <entry><varname>PYTHON_SITELIBDIR</varname></entry> <entry>Location of the site-packages tree, that contains installation path of Python (usually - <makevar>LOCALBASE</makevar>). The - <makevar>PYTHON_SITELIBDIR</makevar> variable can be + <varname>LOCALBASE</varname>). The + <varname>PYTHON_SITELIBDIR</varname> variable can be very useful when installing Python modules.</entry> </row> <row> - <entry><makevar>PYTHONPREFIX_SITELIBDIR</makevar></entry> + <entry><varname>PYTHONPREFIX_SITELIBDIR</varname></entry> <entry>The PREFIX-clean variant of PYTHON_SITELIBDIR. Always use <literal>%%PYTHON_SITELIBDIR%%</literal> in <filename>pkg-plist</filename> when possible. The @@ -7916,32 +7863,32 @@ _DOCSDIR= . </row> <row> - <entry><makevar>PYTHON_CMD</makevar></entry> + <entry><varname>PYTHON_CMD</varname></entry> <entry>Python interpreter command line, including version number.</entry> </row> <row> - <entry><makevar>PYNUMERIC</makevar></entry> + <entry><varname>PYNUMERIC</varname></entry> <entry>Dependency line for numeric extension.</entry> </row> <row> - <entry><makevar>PYNUMPY</makevar></entry> + <entry><varname>PYNUMPY</varname></entry> <entry>Dependency line for the new numeric extension, numpy. (PYNUMERIC is deprecated by upstream vendor).</entry> </row> <row> - <entry><makevar>PYXML</makevar></entry> + <entry><varname>PYXML</varname></entry> <entry>Dependency line for XML extension (not needed for Python 2.0 and higher as it is also in base distribution).</entry> </row> <row> - <entry><makevar>USE_TWISTED</makevar></entry> + <entry><varname>USE_TWISTED</varname></entry> <entry>Add dependency on twistedCore. The list of required components can be specified as a value of this variable. Example: @@ -7949,10 +7896,10 @@ _DOCSDIR= . </row> <row> - <entry><makevar>USE_ZOPE</makevar></entry> + <entry><varname>USE_ZOPE</varname></entry> <entry>Add dependency on Zope, a web application platform. Change Python dependency to Python 2.7. - Set <makevar>ZOPEBASEDIR</makevar> containing a + Set <varname>ZOPEBASEDIR</varname> containing a directory with Zope installation.</entry> </row> </tbody> @@ -7963,12 +7910,12 @@ _DOCSDIR= . <filename>/usr/ports/Mk/bsd.python.mk</filename>.</para> <para>Some Python applications claim to have - <makevar>DESTDIR</makevar> support (which would be required for + <varname>DESTDIR</varname> support (which would be required for staging) but it is broken (Mailman up to 2.1.16, for instance). This can be worked around by recompiling the scripts. This can - be done, for example, in the <maketarget>post-build</maketarget> + be done, for example, in the <buildtarget>post-build</buildtarget> target. Assuming the Python scripts are supposed to reside in - <makevar>PYTHONPREFIX_SITELIBDIR</makevar> after + <varname>PYTHONPREFIX_SITELIBDIR</varname> after installation, this solution can be applied:</para> <programlisting>(cd ${STAGEDIR}${PREFIX} \ @@ -7978,29 +7925,29 @@ _DOCSDIR= . <para>This recompiles the sources with a path relative to the stage directory, and prepends the value of - <makevar>PREFIX</makevar> to the file name recorded in the + <varname>PREFIX</varname> to the file name recorded in the byte-compiled output file by <literal>-d</literal>. <literal>-f</literal> is required to force recompilation, and the <literal>:S;${PREFIX}/;;</literal> strips prefixes from - the value of the <makevar>PYTHONPREFIX_SITELIBDIR</makevar> + the value of the <varname>PYTHONPREFIX_SITELIBDIR</varname> variable to make it relative to - <makevar>PREFIX</makevar>.</para> + <varname>PREFIX</varname>.</para> <para>Python 2.7 or newer is required for this. It does not work with Python 2.6.</para> </sect1> - <sect1 id="using-tcl"> + <sect1 xml:id="using-tcl"> <title>Using <application>Tcl/Tk</application></title> <para>The Ports Collection supports parallel installation of multiple <application>Tcl/Tk</application> versions. Ports should try to support at least the default <application>Tcl/Tk</application> version and higher with the - <makevar>USE_TCL</makevar> and <makevar>USE_TK</makevar> + <varname>USE_TCL</varname> and <varname>USE_TK</varname> variables. It is possible to specify the desired version of <command>tcl</command> with the - <makevar>WITH_TCL_VER</makevar> variable.</para> + <varname>WITH_TCL_VER</varname> variable.</para> <table frame="none"> <title>The Most Useful Variables for Ports That Use @@ -8009,23 +7956,23 @@ _DOCSDIR= . <tgroup cols="2"> <tbody> <row> - <entry><makevar>USE_TCL</makevar></entry> + <entry><varname>USE_TCL</varname></entry> <entry>The port depends on the <application>Tcl</application> library (not the shell). Minimal required version can be specified with values such as 84+. Individual unsupported versions can be specified with the - <makevar>INVALID_TCL_VER</makevar> variable.</entry> + <varname>INVALID_TCL_VER</varname> variable.</entry> </row> <row> - <entry><makevar>USE_TCL_BUILD</makevar></entry> + <entry><varname>USE_TCL_BUILD</varname></entry> <entry>The port needs <application>Tcl</application> only during the build time.</entry> </row> <row> - <entry><makevar>USE_TCL_WRAPPER</makevar></entry> + <entry><varname>USE_TCL_WRAPPER</varname></entry> <entry>Ports that require the <application>Tcl</application> shell and do not require a specific <literal>tclsh</literal> version @@ -8036,48 +7983,48 @@ _DOCSDIR= . </row> <row> - <entry><makevar>WITH_TCL_VER</makevar></entry> + <entry><varname>WITH_TCL_VER</varname></entry> <entry>User-defined variable that sets the desired <application>Tcl</application> version.</entry> </row> <row> - <entry><makevar><replaceable>UNIQUENAME</replaceable>_WITH_TCL_VER</makevar></entry> - <entry>Like <makevar>WITH_TCL_VER</makevar>, but + <entry><varname><replaceable>UNIQUENAME</replaceable>_WITH_TCL_VER</varname></entry> + <entry>Like <varname>WITH_TCL_VER</varname>, but per-port.</entry> </row> <row> - <entry><makevar>USE_TCL_THREADS</makevar></entry> + <entry><varname>USE_TCL_THREADS</varname></entry> <entry>Require a threaded build of <application>Tcl/Tk</application>.</entry> </row> <row> - <entry><makevar>USE_TK</makevar></entry> + <entry><varname>USE_TK</varname></entry> <entry>The port depends on the <application>Tk</application> library (not the wish - shell). Implies <makevar>USE_TCL</makevar> with the + shell). Implies <varname>USE_TCL</varname> with the same value. For more information see the description - of <makevar>USE_TCL</makevar> variable.</entry> + of <varname>USE_TCL</varname> variable.</entry> </row> <row> - <entry><makevar>USE_TK_BUILD</makevar></entry> - <entry>Analog to the <makevar>USE_TCL_BUILD</makevar> + <entry><varname>USE_TK_BUILD</varname></entry> + <entry>Analog to the <varname>USE_TCL_BUILD</varname> variable.</entry> </row> <row> - <entry><makevar>USE_TK_WRAPPER</makevar></entry> - <entry>Analog to the <makevar>USE_TCL_WRAPPER</makevar> + <entry><varname>USE_TK_WRAPPER</varname></entry> + <entry>Analog to the <varname>USE_TCL_WRAPPER</varname> variable.</entry> </row> <row> - <entry><makevar>WITH_TK_VER</makevar></entry> - <entry>Analog to the <makevar>WITH_TCL_VER</makevar> - variable and implies <makevar>WITH_TCL_VER</makevar> + <entry><varname>WITH_TK_VER</varname></entry> + <entry>Analog to the <varname>WITH_TCL_VER</varname> + variable and implies <varname>WITH_TCL_VER</varname> of the same value.</entry> </row> </tbody> @@ -8088,13 +8035,13 @@ _DOCSDIR= . <filename>/usr/ports/Mk/bsd.tcl.mk</filename>.</para> </sect1> - <sect1 id="using-emacs"> + <sect1 xml:id="using-emacs"> <title>Using Emacs</title> <para>This section is yet to be written.</para> </sect1> - <sect1 id="using-ruby"> + <sect1 xml:id="using-ruby"> <title>Using Ruby</title> <table frame="none"> @@ -8109,24 +8056,24 @@ _DOCSDIR= . </thead> <tbody> <row> - <entry><makevar>USE_RUBY</makevar></entry> + <entry><varname>USE_RUBY</varname></entry> <entry>The port requires Ruby.</entry> </row> <row> - <entry><makevar>USE_RUBY_EXTCONF</makevar></entry> + <entry><varname>USE_RUBY_EXTCONF</varname></entry> <entry>The port uses <filename>extconf.rb</filename> to configure.</entry> </row> <row> - <entry><makevar>USE_RUBY_SETUP</makevar></entry> + <entry><varname>USE_RUBY_SETUP</varname></entry> <entry>The port uses <filename>setup.rb</filename> to configure.</entry> </row> <row> - <entry><makevar>RUBY_SETUP</makevar></entry> + <entry><varname>RUBY_SETUP</varname></entry> <entry>Set to the alternative name of <filename>setup.rb</filename>. Common value is <filename>install.rb</filename>.</entry> @@ -8157,42 +8104,42 @@ _DOCSDIR= . <tbody> <row> - <entry><makevar>RUBY_PKGNAMEPREFIX</makevar></entry> - <entry>Used as a <makevar>PKGNAMEPREFIX</makevar> to + <entry><varname>RUBY_PKGNAMEPREFIX</varname></entry> + <entry>Used as a <varname>PKGNAMEPREFIX</varname> to distinguish packages for different Ruby versions.</entry> <entry><literal>ruby18-</literal></entry> </row> <row> - <entry><makevar>RUBY_VERSION</makevar></entry> + <entry><varname>RUBY_VERSION</varname></entry> <entry>Full version of Ruby in the form of <literal>x.y.z</literal>.</entry> <entry><literal>1.8.2</literal></entry> </row> <row> - <entry><makevar>RUBY_SITELIBDIR</makevar></entry> + <entry><varname>RUBY_SITELIBDIR</varname></entry> <entry>Architecture independent libraries installation path.</entry> <entry><literal>/usr/local/lib/ruby/site_ruby/1.8</literal></entry> </row> <row> - <entry><makevar>RUBY_SITEARCHLIBDIR</makevar></entry> + <entry><varname>RUBY_SITEARCHLIBDIR</varname></entry> <entry>Architecture dependent libraries installation path.</entry> <entry><literal>/usr/local/lib/ruby/site_ruby/1.8/amd64-freebsd6</literal></entry> </row> <row> - <entry><makevar>RUBY_MODDOCDIR</makevar></entry> + <entry><varname>RUBY_MODDOCDIR</varname></entry> <entry>Module documentation installation path.</entry> <entry><literal>/usr/local/share/doc/ruby18/patsy</literal></entry> </row> <row> - <entry><makevar>RUBY_MODEXAMPLESDIR</makevar></entry> + <entry><varname>RUBY_MODEXAMPLESDIR</varname></entry> <entry>Module examples installation path.</entry> <entry><literal>/usr/local/share/examples/ruby18/patsy</literal></entry> </row> @@ -8205,106 +8152,95 @@ _DOCSDIR= . </sect1> - <sect1 id="using-sdl"> + <sect1 xml:id="using-sdl"> <title>Using SDL</title> - <para>The <makevar>USE_SDL</makevar> variable is used to + <para>The <varname>USE_SDL</varname> variable is used to autoconfigure the dependencies for ports which use an SDL based library like - <filename role="package">devel/sdl12</filename> and <filename - role="package">x11-toolkits/sdl_gui</filename>.</para> + <package>devel/sdl12</package> and <package>x11-toolkits/sdl_gui</package>.</para> <para>The following SDL libraries are recognized at the moment:</para> <itemizedlist> <listitem> - <para>sdl: <filename - role="package">devel/sdl12</filename></para> + <para>sdl: <package>devel/sdl12</package></para> </listitem> <listitem> - <para>gfx: <filename - role="package">graphics/sdl_gfx</filename></para> + <para>gfx: <package>graphics/sdl_gfx</package></para> </listitem> <listitem> - <para>gui: <filename - role="package">x11-toolkits/sdl_gui</filename></para> + <para>gui: <package>x11-toolkits/sdl_gui</package></para> </listitem> <listitem> - <para>image: <filename - role="package">graphics/sdl_image</filename></para> + <para>image: <package>graphics/sdl_image</package></para> </listitem> <listitem> - <para>ldbad: <filename - role="package">devel/sdl_ldbad</filename></para> + <para>ldbad: <package>devel/sdl_ldbad</package></para> </listitem> <listitem> - <para>mixer: <filename - role="package">audio/sdl_mixer</filename></para> + <para>mixer: <package>audio/sdl_mixer</package></para> </listitem> <listitem> - <para>mm: <filename - role="package">devel/sdlmm</filename></para> + <para>mm: <package>devel/sdlmm</package></para> </listitem> <listitem> - <para>net: <filename - role="package">net/sdl_net</filename></para> + <para>net: <package>net/sdl_net</package></para> </listitem> <listitem> - <para>sound: <filename - role="package">audio/sdl_sound</filename></para> + <para>sound: <package>audio/sdl_sound</package></para> </listitem> <listitem> - <para>ttf: <filename - role="package">graphics/sdl_ttf</filename></para> + <para>ttf: <package>graphics/sdl_ttf</package></para> </listitem> </itemizedlist> <para>Therefore, if a port has a dependency on - <filename role="package">net/sdl_net</filename> and - <filename role="package">audio/sdl_mixer</filename>, + <package>net/sdl_net</package> and + <package>audio/sdl_mixer</package>, the syntax will be:</para> <programlisting>USE_SDL= net mixer</programlisting> <para>The dependency - <filename role="package">devel/sdl12</filename>, which is - required by <filename role="package">net/sdl_net</filename> - and <filename role="package">audio/sdl_mixer</filename>, is + <package>devel/sdl12</package>, which is + required by <package>net/sdl_net</package> + and <package>audio/sdl_mixer</package>, is automatically added as well.</para> - <para>If you use <makevar>USE_SDL</makevar>, it will + <para>If you use <varname>USE_SDL</varname>, it will automatically:</para> <itemizedlist> <listitem> <para>Add a dependency on <application>sdl12-config</application> to - <makevar>BUILD_DEPENDS</makevar></para> + <varname>BUILD_DEPENDS</varname></para> </listitem> <listitem> - <para>Add the variable <makevar>SDL_CONFIG</makevar> to - <makevar>CONFIGURE_ENV</makevar></para> + <para>Add the variable <varname>SDL_CONFIG</varname> to + <varname>CONFIGURE_ENV</varname></para> </listitem> <listitem> <para>Add the dependencies of the selected libraries to the - <makevar>LIB_DEPENDS</makevar></para> + <varname>LIB_DEPENDS</varname></para> </listitem> </itemizedlist> <para>To check whether an SDL library is available, you can do - it with the <makevar>WANT_SDL</makevar> variable:</para> + it with the <varname>WANT_SDL</varname> variable:</para> <programlisting>WANT_SDL= yes @@ -8317,14 +8253,14 @@ USE_SDL+= mixer .include <bsd.port.post.mk></programlisting> </sect1> - <sect1 id="using-wx"> + <sect1 xml:id="using-wx"> <title>Using <application>wxWidgets</application></title> <para>This section describes the status of the <application>wxWidgets</application> libraries in the ports tree and its integration with the ports system.</para> - <sect2 id="wx-introduction"> + <sect2 xml:id="wx-introduction"> <title>Introduction</title> <para>There are many versions of the @@ -8346,7 +8282,7 @@ USE_SDL+= mixer have to be patched.</para> </sect2> - <sect2 id="wx-version"> + <sect2 xml:id="wx-version"> <title>Version Selection</title> <para>To make your port use a specific version of @@ -8354,7 +8290,7 @@ USE_SDL+= mixer available for defining (if only one is defined the other will be set to a default value):</para> - <table id="wx-ver-sel-table" frame="none"> + <table xml:id="wx-ver-sel-table" frame="none"> <title>Variables to Select <application>wxWidgets</application> Versions</title> @@ -8369,13 +8305,13 @@ USE_SDL+= mixer <tbody> <row> - <entry><makevar>USE_WX</makevar></entry> + <entry><varname>USE_WX</varname></entry> <entry>List of versions the port can use</entry> <entry>All available versions</entry> </row> <row> - <entry><makevar>USE_WX_NOT</makevar></entry> + <entry><varname>USE_WX_NOT</varname></entry> <entry>List of versions the port can not use</entry> <entry>None</entry> </row> @@ -8402,20 +8338,17 @@ USE_SDL+= mixer <tbody> <row> <entry><literal>2.4</literal></entry> - <entry><filename - role="package">x11-toolkits/wxgtk24</filename></entry> + <entry><package>x11-toolkits/wxgtk24</package></entry> </row> <row> <entry><literal>2.6</literal></entry> - <entry><filename - role="package">x11-toolkits/wxgtk26</filename></entry> + <entry><package>x11-toolkits/wxgtk26</package></entry> </row> <row> <entry><literal>2.8</literal></entry> - <entry><filename - role="package">x11-toolkits/wxgtk28</filename></entry> + <entry><package>x11-toolkits/wxgtk28</package></entry> </row> </tbody> </tgroup> @@ -8426,8 +8359,7 @@ USE_SDL+= mixer come in Unicode version and are installed by a slave port named like the normal one plus a <literal>-unicode</literal> suffix, but this can be - handled with variables (see <xref - linkend="wx-unicode"/>).</para> + handled with variables (see <xref linkend="wx-unicode"/>).</para> </note> <para>The variables in <xref linkend="wx-ver-sel-table"/> can @@ -8489,12 +8421,12 @@ USE_SDL+= mixer <tbody> <row> - <entry><makevar>WANT_WX_VER</makevar></entry> + <entry><varname>WANT_WX_VER</varname></entry> <entry>the port</entry> </row> <row> - <entry><makevar>WITH_WX_VER</makevar></entry> + <entry><varname>WITH_WX_VER</varname></entry> <entry>the user</entry> </row> </tbody> @@ -8502,13 +8434,13 @@ USE_SDL+= mixer </table> </sect2> - <sect2 id="wx-components"> + <sect2 xml:id="wx-components"> <title>Component Selection</title> <para>There are other applications that, while not being <application>wxWidgets</application> libraries, are related to them. These applications can be specified in the - <makevar>WX_COMPS</makevar> variable. The following + <varname>WX_COMPS</varname> variable. The following components are available:</para> <table frame="none"> @@ -8581,19 +8513,19 @@ USE_SDL+= mixer <row> <entry><literal>build</literal></entry> <entry>Component is required for building, equivalent - to <makevar>BUILD_DEPENDS</makevar></entry> + to <varname>BUILD_DEPENDS</varname></entry> </row> <row> <entry><literal>run</literal></entry> <entry>Component is required for running, equivalent - to <makevar>RUN_DEPENDS</makevar></entry> + to <varname>RUN_DEPENDS</varname></entry> </row> <row> <entry><literal>lib</literal></entry> <entry>Component is required for building and running, - equivalent to <makevar>LIB_DEPENDS</makevar></entry> + equivalent to <varname>LIB_DEPENDS</varname></entry> </row> </tbody> </tgroup> @@ -8602,7 +8534,7 @@ USE_SDL+= mixer <para>The default values for the components are detailed in the following table:</para> - <table id="wx-def-dep-types" frame="none"> + <table xml:id="wx-def-dep-types" frame="none"> <title>Default <application>wxWidgets</application> Dependency Types</title> @@ -8643,7 +8575,7 @@ USE_SDL+= mixer </tgroup> </table> - <example id="wx-components-example"> + <example xml:id="wx-components-example"> <title>Selecting <application>wxWidgets</application> Components</title> @@ -8657,7 +8589,7 @@ WX_COMPS= wx contrib</programlisting> </example> </sect2> - <sect2 id="wx-unicode"> + <sect2 xml:id="wx-unicode"> <title>Unicode</title> <para>The <application>wxWidgets</application> library @@ -8665,7 +8597,7 @@ WX_COMPS= wx contrib</programlisting> the ports tree both versions are available and can be selected with the following variables:</para> - <table id="wx-unicode-var-table" frame="none"> + <table xml:id="wx-unicode-var-table" frame="none"> <title>Variables to Select Unicode in <application>wxWidgets</application> Versions</title> @@ -8681,29 +8613,29 @@ WX_COMPS= wx contrib</programlisting> <tbody> <row> - <entry><makevar>WX_UNICODE</makevar></entry> + <entry><varname>WX_UNICODE</varname></entry> <entry>The port works <emphasis>only</emphasis> with the Unicode version</entry> <entry>the port</entry> </row> <row> - <entry><makevar>WANT_UNICODE</makevar></entry> + <entry><varname>WANT_UNICODE</varname></entry> <entry>The port works with both versions but prefers the Unicode one</entry> <entry>the port</entry> </row> <row> - <entry><makevar>WITH_UNICODE</makevar></entry> + <entry><varname>WITH_UNICODE</varname></entry> <entry>The port will use the Unicode version</entry> <entry>the user</entry> </row> <row> - <entry><makevar>WITHOUT_UNICODE</makevar></entry> + <entry><varname>WITHOUT_UNICODE</varname></entry> <entry>The port will use the normal version if - supported (when <makevar>WX_UNICODE</makevar> is not + supported (when <varname>WX_UNICODE</varname> is not defined)</entry> <entry>the user</entry> </row> @@ -8712,23 +8644,23 @@ WX_COMPS= wx contrib</programlisting> </table> <warning> - <para>Do not use <makevar>WX_UNICODE</makevar> for ports + <para>Do not use <varname>WX_UNICODE</varname> for ports that can use both Unicode and normal versions. If you want the port to use Unicode by default define - <makevar>WANT_UNICODE</makevar> instead.</para> + <varname>WANT_UNICODE</varname> instead.</para> </warning> </sect2> - <sect2 id="wx-version-detection"> + <sect2 xml:id="wx-version-detection"> <title>Detecting Installed Versions</title> <para>To detect an installed version you have to define - <makevar>WANT_WX</makevar>. If you do not set it to a + <varname>WANT_WX</varname>. If you do not set it to a specific version then the components will have a version - suffix. The <makevar>HAVE_WX</makevar> variable will be + suffix. The <varname>HAVE_WX</varname> variable will be filled after detection.</para> - <example id="wx-ver-det-example"> + <example xml:id="wx-ver-det-example"> <title>Detecting Installed <application>wxWidgets</application> Versions and Components</title> @@ -8765,7 +8697,7 @@ CONFIGURE_ARGS+= --enable-wxpython </example> </sect2> - <sect2 id="wx-defined-variables"> + <sect2 xml:id="wx-defined-variables"> <title>Defined Variables</title> <para>The following variables are available in the port (after @@ -8786,7 +8718,7 @@ CONFIGURE_ARGS+= --enable-wxpython <tbody> <row> - <entry><makevar>WX_CONFIG</makevar></entry> + <entry><varname>WX_CONFIG</varname></entry> <entry>The path to the <application>wxWidgets</application> <command>wx-config</command> script (with different @@ -8794,7 +8726,7 @@ CONFIGURE_ARGS+= --enable-wxpython </row> <row> - <entry><makevar>WXRC_CMD</makevar></entry> + <entry><varname>WXRC_CMD</varname></entry> <entry>The path to the <application>wxWidgets</application> <command>wxrc</command> program (with different @@ -8802,14 +8734,14 @@ CONFIGURE_ARGS+= --enable-wxpython </row> <row> - <entry><makevar>WX_VERSION</makevar></entry> + <entry><varname>WX_VERSION</varname></entry> <entry>The <application>wxWidgets</application> version that is going to be used (e.g., <literal>2.6</literal>)</entry> </row> <row> - <entry><makevar>WX_UNICODE</makevar></entry> + <entry><varname>WX_UNICODE</varname></entry> <entry>If not defined but Unicode is going to be used then it will be defined</entry> </row> @@ -8818,16 +8750,16 @@ CONFIGURE_ARGS+= --enable-wxpython </table> </sect2> - <sect2 id="wx-premk"> + <sect2 xml:id="wx-premk"> <title>Processing in <filename>bsd.port.pre.mk</filename></title> <para>If you need to use the variables for running commands right after including <filename>bsd.port.pre.mk</filename> - you need to define <makevar>WX_PREMK</makevar>.</para> + you need to define <varname>WX_PREMK</varname>.</para> <important> - <para>If you define <makevar>WX_PREMK</makevar>, then the + <para>If you define <varname>WX_PREMK</varname>, then the version, dependencies, components and defined variables will not change if you modify the <application>wxWidgets</application> port variables @@ -8835,12 +8767,12 @@ CONFIGURE_ARGS+= --enable-wxpython <filename>bsd.port.pre.mk</filename>.</para> </important> - <example id="wx-premk-example"> + <example xml:id="wx-premk-example"> <title>Using <application>wxWidgets</application> Variables in Commands</title> <para>The following fragment illustrates the use of - <makevar>WX_PREMK</makevar> by running the + <varname>WX_PREMK</varname> by running the <command>wx-config</command> script to obtain the full version string, assign it to a variable and pass it to the program.</para> @@ -8860,11 +8792,11 @@ PLIST_SUB+= VERSION="${VER_STR}" <note> <para>The <application>wxWidgets</application> variables can be safely used in commands when they are inside targets - without the need of <makevar>WX_PREMK</makevar>.</para> + without the need of <varname>WX_PREMK</varname>.</para> </note> </sect2> - <sect2 id="wx-additional-config-args"> + <sect2 xml:id="wx-additional-config-args"> <title>Additional <command>configure</command> Arguments</title> @@ -8872,12 +8804,12 @@ PLIST_SUB+= VERSION="${VER_STR}" find <application>wxWidgets</application> with just the <literal>WX_CONFIG</literal> environment variable set, requiring additional arguments. The - <makevar>WX_CONF_ARGS</makevar> variable can be used for + <varname>WX_CONF_ARGS</varname> variable can be used for provide them.</para> <table frame="none"> <title>Legal Values for - <makevar>WX_CONF_ARGS</makevar></title> + <varname>WX_CONF_ARGS</varname></title> <tgroup cols="2"> <thead> @@ -8904,14 +8836,14 @@ PLIST_SUB+= VERSION="${VER_STR}" </sect2> </sect1> - <sect1 id="using-lua"> + <sect1 xml:id="using-lua"> <title>Using <application>Lua</application></title> <para>This section describes the status of the <application>Lua</application> libraries in the ports tree and its integration with the ports system.</para> - <sect2 id="lua-introduction"> + <sect2 xml:id="lua-introduction"> <title>Introduction</title> <para>There are many versions of the @@ -8927,7 +8859,7 @@ PLIST_SUB+= VERSION="${VER_STR}" compiler and linker.</para> </sect2> - <sect2 id="lua-version"> + <sect2 xml:id="lua-version"> <title>Version Selection</title> <para>To make your port use a specific version of @@ -8935,7 +8867,7 @@ PLIST_SUB+= VERSION="${VER_STR}" available for defining (if only one is defined the other will be set to a default value):</para> - <table id="lua-ver-sel-table" frame="none"> + <table xml:id="lua-ver-sel-table" frame="none"> <title>Variables to Select <application>Lua</application> Versions</title> @@ -8950,13 +8882,13 @@ PLIST_SUB+= VERSION="${VER_STR}" <tbody> <row> - <entry><makevar>USE_LUA</makevar></entry> + <entry><varname>USE_LUA</varname></entry> <entry>List of versions the port can use</entry> <entry>All available versions</entry> </row> <row> - <entry><makevar>USE_LUA_NOT</makevar></entry> + <entry><varname>USE_LUA_NOT</varname></entry> <entry>List of versions the port can not use</entry> <entry>None</entry> </row> @@ -8983,20 +8915,17 @@ PLIST_SUB+= VERSION="${VER_STR}" <tbody> <row> <entry><literal>4.0</literal></entry> - <entry><filename - role="package">lang/lua4</filename></entry> + <entry><package>lang/lua4</package></entry> </row> <row> <entry><literal>5.0</literal></entry> - <entry><filename - role="package">lang/lua50</filename></entry> + <entry><package>lang/lua50</package></entry> </row> <row> <entry><literal>5.1</literal></entry> - <entry><filename - role="package">lang/lua</filename></entry> + <entry><package>lang/lua</package></entry> </row> </tbody> </tgroup> @@ -9061,19 +8990,19 @@ PLIST_SUB+= VERSION="${VER_STR}" <tbody> <row> - <entry><makevar>WANT_LUA_VER</makevar></entry> + <entry><varname>WANT_LUA_VER</varname></entry> <entry>the port</entry> </row> <row> - <entry><makevar>WITH_LUA_VER</makevar></entry> + <entry><varname>WITH_LUA_VER</varname></entry> <entry>the user</entry> </row> </tbody> </tgroup> </table> - <example id="lua-version-example"> + <example xml:id="lua-version-example"> <title>Selecting the <application>Lua</application> Version</title> @@ -9081,20 +9010,20 @@ PLIST_SUB+= VERSION="${VER_STR}" <application>Lua</application> version <literal>5.0</literal> or <literal>5.1</literal>, and uses <literal>5.0</literal> by default. It can be overridden - by the user with <makevar>WITH_LUA_VER</makevar>.</para> + by the user with <varname>WITH_LUA_VER</varname>.</para> <programlisting>USE_LUA= 5.0-5.1 WANT_LUA_VER= 5.0</programlisting> </example> </sect2> - <sect2 id="lua-components"> + <sect2 xml:id="lua-components"> <title>Component Selection</title> <para>There are other applications that, while not being <application>Lua</application> libraries, are related to them. These applications can be specified in the - <makevar>LUA_COMPS</makevar> variable. The following + <varname>LUA_COMPS</varname> variable. The following components are available:</para> <table frame="none"> @@ -9160,19 +9089,19 @@ WANT_LUA_VER= 5.0</programlisting> <row> <entry><literal>build</literal></entry> <entry>Component is required for building, equivalent - to <makevar>BUILD_DEPENDS</makevar></entry> + to <varname>BUILD_DEPENDS</varname></entry> </row> <row> <entry><literal>run</literal></entry> <entry>Component is required for running, equivalent - to <makevar>RUN_DEPENDS</makevar></entry> + to <varname>RUN_DEPENDS</varname></entry> </row> <row> <entry><literal>lib</literal></entry> <entry>Component is required for building and running, - equivalent to <makevar>LIB_DEPENDS</makevar></entry> + equivalent to <varname>LIB_DEPENDS</varname></entry> </row> </tbody> </tgroup> @@ -9181,7 +9110,7 @@ WANT_LUA_VER= 5.0</programlisting> <para>The default values for the components are detailed in the following table:</para> - <table id="lua-def-dep-types" frame="none"> + <table xml:id="lua-def-dep-types" frame="none"> <title>Default <application>Lua</application> Dependency Types</title> @@ -9215,7 +9144,7 @@ WANT_LUA_VER= 5.0</programlisting> </tgroup> </table> - <example id="lua-components-example"> + <example xml:id="lua-components-example"> <title>Selecting <application>Lua</application> Components</title> @@ -9229,16 +9158,16 @@ LUA_COMPS= lua ruby</programlisting> </example> </sect2> - <sect2 id="lua-version-detection"> + <sect2 xml:id="lua-version-detection"> <title>Detecting Installed Versions</title> <para>To detect an installed version you have to define - <makevar>WANT_LUA</makevar>. If you do not set it to a + <varname>WANT_LUA</varname>. If you do not set it to a specific version then the components will have a version - suffix. The <makevar>HAVE_LUA</makevar> variable will be + suffix. The <varname>HAVE_LUA</varname> variable will be filled after detection.</para> - <example id="lua-ver-det-example"> + <example xml:id="lua-ver-det-example"> <title>Detecting Installed <application>Lua</application> Versions and Components</title> @@ -9274,7 +9203,7 @@ CONFIGURE_ARGS+= --enable-tolua </example> </sect2> - <sect2 id="lua-defined-variables"> + <sect2 xml:id="lua-defined-variables"> <title>Defined Variables</title> <para>The following variables are available in the port (after @@ -9295,34 +9224,34 @@ CONFIGURE_ARGS+= --enable-tolua <tbody> <row> - <entry><makevar>LUA_VER</makevar></entry> + <entry><varname>LUA_VER</varname></entry> <entry>The <application>Lua</application> version that is going to be used (e.g., <literal>5.1</literal>)</entry> </row> <row> - <entry><makevar>LUA_VER_SH</makevar></entry> + <entry><varname>LUA_VER_SH</varname></entry> <entry>The <application>Lua</application> shared library major version (e.g., <literal>1</literal>)</entry> </row> <row> - <entry><makevar>LUA_VER_STR</makevar></entry> + <entry><varname>LUA_VER_STR</varname></entry> <entry>The <application>Lua</application> version without the dots (e.g., <literal>51</literal>)</entry> </row> <row> - <entry><makevar>LUA_PREFIX</makevar></entry> + <entry><varname>LUA_PREFIX</varname></entry> <entry>The prefix where <application>Lua</application> (and components) is installed</entry> </row> <row> - <entry><makevar>LUA_SUBDIR</makevar></entry> + <entry><varname>LUA_SUBDIR</varname></entry> <entry>The directory under <filename>${PREFIX}/bin</filename>, <filename>${PREFIX}/share</filename> and @@ -9331,7 +9260,7 @@ CONFIGURE_ARGS+= --enable-tolua </row> <row> - <entry><makevar>LUA_INCDIR</makevar></entry> + <entry><varname>LUA_INCDIR</varname></entry> <entry>The directory where <application>Lua</application> and <application>tolua</application> header files are @@ -9339,7 +9268,7 @@ CONFIGURE_ARGS+= --enable-tolua </row> <row> - <entry><makevar>LUA_LIBDIR</makevar></entry> + <entry><varname>LUA_LIBDIR</varname></entry> <entry>The directory where <application>Lua</application> and <application>tolua</application> libraries are @@ -9347,39 +9276,39 @@ CONFIGURE_ARGS+= --enable-tolua </row> <row> - <entry><makevar>LUA_MODLIBDIR</makevar></entry> + <entry><varname>LUA_MODLIBDIR</varname></entry> <entry>The directory where <application>Lua</application> module libraries (<filename>.so</filename>) are installed</entry> </row> <row> - <entry><makevar>LUA_MODSHAREDIR</makevar></entry> + <entry><varname>LUA_MODSHAREDIR</varname></entry> <entry>The directory where <application>Lua</application> modules (<filename>.lua</filename>) are installed</entry> </row> <row> - <entry><makevar>LUA_PKGNAMEPREFIX</makevar></entry> + <entry><varname>LUA_PKGNAMEPREFIX</varname></entry> <entry>The package name prefix used by <application>Lua</application> modules</entry> </row> <row> - <entry><makevar>LUA_CMD</makevar></entry> + <entry><varname>LUA_CMD</varname></entry> <entry>The path to the <application>Lua</application> interpreter</entry> </row> <row> - <entry><makevar>LUAC_CMD</makevar></entry> + <entry><varname>LUAC_CMD</varname></entry> <entry>The path to the <application>Lua</application> compiler</entry> </row> <row> - <entry><makevar>TOLUA_CMD</makevar></entry> + <entry><varname>TOLUA_CMD</varname></entry> <entry>The path to the <application>tolua</application> program</entry> </row> @@ -9387,7 +9316,7 @@ CONFIGURE_ARGS+= --enable-tolua </tgroup> </table> - <example id="lua-variables-example"> + <example xml:id="lua-variables-example"> <title>Telling the Port Where to Find <application>Lua</application></title> @@ -9402,16 +9331,16 @@ CONFIGURE_ENV= CPPFLAGS="-I${LUA_INCDIR}" LDFLAGS="-L${LUA_LIBDIR}"</programlist </example> </sect2> - <sect2 id="lua-premk"> + <sect2 xml:id="lua-premk"> <title>Processing in <filename>bsd.port.pre.mk</filename></title> <para>If you need to use the variables for running commands right after including <filename>bsd.port.pre.mk</filename> - you need to define <makevar>LUA_PREMK</makevar>.</para> + you need to define <varname>LUA_PREMK</varname>.</para> <important> - <para>If you define <makevar>LUA_PREMK</makevar>, then the + <para>If you define <varname>LUA_PREMK</varname>, then the version, dependencies, components and defined variables will not change if you modify the <application>Lua</application> port variables @@ -9419,12 +9348,12 @@ CONFIGURE_ENV= CPPFLAGS="-I${LUA_INCDIR}" LDFLAGS="-L${LUA_LIBDIR}"</programlist <filename>bsd.port.pre.mk</filename>.</para> </important> - <example id="lua-premk-example"> + <example xml:id="lua-premk-example"> <title>Using <application>Lua</application> Variables in Commands</title> <para>The following fragment illustrates the use of - <makevar>LUA_PREMK</makevar> by running the + <varname>LUA_PREMK</varname> by running the <application>Lua</application> interpreter to obtain the full version string, assign it to a variable and pass it to the program.</para> @@ -9444,27 +9373,27 @@ CFLAGS+= -DLUA_VERSION_STRING="${VER_STR}" <note> <para>The <application>Lua</application> variables can be safely used in commands when they are inside targets - without the need of <makevar>LUA_PREMK</makevar>.</para> + without the need of <varname>LUA_PREMK</varname>.</para> </note> </sect2> </sect1> - <sect1 id="using-iconv"> + <sect1 xml:id="using-iconv"> <title>Using <command>iconv</command></title> - <para>After 2013-10-08 (<svnref>254273</svnref>), &os; + <para>After 2013-10-08 (<revnumber>254273</revnumber>), &os; 10-CURRENT and newer versions have a native <command>iconv</command> in the operating system. On earlier versions, - <filename role="package">converters/libiconv</filename> was + <package>converters/libiconv</package> was used as a dependency.</para> <para>For software that needs <command>iconv</command>, define <literal>USES=iconv</literal>. &os; versions before - 10-CURRENT on 2013-08-13 (<svnref>254273</svnref>) do not have + 10-CURRENT on 2013-08-13 (<revnumber>254273</revnumber>) do not have a native <command>iconv</command>. On these earlier versions, a dependency on - <filename role="package">converters/libiconv</filename> will + <package>converters/libiconv</package> will be added automatically.</para> <para>When a port defines <literal>USES=iconv</literal>, these @@ -9477,25 +9406,24 @@ CFLAGS+= -DLUA_VERSION_STRING="${VER_STR}" <entry>Variable name</entry> <entry>Purpose</entry> <entry>Value before &os; 10-CURRENT - <svnref>254273</svnref> (2013-08-13)</entry> + <revnumber>254273</revnumber> (2013-08-13)</entry> <entry>Value after &os; 10-CURRENT - <svnref>254273</svnref> (2013-08-13)</entry> + <revnumber>254273</revnumber> (2013-08-13)</entry> </row> </thead> <tbody> <row> - <entry><makevar>ICONV_CMD</makevar></entry> + <entry><varname>ICONV_CMD</varname></entry> <entry>Directory where the <command>iconv</command> binary resides</entry> <entry><literal>${LOCALBASE}/bin/iconv</literal></entry> - <entry><filename - class="directory">/usr/bin/iconv</filename></entry> + <entry><filename>/usr/bin/iconv</filename></entry> </row> <row> - <entry><makevar>ICONV_LIB</makevar></entry> + <entry><varname>ICONV_LIB</varname></entry> <entry><command>ld</command> argument to link to <filename>libiconv</filename> (if needed)</entry> <entry><literal>-liconv</literal></entry> @@ -9503,17 +9431,16 @@ CFLAGS+= -DLUA_VERSION_STRING="${VER_STR}" </row> <row> - <entry><makevar>ICONV_PREFIX</makevar></entry> + <entry><varname>ICONV_PREFIX</varname></entry> <entry>Directory where the <command>iconv</command> implementation resides (useful for configure scripts)</entry> <entry><literal>${LOCALBASE}</literal></entry> - <entry><filename - class="directory">/usr</filename></entry> + <entry><filename>/usr</filename></entry> </row> <row> - <entry><makevar>ICONV_CONFIGURE_ARG</makevar></entry> + <entry><varname>ICONV_CONFIGURE_ARG</varname></entry> <entry>Preconstructed configure argument for configure scripts</entry> <entry><literal>--with-libiconv-prefix=${LOCALBASE}</literal></entry> @@ -9521,7 +9448,7 @@ CFLAGS+= -DLUA_VERSION_STRING="${VER_STR}" </row> <row> - <entry><makevar>ICONV_CONFIGURE_BASE</makevar></entry> + <entry><varname>ICONV_CONFIGURE_BASE</varname></entry> <entry>Preconstructed configure argument for configure scripts</entry> <entry><literal>--with-libiconv=${LOCALBASE}</literal></entry> @@ -9533,17 +9460,17 @@ CFLAGS+= -DLUA_VERSION_STRING="${VER_STR}" <para>These two examples automatically populate the variables with the correct value for systems using - <filename role="package">converters/libiconv</filename> or the + <package>converters/libiconv</package> or the native <command>iconv</command> respectively:</para> - <example id="iconv-simple-use"> + <example xml:id="iconv-simple-use"> <title>Simple <command>iconv</command> Usage</title> <programlisting>USES= iconv LDFLAGS+= -L${LOCALBASE}/lib ${ICONV_LIB}</programlisting> </example> - <example id="iconv-configure-use"> + <example xml:id="iconv-configure-use"> <title><command>iconv</command> Usage with <command>configure</command></title> @@ -9551,7 +9478,7 @@ LDFLAGS+= -L${LOCALBASE}/lib ${ICONV_LIB}</programlisting> CONFIGURE_ARGS+=${ICONV_CONFIGURE_ARG}</programlisting> </example> - <para>As shown above, <makevar>ICONV_LIB</makevar> is empty when + <para>As shown above, <varname>ICONV_LIB</varname> is empty when a native <command>iconv</command> is present. This can be used to detect the native <command>iconv</command> and respond appropriately.</para> @@ -9561,7 +9488,7 @@ CONFIGURE_ARGS+=${ICONV_CONFIGURE_ARG}</programlisting> configure script. This approach can be used to solve that problem:</para> - <example id="iconv-reinplace"> + <example xml:id="iconv-reinplace"> <title>Fixing Hardcoded <literal>-liconv</literal></title> <programlisting>USES= iconv @@ -9574,9 +9501,9 @@ post-patch: perform operations depending on whether there is a native <command>iconv</command>. <filename>bsd.port.pre.mk</filename> must be included before - testing the value of <makevar>ICONV_LIB</makevar>:</para> + testing the value of <varname>ICONV_LIB</varname>:</para> - <example id="iconv-conditional"> + <example xml:id="iconv-conditional"> <title>Checking for Native <command>iconv</command> Availability</title> @@ -9594,63 +9521,53 @@ post-patch: </example> </sect1> - <sect1 id="using-xfce"> + <sect1 xml:id="using-xfce"> <title>Using Xfce</title> - <para>The <makevar>USE_XFCE</makevar> variable is used to + <para>The <varname>USE_XFCE</varname> variable is used to autoconfigure the dependencies for ports which use an Xfce based library or application like - <filename role="package">x11-toolkits/libxfce4gui</filename> - and <filename - role="package">x11-wm/xfce4-panel</filename>.</para> + <package>x11-toolkits/libxfce4gui</package> + and <package>x11-wm/xfce4-panel</package>.</para> <para>The following Xfce libraries and applications are recognized at the moment:</para> <itemizedlist> <listitem> - <para>libexo: <filename - role="package">x11/libexo</filename></para> + <para>libexo: <package>x11/libexo</package></para> </listitem> <listitem> - <para>libgui: <filename - role="package">x11-toolkits/libxfce4gui</filename></para> + <para>libgui: <package>x11-toolkits/libxfce4gui</package></para> </listitem> <listitem> - <para>libutil: <filename - role="package">x11/libxfce4util</filename></para> + <para>libutil: <package>x11/libxfce4util</package></para> </listitem> <listitem> - <para>libmcs: <filename - role="package">x11/libxfce4mcs</filename></para> + <para>libmcs: <package>x11/libxfce4mcs</package></para> </listitem> <listitem> - <para>mcsmanager: <filename - role="package">sysutils/xfce4-mcs-manager</filename></para> + <para>mcsmanager: <package>sysutils/xfce4-mcs-manager</package></para> </listitem> <listitem> - <para>panel: <filename - role="package">x11-wm/xfce4-panel</filename></para> + <para>panel: <package>x11-wm/xfce4-panel</package></para> </listitem> <listitem> - <para>thunar: <filename - role="package">x11-fm/thunar</filename></para> + <para>thunar: <package>x11-fm/thunar</package></para> </listitem> <listitem> - <para>wm: <filename - role="package">x11-wm/xfce4-wm</filename></para> + <para>wm: <package>x11-wm/xfce4-wm</package></para> </listitem> <listitem> - <para>xfdev: <filename - role="package">dev/xfce4-dev-tools</filename></para> + <para>xfdev: <package>dev/xfce4-dev-tools</package></para> </listitem> </itemizedlist> @@ -9659,25 +9576,25 @@ post-patch: <itemizedlist> <listitem> <para>configenv: Use this if your port requires a special - modified <makevar>CONFIGURE_ENV</makevar> to find its + modified <varname>CONFIGURE_ENV</varname> to find its required libraries.</para> <programlisting>-I${LOCALBASE}/include -L${LOCALBASE}/lib</programlisting> <para>gets added to CPPFLAGS to - <makevar>CONFIGURE_ENV</makevar>.</para> + <varname>CONFIGURE_ENV</varname>.</para> </listitem> </itemizedlist> <para>Therefore, if a port has a dependency on - <filename role="package">sysutils/xfce4-mcs-manager</filename> + <package>sysutils/xfce4-mcs-manager</package> and requires the special CPPFLAGS in its configure environment, the syntax will be:</para> <programlisting>USE_XFCE= mcsmanager configenv</programlisting> </sect1> - <sect1 id="using-mozilla"> + <sect1 xml:id="using-mozilla"> <title>Using Mozilla</title> <table frame="none"> @@ -9687,7 +9604,7 @@ post-patch: <tbody> <row> - <entry><makevar>USE_GECKO</makevar></entry> + <entry><varname>USE_GECKO</varname></entry> <entry>Gecko backend the port can handle. Possible values: <literal>libxul</literal> (<filename>libxul.so</filename>), @@ -9697,7 +9614,7 @@ post-patch: </row> <row> - <entry><makevar>USE_FIREFOX</makevar></entry> + <entry><varname>USE_FIREFOX</varname></entry> <entry>The port requires Firefox as a runtime dependency. Possible values: <literal>yes</literal> (get default version), <literal>40</literal>, @@ -9707,7 +9624,7 @@ post-patch: </row> <row> - <entry><makevar>USE_FIREFOX_BUILD</makevar></entry> + <entry><varname>USE_FIREFOX_BUILD</varname></entry> <entry>The port requires Firefox as a buildtime dependency. Possible values: see USE_FIREFOX. This automatically sets USE_FIREFOX and assigns the same @@ -9715,7 +9632,7 @@ post-patch: </row> <row> - <entry><makevar>USE_SEAMONKEY</makevar></entry> + <entry><varname>USE_SEAMONKEY</varname></entry> <entry>The port requires SeaMonkey as a runtime dependency. Possible values: <literal>yes</literal> (get default version), <literal>20</literal>, @@ -9725,7 +9642,7 @@ post-patch: </row> <row> - <entry><makevar>USE_SEAMONKEY_BUILD</makevar></entry> + <entry><varname>USE_SEAMONKEY_BUILD</varname></entry> <entry>The port requires SeaMonkey as a buildtime dependency. Possible values: see USE_SEAMONKEY. This automatically sets USE_SEAMONKEY and assigns the same @@ -9733,7 +9650,7 @@ post-patch: </row> <row> - <entry><makevar>USE_THUNDERBIRD</makevar></entry> + <entry><varname>USE_THUNDERBIRD</varname></entry> <entry>The port requires Thunderbird as a runtime dependency. Possible values: <literal>yes</literal> (get default version), <literal>31</literal>, @@ -9743,7 +9660,7 @@ post-patch: </row> <row> - <entry><makevar>USE_THUNDERBIRD_BUILD</makevar></entry> + <entry><varname>USE_THUNDERBIRD_BUILD</varname></entry> <entry>The port requires Thunderbird as a buildtime dependency. Possible values: see USE_THUNDERBIRD. This automatically sets USE_THUNDERBIRD and assigns @@ -9757,7 +9674,7 @@ post-patch: <filename>/usr/ports/Mk/bsd.gecko.mk</filename>.</para> </sect1> - <sect1 id="using-databases"> + <sect1 xml:id="using-databases"> <title>Using Databases</title> <table frame="none"> @@ -9773,48 +9690,46 @@ post-patch: <tbody> <row> - <entry><makevar>USE_BDB</makevar></entry> + <entry><varname>USE_BDB</varname></entry> <entry>If variable is set to <literal>yes</literal>, add dependency on - <filename role="package">databases/db41</filename> + <package>databases/db41</package> port. The variable may also be set to values: 40, 41, 42, 43, 44, 46, 47, 48, or 51. You can declare a range of acceptable values, - <makevar>USE_BDB</makevar>=42+ will find the highest + <varname>USE_BDB</varname>=42+ will find the highest installed version, and fall back to 42 if nothing else is installed.</entry> </row> <row> - <entry><makevar>USE_MYSQL</makevar></entry> + <entry><varname>USE_MYSQL</varname></entry> <entry>If variable is set to <literal>yes</literal>, add - dependency on <filename - role="package">databases/mysql55-client</filename> + dependency on <package>databases/mysql55-client</package> port. An associated variable, - <makevar>WANT_MYSQL_VER</makevar>, may be set to + <varname>WANT_MYSQL_VER</varname>, may be set to values such as 323, 40, 41, 50, 51, 52, 55, or 60.</entry> </row> <row> - <entry><makevar>USE_PGSQL</makevar></entry> + <entry><varname>USE_PGSQL</varname></entry> <entry>If set to <literal>yes</literal>, add dependency - on <filename - role="package">databases/postgresql90-client</filename> + on <package>databases/postgresql90-client</package> port. An associated variable, - <makevar>WANT_PGSQL_VER</makevar>, may be set to + <varname>WANT_PGSQL_VER</varname>, may be set to values such as 83, 84, 90, 91 or 92. You can declare a minimum or maximum value; - <makevar>WANT_PGSQL_VER</makevar>= + <varname>WANT_PGSQL_VER</varname>= <literal> 90+</literal> will cause the port to depend on a minimum version of 9.0.</entry> </row> <row> - <entry><makevar>USE_SQLITE</makevar></entry> + <entry><varname>USE_SQLITE</varname></entry> <entry>If variable is set to <literal>yes</literal>, add dependency on - <filename role="package">databases/sqlite3</filename> + <package>databases/sqlite3</package> port. The variable may also be set to values: 3, 2.</entry> </row> @@ -9822,11 +9737,10 @@ post-patch: </tgroup> </table> - <para>More details are available in <ulink - url="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.database.mk?view=markup">bsd.database.mk</ulink>.</para> + <para>More details are available in <link xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.database.mk?view=markup">bsd.database.mk</link>.</para> </sect1> - <sect1 id="rc-scripts"> + <sect1 xml:id="rc-scripts"> <title>Starting and Stopping Services (<literal>rc</literal> Scripts)</title> @@ -9834,12 +9748,11 @@ post-patch: services on system startup, and to give administrators a standard way of stopping, starting and restarting the service. Ports integrate into the system <filename>rc.d</filename> - framework. Details on its usage can be found in <ulink - url="&url.books.handbook;/configtuning-rcd.html">the rc.d - Handbook chapter</ulink>. Detailed explanation of available + framework. Details on its usage can be found in <link xlink:href="&url.books.handbook;/configtuning-rcd.html">the rc.d + Handbook chapter</link>. Detailed explanation of available commands is provided in &man.rc.8; and &man.rc.subr.8;. - Finally, there is <ulink url="&url.articles.rc-scripting;">an - article</ulink> on practical aspects of + Finally, there is <link xlink:href="&url.articles.rc-scripting;">an + article</link> on practical aspects of <filename>rc.d</filename> scripting.</para> <para>One or more <filename>rc.d</filename> scripts can be @@ -9849,18 +9762,18 @@ post-patch: <para>Scripts must be placed in the <filename>files</filename> subdirectory and a <literal>.in</literal> suffix must be added - to their filename. Standard <makevar>SUB_LIST</makevar> + to their filename. Standard <varname>SUB_LIST</varname> expansions will be used for this file. Use of the <literal>%%PREFIX%%</literal> and <literal>%%LOCALBASE%%</literal> expansions is strongly - encouraged as well. More on <makevar>SUB_LIST</makevar> in + encouraged as well. More on <varname>SUB_LIST</varname> in <link linkend="using-sub-files">the relevant section</link>.</para> <para>Prior to &os; 6.1-RELEASE, integration with &man.rcorder.8; is available by using - <makevar>USE_RCORDER</makevar> instead of - <makevar>USE_RC_SUBR</makevar>. However, use of this method + <varname>USE_RCORDER</varname> instead of + <varname>USE_RC_SUBR</varname>. However, use of this method is not necessary unless the port has an option to install itself in the base, or the service needs to run prior to the <filename>FILESYSTEMS</filename> <filename>rc.d</filename> @@ -10015,7 +9928,7 @@ run_rc_command "$1"</programlisting> <varname>command_interpreter</varname> is set appropriately. Otherwise,</para> - <screen>&prompt.root; <userinput>service <replaceable>name</replaceable> stop</userinput></screen> + <screen>&prompt.root; <userinput>service name stop</userinput></screen> <para>will probably not work properly. See &man.service.8; for more information.</para> @@ -10098,7 +10011,7 @@ run_rc_command "$1"</programlisting> </sect2> </sect1> - <sect1 id="users-and-groups"> + <sect1 xml:id="users-and-groups"> <title>Adding Users and Groups</title> <para>Some ports require a certain user to be on the installed @@ -10112,8 +10025,8 @@ run_rc_command "$1"</programlisting> require a new user or group to be created for your port.</para> - <para>Then you can use <makevar>USERS</makevar> and - <makevar>GROUPS</makevar> variables in your + <para>Then you can use <varname>USERS</varname> and + <varname>GROUPS</varname> variables in your <filename>Makefile</filename>, and the user will be automatically created when installing the port.</para> @@ -10125,7 +10038,7 @@ GROUPS= pulse pulse-access pulse-rt</programlisting> <filename>ports/GIDs</filename>.</para> </sect1> - <sect1 id="requiring-kernel-sources"> + <sect1 xml:id="requiring-kernel-sources"> <title>Ports That Rely on Kernel Sources</title> <para>Some ports (such as kernel loadable modules) need the @@ -10139,10 +10052,10 @@ IGNORE= requires kernel sources to be installed </sect1> </chapter> - <chapter id="plist"> + <chapter xml:id="plist"> <title>Advanced <filename>pkg-plist</filename> Practices</title> - <sect1 id="plist-sub"> + <sect1 xml:id="plist-sub"> <title>Changing <filename>pkg-plist</filename> Based on Make Variables</title> @@ -10160,16 +10073,16 @@ IGNORE= requires kernel sources to be installed and <literal>%%PERL_VER%%</literal> is the full version number of <command>perl</command> (e.g., <literal>5.8.9</literal>). Several other - <literal>%%<replaceable>VARS</replaceable>%%</literal> related + <literal>%%VARS%%</literal> related to port's documentation files are described in <link linkend="install-documentation">the relevant section</link>.</para> <para>If you need to make other substitutions, you can set the - <makevar>PLIST_SUB</makevar> variable with a list of - <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal> + <varname>PLIST_SUB</varname> variable with a list of + <literal>VAR=VALUE</literal> pairs and instances of - <literal>%%<replaceable>VAR</replaceable>%%</literal> will be + <literal>%%VAR%%</literal> will be substituted with <replaceable>VALUE</replaceable> in the <filename>pkg-plist</filename>.</para> @@ -10191,7 +10104,7 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting> set in the port, the usual way of handling it is prefixing the <filename>pkg-plist</filename> lines with a <literal>%%TAG%%</literal> and adding that - <literal>TAG</literal> to the <makevar>PLIST_SUB</makevar> + <literal>TAG</literal> to the <varname>PLIST_SUB</varname> variable inside the <filename>Makefile</filename> with a special value of <literal>@comment</literal>, which makes package tools to ignore the line:</para> @@ -10208,47 +10121,47 @@ PLIST_SUB+= X11="@comment " <para>This substitution will be - done between the <maketarget>pre-install</maketarget> and - <maketarget>do-install</maketarget> targets, by reading from - <filename><makevar>PLIST</makevar></filename> and writing to - <filename><makevar>TMPPLIST</makevar></filename> (default: - <filename><makevar>WRKDIR</makevar>/.PLIST.mktmp</filename>). + done between the <buildtarget>pre-install</buildtarget> and + <buildtarget>do-install</buildtarget> targets, by reading from + <filename>PLIST</filename> and writing to + <filename>TMPPLIST</filename> (default: + <filename>WRKDIR/.PLIST.mktmp</filename>). So if your port builds - <filename><makevar>PLIST</makevar></filename> on the fly, do - so in or before <maketarget>pre-install</maketarget>. Also, + <filename>PLIST</filename> on the fly, do + so in or before <buildtarget>pre-install</buildtarget>. Also, if your port needs to edit the resulting file, do so in - <maketarget>post-install</maketarget> to a file named - <filename><makevar>TMPPLIST</makevar></filename>.</para> + <buildtarget>post-install</buildtarget> to a file named + <filename>TMPPLIST</filename>.</para> <para>Another way of modifying a port's packing list is based - on setting the variables <makevar>PLIST_FILES</makevar>, - <makevar>PLIST_DIRS</makevar>, and - <makevar>PLIST_DIRSTRY</makevar>. The value of each variable + on setting the variables <varname>PLIST_FILES</varname>, + <varname>PLIST_DIRS</varname>, and + <varname>PLIST_DIRSTRY</varname>. The value of each variable is regarded as a list of pathnames to write to - <filename><makevar>TMPPLIST</makevar></filename> along with - <filename><makevar>PLIST</makevar></filename> contents. Names - listed in <makevar>PLIST_FILES</makevar>, - <makevar>PLIST_DIRS</makevar>, and - <makevar>PLIST_DIRSTRY</makevar> are subject to - <literal>%%<replaceable>VAR</replaceable>%%</literal> + <filename>TMPPLIST</filename> along with + <filename>PLIST</filename> contents. Names + listed in <varname>PLIST_FILES</varname>, + <varname>PLIST_DIRS</varname>, and + <varname>PLIST_DIRSTRY</varname> are subject to + <literal>%%VAR%%</literal> substitution as described above. Except for that, names from - <makevar>PLIST_FILES</makevar> will appear in the final + <varname>PLIST_FILES</varname> will appear in the final packing list unchanged, while <literal>@dirrm</literal> and <literal>@dirrmtry</literal> will - be prepended to names from <makevar>PLIST_DIRS</makevar> - and <makevar>PLIST_DIRSTRY</makevar>, respectively. To - take effect, <makevar>PLIST_FILES</makevar>, - <makevar>PLIST_DIRS</makevar>, and - <makevar>PLIST_DIRSTRY</makevar> must be set before - <filename><makevar>TMPPLIST</makevar></filename> is written, - i.e., in <maketarget>pre-install</maketarget> or + be prepended to names from <varname>PLIST_DIRS</varname> + and <varname>PLIST_DIRSTRY</varname>, respectively. To + take effect, <varname>PLIST_FILES</varname>, + <varname>PLIST_DIRS</varname>, and + <varname>PLIST_DIRSTRY</varname> must be set before + <filename>TMPPLIST</filename> is written, + i.e., in <buildtarget>pre-install</buildtarget> or earlier.</para> </sect1> - <sect1 id="plist-cleaning"> + <sect1 xml:id="plist-cleaning"> <title>Empty Directories</title> - <sect2 id="plist-dir-cleaning"> + <sect2 xml:id="plist-dir-cleaning"> <title>Cleaning Up Empty Directories</title> <para>Do make your ports remove empty directories when they @@ -10275,12 +10188,12 @@ lib/X11/oneko/sounds/cat.au <para>This will neither print any error messages nor cause &man.pkg.delete.1; to exit abnormally even if - <filename><makevar>${PREFIX}</makevar>/share/doc/gimp</filename> + <filename>${PREFIX}/share/doc/gimp</filename> is not empty due to other ports installing some files in there.</para> </sect2> - <sect2 id="plist-dir-empty"> + <sect2 xml:id="plist-dir-empty"> <title>Creating Empty Directories</title> <para>Empty directories created during port installation need @@ -10296,18 +10209,18 @@ lib/X11/oneko/sounds/cat.au </sect2> </sect1> - <sect1 id="plist-config"> + <sect1 xml:id="plist-config"> <title>Configuration Files</title> <para>If your port installs configuration files to - <filename><makevar>PREFIX</makevar>/etc</filename> (or + <filename>PREFIX/etc</filename> (or elsewhere) do <emphasis>not</emphasis> simply list them in the <filename>pkg-plist</filename>. That will cause &man.pkg.delete.1; to remove the files carefully edited by the user, and a re-installation will wipe them out.</para> <para>Instead, install sample file(s) with a - <filename><replaceable>filename</replaceable>.sample</filename> + <filename>filename.sample</filename> suffix. Then copy the sample file to the real configuration file name, if it does not already exist. On deinstall delete the configuration file, but only if it is identical @@ -10359,7 +10272,7 @@ etc/orbit.conf.sample will work.</para> </sect1> - <sect1 id="plist-dynamic"> + <sect1 xml:id="plist-dynamic"> <title>Dynamic Versus Static Package List</title> <para>A <emphasis>static package list</emphasis> is a package @@ -10367,9 +10280,9 @@ etc/orbit.conf.sample <filename>pkg-plist</filename> file (with or without variable substitution), or embedded into the <filename>Makefile</filename> via - <makevar>PLIST_FILES</makevar>, - <makevar>PLIST_DIRS</makevar>, and - <makevar>PLIST_DIRSTRY</makevar>. Even if the contents are + <varname>PLIST_FILES</varname>, + <varname>PLIST_DIRS</varname>, and + <varname>PLIST_DIRSTRY</varname>. Even if the contents are auto-generated by a tool or a target in the Makefile <emphasis>before</emphasis> the inclusion into the Ports Collection by a committer, this is still considered a static @@ -10395,23 +10308,23 @@ etc/orbit.conf.sample which generate docs with <application>Javadoc</application>).</para> - <para>Note that the <maketarget>makeplist</maketarget> target can + <para>Note that the <buildtarget>makeplist</buildtarget> target can be used for ports that support staging to display the package list.</para> </sect1> - <sect1 id="plist-autoplist"> + <sect1 xml:id="plist-autoplist"> <title>Automated Package List Creation</title> <para>First, make sure your port is almost complete, with only <filename>pkg-plist</filename> missing. You may then run - <command>make <maketarget>makeplist</maketarget></command> to + <command>make makeplist</command> to generate a <filename>pkg-plist</filename> automatically. This file must be double checked for correctness.</para> <para>User configuration files should be removed, or installed as - <filename><replaceable>filename</replaceable>.sample</filename>. + <filename>filename.sample</filename>. The <filename>info/dir</filename> file should not be listed and appropriate <filename>install-info</filename> lines should be added as noted in the @@ -10441,22 +10354,22 @@ etc/orbit.conf.sample <para>Another tool that might be used to create an initial <filename>pkg-plist</filename> is - <filename role="package">ports-mgmt/genplist</filename>. As + <package>ports-mgmt/genplist</package>. As with any automated tool, the resulting <filename>pkg-plist</filename> should be checked and manually edited as needed.</para> </sect1> </chapter> - <chapter id="pkg-files"> - <title>The <filename>pkg-<replaceable>*</replaceable></filename> + <chapter xml:id="pkg-files"> + <title>The <filename>pkg-*</filename> Files</title> <para>There are some tricks we have not mentioned yet about the - <filename>pkg-<replaceable>*</replaceable></filename> files + <filename>pkg-*</filename> files that come in handy sometimes.</para> - <sect1 id="porting-message"> + <sect1 xml:id="porting-message"> <title><filename>pkg-message</filename></title> <para>If you need to display a message to the installer, you may @@ -10466,10 +10379,10 @@ etc/orbit.conf.sample licensing information.</para> <para>When some lines about the build-time knobs or warnings - have to be displayed, use <makevar>ECHO_MSG</makevar>. The + have to be displayed, use <varname>ECHO_MSG</varname>. The <filename>pkg-message</filename> file is only for post-installation steps. Likewise, the distinction between - <makevar>ECHO_MSG</makevar> and <makevar>ECHO_CMD</makevar> + <varname>ECHO_MSG</varname> and <varname>ECHO_CMD</varname> should be kept in mind. The former is for printing informational text to the screen, while the latter is for command pipelining:</para> @@ -10487,7 +10400,7 @@ etc/orbit.conf.sample </note> </sect1> - <sect1 id="pkg-install"> + <sect1 xml:id="pkg-install"> <title><filename>pkg-install</filename></title> <para>If your port needs to execute commands when the binary @@ -10515,7 +10428,7 @@ etc/orbit.conf.sample </note> </sect1> - <sect1 id="pkg-deinstall"> + <sect1 xml:id="pkg-deinstall"> <title><filename>pkg-deinstall</filename></title> <para>This script executes when a package is removed.</para> @@ -10527,27 +10440,27 @@ etc/orbit.conf.sample POST-DEINSTALL</literal>.</para> </sect1> - <sect1 id="pkg-names"> - <title id="porting-pkgfiles">Changing the Names of - <filename>pkg-<replaceable>*</replaceable></filename> + <sect1 xml:id="pkg-names"> + <title xml:id="porting-pkgfiles">Changing the Names of + <filename>pkg-*</filename> Files</title> <para>All the names of - <filename>pkg-<replaceable>*</replaceable></filename> files + <filename>pkg-*</filename> files are defined using variables so you can change them in your <filename>Makefile</filename> if need be. This is especially useful when you are sharing the same - <filename>pkg-<replaceable>*</replaceable></filename> files + <filename>pkg-*</filename> files among several ports or have to write to one of the above files (see <link linkend="porting-wrkdir">writing to places other - than <makevar>WRKDIR</makevar></link> for why it is a bad + than <varname>WRKDIR</varname></link> for why it is a bad idea to write directly into the - <filename>pkg-<replaceable>*</replaceable></filename> + <filename>pkg-*</filename> subdirectory).</para> <para>Here is a list of variable names and their default values. - (<makevar>PKGDIR</makevar> defaults to - <makevar>${MASTERDIR}</makevar>.)</para> + (<varname>PKGDIR</varname> defaults to + <varname>${MASTERDIR}</varname>.)</para> <informaltable frame="none" pgwide="0"> <tgroup cols="2"> @@ -10560,27 +10473,27 @@ etc/orbit.conf.sample <tbody> <row> - <entry><makevar>DESCR</makevar></entry> + <entry><varname>DESCR</varname></entry> <entry><literal>${PKGDIR}/pkg-descr</literal></entry> </row> <row> - <entry><makevar>PLIST</makevar></entry> + <entry><varname>PLIST</varname></entry> <entry><literal>${PKGDIR}/pkg-plist</literal></entry> </row> <row> - <entry><makevar>PKGINSTALL</makevar></entry> + <entry><varname>PKGINSTALL</varname></entry> <entry><literal>${PKGDIR}/pkg-install</literal></entry> </row> <row> - <entry><makevar>PKGDEINSTALL</makevar></entry> + <entry><varname>PKGDEINSTALL</varname></entry> <entry><literal>${PKGDIR}/pkg-deinstall</literal></entry> </row> <row> - <entry><makevar>PKGMESSAGE</makevar></entry> + <entry><varname>PKGMESSAGE</varname></entry> <entry><literal>${PKGDIR}/pkg-message</literal></entry> </row> </tbody> @@ -10588,32 +10501,32 @@ etc/orbit.conf.sample </informaltable> <para>Please change these variables rather than overriding - <makevar>PKG_ARGS</makevar>. If you change - <makevar>PKG_ARGS</makevar>, those files will not correctly be + <varname>PKG_ARGS</varname>. If you change + <varname>PKG_ARGS</varname>, those files will not correctly be installed in <filename>/var/db/pkg</filename> upon install from a port.</para> </sect1> - <sect1 id="using-sub-files"> - <title>Making Use of <makevar>SUB_FILES</makevar> and - <makevar>SUB_LIST</makevar></title> + <sect1 xml:id="using-sub-files"> + <title>Making Use of <varname>SUB_FILES</varname> and + <varname>SUB_LIST</varname></title> - <para>The <makevar>SUB_FILES</makevar> and - <makevar>SUB_LIST</makevar> variables are useful for dynamic + <para>The <varname>SUB_FILES</varname> and + <varname>SUB_LIST</varname> variables are useful for dynamic values in port files, such as the installation - <makevar>PREFIX</makevar> in + <varname>PREFIX</varname> in <filename>pkg-message</filename>.</para> - <para>The <makevar>SUB_FILES</makevar> variable specifies a list + <para>The <varname>SUB_FILES</varname> variable specifies a list of files to be automatically modified. Each <replaceable>file</replaceable> in the - <makevar>SUB_FILES</makevar> list must have a corresponding - <filename><replaceable>file</replaceable>.in</filename> - present in <makevar>FILESDIR</makevar>. A modified version - will be created in <makevar>WRKDIR</makevar>. Files defined - as a value of <makevar>USE_RC_SUBR</makevar> (or the - deprecated <makevar>USE_RCORDER</makevar>) are automatically - added to the <makevar>SUB_FILES</makevar>. For the files + <varname>SUB_FILES</varname> list must have a corresponding + <filename>file.in</filename> + present in <varname>FILESDIR</varname>. A modified version + will be created in <varname>WRKDIR</varname>. Files defined + as a value of <varname>USE_RC_SUBR</varname> (or the + deprecated <varname>USE_RCORDER</varname>) are automatically + added to the <varname>SUB_FILES</varname>. For the files <filename>pkg-message</filename>, <filename>pkg-install</filename>, and @@ -10622,15 +10535,15 @@ etc/orbit.conf.sample variable is automatically set to point to the processed version.</para> - <para>The <makevar>SUB_LIST</makevar> variable is a list of + <para>The <varname>SUB_LIST</varname> variable is a list of <literal>VAR=VALUE</literal> pairs. For each pair <literal>%%VAR%%</literal> will get replaced with <literal>VALUE</literal> in each file listed in - <makevar>SUB_FILES</makevar>. Several common pairs are - automatically defined: <makevar>PREFIX</makevar>, - <makevar>LOCALBASE</makevar>, <makevar>DATADIR</makevar>, - <makevar>DOCSDIR</makevar>, <makevar>EXAMPLESDIR</makevar>, - <makevar>WWWDIR</makevar>, and <makevar>ETCDIR</makevar>. + <varname>SUB_FILES</varname>. Several common pairs are + automatically defined: <varname>PREFIX</varname>, + <varname>LOCALBASE</varname>, <varname>DATADIR</varname>, + <varname>DOCSDIR</varname>, <varname>EXAMPLESDIR</varname>, + <varname>WWWDIR</varname>, and <varname>ETCDIR</varname>. Any line beginning with <literal>@comment</literal> will be deleted from resulting files after a variable substitution.</para> @@ -10644,7 +10557,7 @@ SUB_LIST= ARCH=${ARCH}</programlisting> <para>Note that for this example, the <filename>pkg-message.in</filename> file must exist in - <makevar>FILESDIR</makevar>.</para> + <varname>FILESDIR</varname>.</para> <para>Example of a good <filename>pkg-message.in</filename>:</para> @@ -10655,10 +10568,10 @@ as .putsy.conf and edit it.</programlisting> </sect1> </chapter> - <chapter id="testing"> + <chapter xml:id="testing"> <title>Testing Your Port</title> - <sect1 id="make-describe"> + <sect1 xml:id="make-describe"> <title>Running <command>make describe</command></title> <para>Several of the &os; port maintenance tools, such as @@ -10693,11 +10606,10 @@ as .putsy.conf and edit it.</programlisting> automatically.</para> </sect1> - <sect1 id="testing-portlint"> + <sect1 xml:id="testing-portlint"> <title>Portlint</title> - <para>Do check your work with <link - linkend="porting-portlint"><command>portlint</command></link> + <para>Do check your work with <link linkend="porting-portlint"><command>portlint</command></link> before you submit or commit it. <command>portlint</command> warns you about many common errors, both functional and stylistic. For a new (or repocopied) port, @@ -10713,19 +10625,18 @@ as .putsy.conf and edit it.</programlisting> doubt, the best thing to do is ask on &a.ports;.</para> </sect1> - <sect1 id="testing-porttools"> + <sect1 xml:id="testing-porttools"> <title>Port Tools</title> <para>The - <filename role="package">ports-mgmt/porttools</filename> + <package>ports-mgmt/porttools</package> program is part of the Ports Collection.</para> <para><command>port</command> is the front-end script, which can help you simplify the testing job. Whenever you want to test a new port or update an existing one, you can use <command>port test</command> to test your port, including the - <link - linkend="testing-portlint"><command>portlint</command></link> + <link linkend="testing-portlint"><command>portlint</command></link> checking. This command also detects and lists any files that are not listed in <filename>pkg-plist</filename>. See the following example:</para> @@ -10733,33 +10644,33 @@ as .putsy.conf and edit it.</programlisting> <screen>&prompt.root; <userinput>port test /usr/ports/net/csup</userinput></screen> </sect1> - <sect1 id="porting-prefix"> - <title><makevar>PREFIX</makevar> and - <makevar>DESTDIR</makevar></title> + <sect1 xml:id="porting-prefix"> + <title><varname>PREFIX</varname> and + <varname>DESTDIR</varname></title> - <para><makevar>PREFIX</makevar> determines where the port will + <para><varname>PREFIX</varname> determines where the port will be installed. It defaults to <filename>/usr/local</filename>, but can be set by the user to a custom path like <filename>/opt</filename>. Your port must respect the value of this variable.</para> - <para><makevar>DESTDIR</makevar>, if set by the user, determines + <para><varname>DESTDIR</varname>, if set by the user, determines the complete alternative environment, usually a jail or an installed system mounted somewhere other than <filename>/</filename>. A port will actually install into - <filename><makevar>DESTDIR</makevar>/<makevar>PREFIX</makevar></filename>, + <filename>DESTDIR/PREFIX</filename>, and register with the package database in - <filename><makevar>DESTDIR</makevar>/var/db/pkg</filename>. - As <makevar>DESTDIR</makevar> is handled automatically by the + <filename>DESTDIR/var/db/pkg</filename>. + As <varname>DESTDIR</varname> is handled automatically by the ports infrastructure with &man.chroot.8;, you do not need any modifications or any extra care to write - <makevar>DESTDIR</makevar>-compliant ports.</para> + <varname>DESTDIR</varname>-compliant ports.</para> - <para>The value of <makevar>PREFIX</makevar> will be set to - <makevar>LOCALBASE</makevar> (defaulting to + <para>The value of <varname>PREFIX</varname> will be set to + <varname>LOCALBASE</varname> (defaulting to <filename>/usr/local</filename>). If - <makevar>USE_LINUX_PREFIX</makevar> is set, - <makevar>PREFIX</makevar> will be <makevar>LINUXBASE</makevar> + <varname>USE_LINUX_PREFIX</varname> is set, + <varname>PREFIX</varname> will be <varname>LINUXBASE</varname> (defaulting to <filename>/compat/linux</filename>).</para> <para>Avoiding hard-coded <filename>/usr/local</filename> paths @@ -10774,13 +10685,13 @@ as .putsy.conf and edit it.</programlisting> <para>Make sure your application is not installing things in <filename>/usr/local</filename> instead of - <makevar>PREFIX</makevar>. A quick test for such hard-coded + <varname>PREFIX</varname>. A quick test for such hard-coded paths is:</para> <screen>&prompt.root; <userinput>make clean; make package PREFIX=/var/tmp/`make -V PORTNAME`</userinput></screen> <para>If anything is installed outside of - <makevar>PREFIX</makevar>, the package creation process will + <varname>PREFIX</varname>, the package creation process will complain that it cannot find the files.</para> <para>In addition, it is worth checking the same with the @@ -10790,15 +10701,15 @@ as .putsy.conf and edit it.</programlisting> <para>These tests will not find hard-coded paths inside the port's files, nor will it verify that - <makevar>LOCALBASE</makevar> is being used to correctly refer + <varname>LOCALBASE</varname> is being used to correctly refer to files from other ports. The temporarily-installed port in <filename>/var/tmp/`make -V PORTNAME`</filename> should be tested for proper operation to make sure there are no problems with paths.</para> - <para><makevar>PREFIX</makevar> should not be set explicitly + <para><varname>PREFIX</varname> should not be set explicitly in a port's <filename>Makefile</filename>. Users installing - the port may have set <makevar>PREFIX</makevar> to a custom + the port may have set <varname>PREFIX</varname> to a custom location, and the port should respect that setting.</para> <para>Refer to programs and files from other ports with the @@ -10811,12 +10722,12 @@ as .putsy.conf and edit it.</programlisting> <programlisting>-DPAGER=\"${LOCALBASE}/bin/less\"</programlisting> - <para>The path with <makevar>LOCALBASE</makevar> is more likely + <para>The path with <varname>LOCALBASE</varname> is more likely to still work if the system administrator has moved the whole <filename>/usr/local</filename> tree somewhere else.</para> </sect1> - <sect1 id="testing-tinderbox"> + <sect1 xml:id="testing-tinderbox"> <title>Tinderbox</title> <para>If you are an avid ports contributor, you might want to @@ -10825,17 +10736,17 @@ as .putsy.conf and edit it.</programlisting> scripts used on <link linkend="build-cluster">Pointyhat</link>. You can install <application>Tinderbox</application> using - <filename role="package">ports-mgmt/tinderbox</filename> port. + <package>ports-mgmt/tinderbox</package> port. Be sure to read supplied documentation since the configuration is not trivial.</para> <para>Visit the - <ulink url="http://tinderbox.marcuscom.com/">Tinderbox - website</ulink> for more details.</para> + <link xlink:href="http://tinderbox.marcuscom.com/">Tinderbox + website</link> for more details.</para> </sect1> </chapter> - <chapter id="port-upgrading"> + <chapter xml:id="port-upgrading"> <title>Upgrading an Individual Port</title> <para>When you notice that a port is out of date compared to the @@ -10846,16 +10757,14 @@ as .putsy.conf and edit it.</programlisting> few ports, you will probably find it easier to use <application>Subversion</application> or &man.portsnap.8; to keep your whole ports - collection up-to-date, as described in the <ulink - url="&url.books.handbook;/ports-using.html">Handbook</ulink>. + collection up-to-date, as described in the <link xlink:href="&url.books.handbook;/ports-using.html">Handbook</link>. This will have the added benefit of tracking all the ports' dependencies.</para> <para>The next step is to see if there is an update already pending. To do this, you have two options. There is a - searchable interface to the <ulink - url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">FreeBSD - Problem Report (PR) database</ulink> (also known as + searchable interface to the <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">FreeBSD + Problem Report (PR) database</link> (also known as <literal>GNATS</literal>). Select <literal>ports</literal> in the dropdown, and enter the name of the port.</para> @@ -10865,9 +10774,8 @@ as .putsy.conf and edit it.</programlisting> <link linkend="portsmon">FreeBSD Ports Monitoring System</link> (also known as <literal>portsmon</literal>). This system attempts to classify port PRs by portname. To search for PRs - about a particular port, use the <ulink - url="http://portsmon.FreeBSD.org/portoverview.py">Overview of - One Port</ulink>.</para> + about a particular port, use the <link xlink:href="http://portsmon.FreeBSD.org/portoverview.py">Overview of + One Port</link>.</para> <para>If there is no pending PR, the next step is to send an email to the port's maintainer, as shown by @@ -10892,7 +10800,7 @@ as .putsy.conf and edit it.</programlisting> patch:</para> <informalexample> - <screen>&prompt.user; <userinput>diff -u something.orig something > something.diff</userinput></screen> + <screen>&prompt.user; <userinput>diff -u something.orig something > something.diff</userinput></screen> </informalexample> <para>Otherwise, you should either use the @@ -10923,9 +10831,8 @@ as .putsy.conf and edit it.</programlisting> maintainer. &os; has over 4000 ports without maintainers, and this is an area where more volunteers are always needed. (For a detailed description of the responsibilities of maintainers, - refer to the section in the <ulink - url="&url.books.developers-handbook;/policies.html#POLICIES-MAINTAINER"> - Developer's Handbook</ulink>.)</para> + refer to the section in the <link xlink:href="&url.books.developers-handbook;/policies.html#POLICIES-MAINTAINER"> + Developer's Handbook</link>.)</para> <para>The best way to send us the diff is by including it via &man.send-pr.1; (category <literal>ports</literal>). If you are @@ -10941,8 +10848,8 @@ as .putsy.conf and edit it.</programlisting> otherwise, just include it in the PR as is.</para> <para>Before you &man.send-pr.1;, you should review the - <ulink url="&url.articles.problem-reports;/pr-writing.html"> - Writing the problem report</ulink> section in the Problem + <link xlink:href="&url.articles.problem-reports;/pr-writing.html"> + Writing the problem report</link> section in the Problem Reports article; it contains far more information about how to write useful problem reports.</para> @@ -10965,7 +10872,7 @@ as .putsy.conf and edit it.</programlisting> <para>Now that you have done all that, you will want to read about how to keep up-to-date in <xref linkend="keeping-up"/>.</para> - <sect1 id="svn-diff"> + <sect1 xml:id="svn-diff"> <title>Using <literal>SVN</literal> to Make Patches</title> <para>If you can, please submit a &man.svn.1; diff — they @@ -10976,8 +10883,8 @@ as .putsy.conf and edit it.</programlisting> started to work on it until you submit your changes, or if the committer asks you to fix something.</para> - <screen>&prompt.user; <userinput>cd ~/my_wrkdir</userinput> <co id="my-wrkdir"/> -&prompt.user; <userinput>svn co <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/ports/head/dns/pdnsd</userinput> <co id="svn-FreeBSD-org"/> + <screen>&prompt.user; <userinput>cd ~/my_wrkdir</userinput> <co xml:id="my-wrkdir"/> +&prompt.user; <userinput>svn co https://svn0.us-west.FreeBSD.org/ports/head/dns/pdnsd</userinput> <co xml:id="svn-FreeBSD-org"/> &prompt.user; <userinput>cd ~/my_wrkdir/pdnsd</userinput></screen> <calloutlist> @@ -10985,17 +10892,15 @@ as .putsy.conf and edit it.</programlisting> <para>This can be anywhere you want, of course; building ports is not limited to within - <filename class="directory">/usr/ports/</filename>.</para> + <filename>/usr/ports/</filename>.</para> </callout> <callout arearefs="svn-FreeBSD-org"> - <para><ulink - url="https://svn0.us-west.FreeBSD.org/">svn0.us-west.FreeBSD.org</ulink> + <para><link xlink:href="https://svn0.us-west.FreeBSD.org/">svn0.us-west.FreeBSD.org</link> is a public <literal>SVN</literal> server. Select the closest mirror and verify the mirror server - certificate from the list of <ulink - url="&url.books.handbook;/svn-mirrors.html">Subversion - mirror sites</ulink>.</para> + certificate from the list of <link xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion + mirror sites</link>.</para> </callout> </calloutlist> @@ -11011,7 +10916,7 @@ as .putsy.conf and edit it.</programlisting> <xref linkend="porting-portlint"/>.</para> <screen>&prompt.user; <userinput>svn status</userinput> -&prompt.user; <userinput>svn update</userinput> <co id="svn-update"/></screen> +&prompt.user; <userinput>svn update</userinput> <co xml:id="svn-update"/></screen> <calloutlist> <callout arearefs="svn-update"> @@ -11023,7 +10928,7 @@ as .putsy.conf and edit it.</programlisting> </callout> </calloutlist> - <table pgwide="1" frame="none" id="table-svn-up"> + <table pgwide="1" frame="none" xml:id="table-svn-up"> <title><literal>SVN</literal> Update File Prefixes</title> <tgroup cols="2"> @@ -11079,7 +10984,7 @@ as .putsy.conf and edit it.</programlisting> <xref linkend="port-upgrading"/>.</para> </sect1> - <sect1 id="moved-and-updating-files"> + <sect1 xml:id="moved-and-updating-files"> <title>The Files <filename>UPDATING</filename> and <filename>MOVED</filename></title> @@ -11122,10 +11027,10 @@ as .putsy.conf and edit it.</programlisting> </sect1> </chapter> - <chapter id="security"> + <chapter xml:id="security"> <title>Ports Security</title> - <sect1 id="security-intro"> + <sect1 xml:id="security-intro"> <title>Why Security is So Important</title> <para>Bugs are occasionally introduced to the software. @@ -11161,7 +11066,7 @@ as .putsy.conf and edit it.</programlisting> actions.</para> </sect1> - <sect1 id="security-fix"> + <sect1 xml:id="security-fix"> <title>Fixing Security Vulnerabilities</title> <para>While on the subject of ports and packages, a security @@ -11172,7 +11077,7 @@ as .putsy.conf and edit it.</programlisting> port promptly with respect to the author's fix. If the fix is delayed for some reason, you should either <link linkend="dads-noinstall">mark the port as - <makevar>FORBIDDEN</makevar></link> or introduce a patch file + <varname>FORBIDDEN</varname></link> or introduce a patch file of your own to the port. In the case of a vulnerable port, just fix the port as soon as possible. In either case, <link linkend="port-upgrading">the standard procedure for @@ -11191,21 +11096,21 @@ as .putsy.conf and edit it.</programlisting> on a regular basis will see they need to run an update. Besides, a new package will be built and distributed over FTP and WWW mirrors, replacing the vulnerable one. - <makevar>PORTREVISION</makevar> should be bumped unless - <makevar>PORTVERSION</makevar> has changed in the course + <varname>PORTREVISION</varname> should be bumped unless + <varname>PORTVERSION</varname> has changed in the course of correcting the vulnerability. That is you should - bump <makevar>PORTREVISION</makevar> if you have added a + bump <varname>PORTREVISION</varname> if you have added a patch file to the port, but you should not if you have updated the port to the latest software version and thus already - touched <makevar>PORTVERSION</makevar>. Please refer to the + touched <varname>PORTVERSION</varname>. Please refer to the <link linkend="makefile-naming-revepoch">corresponding section</link> for more information.</para> </sect1> - <sect1 id="security-notify"> + <sect1 xml:id="security-notify"> <title>Keeping the Community Informed</title> - <sect2 id="security-notify-vuxml-db"> + <sect2 xml:id="security-notify-vuxml-db"> <title>The VuXML Database</title> <para>A very important and urgent step to take as early after @@ -11226,8 +11131,8 @@ as .putsy.conf and edit it.</programlisting> a flood and losing the attention of the audience when it comes to really serious matters. Therefore security vulnerabilities found in ports are recorded in - <ulink url="http://vuxml.freebsd.org/">the FreeBSD VuXML - database</ulink>. The Security Officer Team members also + <link xlink:href="http://vuxml.freebsd.org/">the FreeBSD VuXML + database</link>. The Security Officer Team members also monitor it for issues requiring their intervention.</para> <para>If you have committer rights you can update the VuXML @@ -11237,14 +11142,14 @@ as .putsy.conf and edit it.</programlisting> you believe you have found an exceptionally severe vulnerability please do not hesitate to contact the Security Officer Team directly as described on the - <ulink url="http://www.freebsd.org/security/#how">FreeBSD - Security Information</ulink> page.</para> + <link xlink:href="http://www.freebsd.org/security/#how">FreeBSD + Security Information</link> page.</para> <para>The VuXML database is an XML document. Its source file <filename>vuln.xml</filename> is kept right inside the port - <filename role="package">security/vuxml</filename>. + <package>security/vuxml</package>. Therefore the file's full pathname will be - <filename><envar>PORTSDIR</envar>/security/vuxml/vuln.xml</filename>. + <filename>PORTSDIR/security/vuxml/vuln.xml</filename>. Each time you discover a security vulnerability in a port please add an entry for it to that file. Until you are familiar with VuXML, the best thing you can do is to find an @@ -11252,7 +11157,7 @@ as .putsy.conf and edit it.</programlisting> a template.</para> </sect2> - <sect2 id="security-notify-vuxml-intro"> + <sect2 xml:id="security-notify-vuxml-intro"> <title>A Short Introduction to VuXML</title> <para>The full-blown XML format is complex, and far beyond the @@ -11272,26 +11177,26 @@ as .putsy.conf and edit it.</programlisting> <para>Now consider a realistic VuXML entry:</para> - <programlisting><vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9"> <co id="co-vx-vid"/> - <topic>Several vulnerabilities found in Foo</topic> <co id="co-vx-top"/> + <programlisting><vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9"> <co xml:id="co-vx-vid"/> + <topic>Several vulnerabilities found in Foo</topic> <co xml:id="co-vx-top"/> <affects> <package> - <name>foo</name> <co id="co-vx-nam"/> + <name>foo</name> <co xml:id="co-vx-nam"/> <name>foo-devel</name> <name>ja-foo</name> - <range><ge>1.6</ge><lt>1.9</lt></range> <co id="co-vx-rng"/> + <range><ge>1.6</ge><lt>1.9</lt></range> <co xml:id="co-vx-rng"/> <range><ge>2.*</ge><lt>2.4_1</lt></range> <range><eq>3.0b1</eq></range> </package> <package> - <name>openfoo</name> <co id="co-vx-nm2"/> - <range><lt>1.10_7</lt></range> <co id="co-vx-epo"/> + <name>openfoo</name> <co xml:id="co-vx-nm2"/> + <range><lt>1.10_7</lt></range> <co xml:id="co-vx-epo"/> <range><ge>1.2,1</ge><lt>1.3_1,1</lt></range> </package> </affects> <description> <body xmlns="http://www.w3.org/1999/xhtml"> - <p>J. Random Hacker reports:</p> <co id="co-vx-bdy"/> + <p>J. Random Hacker reports:</p> <co xml:id="co-vx-bdy"/> <blockquote cite="http://j.r.hacker.com/advisories/1"> <p>Several issues in the Foo software may be exploited @@ -11301,23 +11206,23 @@ as .putsy.conf and edit it.</programlisting> </blockquote> </body> </description> - <references> <co id="co-vx-ref"/> - <freebsdsa>SA-10:75.foo</freebsdsa> <co id="co-vx-fsa"/> - <freebsdpr>ports/987654</freebsdpr> <co id="co-vx-fpr"/> - <cvename>CAN-2010-0201</cvename> <co id="co-vx-cve"/> + <references> <co xml:id="co-vx-ref"/> + <freebsdsa>SA-10:75.foo</freebsdsa> <co xml:id="co-vx-fsa"/> + <freebsdpr>ports/987654</freebsdpr> <co xml:id="co-vx-fpr"/> + <cvename>CAN-2010-0201</cvename> <co xml:id="co-vx-cve"/> <cvename>CAN-2010-0466</cvename> - <bid>96298</bid> <co id="co-vx-bid"/> - <certsa>CA-2010-99</certsa> <co id="co-vx-cts"/> - <certvu>740169</certvu> <co id="co-vx-ctv"/> - <uscertsa>SA10-99A</uscertsa> <co id="co-vx-ucs"/> - <uscertta>SA10-99A</uscertta> <co id="co-vx-uct"/> - <mlist msgid="201075606@hacker.com">http://marc.theaimsgroup.com/?l=bugtraq&amp;m=203886607825605</mlist> <co id="co-vx-mls"/> - <url>http://j.r.hacker.com/advisories/1</url> <co id="co-vx-url"/> + <bid>96298</bid> <co xml:id="co-vx-bid"/> + <certsa>CA-2010-99</certsa> <co xml:id="co-vx-cts"/> + <certvu>740169</certvu> <co xml:id="co-vx-ctv"/> + <uscertsa>SA10-99A</uscertsa> <co xml:id="co-vx-ucs"/> + <uscertta>SA10-99A</uscertta> <co xml:id="co-vx-uct"/> + <mlist msgid="201075606@hacker.com">http://marc.theaimsgroup.com/?l=bugtraq&amp;m=203886607825605</mlist> <co xml:id="co-vx-mls"/> + <url>http://j.r.hacker.com/advisories/1</url> <co xml:id="co-vx-url"/> </references> <dates> - <discovery>2010-05-25</discovery> <co id="co-vx-dsc"/> - <entry>2010-07-13</entry> <co id="co-vx-ent"/> - <modified>2010-09-17</modified> <co id="co-vx-mod"/> + <discovery>2010-05-25</discovery> <co xml:id="co-vx-dsc"/> + <entry>2010-07-13</entry> <co xml:id="co-vx-ent"/> + <modified>2010-09-17</modified> <co xml:id="co-vx-mod"/> </dates> </vuln></programlisting> @@ -11427,12 +11332,12 @@ as .putsy.conf and edit it.</programlisting> <callout arearefs="co-vx-epo"> <para>The version ranges should allow for - <makevar>PORTEPOCH</makevar> and - <makevar>PORTREVISION</makevar> if applicable. Please + <varname>PORTEPOCH</varname> and + <varname>PORTREVISION</varname> if applicable. Please remember that according to the collation rules, a - version with a non-zero <makevar>PORTEPOCH</makevar> is + version with a non-zero <varname>PORTEPOCH</varname> is greater than any version without - <makevar>PORTEPOCH</makevar>, e.g., + <varname>PORTEPOCH</varname>, e.g., <literal>3.0,1</literal> is greater than <literal>3.1</literal> or even than <literal>8.9</literal>.</para> @@ -11454,50 +11359,47 @@ as .putsy.conf and edit it.</programlisting> </callout> <callout arearefs="co-vx-fsa"> - <para>This is a <ulink - url="http://www.freebsd.org/security/#adv">FreeBSD - security advisory</ulink>.</para> + <para>This is a <link xlink:href="http://www.freebsd.org/security/#adv">FreeBSD + security advisory</link>.</para> </callout> <callout arearefs="co-vx-fpr"> - <para>This is a <ulink - url="http://www.freebsd.org/support.html#gnats">FreeBSD - problem report</ulink>.</para> + <para>This is a <link xlink:href="http://www.freebsd.org/support.html#gnats">FreeBSD + problem report</link>.</para> </callout> <callout arearefs="co-vx-cve"> <para>This is a - <ulink url="http://www.cve.mitre.org/">MITRE - CVE</ulink> identifier.</para> + <link xlink:href="http://www.cve.mitre.org/">MITRE + CVE</link> identifier.</para> </callout> <callout arearefs="co-vx-bid"> - <para>This is a <ulink - url="http://www.securityfocus.com/bid">SecurityFocus - Bug ID</ulink>.</para> + <para>This is a <link xlink:href="http://www.securityfocus.com/bid">SecurityFocus + Bug ID</link>.</para> </callout> <callout arearefs="co-vx-cts"> <para>This is a - <ulink url="http://www.cert.org/">US-CERT</ulink> + <link xlink:href="http://www.cert.org/">US-CERT</link> security advisory.</para> </callout> <callout arearefs="co-vx-ctv"> <para>This is a - <ulink url="http://www.cert.org/">US-CERT</ulink> + <link xlink:href="http://www.cert.org/">US-CERT</link> vulnerability note.</para> </callout> <callout arearefs="co-vx-ucs"> <para>This is a - <ulink url="http://www.cert.org/">US-CERT</ulink> + <link xlink:href="http://www.cert.org/">US-CERT</link> Cyber Security Alert.</para> </callout> <callout arearefs="co-vx-uct"> <para>This is a - <ulink url="http://www.cert.org/">US-CERT</ulink> + <link xlink:href="http://www.cert.org/">US-CERT</link> Technical Cyber Security Alert.</para> </callout> @@ -11533,7 +11435,7 @@ as .putsy.conf and edit it.</programlisting> </calloutlist> </sect2> - <sect2 id="security-notify-vuxml-testing"> + <sect2 xml:id="security-notify-vuxml-testing"> <title>Testing Your Changes to the VuXML Database</title> <para>Assume you just wrote or filled in an entry for a @@ -11542,24 +11444,24 @@ as .putsy.conf and edit it.</programlisting> <para>As a prerequisite, you need to <emphasis>install</emphasis> fresh versions of the ports - <filename role="package">ports-mgmt/portaudit</filename>, - <filename role="package">ports-mgmt/portaudit-db</filename>, + <package>ports-mgmt/portaudit</package>, + <package>ports-mgmt/portaudit-db</package>, and - <filename role="package">security/vuxml</filename>.</para> + <package>security/vuxml</package>.</para> <note> <para>To run <command>packaudit</command> you must have permission to write to its - <filename><makevar>DATABASEDIR</makevar></filename>, + <filename>DATABASEDIR</filename>, typically <filename>/var/db/portaudit</filename>.</para> <para>To use a different directory set the - <filename><makevar>DATABASEDIR</makevar></filename> + <filename>DATABASEDIR</filename> environment variable to a different location.</para> <para>If you are working in a directory other than <filename>${PORTSDIR}/security/vuxml</filename> set the - <filename><makevar>VUXMLDIR</makevar></filename> + <filename>VUXMLDIR</filename> environment variable to the directory where <filename>vuln.xml</filename> is located.</para> </note> @@ -11586,8 +11488,8 @@ as .putsy.conf and edit it.</programlisting> <note> <para>You will need at least one of the following packages installed: - <filename role="package">textproc/libxml2</filename>, - <filename role="package">textproc/jade</filename>.</para> + <package>textproc/libxml2</package>, + <package>textproc/jade</package>.</para> </note> <para>Now rebuild the <command>portaudit</command> database @@ -11599,7 +11501,7 @@ as .putsy.conf and edit it.</programlisting> section of your entry will match correct package(s), issue the following command:</para> - <screen>&prompt.user; <userinput>portaudit -f /usr/ports/INDEX -r <replaceable>uuid</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>portaudit -f /usr/ports/INDEX -r uuid</userinput></screen> <note> <para>Please refer to &man.portaudit.1; for better @@ -11632,71 +11534,68 @@ Reference: <http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-00 </sect1> </chapter> - <chapter id="porting-dads"> + <chapter xml:id="porting-dads"> <title>Dos and Don'ts</title> - <sect1 id="dads-intro"> + <sect1 xml:id="dads-intro"> <title>Introduction</title> <para>Here is a list of common dos and don'ts that you encounter during the porting process. You should check your own port - against this list, but you can also check ports in the <ulink - url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">PR - database</ulink> that others have submitted. Submit any - comments on ports you check as described in <ulink - url="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug - Reports and General Commentary</ulink>. Checking ports in + against this list, but you can also check ports in the <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">PR + database</link> that others have submitted. Submit any + comments on ports you check as described in <link xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug + Reports and General Commentary</link>. Checking ports in the PR database will both make it faster for us to commit them, and prove that you know what you are doing.</para> </sect1> - <sect1 id="porting-wrkdir"> - <title><makevar>WRKDIR</makevar></title> + <sect1 xml:id="porting-wrkdir"> + <title><varname>WRKDIR</varname></title> <para>Do not write anything to files outside - <makevar>WRKDIR</makevar>. <makevar>WRKDIR</makevar> is the + <varname>WRKDIR</varname>. <varname>WRKDIR</varname> is the only place that is guaranteed to be writable during the port build (see - <ulink url="&url.books.handbook;/ports-using.html#PORTS-CD"> - installing ports from a CDROM</ulink> for an example of + <link xlink:href="&url.books.handbook;/ports-using.html#PORTS-CD"> + installing ports from a CDROM</link> for an example of building ports from a read-only tree). If you need to modify one of the - <filename>pkg-<replaceable>*</replaceable></filename> files, + <filename>pkg-*</filename> files, do so by <link linkend="porting-pkgfiles">redefining a variable</link>, not by writing over it.</para> </sect1> - <sect1 id="porting-wrkdirprefix"> - <title><makevar>WRKDIRPREFIX</makevar></title> + <sect1 xml:id="porting-wrkdirprefix"> + <title><varname>WRKDIRPREFIX</varname></title> <para>Make sure your port honors - <makevar>WRKDIRPREFIX</makevar>. Most ports do not have to + <varname>WRKDIRPREFIX</varname>. Most ports do not have to worry about this. In particular, if you are referring to a - <makevar>WRKDIR</makevar> of another port, note that the + <varname>WRKDIR</varname> of another port, note that the correct location is - <filename><makevar>WRKDIRPREFIX</makevar><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> + <filename>WRKDIRPREFIXPORTSDIR/subdir/name/work</filename> not - <filename><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> + <filename>PORTSDIR/subdir/name/work</filename> or - <filename><makevar>.CURDIR</makevar>/../../<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> + <filename>.CURDIR/../../subdir/name/work</filename> or some such.</para> - <para>Also, if you are defining <makevar>WRKDIR</makevar> + <para>Also, if you are defining <varname>WRKDIR</varname> yourself, make sure you prepend <literal>${WRKDIRPREFIX}${.CURDIR}</literal> in the front.</para> </sect1> - <sect1 id="porting-versions"> + <sect1 xml:id="porting-versions"> <title>Differentiating Operating Systems and OS Versions</title> <para>You may come across code that needs modifications or conditional compilation based upon what version of &os; Unix it is running under. The preferred way to tell &os; versions apart are the <literal>__FreeBSD_version</literal> and - <literal>__FreeBSD__</literal> macros defined in <ulink - url="http://svnweb.freebsd.org/base/head/sys/sys/param.h?view=markup">sys/param.h</ulink>. + <literal>__FreeBSD__</literal> macros defined in <link xlink:href="http://svnweb.freebsd.org/base/head/sys/sys/param.h?view=markup">sys/param.h</link>. If this file is not included add the code,</para> <programlisting>#include <sys/param.h></programlisting> @@ -11718,7 +11617,7 @@ Reference: <http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-00 </para> </sect1> - <sect1 id="dads-after-port-mk"> + <sect1 xml:id="dads-after-port-mk"> <title>Writing Something After <filename>bsd.port.mk</filename></title> @@ -11756,43 +11655,41 @@ Reference: <http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-00 <tbody> <row> - <entry><makevar>ARCH</makevar></entry> + <entry><varname>ARCH</varname></entry> <entry>The architecture as returned by <command>uname -m</command> (e.g., <literal>i386</literal>)</entry> </row> <row> - <entry><makevar>OPSYS</makevar></entry> + <entry><varname>OPSYS</varname></entry> <entry>The operating system type, as returned by <command>uname -s</command> (e.g., <literal>FreeBSD</literal>)</entry> </row> <row> - <entry><makevar>OSREL</makevar></entry> + <entry><varname>OSREL</varname></entry> <entry>The release version of the operating system (e.g., <literal>2.1.5</literal> or <literal>2.2.7</literal>)</entry> </row> <row> - <entry><makevar>OSVERSION</makevar></entry> + <entry><varname>OSVERSION</varname></entry> <entry>The numeric version of the operating system; the - same as <link - linkend="freebsd-versions"><literal>__FreeBSD_version</literal></link>.</entry> + same as <link linkend="freebsd-versions"><literal>__FreeBSD_version</literal></link>.</entry> </row> <row> - <entry><makevar>LOCALBASE</makevar></entry> + <entry><varname>LOCALBASE</varname></entry> <entry>The base of the <quote>local</quote> tree (e.g., <literal>/usr/local</literal>)</entry> </row> <row> - <entry><makevar>PREFIX</makevar></entry> - <entry>Where the port installs itself (see <link - linkend="porting-prefix">more on - <makevar>PREFIX</makevar></link>).</entry> + <entry><varname>PREFIX</varname></entry> + <entry>Where the port installs itself (see <link linkend="porting-prefix">more on + <varname>PREFIX</varname></link>).</entry> </row> </tbody> </tgroup> @@ -11800,7 +11697,7 @@ Reference: <http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-00 <note> <para>If you have to define the variable - <makevar>MASTERDIR</makevar>, do so before including + <varname>MASTERDIR</varname>, do so before including <filename>bsd.port.pre.mk</filename>.</para> </note> @@ -11817,7 +11714,7 @@ BROKEN= perl is in system <!-- smiley -->:-).</para> </sect1> - <sect1 id="dads-sh-exec"> + <sect1 xml:id="dads-sh-exec"> <title>Use the <function>exec</function> Statement in Wrapper Scripts</title> @@ -11837,7 +11734,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> needlessly consumes system resources.</para> </sect1> - <sect1 id="dads-rational"> + <sect1 xml:id="dads-rational"> <title>Do Things Rationally</title> <para>The <filename>Makefile</filename> should do things simply @@ -11845,9 +11742,9 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> or more readable, then do so. Examples include using a make <literal>.if</literal> construct instead of a shell <literal>if</literal> construct, not redefining - <maketarget>do-extract</maketarget> if you can redefine - <makevar>EXTRACT*</makevar> instead, and using - <makevar>GNU_CONFIGURE</makevar> instead of + <buildtarget>do-extract</buildtarget> if you can redefine + <varname>EXTRACT*</varname> instead, and using + <varname>GNU_CONFIGURE</varname> instead of <literal>CONFIGURE_ARGS += --prefix=${PREFIX}</literal>.</para> @@ -11860,12 +11757,12 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> shorthand solution.</para> </sect1> - <sect1 id="dads-cc"> - <title>Respect Both <makevar>CC</makevar> and - <makevar>CXX</makevar></title> + <sect1 xml:id="dads-cc"> + <title>Respect Both <varname>CC</varname> and + <varname>CXX</varname></title> - <para>The port must respect both <makevar>CC</makevar> and - <makevar>CXX</makevar> variables. What we mean by this is + <para>The port must respect both <varname>CC</varname> and + <varname>CXX</varname> variables. What we mean by this is that the port must not set the values of these variables absolutely, overriding existing values; instead, it may append whatever values it needs to the existing values. This @@ -11878,22 +11775,22 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> <filename>Makefile</filename>.</para> <para>An example of a <filename>Makefile</filename> respecting - both <makevar>CC</makevar> and <makevar>CXX</makevar> - variables follows. Note the <makevar>?=</makevar>:</para> + both <varname>CC</varname> and <varname>CXX</varname> + variables follows. Note the <varname>?=</varname>:</para> <programlisting>CC?= gcc</programlisting> <programlisting>CXX?= g++</programlisting> <para>Here is an example which respects neither - <makevar>CC</makevar> nor <makevar>CXX</makevar> + <varname>CC</varname> nor <varname>CXX</varname> variables:</para> <programlisting>CC= gcc</programlisting> <programlisting>CXX= g++</programlisting> - <para>Both <makevar>CC</makevar> and <makevar>CXX</makevar> + <para>Both <varname>CC</varname> and <varname>CXX</varname> variables can be defined on FreeBSD systems in <filename>/etc/make.conf</filename>. The first example defines a value if it was not previously set in @@ -11902,10 +11799,10 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> anything previously defined.</para> </sect1> - <sect1 id="dads-cflags"> - <title>Respect <makevar>CFLAGS</makevar></title> + <sect1 xml:id="dads-cflags"> + <title>Respect <varname>CFLAGS</varname></title> - <para>The port must respect the <makevar>CFLAGS</makevar> + <para>The port must respect the <varname>CFLAGS</varname> variable. What we mean by this is that the port must not set the value of this variable absolutely, overriding the existing value; instead, it may append whatever values it @@ -11917,26 +11814,26 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> <filename>Makefile</filename>.</para> <para>An example of a <filename>Makefile</filename> respecting - the <makevar>CFLAGS</makevar> variable follows. Note the - <makevar>+=</makevar>:</para> + the <varname>CFLAGS</varname> variable follows. Note the + <varname>+=</varname>:</para> <programlisting>CFLAGS+= -Wall -Werror</programlisting> <para>Here is an example which does not respect the - <makevar>CFLAGS</makevar> variable:</para> + <varname>CFLAGS</varname> variable:</para> <programlisting>CFLAGS= -Wall -Werror</programlisting> - <para>The <makevar>CFLAGS</makevar> variable is defined on + <para>The <varname>CFLAGS</varname> variable is defined on FreeBSD systems in <filename>/etc/make.conf</filename>. The first example appends additional flags to the - <makevar>CFLAGS</makevar> variable, preserving any system-wide + <varname>CFLAGS</varname> variable, preserving any system-wide definitions. The second example clobbers anything previously defined.</para> <para>You should remove optimization flags from the third party <filename>Makefile</filename>s. System - <makevar>CFLAGS</makevar> contains system-wide optimization + <varname>CFLAGS</varname> contains system-wide optimization flags. An example from an unmodified <filename>Makefile</filename>:</para> @@ -11949,7 +11846,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> <programlisting>CFLAGS+= -DHAVE_SOUND</programlisting> </sect1> - <sect1 id="dads-pthread"> + <sect1 xml:id="dads-pthread"> <title>Threading Libraries</title> <para>The threading library must be linked to the binaries using @@ -11961,14 +11858,14 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> <para>If building the port errors out with <literal>unrecognized option '-pthread'</literal>, it may be desirable to use <command>cc</command> as linker by setting - <makevar>CONFIGURE_ENV</makevar> to + <varname>CONFIGURE_ENV</varname> to <literal>LD=${CC}</literal>. The <literal>-pthread</literal> option is not supported by <command>ld</command> directly.</para> </note> </sect1> - <sect1 id="dads-freedback"> + <sect1 xml:id="dads-freedback"> <title>Feedback</title> <para>Do send applicable changes/patches to the original @@ -11977,7 +11874,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> release.</para> </sect1> - <sect1 id="dads-readme"> + <sect1 xml:id="dads-readme"> <title><filename>README.html</filename></title> <para>Do not include the <filename>README.html</filename> file. @@ -11986,15 +11883,15 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> <note> <para>If <command>make readme</command> fails, make sure that - the default value of <makevar>ECHO_MSG</makevar> has not + the default value of <varname>ECHO_MSG</varname> has not been modified by the port.</para> </note> </sect1> - <sect1 id="dads-noinstall"> + <sect1 xml:id="dads-noinstall"> <title>Marking a Port Not Installable with - <makevar>BROKEN</makevar>, <makevar>FORBIDDEN</makevar>, or - <makevar>IGNORE</makevar></title> + <varname>BROKEN</varname>, <varname>FORBIDDEN</varname>, or + <varname>IGNORE</varname></title> <para>In certain cases users should be prevented from installing a port. To tell a user that a port should not be installed, @@ -12010,12 +11907,12 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> cluster</link>, <link linkend="freshports">FreshPorts</link>, and <link linkend="portsmon">portsmon</link>.</para> - <sect2 id="dads-noinstall-variables"> + <sect2 xml:id="dads-noinstall-variables"> <title>Variables</title> <itemizedlist> <listitem> - <para><makevar>BROKEN</makevar> is reserved for ports that + <para><varname>BROKEN</varname> is reserved for ports that currently do not compile, install, or deinstall correctly. It should be used for ports where the problem is believed to be temporary.</para> @@ -12025,7 +11922,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> has been resolved. (However, in general, the cluster is run without this.)</para> - <para>For instance, use <makevar>BROKEN</makevar> when a + <para>For instance, use <varname>BROKEN</varname> when a port:</para> <itemizedlist> @@ -12053,12 +11950,12 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> </listitem> <listitem> - <para><makevar>FORBIDDEN</makevar> is used for ports that + <para><varname>FORBIDDEN</varname> is used for ports that contain a security vulnerability or induce grave concern regarding the security of a FreeBSD system with a given port installed (e.g., a reputably insecure program or a program that provides easily exploitable services). - Ports should be marked as <makevar>FORBIDDEN</makevar> + Ports should be marked as <varname>FORBIDDEN</varname> as soon as a particular piece of software has a vulnerability and there is no released upgrade. Ideally ports should be upgraded as soon as possible when a @@ -12068,18 +11965,18 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> noticeable time gap between disclosure of a vulnerability and an updated release of the vulnerable software. Do not mark a port - <makevar>FORBIDDEN</makevar> for any reason other than + <varname>FORBIDDEN</varname> for any reason other than security.</para> </listitem> <listitem> - <para><makevar>IGNORE</makevar> is reserved for ports that + <para><varname>IGNORE</varname> is reserved for ports that should not be built for some other reason. It should be used for ports where the problem is believed to be structural. The build cluster will not, under any circumstances, build ports marked as - <makevar>IGNORE</makevar>. For instance, use - <makevar>IGNORE</makevar> when a port:</para> + <varname>IGNORE</varname>. For instance, use + <varname>IGNORE</varname> when a port:</para> <itemizedlist> <listitem> @@ -12104,8 +12001,8 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> <listitem> <para>does not work with some other currently installed port (for instance, the port depends on - <filename role="package">www/apache20</filename> but - <filename role="package">www/apache22</filename> is + <package>www/apache20</package> but + <package>www/apache22</package> is installed)</para> </listitem> </itemizedlist> @@ -12115,47 +12012,47 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> installed port (for example, if they install a file in the same place that performs a different function), <link linkend="conflicts">use - <makevar>CONFLICTS</makevar> instead</link>. - <makevar>CONFLICTS</makevar> will set - <makevar>IGNORE</makevar> by itself.</para> + <varname>CONFLICTS</varname> instead</link>. + <varname>CONFLICTS</varname> will set + <varname>IGNORE</varname> by itself.</para> </note> </listitem> <listitem> - <para>If a port should be marked <makevar>IGNORE</makevar> + <para>If a port should be marked <varname>IGNORE</varname> only on certain architectures, there are two other convenience variables that will automatically set - <makevar>IGNORE</makevar> for you: - <makevar>ONLY_FOR_ARCHS</makevar> and - <makevar>NOT_FOR_ARCHS</makevar>. Examples:</para> + <varname>IGNORE</varname> for you: + <varname>ONLY_FOR_ARCHS</varname> and + <varname>NOT_FOR_ARCHS</varname>. Examples:</para> <programlisting>ONLY_FOR_ARCHS= i386 amd64</programlisting> <programlisting>NOT_FOR_ARCHS= ia64 sparc64</programlisting> - <para>A custom <makevar>IGNORE</makevar> message can be - set using <makevar>ONLY_FOR_ARCHS_REASON</makevar> and - <makevar>NOT_FOR_ARCHS_REASON</makevar>. Per + <para>A custom <varname>IGNORE</varname> message can be + set using <varname>ONLY_FOR_ARCHS_REASON</varname> and + <varname>NOT_FOR_ARCHS_REASON</varname>. Per architecture entries are possible with - <makevar>ONLY_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></makevar> + <varname>ONLY_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></varname> and - <makevar>NOT_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></makevar>.</para> + <varname>NOT_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></varname>.</para> </listitem> <listitem> <para>If a port fetches i386 binaries and installs them, - <makevar>IA32_BINARY_PORT</makevar> should be set. If + <varname>IA32_BINARY_PORT</varname> should be set. If this variable is set, it will be checked whether the <filename>/usr/lib32</filename> directory is available for IA32 versions of libraries and whether the kernel has IA32 compatibility compiled in. If one of these two - dependencies is not satisfied, <makevar>IGNORE</makevar> + dependencies is not satisfied, <varname>IGNORE</varname> will be set automatically.</para> </listitem> </itemizedlist> </sect2> - <sect2 id="dads-noinstall-notes"> + <sect2 xml:id="dads-noinstall-notes"> <title>Implementation Notes</title> <para>The strings should not be quoted. @@ -12176,25 +12073,25 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> </sect2> </sect1> - <sect1 id="dads-deprecated"> + <sect1 xml:id="dads-deprecated"> <title>Marking a Port for Removal with - <makevar>DEPRECATED</makevar> or - <makevar>EXPIRATION_DATE</makevar></title> + <varname>DEPRECATED</varname> or + <varname>EXPIRATION_DATE</varname></title> - <para>Do remember that <makevar>BROKEN</makevar> and - <makevar>FORBIDDEN</makevar> are to be used as a temporary + <para>Do remember that <varname>BROKEN</varname> and + <varname>FORBIDDEN</varname> are to be used as a temporary resort if a port is not working. Permanently broken ports should be removed from the tree entirely.</para> <para>When it makes sense to do so, users can be warned about - a pending port removal with <makevar>DEPRECATED</makevar> - and <makevar>EXPIRATION_DATE</makevar>. The former is + a pending port removal with <varname>DEPRECATED</varname> + and <varname>EXPIRATION_DATE</varname>. The former is simply a string stating why the port is scheduled for removal; the latter is a string in ISO 8601 format (YYYY-MM-DD). Both will be shown to the user.</para> - <para>It is possible to set <makevar>DEPRECATED</makevar> - without an <makevar>EXPIRATION_DATE</makevar> (for instance, + <para>It is possible to set <varname>DEPRECATED</varname> + without an <varname>EXPIRATION_DATE</varname> (for instance, recommending a newer version of the port), but the converse does not make any sense.</para> @@ -12205,7 +12102,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> problems.</para> </sect1> - <sect1 id="dads-dot-error"> + <sect1 xml:id="dads-dot-error"> <title>Avoid Use of the <literal>.error</literal> Construct</title> @@ -12213,7 +12110,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> signal that the port can not be installed due to some external factor (for instance, the user has specified an illegal combination of build options) is to set a non-blank value to - <makevar>IGNORE</makevar>. This value will be formatted and + <varname>IGNORE</varname>. This value will be formatted and shown to the user by <command>make install</command>.</para> <para>It is a common mistake to use <literal>.error</literal> @@ -12225,7 +12122,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> trivial commands such as <command>make maintainer</command> also fail in this scenario. This is not acceptable.</para> - <example id="dot-error-breaks-index"> + <example xml:id="dot-error-breaks-index"> <title>How to Avoid Using <literal>.error</literal></title> <para>Assume that someone has the line</para> @@ -12247,7 +12144,7 @@ IGNORE= POINTYHAT is not supported </example> </sect1> - <sect1 id="dads-sysctl"> + <sect1 xml:id="dads-sysctl"> <title>Usage of <filename>sysctl</filename></title> <para>The usage of <filename>sysctl</filename> is discouraged @@ -12257,12 +12154,12 @@ IGNORE= POINTYHAT is not supported further slowing down that process.</para> <para>Usage of &man.sysctl.8; should always be done with the - <makevar>SYSCTL</makevar> variable, as it contains the fully + <varname>SYSCTL</varname> variable, as it contains the fully qualified path and can be overridden, if one has such a special need.</para> </sect1> - <sect1 id="dads-rerolling-distfiles"> + <sect1 xml:id="dads-rerolling-distfiles"> <title>Rerolling Distfiles</title> <para>Sometimes the authors of software change the content of @@ -12284,7 +12181,7 @@ IGNORE= POINTYHAT is not supported and confirm the changes with them.</para> </sect1> - <sect1 id="dads-avoiding-linuxisms"> + <sect1 xml:id="dads-avoiding-linuxisms"> <title>Avoiding Linuxisms</title> <para>Do not use <filename>/proc</filename> if there are any @@ -12323,8 +12220,7 @@ IGNORE= POINTYHAT is not supported do a check for the behaviour in the configure stage, and stop if it is missing.</para> - <para>Check the <ulink - url="http://www.freebsd.org/cgi/man.cgi">man pages</ulink> + <para>Check the <link xlink:href="http://www.freebsd.org/cgi/man.cgi">man pages</link> to see if the function used is a <acronym>POSIX</acronym> interface (in the <quote>STANDARDS</quote> section of the man page).</para> @@ -12335,8 +12231,7 @@ IGNORE= POINTYHAT is not supported <acronym>POSIX</acronym> compliant shell.</para> <para>A list of common <application>bash</application>isms is - available <ulink - url="https://wiki.ubuntu.com/DashAsBinSh">here</ulink>.</para> + available <link xlink:href="https://wiki.ubuntu.com/DashAsBinSh">here</link>.</para> <para>Check that headers are included in the <acronym>POSIX</acronym> or man page recommended way, e.g., @@ -12348,7 +12243,7 @@ IGNORE= POINTYHAT is not supported variations thereof.</para> </sect1> - <sect1 id="dads-misc"> + <sect1 xml:id="dads-misc"> <title>Miscellanea</title> <para>The files <filename>pkg-descr</filename> and @@ -12364,7 +12259,7 @@ IGNORE= POINTYHAT is not supported </sect1> </chapter> - <chapter id="porting-samplem"> + <chapter xml:id="porting-samplem"> <title>A Sample <filename>Makefile</filename></title> <para>Here is a sample <filename>Makefile</filename> that you can @@ -12458,18 +12353,18 @@ pre-install: .include <bsd.port.mk></programlisting> </chapter> - <chapter id="keeping-up"> + <chapter xml:id="keeping-up"> <title>Keeping Up</title> <para>The &os; Ports Collection is constantly changing. Here is some information on how to keep up.</para> - <sect1 id="freshports"> + <sect1 xml:id="freshports"> <title>FreshPorts</title> <para>One of the easiest ways to learn about updates that have already been committed is by subscribing to - <ulink url="http://www.FreshPorts.org/">FreshPorts</ulink>. + <link xlink:href="http://www.FreshPorts.org/">FreshPorts</link>. You can select multiple ports to monitor. Maintainers are strongly encouraged to subscribe, because they will receive notification of not only their own changes, but also any @@ -12498,23 +12393,20 @@ pre-install: commits.</para> </sect1> - <sect1 id="svnweb"> + <sect1 xml:id="svnweb"> <title>The Web Interface to the Source Repository</title> <para>It is possible to browse the files in the source repository by using a web interface. Changes that affect the - entire port system are now documented in the <ulink - url="http://svnweb.FreeBSD.org/ports/head/CHANGES">CHANGES</ulink> + entire port system are now documented in the <link xlink:href="http://svnweb.FreeBSD.org/ports/head/CHANGES">CHANGES</link> file. Changes that affect individual ports - are now documented in the <ulink - url="http://svnweb.FreeBSD.org/ports/head/UPDATING">UPDATING</ulink> + are now documented in the <link xlink:href="http://svnweb.FreeBSD.org/ports/head/UPDATING">UPDATING</link> file. However, the definitive answer to - any question is undoubtedly to read the source code of <ulink - url="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.port.mk">bsd.port.mk</ulink>, + any question is undoubtedly to read the source code of <link xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.port.mk">bsd.port.mk</link>, and associated files.</para> </sect1> - <sect1 id="ports-mailling-list"> + <sect1 xml:id="ports-mailling-list"> <title>The &os; Ports Mailing List</title> <para>If you maintain ports, you should consider following the @@ -12527,34 +12419,34 @@ pre-install: discussion.</para> </sect1> - <sect1 id="build-cluster"> + <sect1 xml:id="build-cluster"> <title>The &os; Port Building Cluster on - <hostid role="hostname">pointyhat.FreeBSD.org</hostid></title> + <systemitem class="fqdomainname">pointyhat.FreeBSD.org</systemitem></title> <para>One of the least-publicized strengths of &os; is that an entire cluster of machines is dedicated to continually building the Ports Collection, for each of the major OS releases and for each Tier-1 architecture. You can find the results of these builds at - <ulink url="http://pointyhat.FreeBSD.org/">package building - logs and errors</ulink>.</para> + <link xlink:href="http://pointyhat.FreeBSD.org/">package building + logs and errors</link>.</para> <para>Individual ports are built unless they are specifically - marked with <makevar>IGNORE</makevar>. Ports that are - marked with <makevar>BROKEN</makevar> will still be attempted, + marked with <varname>IGNORE</varname>. Ports that are + marked with <varname>BROKEN</varname> will still be attempted, to see if the underlying problem has been resolved. (This - is done by passing <makevar>TRYBROKEN</makevar> to the + is done by passing <varname>TRYBROKEN</varname> to the port's <filename>Makefile</filename>.)</para> </sect1> - <sect1 id="distfile-survey"> + <sect1 xml:id="distfile-survey"> <title>Portscout: the &os; Ports Distfile Scanner</title> <para>The build cluster is dedicated to building the latest release of each port with distfiles that have already been fetched. However, as the Internet continually changes, distfiles can quickly go missing. - <ulink url="http://portscout.FreeBSD.org">Portscout</ulink>, + <link xlink:href="http://portscout.FreeBSD.org">Portscout</link>, the &os; Ports distfile scanner, attempts to query every download site for every port to find out if each distfile is still available. <application>Portscout</application> can @@ -12580,16 +12472,16 @@ pre-install: search for a specific port.</para> <para>Clicking on a port name in the list displays the - <ulink url="http://freshports.org">FreshPorts</ulink> port + <link xlink:href="http://freshports.org">FreshPorts</link> port information.</para> </sect1> - <sect1 id="portsmon"> + <sect1 xml:id="portsmon"> <title>The &os; Ports Monitoring System</title> <para>Another handy resource is the - <ulink url="http://portsmon.FreeBSD.org">FreeBSD Ports - Monitoring System</ulink> (also known as + <link xlink:href="http://portsmon.FreeBSD.org">FreeBSD Ports + Monitoring System</link> (also known as <literal>portsmon</literal>). This system comprises a database that processes information from several sources and allows it to be browsed via a web interface. Currently, the @@ -12599,9 +12491,8 @@ pre-install: distfile survey, as well as other sources.</para> <para>To get started, you can view all information about a - particular port by using the <ulink - url="http://portsmon.FreeBSD.org/portoverview.py">Overview - of One Port</ulink>.</para> + particular port by using the <link xlink:href="http://portsmon.FreeBSD.org/portoverview.py">Overview + of One Port</link>.</para> <para>As of this writing, this is the only resource available that maps GNATS PR entries to portnames. (PR submitters do @@ -12614,14 +12505,14 @@ pre-install: </sect1> </chapter> - <chapter id="appendices"> + <chapter xml:id="appendices"> <title>Appendices</title> - <sect1 id="uses-values"> - <title>Values of <makevar>USES</makevar></title> + <sect1 xml:id="uses-values"> + <title>Values of <varname>USES</varname></title> <table frame="none"> - <title>Values of <makevar>USES</makevar></title> + <title>Values of <varname>USES</varname></title> <tgroup cols="3"> <thead> @@ -12639,13 +12530,12 @@ pre-install: </table> </sect1> - <sect1 id="freebsd-versions"> + <sect1 xml:id="freebsd-versions"> <title><literal>__FreeBSD_version</literal> Values</title> <para>Here is a convenient list of <literal>__FreeBSD_version</literal> values as defined in - <ulink - url="http://svnweb.FreeBSD.org/base/head/sys/sys/param.h?view=markup">sys/param.h</ulink>:</para> + <link xlink:href="http://svnweb.FreeBSD.org/base/head/sys/sys/param.h?view=markup">sys/param.h</link>:</para> <table frame="none"> <title><literal>__FreeBSD_version</literal> Values</title> |