Skip site navigation (1)Skip section navigation (2)
Date:      Mon, 3 Apr 2000 01:38:48 -0700 (PDT)
From:      asami@cs.berkeley.edu (Satoshi Asami)
To:        ports@freebsd.org
Cc:        jim@freebsd.org
Subject:   porting section (handbook) diff
Message-ID:  <200004030838.BAA52719@silvia.hip.berkeley.edu>

next in thread | raw e-mail | index | archive | help
Hi,

Please review the following diff.  It includes changes for
PORTNAME/PORTVERSION, including a little blurb about choosing version
numbers carefully so they can be sorted mechanically), removing a.out
support (actually removing the section for a.out/ELF support), and not
including info/dir in the PLIST that you generate.

Satoshi

P.S. Jim, please take a look at the use of various tags in the first
     couple of hunks.  (Gosh, I long for the day when I didn't have to
     worry about which of the bazzilion tags I should use for
     something I just wanted to be in fixed width font.... ;)

Index: ports/chapter.sgml
===================================================================
RCS file: /usr/cvs/doc/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml,v
retrieving revision 1.91
diff -u -r1.91 chapter.sgml
--- chapter.sgml	2000/03/17 16:46:01	1.91
+++ chapter.sgml	2000/04/03 08:36:59
@@ -1023,14 +1023,14 @@
 
         <programlisting>
 # New ports collection makefile for:   oneko
-# Version required:    1.1b
 # Date created:        5 December 1994
 # Whom:                asami
 #
 # &dollar;FreeBSD&dollar;
 #
 
-DISTNAME=      oneko-1.1b
+PORTNAME=      oneko
+PORTVERSION=   1.1b
 CATEGORIES=    games
 MASTER_SITES=  ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
 
@@ -1555,9 +1555,12 @@
       <sect3>
         <title>The original source</title>
 
-        <para>Does it live in <makevar>DISTDIR</makevar> as a standard gzip'd
-          tarball? If so, you can go on to the next step.  If not, you should
-          look at overriding any of the <makevar>EXTRACT_CMD</makevar>,
+        <para>Does it live in <makevar>DISTDIR</makevar> as a standard
+          gzip'd tarball named something like
+          <literal>foozolix-1.2.tar.gz</literal>? If so, you can go on
+          to the next step.  If not, you should look at overriding any
+          of the <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>
@@ -1573,40 +1576,35 @@
       </sect3>
 
       <sect3>
-        <title><makevar>DISTNAME</makevar></title>
+        <title><makevar>PORTNAME</makevar> and <makevar>PORTVERSION</makevar></title>
 
-        <para>You should set <makevar>DISTNAME</makevar> to be the base name
-          of your port.  The default rules expect the distribution file list
-          (<makevar>DISTFILES</makevar>) to be named
-          <makevar>DISTNAME</makevar><makevar>EXTRACT_SUFX</makevar> which, if
-          it is a normal tarball, is going to be something like
-          <literal>foozolix-1.0.tar.gz</literal> for a setting of
-          <literal>DISTNAME=foozolix-1.0</literal>.</para>
-
-        <para>The default rules also expect the tarball(s) to extract into a
-          subdirectory called
-          <filename>work/<makevar>DISTNAME</makevar></filename>, e.g.
-          <filename>work/foozolix-1.0/</filename>.</para>
-
-        <para>All this behavior can be overridden, of course; it simply
-          represents the most common time-saving defaults.  For a port
-          requiring multiple distribution files, simply set
-          <makevar>DISTFILES</makevar> explicitly.  If only a subset of
-          <makevar>DISTFILES</makevar> are actual extractable archives, then
-          set them up in <makevar>EXTRACT_ONLY</makevar>, which will override
-          the <makevar>DISTFILES</makevar> list when it comes to extraction,
-          and the rest will be just left in <makevar>DISTDIR</makevar> for
-          later use.</para>
+        <para>You should set <makevar>PORTNAME</makevar> to be the
+          base name of your port, and <makevar>PORTVERSION</makevar>
+          to the version number of the port.  They are combined to
+          form <makevar>PKGNAME</makevar> as
+          <literal>${PORTNAME}-${PORTVERSION}</literal>.
+          Make sure this conforms to our <link
+          linkend="porting-pkgname">guidelines for a good package
+          name</link>.  In particular, you are not allowed to use a
+          hyphen (<literal>-</literal>) in
+          <makevar>PORTVERSION</makevar>.</para>
       </sect3>
 
       <sect3>
