Date: Fri, 25 May 2012 03:08:43 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r38883 - head/en_US.ISO8859-1/books/porters-handbook Message-ID: <201205250308.q4P38h23076684@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Fri May 25 03:08:43 2012 New Revision: 38883 URL: http://svn.freebsd.org/changeset/doc/38883 Log: Update the Using Perl section. Some wording and markup corrections, and a rewording of the note about not using ${SITE_PERL}. Reviewed by: jgh, crees, swills Modified: head/en_US.ISO8859-1/books/porters-handbook/book.sgml Modified: head/en_US.ISO8859-1/books/porters-handbook/book.sgml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/book.sgml Fri May 25 02:32:14 2012 (r38882) +++ head/en_US.ISO8859-1/books/porters-handbook/book.sgml Fri May 25 03:08:43 2012 (r38883) @@ -5461,12 +5461,12 @@ PLIST_SUB+= NLS="@comment " </sect1> <sect1 id="using-perl"> - <title>Using <literal>perl</literal></title> + <title>Using <application>Perl</application></title> <para>If <makevar>MASTER_SITES</makevar> is set to - <makevar>MASTER_SITE_PERL_CPAN</makevar>, then preferred value - of <makevar>MASTER_SITE_SUBDIR</makevar> is top-level - hierarchy name. For example, the recommend value for + <makevar>MASTER_SITE_PERL_CPAN</makevar>, then the preferred value + of <makevar>MASTER_SITE_SUBDIR</makevar> 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 @@ -5475,56 +5475,56 @@ PLIST_SUB+= NLS="@comment " changes.</para> <para>The exception to this rule is when the relevant directory - does not exist or the distfile does not exist in the + 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> - <para>All of the tunable knobs below accept both - <literal>YES</literal> and a version string, like - <literal>5.8.0+</literal>. Using <literal>YES</literal> means - that the port can be used with all of the supported - <application>Perl</application> versions. If a port only + <para>All of the tunable knobs below accept either + <literal>YES</literal> or a version string like + <literal>5.8.0+</literal>. <literal>YES</literal> means + that the port can be used with any of the supported + Perl versions. If a port only works with specific versions of - <application>Perl</application>, it can be indicated with a - version string, specifying a minimal version (e.g. - <literal>5.7.3+</literal>), a maximal version (e.g. - <literal>5.8.0-</literal>) or an exact version (e.g. + Perl, it can be indicated with a + version string, specifying a minimum version (e.g., + <literal>5.7.3+</literal>), a maximum version (e.g., + <literal>5.8.0-</literal>) or an exact version (e.g., <literal>5.8.3</literal>).</para> <table frame="none"> <title>Variables for Ports That Use - <literal>perl</literal></title> + <application>Perl</application></title> <tgroup cols="2"> <thead> <row> <entry>Variable</entry> - <entry>Means</entry> + <entry>Meaning</entry> </row> </thead> <tbody> <row> <entry><makevar>USE_PERL5</makevar></entry> - <entry>Says that the port uses <literal>perl 5</literal> + <entry>The port uses Perl 5 to build and run.</entry> </row> <row> <entry><makevar>USE_PERL5_BUILD</makevar></entry> - <entry>Says that the port uses <literal>perl 5</literal> + <entry>The port uses Perl 5 to build.</entry> </row> <row> <entry><makevar>USE_PERL5_RUN</makevar></entry> - <entry>Says that the port uses <literal>perl 5</literal> + <entry>The port uses Perl 5 to run.</entry> </row> <row> <entry><makevar>PERL</makevar></entry> - <entry>The full path of <literal>perl 5</literal>, + <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 replace <quote><literal>#!</literal></quote>lines in @@ -5555,60 +5555,61 @@ PLIST_SUB+= NLS="@comment " <tbody> <row> <entry><makevar>PERL_VERSION</makevar></entry> - <entry>The full version of <literal>perl</literal> + <entry>The full version of Perl installed (e.g., <literal>5.8.9</literal>).</entry> </row> <row> <entry><makevar>PERL_LEVEL</makevar></entry> - <entry>The installed <literal>perl</literal> version as + <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>Where <literal>perl</literal> stores architecture + <entry>Where Perl stores architecture dependent libraries. Defaults to <literal>${ARCH}-freebsd</literal>.</entry> </row> <row> <entry><makevar>PERL_PORT</makevar></entry> - <entry>Name of the <literal>perl</literal> port that is + <entry>Name of the Perl port that is installed (e.g., <literal>perl5</literal>).</entry> </row> <row> <entry><makevar>SITE_PERL</makevar></entry> <entry>Directory name where site specific - <literal>perl</literal> packages go. This value is - added to PLIST_SUB.</entry> + Perl packages go. This value is + added to <makevar>PLIST_SUB</makevar>.</entry> </row> </tbody> </tgroup> </table> <note> - <para>Ports of Perl modules, which do not have an official - website, should link <hostid>cpan.org</hostid> in the WWW - line of a <filename>pkg-descr</filename> file. The + <para>Ports of Perl modules which do not have an official + website should link to <hostid>cpan.org</hostid> in the WWW + line of <filename>pkg-descr</filename>. The preferred URL form is <literal>http://search.cpan.org/dist/Module-Name/</literal>; (including the trailing slash).</para> </note> + <note> - <para>It is recommended to avoid using <literal> - ${SITE_PERL}</literal> as a dependency listing. This is - problematic because it means that - <filename>bsd.perl.mk</filename> must be included - to satisfy the dependency. Additionally, if the module's - files change, it would require changing all - dependent ports.</para> + <para>Do not use <literal>${SITE_PERL}</literal> in dependency + declarations. Doing so assumes that + <filename>bsd.perl.mk</filename> has been included, which is + not always true. Ports depending on this port will have + incorrect dependencies if this port's files move later in an + upgrade. The right way to declare Perl module dependencies + is shown in the example below.</para> </note> <example id="use-perl-dependency-example"> - <title>PERL Dependency Example</title> + <title>Perl Dependency Example</title> <programlisting>p5-IO-Tee>=0.64:${PORTSDIR}/devel/p5-IO-Tee</programlisting> </example>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201205250308.q4P38h23076684>