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 # # $FreeBSD$ # -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 "$FreeBSD$". 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>