-        <title><makevar>PKGNAME</makevar></title>
-
-        <para>If <makevar>DISTNAME</makevar> does not conform to our <link
-            linkend="porting-pkgname">guidelines for a good package
-            name</link>, you should set the <makevar>PKGNAME</makevar>
-          variable to something better.  See the abovementioned guidelines for
-          more details.</para>
+
+        <title><makevar>DISTNAME</makevar></title>
+
+        <para><makevar>DISTNAME</makevar> is the name of the port as
+          called by the authors of the software.
+          <makevar>DISTNAME</makevar> defaults to
+          <makevar>PKGNAME</makevar>, so override it if necessary.
+          <makevar>DISTNAME</makevar> is only used in two places.
+          First, the distribution file list
+          (<makevar>DISTFILES</makevar>) defaults to
+          <makevar>${DISTNAME}</makevar><makevar>${EXTRACT_SUFX}</makevar>.
+          Second, the distribution file is expected to extract into a
+          subdirectory named <makevar>WRKSRC</makevar>, which defaults
+          to <filename>work/<makevar>${DISTNAME}</makevar></filename>.</para>
       </sect3>
 
       <sect3>
@@ -2019,6 +2017,8 @@
       </sect3>
     </sect2>
 
+<!--
+
     <sect2>
       <title>ELF support</title>
 
@@ -2189,6 +2189,8 @@
       </sect3>
     </sect2>
 
+-->
+
     <sect2 id="porting-masterdir">
       <title><makevar>MASTERDIR</makevar></title>
 
@@ -2201,14 +2203,16 @@
         use variables cleverly.  In the sole <filename>Makefiles</filename>,
         you can use <makevar>MASTERDIR</makevar> to specify the directory
         where the rest of the files are.  Also, use a variable as part of
-        <link linkend="porting-pkgname"><makevar>PKGNAME</makevar></link> so
+        <link linkend="porting-pkgname"><makevar>PORTNAME</makevar> or
+        <makevar>PORTVERSION</makevar></link> so
         the packages will have different names.</para>
 
       <para>This will be best demonstrated by an example.  This is part of
         <filename>japanese/xdvi300/Makefile</filename>;</para>
 
       <programlisting>
-PKGNAME=       ja-xdvi${RESOLUTION}-17
+PORTNAME=       ja-xdvi${RESOLUTION}
+PORTVERSION=    17
  :
 # default
 RESOLUTION?=   300
@@ -2248,8 +2252,8 @@
     <sect2>
       <title>Shared library versions</title>
 
-      <para>First, please read our <link linkend="policies-shlib">policy on
-          shared library versioning</link> to understand what to do with
+      <para>Please read our <link linkend="policies-shlib">policy on
+        shared library versioning</link> to understand what to do with
         shared library versions in general.  Do not blindly assume software
         authors know what they are doing; many of them do not.  It is very
         important that these details are carefully considered, as we have
@@ -2257,11 +2261,12 @@
         potentially incompatible software pairs co-exist. Careless port
         imports have caused great trouble regarding shared libraries in the
         past (ever wondered why the port <filename>jpeg-6b</filename> has a
-        shared library version of 9.0?). If in doubt, send a message to the
+        shared library version of 9?). If in doubt, send a message to the
         &a.ports;.  Most of the time, your job ends by determining the right
         shared library version and making appropriate patches to implement
         it.</para>
 
+<!--
       <para>However, if there is a port which is a different version of the
         same software already in the tree, the situation is much more complex.
         In short, the FreeBSD implementation does not allow the user to
@@ -2277,6 +2282,7 @@
         <filename>libfoo.so.4.0</filename> to
         <filename>libfoo4.so.1.0</filename> so both version 3.2 and 4.0 can be
         linked from other ports.</para>
+-->
     </sect2>
 
     <sect2 id="porting-manpages">
@@ -2424,7 +2430,7 @@
         font path in <filename>/etc/XF86Config</filename>.</para>
     </sect2>
 
-    <sect2>
+    <sect2 id="porting-info">
       <title>Info files</title>
 
       <para>The new version of texinfo (included in 2.2.2-RELEASE and onwards)
@@ -3675,7 +3681,7 @@
 
         <para>Create a new directory for your port.  The directory name should
           reflect what the port is.  This usually means
