os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Describe and recommend the use of the LATEST_LINK variable in

Browse source 
the Committer's Guide ports repo-copy section and in the package naming
section of the Porter's Handbook.  In the end, I wrote something that
turned out quite a bit different and somewhat more long-winded than
the suggestions in the PR, but LATEST_LINK was not documented anywhere
until now, so there :)

PR:		66775
Submitted by:	eik
This commit is contained in:
Peter Pentchev 2007-04-25 13:13:22 +00:00
parent 444f23be02
commit be122238a0
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=30088
2 changed files with 62 additions and 12 deletions
en_US.ISO8859-1
articles/committers-guide
article.sgml
books/porters-handbook
book.sgml

24
en_US.ISO8859-1/articles/committers-guide/article.sgml
View file

@ -731,11 +731,11 @@ alias scvs cvs -d <replaceable>user</replaceable>@ncvs.FreeBSD.org:/home/ncvs</p
</itemizedlist>
<para>You will almost certainly get a conflict because
of the <literal>$Id: article.sgml,v 1.260 2007-04-08 17:45:24 blackend Exp $</literal> (or in FreeBSD's case,
of the <literal>$Id: article.sgml,v 1.261 2007-04-25 13:13:22 roam Exp $</literal> (or in FreeBSD's case,
<literal>$<!-- stop expansion -->FreeBSD<!-- stop expansion -->$</literal>)
lines, so you will have to edit the file to resolve the conflict
(remove the marker lines and the second <literal>$Id: article.sgml,v 1.260 2007-04-08 17:45:24 blackend Exp $</literal> line,
leaving the original <literal>$Id: article.sgml,v 1.260 2007-04-08 17:45:24 blackend Exp $</literal> line intact).</para>
(remove the marker lines and the second <literal>$Id: article.sgml,v 1.261 2007-04-25 13:13:22 roam Exp $</literal> line,
leaving the original <literal>$Id: article.sgml,v 1.261 2007-04-25 13:13:22 roam Exp $</literal> line intact).</para>
</listitem>
<listitem>
@ -2547,9 +2547,21 @@ docs:Documentation Bug:freebsd-doc:</programlisting>
<procedure>
<step>
<para>Upgrade the copied port to the new version (remember
to change the <makevar>PORTNAME</makevar> so there
are not duplicate ports with the same name).</para>
<para>Upgrade the copied port to the new version.
Remember to change the <makevar>LATEST_LINK</makevar>
so there are no duplicate ports with the same name.
In some rare cases it may be necessary to change the
<makevar>PORTNAME</makevar> instead of
<makevar>LATEST_LINK</makevar>, but this should only
be done when it is really needed &mdash; e.g. using
an existing port as the base for a very similar
program with a different name, or upgrading a port to
a new upstream version which actually changes the
distribution name, like the transition from
<filename>textproc/libxml</filename> to
<filename>textproc/libxml2</filename>. In most cases,
changing <makevar>LATEST_LINK</makevar> should
suffice.</para>
</step>
<step>

50
en_US.ISO8859-1/books/porters-handbook/book.sgml
View file

@ -1043,6 +1043,28 @@ PORTEPOCH= 1</programlisting>
them part of <makevar>PORTNAME</makevar>.</para>
</sect2>
<sect2>
<title><makevar>LATEST_LINK</makevar></title>
<para>In some cases, several versions of a program may be 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 set to
a different value for all ports except the <quote>main</quote>
one &mdash; see the <filename>editors/vim5</filename> and
<filename>editors/vim</filename> ports, and the
<filename>www/apache*</filename> family for examples of its use.
Note that how to choose a <quote>main</quote> version &mdash;
<quote>most popular</quote>, <quote>best supported</quote>,
<quote>least patched</quote>, and so on &mdash; is outside the
scope of this handbook's recommendations; we only tell you how to
specify the other ports' versions after you have picked a
<quote>main</quote> one.</para>
</sect2>
<sect2 id="porting-pkgname">
<title>Package Naming Conventions</title>
@ -1079,17 +1101,33 @@ PORTEPOCH= 1</programlisting>
</listitem>
<listitem>
<para>The first letter of <filename>name</filename> part
should be lowercase. (The rest of the name can contain
<para>The first letter of the <filename>name</filename> part
should be lowercase. (The rest of the name may contain
capital letters, so use your own discretion when you are
converting a software name that has some capital letters in it.)
There is a tradition of naming <literal>perl 5</literal> modules by
There is a tradition of naming <literal>Perl 5</literal> modules by
prepending <literal>p5-</literal> and converting the double-colon
separator to a hyphen; for example, the
<literal>Data::Dumper</literal> module becomes
<literal>p5-Data-Dumper</literal>. If the software in question
has numbers, hyphens, or underscores in its name, you may include
them as well (like <literal>kinput2</literal>).</para>
<literal>p5-Data-Dumper</literal>.</para>
</listitem>
<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 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 contain any
version-specific information. It is quite normal for several
ports to have the same <makevar>PORTNAME</makevar>, 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>
</listitem>
<listitem>