-          <makevar>PKGNAME</makevar> minus the version part. However, if you
+          <makevar>PORTNAME</makevar>. 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>
@@ -3716,8 +3722,8 @@
           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 (<makevar>PKGNAME</makevar> without the
-          version part should work fine).  This will change
+          to the name of the port (<makevar>PORTNAME</makevar>
+          should work fine).  This will change
           <makevar>DISTDIR</makevar> from the default
           <filename>/usr/ports/distfiles</filename> to
           <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>,
@@ -4034,8 +4040,9 @@
       <programlisting>
 [the header...just to make it easier for us to identify the ports.]
 # New ports collection makefile for:   xdvi
-[the version required header should updated when upgrading a port.]
-# Version required:    pl18 [things like "1.5alpha" are fine here too]
+[the "version required" line is only needed when the PORTVERSION
+ variable is not specific enough to describe the port.]
+# Version required:    pl18 + japanization patches 18.1 and 18.2
 [this is the date when the first version of this Makefile was created.
 Never change this when doing an update of the port.]
 # Date created:                26 May 1995
@@ -4050,17 +4057,19 @@
 this line back to "&dollar;FreeBSD&dollar;".  CVS deals with it automatically.]
 #
 
-[section to describe the port itself and the master site - DISTNAME
- is always first, followed by PKGNAME (if necessary), CATEGORIES,
+[section to describe the port itself and the master site - PORTNAME
+ and PORTVERSION are always first, followed by CATEGORIES,
  and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR.
- After those, one of EXTRACT_SUFX or DISTFILES can be specified too.]
-DISTNAME=      xdvi
-PKGNAME=       xdvi-pl18
+ Then comes DISTNAME, EXTRACT_SUFX and/or DISTFILES, and then
+ EXTRACT_ONLY, as necessary.]
+PORTNAME=      xdvi
+PORTVERSION=   18.2
 CATEGORIES=    print
 [do not forget the trailing slash ("/")!
  if you are not using MASTER_SITE_* macros]
 MASTER_SITES=  ${MASTER_SITE_XCONTRIB}
 MASTER_SITE_SUBDIR= applications
+DISTNAME=      xdvi-pl18
 [set this if the source is not in the standard ".tar.gz" form]
 EXTRACT_SUFX=  .tar.Z
 
@@ -4149,7 +4158,11 @@
         <makevar>MAN<replaceable>n</replaceable></makevar>, and not in the
         package list.  User configuration files should be removed, or
         installed as
-        <filename><replaceable>filename</replaceable>.sample</filename>.  Any
+        <filename><replaceable>filename</replaceable>.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 <link linkend="porting-info">info
+        files</link> section.  Any
         libraries installed by the port should be listed as specified in the
         <link linkend="porting-ldconfig">ldconfig</link> section.</para>
     </sect2>
@@ -4165,8 +4178,10 @@
       <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>
 
-      <para>If your <makevar>DISTNAME</makevar> does not look like that, set
-        <makevar>PKGNAME</makevar> to something in that format.</para>
+      <para>The package name is defined as
+        <literal>${PORTNAME}-${PORTVERSION}</literal>.  Make sure to
+        choose your <makevar>PORTNAME</makevar> and
+        <makevar>PORTVERSION</makevar> to conform to that format.</para>
 
       <orderedlist>
         <listitem>
@@ -4220,109 +4235,126 @@
             version string.  The only exception is the string
             <literal>pl</literal> (meaning `patchlevel'), which can be
             used <emphasis>only</emphasis> when there are no major and
-            minor version numbers in the software.</para>
+            minor version numbers in the software.  If the software
+            version has strings like "alpha", "beta", or "pre", take
+            the first letter and put it immediately after a period.
+            If the version string continues after those names, the
+            numbers should follow the single alphabet without an extra
+            period between them.</para>
+
+          <para>The idea is to make it easier to sort ports by 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><replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>
+            format, not
+            <literal><replaceable>dd</replaceable>.<replaceable>mm</replaceable>.<replaceable>yyyy</replaceable></literal>
+            or the non-Y2K compliant
+            <literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>
+            format.</para>
         </listitem>
       </orderedlist>
 
-      <para>Here are some (real) examples on how to convert a
-        <makevar>DISTNAME</makevar> into a suitable
-        <makevar>PKGNAME</makevar>:</para>
+      <para>Here are some (real) examples on how to convert the name
+        as called by the software authors to a suitable package
+        name:</para>
 
       <informaltable frame="none">
-        <tgroup cols="3">
+        <tgroup cols="4">
           <thead>
             <row>
               <entry>Distribution Name</entry>
-              <entry>Package Name</entry>
+              <entry><makevar>PORTNAME</makevar></entry>
+              <entry><makevar>PORTVERSION</makevar></entry>
               <entry>Reason</entry>
             </row>
           </thead>
 
           <tbody>
             <row>
-              <entry>mule-2.2.2</entry>
               <entry>mule-2.2.2</entry>
+              <entry>mule</entry>
+              <entry>2.2.2</entry>
               <entry>No changes required</entry>
             </row>
 
             <row>
-              <entry>XFree86-3.1.2</entry>
-              <entry>XFree86-3.1.2</entry>
+              <entry>XFree86-3.3.6</entry>
+              <entry>XFree86</entry>
+              <entry>3.3.6</entry>
               <entry>No changes required</entry>
             </row>
 
             <row>
               <entry>EmiClock-1.0.2</entry>
-              <entry>emiclock-1.0.2</entry>
+              <entry>emiclock</entry>
+              <entry>1.0.2</entry>
               <entry>No uppercase names for single programs</entry>
             </row>
 
             <row>
-              <entry>gmod1.4</entry>
-              <entry>gmod-1.4</entry>
-              <entry>Need a hyphen before version numbers</entry>
-            </row>
-
-            <row>
-              <entry>xmris.4.0.2</entry>
-              <entry>xmris-4.0.2</entry>
-              <entry>Need a hyphen before version numbers</entry>
-            </row>
-
-            <row>
               <entry>rdist-1.3alpha</entry>
-              <entry>rdist-1.3a</entry>
+              <entry>rdist</entry>
+              <entry>1.3.a</entry>
               <entry>No strings like <literal>alpha</literal>
                 allowed</entry>
             </row>
 
             <row>
               <entry>es-0.9-beta1</entry>
-              <entry>es-0.9b1</entry>
+              <entry>es-0.9</entry>
+              <entry>b1</entry>
               <entry>No strings like <literal>beta</literal>
                 allowed</entry>
             </row>
 
             <row>
               <entry>v3.3beta021.src</entry>
-              <entry>tiff-3.3</entry>
+              <entry>tiff</entry>
+              <entry>3.3</entry>
               <entry>What the heck was that anyway?</entry>
             </row>
 
             <row>
               <entry>tvtwm</entry>
-              <entry>tvtwm-pl11</entry>
+              <entry>tvtwm</entry>
+              <entry>pl11</entry>
               <entry>Version string always required</entry>
             </row>
 
             <row>
+              <entry>piewm</entry>
               <entry>piewm</entry>
-              <entry>piewm-1.0</entry>
+              <entry>1.0</entry>
               <entry>Version string always required</entry>
             </row>
 
             <row>
               <entry>xvgr-2.10pl1</entry>
-              <entry>xvgr-2.10.1</entry>
+              <entry>xvgr</entry>
+              <entry>2.10.1</entry>
               <entry><literal>pl</literal> allowed only when no
                 major/minor version numbers</entry>
             </row>
 
             <row>
               <entry>gawk-2.15.6</entry>
-              <entry>ja-gawk-2.15.6</entry>
+              <entry>ja-gawk</entry>
+              <entry>2.15.6</entry>
               <entry>Japanese language version</entry>
             </row>
 
             <row>
               <entry>psutils-1.13</entry>
-              <entry>psutils-letter-1.13</entry>
+              <entry>psutils-letter</entry>
+              <entry>1.13</entry>
               <entry>Papersize hardcoded at package build time</entry>
             </row>
 
             <row>
               <entry>pkfonts</entry>
-              <entry>pkfonts300-1.0</entry>
+              <entry>pkfonts300</entry>
+              <entry>1.0</entry>
               <entry>Package for 300dpi fonts</entry>
             </row>
           </tbody>
@@ -4334,7 +4366,7 @@
         release another version, just set the version string to
         <literal>1.0</literal> (like the piewm example above).  Otherwise, ask
         the original author or use the date string
-        (<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>)
+        (<literal><replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>)
 	as the version.</para>
     </sect2>
 


To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-ports" in the body of the message




Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200004030838.BAA52719>