diff options
Diffstat (limited to 'en_US.ISO8859-1/books/porters-handbook/book.sgml')
| -rw-r--r-- | en_US.ISO8859-1/books/porters-handbook/book.sgml | 4439 |
1 files changed, 0 insertions, 4439 deletions
diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml deleted file mode 100644 index a6e27859bc..0000000000 --- a/en_US.ISO8859-1/books/porters-handbook/book.sgml +++ /dev/null @@ -1,4439 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/porters-handbook/book.sgml,v 1.143 2001/04/17 01:39:30 dd Exp $ ---> - -<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -<!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN"> -%bookinfo; - -<!ENTITY % authors SYSTEM "../handbook/authors.ent"> %authors; -<!ENTITY % mailing-lists SYSTEM "../handbook/mailing-lists.ent"> -%mailing-lists; - -]> - -<book> - <bookinfo> - <title>FreeBSD Porter's Handbook</title> - - <authorgroup> - <corpauthor>The FreeBSD Documentation Project</corpauthor> - </authorgroup> - - <pubdate>April 2000</pubdate> - - <copyright> - <year>2000</year> - <holder role="mailto:doc@FreeBSD.org">The FreeBSD Documentation - Project</holder> - </copyright> - - &bookinfo.legalnotice; - </bookinfo> - - - <chapter> - <title>Making a port yourself</title> - - <para>So, now you are interested in making your own port or - upgrading an existing one? Great!</para> - - <para>What follows are some guidelines for creating a new port for - FreeBSD. If you want to upgrade an existing port, you should - read this and then read <xref linkend="port-upgrading">.</para> - - <para>When this document is not sufficiently detailed, you should - refer to <filename>/usr/ports/Mk/bsd.port.mk</filename>, which - all port Makefiles include. Even if you do not hack Makefiles - daily, it is well commented, and you will still gain much - knowledge from it. Additionally, you may send specific questions - to the &a.ports;.</para> - - <note> - <para>Only a fraction of the variables - (<makevar><replaceable>VAR</replaceable></makevar>) that can be - overridden are mentioned in this document. Most (if not all) - are documented at the start of <filename>bsd.port.mk</filename>. - This file uses a non-standard tab setting. - <application>Emacs</application> and - <application>Vim</application> should recognize the setting on - loading the file. Both <command>vi</command> and - <command>ex</command> can be set to use the correct value by - typing <command>:set tabstop=4</command> once the file has been - loaded.</para> - </note> - </chapter> - - <chapter id="quick-porting"> - <title>Quick Porting</title> - - <para>This section tells you how to do a quick port. In many cases, it - is not enough, but we will see.</para> - - <para>First, get the original tarball and put it into - <makevar>DISTDIR</makevar>, which defaults to - <filename>/usr/ports/distfiles</filename>.</para> - - <note> - <para>The following assumes that the software compiled out-of-the-box, - i.e., there was absolutely no change required for the port to work - on your FreeBSD box. If you needed to change something, you will - have to refer to the next section too.</para> - </note> - - <sect1> - <title>Writing the <filename>Makefile</filename></title> - - <para>The minimal <filename>Makefile</filename> would look something - like this:</para> - - <programlisting># New ports collection makefile for: oneko -# Date created: 5 December 1994 -# Whom: asami -# -# $FreeBSD$ -# - -PORTNAME= oneko -PORTVERSION= 1.1b -CATEGORIES= games -MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ - -MAINTAINER= asami@FreeBSD.org - -MAN1= oneko.1 -MANCOMPRESSED= yes -USE_IMAKE= yes - -.include <bsd.port.mk></programlisting> - - <para>See if you can figure it out. Do not worry about the contents - of the <literal>$FreeBSD$</literal> line, it will be - filled in automatically by CVS when the port is imported to our main - ports tree. You can find a more detailed example in the <link - linkend="porting-samplem">sample Makefile</link> section.</para> - </sect1> - - <sect1> - <title>Writing the description files</title> - - <para>There are three description files that are required for - any port, whether they actually package or not. They are - <filename>pkg-comment</filename>, - <filename>pkg-descr</filename>, and - <filename>pkg-plist</filename>, and their - <filename>pkg-</filename> prefix distinguishes them from - other files.</para> - - <sect2> - <title><filename>pkg-comment</filename></title> - - <para>This is the one-line description of the port. - <emphasis>Please</emphasis> do not include the package name (or - version number of the software) in the comment. The comment - should begin with a capital, and end without a period. Here - is an example:</para> - - <programlisting>A cat chasing a mouse all over the screen</programlisting> - </sect2> - - <sect2> - <title><filename>pkg-descr</filename></title> - - <para>This is a longer description of the port. One to a few - paragraphs concisely explaining what the port does is - sufficient.</para> - - <note> - <para>This is <emphasis>not</emphasis> a manual or an in-depth - description on how to use or compile the port! <emphasis>Please - be careful if you are copying from the - <filename>README</filename> or manpage</emphasis>; too often - they are not a concise description of the port or are in an - awkward format (e.g., manpages have justified spacing). If the - ported software has an official WWW homepage, you should list it - here. Prefix <emphasis>one</emphasis> of the websites with - <literal>WWW:</literal> so that automated tools will work - correctly.</para> - </note> - - <para>It is recommended that you sign your name at the end of this - file, as in:</para> - - <programlisting>This is a port of oneko, in which a cat chases a poor mouse all over -the screen. - : -(etc.) - -WWW: http://www.oneko.org/ - -- Satoshi -asami@cs.berkeley.edu</programlisting> - </sect2> - - <sect2> - <title><filename>pkg-plist</filename></title> - - <para>This file lists all the files installed by the port. It is - also called the “packing list” because the package is - generated by packing the files listed here. The pathnames are - relative to the installation prefix (usually - <filename>/usr/local</filename> or - <filename>/usr/X11R6</filename>). If you are using the - <makevar>MAN<replaceable>n</replaceable></makevar> variables (as - you should be), do not list any manpages here.</para> - - <para>Here is a small example:</para> - - <programlisting>bin/oneko -lib/X11/app-defaults/Oneko -lib/X11/oneko/cat1.xpm -lib/X11/oneko/cat2.xpm -lib/X11/oneko/mouse.xpm -@dirrm lib/X11/oneko</programlisting> - - <para>Refer to the &man.pkg.create.1; man page for details on the - packing list.</para> - - <note> - <para>You should list all the files, but not the name directories, - in the list. Also, if the port creates directories for itself - during installation, make sure to add <literal>@dirrm</literal> - lines as necessary to remove them when the port is - deleted.</para> - - <para>It is recommended that you keep all the filenames in this - file sorted alphabetically. It will make verifying the changes - when you upgrade the port much easier.</para> - - <para>Creating a packing list manually can be a very tedious - task. If the port installs a large numbers of files, <link - linkend="porting-autoplist">creating the packing list - automatically</link> might save time.</para> - </note> - </sect2> - </sect1> - - <sect1> - <title>Creating the checksum file</title> - - <para>Just type <command>make makesum</command>. The ports make rules - will automatically generate the file - <filename>distinfo</filename>.</para> - </sect1> - - <sect1 id="porting-testing"> - <title>Testing the port</title> - - <para>You should make sure that the port rules do exactly what you - want them to do, including packaging up the port. These are the - important points you need to verify.</para> - - <itemizedlist> - <listitem> - <para><filename>pkg-plist</filename> does not contain anything not - installed by your port</para> - </listitem> - - <listitem> - <para><filename>pkg-plist</filename> contains everything that is - installed by your port</para> - </listitem> - - <listitem> - <para>Your port can be installed multiple times using the - <maketarget>reinstall</maketarget> target</para> - </listitem> - - <listitem> - <para>Your port <link linkend="porting-cleaning">cleans up</link> - after itself upon deinstall</para> - </listitem> - </itemizedlist> - - <procedure> - <title>Recommended test ordering</title> - - <step> - <para><command>make install</command></para> - </step> - - <step> - <para><command>make package</command></para> - </step> - - <step> - <para><command>make deinstall</command></para> - </step> - - <step> - <para><command>pkg_add <replaceable>package-name</replaceable> - </command></para> - </step> - - <step> - <para><command>make deinstall</command></para> - </step> - - <step> - <para><command>make reinstall</command></para> - </step> - - <step> - <para><command>make package</command></para> - </step> - </procedure> - - <para>Make sure that there are not any warnings issued in any of the - <maketarget>package</maketarget> and - <maketarget>deinstall</maketarget> stages. After step 3, check to - see if all the new directories are correctly deleted. Also, try - using the software after step 4, to ensure that it works correctly - when installed from a package.</para> - </sect1> - - <sect1 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 <command>portlint</command> 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 right shape and the <link - linkend="porting-pkgname">package</link> is named - appropriately.</para> - </sect1> - - <sect1 id="porting-submitting"> - <title>Submitting the port</title> - - <para>First, make sure you have read the <link - linkend="porting-dads">DOs and DON'Ts</link> section.</para> - - <para>Now that you are happy with your port, the only thing remaining - is to put it in the main FreeBSD ports tree and make everybody else - happy about it too. We do not need your <filename>work</filename> - directory or the <filename>pkgname.tgz</filename> package, so delete - them now. Next, simply include the output of <command>shar `find - port_dir`</command> in a bug report and send it with the - &man.send-pr.1; program (see <ulink url="../handbook/contrib-how.html#CONTRIB-GENERAL">Bug - Reports and General Commentary</ulink> for more information about - &man.send-pr.1;. If the uncompressed port is larger than 20KB, - you should compress it into a tarfile and use &man.uuencode.1; - before including it in the bug report (uuencoded tarfiles are - acceptable even if the bug report is smaller than 20KB but are not - preferred). 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 and - the shar or uuencoded tarfile to the - <quote>Fix</quote> field. The latter one helps the committers - a lot, who use scripts for the ports-work.</para> - - <para>One more time, <emphasis>do not include the original source - distfile, the <filename>work</filename> directory, or the package - you built with <command>make package</command></emphasis>.</para> - - <note> - <para>In the past, we asked you to upload new port submissions in - our ftp site (<hostid role="fqdn">ftp.FreeBSD.org</hostid>). This - is no longer recommended as read access is turned off on the - <filename>incoming/</filename> directory of that site due to the - large amount of pirated software showing up there.</para> - </note> - - <para>We will look at your port, get back to you if necessary, and put - it in the tree. Your name will also appear in the list of - “Additional FreeBSD contributors” in the FreeBSD - Handbook and other files. Isn't that great?!? <!-- smiley - -->:-)</para> - - <note> - <para>You can make our work a lot easier, if you use a good - description in the synopsis of the problem report. - We prefer something like - “New port: <short description of the port>” for - new ports and - “Update port: <category>/<port> <short description - of the update>” for port updates. - If you stick to this scheme, the chance that one takes a look at - your PR soon is much bigger.</para> - </note> - </sect1> - </chapter> - - <chapter> - <title>Slow Porting</title> - - <para>Ok, so it was not that simple, and the port required some - modifications to get it to work. In this section, we will explain, - step by step, how to modify it to get it to work with the ports - paradigm.</para> - - <sect1> - <title>How things work</title> - - <para>First, this is the sequence of events which occurs when the user - first types <command>make</command> in your port's directory. - You may find that having <filename>bsd.port.mk</filename> in another - window while you read this really helps to understand it.</para> - - <para>But do not worry if you do not really understand what - <filename>bsd.port.mk</filename> is doing, not many people do... - <!-- smiley --><emphasis>:-></emphasis></para> - - <procedure> - - <step> - <para>The <maketarget>fetch</maketarget> target is run. The - <maketarget>fetch</maketarget> 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 Makefile, as well as our main ftp site at <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/</ulink>, - where we put sanctioned distfiles as backup. It will then - attempt to fetch the named distribution file with - <makevar>FETCH</makevar>, assuming that the requesting site has - direct access to the Internet. If that succeeds, it will save - the file in <makevar>DISTDIR</makevar> for future use and - proceed.</para> - </step> - - <step> - <para>The <maketarget>extract</maketarget> target is run. It - looks for your port's distribution file (typically a gzip'd - tarball) in <makevar>DISTDIR</makevar> and unpacks it into a - temporary subdirectory specified by <makevar>WRKDIR</makevar> - (defaults to <filename>work</filename>).</para> - </step> - - <step> - <para>The <maketarget>patch</maketarget> target is run. First, - any patches defined in <makevar>PATCHFILES</makevar> are - applied. Second, if any patch files named - <filename>patch-<replaceable>*</replaceable></filename> are found in - <makevar>PATCHDIR</makevar> (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. This - can do any one of many different things.</para> - - <orderedlist> - <listitem> - <para>If it exists, <filename>scripts/configure</filename> is - run.</para> - </listitem> - - <listitem> - <para>If <makevar>HAS_CONFIGURE</makevar> or - <makevar>GNU_CONFIGURE</makevar> is set, - <filename><makevar>WRKSRC</makevar>/configure</filename> is - run.</para> - </listitem> - - <listitem> - <para>If <makevar>USE_IMAKE</makevar> is set, - <makevar>XMKMF</makevar> (default: <command>xmkmf - -a</command>) is run.</para> - </listitem> - </orderedlist> - </step> - - <step> - <para>The <maketarget>build</maketarget> target is run. This is - responsible for descending into the port's private working - directory (<makevar>WRKSRC</makevar>) and building it. If - <makevar>USE_GMAKE</makevar> is set, GNU <command>make</command> - will be used, otherwise the system <command>make</command> will - be used.</para> - </step> - </procedure> - - <para>The above are the default actions. In addition, you can define - targets - <maketarget>pre-<replaceable>something</replaceable></maketarget> or - <maketarget>post-<replaceable>something</replaceable></maketarget>, - 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 Makefile, and a file - <filename>pre-build</filename> in the <filename>scripts</filename> - subdirectory, the <maketarget>post-extract</maketarget> 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 use - <filename>Makefile</filename> targets if the actions are simple - enough, because it will be easier for someone to figure out what - kind of non-default action the port requires.</para> - - <para>The default actions are done by the - <filename>bsd.port.mk</filename> targets - <maketarget>do-<replaceable>something</replaceable></maketarget>. - For example, the commands to extract a port are in the target - <maketarget>do-extract</maketarget>. If you are not happy with the - default target, you can fix it by redefining the - <maketarget>do-<replaceable>something</replaceable></maketarget> - target in your <filename>Makefile</filename>.</para> - - <note> - <para>The “main” targets (e.g., - <maketarget>extract</maketarget>, - <maketarget>configure</maketarget>, 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 touch - <maketarget>extract</maketarget>!</para> - </note> - - <para>Now that you understand what goes on when the user types - <command>make</command>, let us go through the recommended steps to - create the perfect port.</para> - </sect1> - - <sect1> - <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.Z</filename>) and copy - it into <makevar>DISTDIR</makevar>. Always use - <emphasis>mainstream</emphasis> sources when and where you - can.</para> - - <para>If you cannot find a ftp/http site that is well-connected to the - net, or can only find sites that have irritatingly non-standard - formats, you might want to put a copy on a reliable ftp or http - server that you control (e.g., your home page). Make sure you set - <makevar>MASTER_SITES</makevar> to reflect your choice.</para> - - <para>If you cannot find somewhere convenient and reliable to put the - distfile - we can “house” it ourselves - on <hostid>ftp.FreeBSD.org</hostid>. - The distfile must be placed into - <filename>~/public_distfiles/</filename> of someone's - <hostid>freefall</hostid> 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> - - <para>If your port's distfile changes all the time for no good reason, - consider putting the distfile in your home page and listing it as - the first <makevar>MASTER_SITES</makevar>. This will prevent users - from getting <errorname>checksum mismatch</errorname> errors, and - also 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> - - <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 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> - <title>Modifying the port</title> - - <para>Unpack a copy of the tarball in a private directory and make - whatever changes are necessary to get the port to compile properly - under the current version of FreeBSD. Keep <emphasis>careful - track</emphasis> of everything you do, as you will be automating - the process shortly. Everything, including the deletion, addition, - or modification of files should be doable using an automated script - or patch file when your port is finished.</para> - - <para>If your port requires significant user interaction/customization - to compile or install, you should take a look at one of Larry Wall's - classic <application>Configure</application> scripts and perhaps do - something similar yourself. The goal of the new ports collection is - to make each port as “plug-and-play” as possible for the - end-user while using a minimum of disk space.</para> - - <note> - <para>Unless explicitly stated, patch files, scripts, and other - files you have created and contributed to the FreeBSD ports - collection are assumed to be covered by the standard BSD copyright - conditions.</para> - </note> - </sect1> - - <sect1> - <title>Patching</title> - - <para>In the preparation of the port, files that have been added or - changed can be picked up with a recursive diff for later feeding to - patch. Each set of patches you wish to apply should be collected - into a file named - <filename>patch-<replaceable>*</replaceable></filename> where - <replaceable>*</replaceable> denotes the sequence in which the - patches will be applied — these are done in - <emphasis>alphabetical order</emphasis>, thus <literal>aa</literal> - first, <literal>ab</literal> second and so on. If you wish, - you can use names that indicate the pathnames of the files that - are patched, such as <filename>patch-Imakefile</filename> or - <filename>patch-src-config.h</filename>. These files should - be stored in <makevar>PATCHDIR</makevar>, from where they will be - automatically applied. All patches should be relative to - <makevar>WRKSRC</makevar> (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-aa</filename> and - <filename>patch-ab</filename> both changing - <filename><makevar>WRKSRC</makevar>/foobar.c</filename>).</para> - </sect1> - - <sect1> - <title>Configuring</title> - - <para>Include any additional customization commands in your - <filename>configure</filename> script and save it in the - <filename>scripts</filename> subdirectory. As mentioned above, you - can also do this with <filename>Makefile</filename> targets and/or - scripts with the name <filename>pre-configure</filename> or - <filename>post-configure</filename>.</para> - </sect1> - - <sect1> - <title>Handling user input</title> - - <para>If your port requires user input to build, configure, or install, - then set <makevar>IS_INTERACTIVE</makevar> in your Makefile. This - will allow “overnight builds” to skip your port if the - user sets the variable <envar>BATCH</envar> in his environment (and - if the user sets the variable <envar>INTERACTIVE</envar>, then - <emphasis>only</emphasis> those ports requiring interaction are - built).</para> - - <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 - interactive script when it is set. This will allow us to build the - packages for CD-ROMs and ftp.</para> - </sect1> - </chapter> - - <chapter> - <title>Configuring the Makefile</title> - - <para>Configuring the Makefile is pretty simple, and again we suggest - that you look at existing examples before starting. Also, there is a - <link linkend="porting-samplem">sample Makefile</link> in this - handbook, so take a look and please follow the ordering of variables - and sections in that template to make your port easier for others to - read.</para> - - <para>Now, consider the following problems in sequence as you design - your new Makefile:</para> - - <sect1> - <title>The original source</title> - - <para>Does it live in <makevar>DISTDIR</makevar> as a standard - gzip'd 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>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 a format your port's - distribution file is. (The most common case is - <literal>EXTRACT_SUFX=.tar.Z</literal>, when the tarball is - condensed by regular <command>compress</command>, not - <command>gzip</command>.)</para> - - <para>In the worst case, you can simply create your own - <maketarget>do-extract</maketarget> target to override the - default, though this should be rarely, if ever, - necessary.</para> - </sect1> - - <sect1> - <title><makevar>PORTNAME</makevar> and <makevar>PORTVERSION</makevar></title> - - <para>You should set <makevar>PORTNAME</makevar> to the - base name of your port, and <makevar>PORTVERSION</makevar> - to the version number of the port.</para> - </sect1> - - <sect1> - <title><makevar>PORTREVISION</makevar> and - <makevar>PORTEPOCH</makevar></title> - - <sect2> - <title><makevar>PORTREVISION</makevar></title> - - <para>The <makevar>PORTREVISION</makevar> variable is a - monotonically increasing value which is reset to 0 with - every increase of <makevar>PORTVERSION</makevar> (i.e. - every time a new official vendor release is made), and - appended to the package name if non-zero. - <makevar>PORTREVISION</makevar> is increased each time a - change is made to the FreeBSD port which significantly - affects the content or stucture of the derived - package.</para> - - <para>Examples of when PORTREVISION should be bumped:</para> - - <itemizedlist> - <listitem> - <para>Addition of patches to correct security - vulnerabilities, bugs, or to add new functionality to - the FreeBSD port.</para> - </listitem> - - <listitem> - <para>Changes to the port makefile to enable or disable - compile-time options in the package.</para> - </listitem> - - <listitem> - <para>Changes in the packing list or the install-time - behaviour of the package (e.g. change to a script - which generates initial data for the package, like ssh - host keys).</para> - </listitem> - - <listitem> - <para>Version bump of a port's shared library dependency - (in this case, someone trying to install the old - package after installing a newer version of the - dependency will fail since it will look for the old - libfoo.x instead of libfoo.(x+1)).</para> - </listitem> - - <listitem> - <para>Silent changes to the port distfile which have - 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 <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> - - <itemizedlist> - <listitem> - <para>Style changes to the port skeleton with no - functional change to what appears in the resulting - package.</para> - </listitem> - - <listitem> - <para>Changes to <makevar>MASTER_SITES</makevar> or - other functional changes to the port which do not - effect the resulting package.</para> - </listitem> - - <listitem> - <para>Trivial patches to the distfile such as correction - of typos, which are not important enough that users of - the package should go to the trouble of - upgrading.</para> - </listitem> - - <listitem> - <para>Build fixes which cause a package to become - 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> reflects - the content of the package, if no package was - previously buildable then there is no need to increase - <makevar>PORTREVISION</makevar> to mark a - change.</para> - </listitem> - </itemizedlist> - - <para>A rule of thumb is to ask yourself whether a change - committed to a port is something which someone, somewhere, - would benefit from having (either because of an - enhancement, fix, or by virtue that the new package will - actually work for them). If yes, the - <makevar>PORTREVISION</makevar> should be bumped so that - automated tools (e.g. <command>pkg_version</command>) - will highlight the fact that a new package is - available.</para> - </sect2> - - <sect2> - <title><makevar>PORTEPOCH</makevar></title> - - <para>From time to time a software vendor or FreeBSD porter - will do something silly and release a version of their - software which is actually numerically less than the - previous version. An example of this is a port which goes - from foo-20000801 to foo-1.0 (the former will be - incorrectly treated as a newer version since 20000801 is a - numerically greater value than 1).</para> - - <para>In situations such as this, the - <makevar>PORTEPOCH</makevar> version should be increased. - If <makevar>PORTEPOCH</makevar> is nonzero it is appended - to the package name as described in section 0 above. - <makevar>PORTEPOCH</makevar> is never 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 number (e.g. - <literal>1.0,1</literal> in the above example) is still - numerically less than the previous version (2000801), but - the <literal>,1</literal> suffix is treated specially by - automated tools and found to be greater than the implied - suffix ",0" on the earlier package)</para> - - <para>It is expected that <makevar>PORTEPOCH</makevar> will - not be used for the majority of ports, and that sensible - use of <makevar>PORTVERSION</makevar> can often pre-empt - 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 - without an official version number - such as a code - "snapshot" release. The temptation is to label the - release with the release date, which will cause problems - as in the example above when a new "official" release is - made.</para> - - <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, - not 20000917, so that the succeeding release, say 1.3, is - still a numerically greater value.</para> - </sect2> - - <sect2> - <title>Example of <makevar>PORTREVISION</makevar> and - <makevar>PORTEPOCH</makevar> usage</title> - - <para>The gtkmumble port, version 0.10, is committed to the - ports collection.</para> - - <programlisting>PORTNAME= gtkmumble -PORTVERSION= 0.10</programlisting> - - <para><makevar>PKGNAME</makevar> becomes - <literal>gtkmumble-0.10</literal>.</para> - - <para>A security hole is discovered which requires a local - FreeBSD patch. <makevar>PORTREVISION</makevar> is bumped - accordingly.</para> - - <programlisting>PORTNAME= gtkmumble -PORTVERSIOn= 0.10 -PORTREVISION= 1</programlisting> - - <para><makevar>PKGNAME</makevar> becomes - <literal>gtkmumble-0.10_1</literal></para> - - <para>A new version is released by the vendor, numbered 0.2 - (it turns out the author actually intended - <literal>0.10</literal> to actually mean - <literal>0.1.0</literal>, not <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> must be bumped to manually - force the new package to be detected as "newer". Since it - is a new vendor release of the code, - <makevar>PORTREVISION</makevar> is reset to 0 (or removed - from the makefile).</para> - - <programlisting>PORTNAME= gtkmumble -PORTVERSION= 0.2 -PORTEPOCH= 1</programlisting> - - <para><makevar>PKGNAME</makevar> becomes - <literal>gtkmumble-0.2,1</literal></para> - - <para>The next release is 0.3. Since - <makevar>PORTEPOCH</makevar> never decreases, the version - variables are now:</para> - - <programlisting>PORTNAME= gtkmumble -PORTVERSION= 0.3 -PORTEPOCH= 1</programlisting> - - <para><makevar>PKGNAME</makevar> becomes - <literal>gtkmumble-0.3,1</literal></para> - - <note> - <para>If <makevar>PORTEPOCH</makevar> were reset - to <literal>0</literal> with this upgrade, someone who had - installed the gtkmumble-0.10_1 package would not detect - the gtkmumble-0.3 package as newer, since - <literal>3</literal> is still numerically less than - <literal>10</literal>.</para> - </note> - </sect2> - </sect1> - - <sect1> - <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 - <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 not allowed to use a - hyphen (<literal>-</literal>) in - <makevar>PORTVERSION</makevar>. Also, if the package name - has the <replaceable>language-</replaceable> or the - <replaceable>compiled.specifics</replaceable> part, use - <makevar>PKGNAMEPREFIX</makevar> and - <makevar>PKGNAMESUFFIX</makevar>, respectively. Do not make - them part of <makevar>PORTNAME</makevar>.</para> - </sect1> - - <sect1> - <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 - <literal>${PORTNAME}-${PORTVERSION}</literal>, 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> - - <note> - <para><makevar>PKGNAMEPREFIX</makevar> and - <makevar>PKGNAMESUFFIX</makevar> do not affect - <makevar>DISTNAME</makevar>. Also note that when - <makevar>WRKSRC</makevar> is equal to - <filename>work/<makevar>${PORTNAME}-${PORTVERSION}</makevar></filename> - while the original source archive is named something other than - <makevar>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</makevar>, - you should probably leave <makevar>DISTNAME</makevar> - 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> - </note> - </sect1> - - <sect1> - <title><makevar>CATEGORIES</makevar></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 easier - for the user when he is wading through the pile of packages on the - ftp site or the CD-ROM. Please take a look at the existing <link - linkend="porting-categories">categories</link> and pick the ones - that are suitable for your port.</para> - - <para>This list also determines where in the ports tree the port is - imported. If you put more than one category here, it is assumed - that the port files will be put in the subdirectory with the name in - the first category. See the <link - linkend="porting-categories">categories</link> section for more - discussion about how to pick the right categories.</para> - - <para>If your port truly belongs to something that is different from - all the existing ones, you can even create a new category name. In - that case, please send mail to the &a.ports; to propose a new - category.</para> - </sect1> - - <sect1> - <title><makevar>MASTER_SITES</makevar></title> - - <para>Record the directory part of the ftp/http-URL pointing at the - original tarball in <makevar>MASTER_SITES</makevar>. 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 the - system.</para> - - <para>It is recommended that you put multiple sites on this list, - preferably from different continents. This will safeguard against - wide-area network problems, and we are even planning to add support - for automatically determining the closest master site and fetching - from there!</para> - - <para>If the original tarball is part of one of the popular - archives such as X-contrib, 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_XCONTRIB</makevar> and - <makevar>MASTER_SITE_PERL_GNU</makevar>). Simply set - <makevar>MASTER_SITES</makevar> to one of these variables and - <makevar>MASTER_SITE_SUBDIR</makevar> to the path within the - archive. Here is an example:</para> - - <programlisting>MASTER_SITES= ${MASTER_SITE_XCONTRIB} -MASTER_SITE_SUBDIR= applications</programlisting> - - <para>These variables are defined in - <filename>/usr/ports/Mk/bsd.sites.mk</filename>. There are - new archives added all the time, so make sure to check the - latest version of this file before submitting a port.</para> - - <para>The user can also set the <makevar>MASTER_SITE_*</makevar> - variables in <filename>/etc/make.conf</filename> to override our - choices, and use their favorite mirrors of these popular archives - instead.</para> - </sect1> - - <sect1 id="porting-patchfiles"> - <title><makevar>PATCHFILES</makevar></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> to the URL of the - directory that contains them (the format is the same as - <makevar>MASTER_SITES</makevar>).</para> - - <para>If the patch is not relative to the top of the source tree - (i.e., <makevar>WRKSRC</makevar>) because it contains some extra - pathnames, set <makevar>PATCH_DIST_STRIP</makevar> 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> - - <para>Do not worry if the patches are compressed; they will be - decompressed automatically if the filenames end with - <filename>.gz</filename> or <filename>.Z</filename>.</para> - - <para>If the patch is distributed with some other files, such as - documentation, in a gzip'd tarball, you cannot just use - <makevar>PATCHFILES</makevar>. 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 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 may - not be writable.</para> - - <note> - <para>Note that the tarball will have been extracted alongside the - regular source by then, so there is no need to explicitly extract - it if it is a regular gzip'd or compress'd tarball. If you do the - 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> - </note> - </sect1> - - <sect1> - <title><makevar>MAINTAINER</makevar></title> - - <para>Set your mail-address here. Please. <!-- smiley - --><emphasis>:-)</emphasis></para> - - <para>For a detailed description of the responsibilities of maintainers, - refer to the <ulink url="../handbook/policies.html#POLICIES-MAINTAINER">MAINTAINER on - Makefiles</ulink> section.</para> - </sect1> - - <sect1> - <title>Dependencies</title> - - <para>Many ports depend on other ports. There are five variables that - you can use to ensure that all the required bits will be on the - user's machine. There are also some pre-supported dependency - variables for common cases, plus a few more to control the behaviour - of dependencies.</para> - - <sect2> - <title><makevar>LIB_DEPENDS</makevar></title> - - <para>This variable specifies the shared libraries this port depends - on. It is a list of - <replaceable>lib</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> - tuples where <replaceable>lib</replaceable> is the name of the - shared library, <replaceable>dir</replaceable> is the - directory in which to find it in case it is not available, and - <replaceable>target</replaceable> is the target to call in that - directory. For example, <programlisting> LIB_DEPENDS= - jpeg.9:${PORTSDIR}/graphics/jpeg:install</programlisting> - will check for a shared jpeg library with major version 9, and - descend into the <filename>graphics/jpeg</filename> subdirectory - of your ports tree to build and install it if it is not found. - The <replaceable>target</replaceable> part can be omitted if it is - equal to <makevar>DEPENDS_TARGET</makevar> (which defaults to - <literal>install</literal>).</para> - - <note> - <para>The <replaceable>lib</replaceable> part is an argument given - to <command>ldconfig -r | grep -wF</command>. There shall be no - regular expressions in this variable.</para> - </note> - - <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 of the - dependency is put into the package so that - <command>pkg_add</command> will automatically install it if it is - not on the user's system.</para> - </sect2> - - <sect2> - <title><makevar>RUN_DEPENDS</makevar></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> - 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 available, and - <replaceable>target</replaceable> is the target to call in that - directory. If <replaceable>path</replaceable> starts with a slash - (<literal>/</literal>), it is treated as a file and its existence - is tested with <command>test -e</command>; otherwise, it is - assumed to be an executable, and <command>which -s</command> is - used to determine if the program exists in the user's search - path.</para> - - <para>For example,</para> - - <programlisting>RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \ - wish8.0:${PORTSDIR}/x11-toolkits/tk80</programlisting> - - <para>will check if the file or directory - <filename>/usr/local/etc/innd</filename> exists, and build and - install it from the <filename>news/inn</filename> subdirectory of - the ports tree if it is not found. It will also see if an - executable called <command>wish8.0</command> is in your search - path, and descend into the <filename>x11-toolkits/tk80</filename> - subdirectory of your ports tree to build and install it if it is - not found.</para> - - <note> - <para>In this case, <command>innd</command> is actually an - executable; if an executable is in a place that is not expected - to be in a normal user's search path, you should use the full - pathname.</para> - </note> - - <para>The dependency is checked from within the - <maketarget>install</maketarget> target. Also, the name of the - dependency is put in to the package so that - <command>pkg_add</command> 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> - </sect2> - - <sect2> - <title><makevar>BUILD_DEPENDS</makevar></title> - - <para>This variable specifies executables or files this port - requires to build. Like <makevar>RUN_DEPENDS</makevar>, it is a - list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> - tuples. For example, <programlisting> BUILD_DEPENDS= - unzip:${PORTSDIR}/archivers/unzip</programlisting> will check - for an executable called <command>unzip</command>, and descend - into the <filename>archivers/unzip</filename> subdirectory of your - ports tree to build and install it if it is not found.</para> - - <note> - <para>“build” here means everything from extraction to - compilation. The dependency is checked from within the - <maketarget>extract</maketarget> target. The - <replaceable>target</replaceable> part can be omitted if it is - the same as <makevar>DEPENDS_TARGET</makevar></para> - </note> - </sect2> - - <sect2> - <title><makevar>FETCH_DEPENDS</makevar></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> - tuples. For example, <programlisting> FETCH_DEPENDS= - ncftp2:${PORTSDIR}/net/ncftp2</programlisting> will check for an - executable called <command>ncftp2</command>, and descend into the - <filename>net/ncftp2</filename> subdirectory of your ports 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 - <replaceable>target</replaceable> part can be omitted if it is the - same as <makevar>DEPENDS_TARGET</makevar>.</para> - </sect2> - - <sect2> - <title><makevar>DEPENDS</makevar></title> - - <para>If there is a dependency that does not fall into either of the - above four categories, or your port requires having the source of - the other port extracted in addition to having it installed, - then use this variable. This is a list of - <replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>, - as there is nothing to check, unlike the previous four. The - <replaceable>target</replaceable> part can be omitted if it is the - same as <makevar>DEPENDS_TARGET</makevar>.</para> - </sect2> - - <sect2> - <title>Common dependency variables</title> - - <para>Define <literal>USE_XLIB=yes</literal> if your port requires - the X Window System to be installed (it is implied by - <makevar>USE_IMAKE</makevar>). Define - <literal>USE_GMAKE=yes</literal> if your port requires GNU - <command>make</command> instead of BSD <command>make</command>. - Define <literal>USE_AUTOCONF=yes</literal> if your port requires - GNU autoconf to be run. Define <literal>USE_QT=yes</literal> if - your port uses the latest qt toolkit. Use - <literal>USE_PERL5=yes</literal> if your port requires version 5 - of the perl language. (The last is especially important since - some versions of FreeBSD have perl5 as part of the base system - while others do not.)</para> - </sect2> - - <sect2> - <title>Notes on dependencies</title> - - <para>As mentioned above, the default target to call when a - dependency is required is <maketarget>DEPENDS_TARGET</maketarget>. - 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> - - <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.</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 to - the to get to the source of the other port. You can often save - compilation time by specifying the target too. For - instance - - <programlisting>BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract</programlisting> - - will always descend to the JPEG port and extract it.</para> - - <para>Do not use <makevar>DEPENDS</makevar> unless there is no other - way the behaviour you want can be accomplished. It will cause the - other port to always be built (and installed, by default), and the - dependency will go into the packages as well. If this is really - what you need, you should probably write it as - <literal>BUILD_DEPENDS</literal> and - <literal>RUN_DEPENDS</literal> instead—at least the - intention will be clear.</para> - </sect2> - </sect1> - - <sect1> - <title>Building mechanisms</title> - - <para>If your package uses GNU <command>make</command>, set - <literal>USE_GMAKE=yes</literal>. If your package uses - <command>configure</command>, set - <literal>HAS_CONFIGURE=yes</literal>. If your package uses GNU - <command>configure</command>, set - <literal>GNU_CONFIGURE=yes</literal> (this implies - <literal>HAS_CONFIGURE</literal>). If you want to give some extra - arguments to <command>configure</command> (the default argument list - <literal>--prefix=${PREFIX}</literal> for GNU - <command>configure</command> and empty for non-GNU - <command>configure</command>), set those extra arguments in - <makevar>CONFIGURE_ARGS</makevar>. If your package uses GNU - <command>autoconf</command>, set - <literal>USE_AUTOCONF=yes</literal>. This implies - <makevar>GNU_CONFIGURE</makevar>, and will cause - <command>autoconf</command> to be run before - <command>configure</command>.</para> - - <para>If your package is an X application that creates - <filename>Makefile</filename>s from <filename>Imakefile</filename>s - using <command>imake</command>, then set - <literal>USE_IMAKE=yes</literal>. This will cause the configure - stage to automatically do an <command>xmkmf -a</command>. If the - <option>-a</option> flag is a problem for your port, set - <literal>XMKMF=xmkmf</literal>. If the port uses - <command>imake</command> but does not understand the - <maketarget>install.man</maketarget> target, - <literal>NO_INSTALL_MANPAGES=yes</literal> should be set. In - addition, the author of the original port should be shot. <!-- - smiley --><emphasis>:-></emphasis></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> - </sect1> - </chapter> - - <chapter> - <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="porting-shlibs"> - <title>Shared Libraries</title> - - <para>If your port installs one or more shared libraries, define a - <makevar>INSTALLS_SHLIB</makevar> 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 into the - shared library cache. This variable, when defined, will also - facilitate addition of an appropriate - <literal>@exec /sbin/ldconfig -m</literal> and - <literal>@unexec /sbin/ldconfig -R</literal> pair into your - <filename>pkg-plist</filename> file, so that a user who installed - the package can start using the shared library immediately and - deinstallation will not cause the system to still believe the - library is there.</para> - - <para>If you need, you can override default location where the new - library is installed by defining <makevar>LDCONFIG_DIRS</makevar> - make variable, which should contain 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> directories - you could use the following in your - <filename>Makefile</filename>:</para> - - <programlisting>INSTALLS_SHLIB= yes -LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting> - - <para>Note that content of <makevar>LDCONFIG_DIRS</makevar> is passed - through &man.sed.1; just like the rest of <filename>pkg-plist</filename>, - so <makevar>PLIST_SUB</makevar> substitutions also apply here. It is - recommended that you use <literal>%%PREFIX%%</literal> for - <makevar>PREFIX</makevar>, <literal>%%LOCALBASE%%</literal> for - <makevar>LOCALBASE</makevar> and <literal>%%X11BASE%%</literal> for - <makevar>X11BASE</makevar>.</para> - </sect1> - </chapter> - -<!-- - - <chapter> - <title>ELF support</title> - - <para>Since FreeBSD changed to an ELF binary format shortly after - 3.0-RELEASE, we need to convert many ports that build shared - libraries to support ELF. Complicating this task is that a 3.0 - system can run as both ELF and a.out, and we wish to unofficially - support the 2.2 branch as long as possible. Below are the guidelines on - how to convert a.out only ports to support both a.out and ELF - compilation.</para> - - <para>Some part of this list is only applicable during the conversion, - but will be left here for a while for reference in case you have come - across some old port you wish to upgrade.</para> - - <sect1> - <title>Moving a.out libraries out of the way</title> - - <para>Any a.out libraries should be moved out of - <filename>/usr/local/lib</filename> and similar to an - <filename>aout</filename> subdirectory. (If you do not move them out - of the way, ELF ports will happily overwrite a.out libraries.) The - <maketarget>move-aout-libs</maketarget> target in the 3.0-CURRENT - <filename>src/Makefile</filename> (called from - <maketarget>aout-to-elf</maketarget>) will do this for you. It will - only move a.out libs so it is safe to call it on a system with both - ELF and a.out libs in the standard directories.</para> - </sect1> - - <sect1> - <title>Format</title> - - <para>The ports tree will build packages in the format the machine is - in. This means a.out for 2.2 and a.out or ELF for 3.0 depending on - what <command>`objformat`</command> returns. Also, once users move - a.out libraries to a subdirectory, building a.out libraries will be - unsupported. (I.e., it may still work if you know what you are - doing, but you are on your own.)</para> - - <note> - <para>If a port only works for a.out, set - <makevar>BROKEN_ELF</makevar> to a string describing the reason - why. Such ports will be skipped during a build on an ELF - system.</para> - </note> - </sect1> - - <sect1> - <title><makevar>PORTOBJFORMAT</makevar></title> - - <para><filename>bsd.port.mk</filename> will set - <makevar>PORTOBJFORMAT</makevar> to <literal>aout</literal> or - <literal>elf</literal> and export it in the environments - <envar>CONFIGURE_ENV</envar>, <envar>SCRIPTS_ENV</envar> and - <envar>MAKE_ENV</envar>. (It's always going to be - <literal>aout</literal> in 2.2-STABLE). It is also passed to - <maketarget>PLIST_SUB</maketarget> as - <literal>PORTOBJFORMAT=${PORTOBJFORMAT}</literal>. (See comment on - <literal>ldconfig</literal> lines below.)</para> - - <para>The variable is set using this line in - <filename>bsd.port.mk</filename>:</para> - - <programlisting>PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</programlisting> - - <para>Ports' make processes should use this variable to decide what to - do. However, if the port's <filename>configure</filename> script - already automatically detects an ELF system, it is not necessary to - refer to <makevar>PORTOBJFORMAT</makevar>.</para> - </sect1> - - <sect1> - <title>Building shared libraries</title> - - <para>The following are differences in handling shared libraries for - a.out and ELF.</para> - - <itemizedlist> - <listitem> - <para>Shared library versions</para> - - <para>An ELF shared library should be called - <filename>libfoo.so.<replaceable>M</replaceable></filename> - where <replaceable>M</replaceable> is the single version number, - and an a.out library should be called - <filename>libfoo.so.<replaceable>M</replaceable>.<replaceable>N</replaceable></filename> - where <replaceable>M</replaceable> is the major version and - <replaceable>N</replaceable> is the the minor version number. - Do not mix those; <emphasis>never</emphasis> install an ELF - shared library called - <filename>libfoo.so.<replaceable>N</replaceable>.<replaceable>M</replaceable></filename> - or an a.out shared library (or symlink) called - <filename>libfoo.so.<replaceable>N</replaceable></filename>.</para> - </listitem> - - <listitem> - <para>Linker command lines</para> - - <para>Assuming <command>cc -shared</command> is used rather than - <command>ld</command> directly, the only difference is that you - need to add - <option>-Wl,-<replaceable>soname,libfoo.so.M</replaceable></option -> - on the command line for ELF.</para> - </listitem> - </itemizedlist> - - <para>You need to install a symlink from - <filename>libfoo.so</filename> to - <filename>libfoo.so.<replaceable>N</replaceable></filename> to make - ELF linkers happy. Since it should be listed in - <filename>pkg-plist</filename> too, and it won't hurt in the a.out case - (some ports even require the link for dynamic loading), you should - just make this link regardless of the setting of - <makevar>PORTOBJFORMAT</makevar>.</para> - </sect1> - - <sect1> - <title><makevar>LIB_DEPENDS</makevar></title> - - <para>All port Makefiles are edited to remove minor numbers from - <makevar>LIB_DEPENDS</makevar>, and also to have the regexp support - removed. (E.g., <literal>foo\\.1\\.\\(33|40\\)</literal> becomes - <literal>foo.2</literal>.) They will be matched using <command>grep - -wF</command>.</para> - </sect1> - - <sect1> - <title><filename>pkg-plist</filename></title> - - <para><filename>pkg-plist</filename> should contain the short (ELF) shlib - names if the a.out minor number is zero, and the long (a.out) names - otherwise. <filename>bsd.port.mk</filename> will automatically add - <literal>.0</literal> to the end of short shlib lines if - <makevar>PORTOBJFORMAT</makevar> equals <literal>aout</literal>, and - will delete the minor number from long shlib names if - <makevar>PORTOBJFORMAT</makevar> equals - <literal>elf</literal>.</para> - - <para>In cases where you really need to install shlibs with two - versions on an ELF system or those with one version on an a.out - system (for instance, ports that install compatibility libraries for - other operating systems), define the variable - <makevar>NO_FILTER_SHLIBS</makevar>. This will turn off the editing - of <filename>pkg-plist</filename> mentioned in the previous - paragraph.</para> - </sect1> - - <sect1> - <title><literal>ldconfig</literal></title> - - <para>The <literal>ldconfig</literal> line in Makefiles should - read:</para> - - <programlisting>${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting> - - <para>In <filename>pkg-plist</filename> it should read;</para> - - <programlisting>@exec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -m ... -@unexec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -R</programlisting> - - <para>This is to ensure that the correct <command>ldconfig</command> - will be called depending on the format of the package, not the - default format of the system.</para> - </sect1> - </chapter> - ---> - - <chapter id="porting-masterdir"> - <title><makevar>MASTERDIR</makevar></title> - - <para>If your port needs to build slightly different versions of - packages by having a variable (for instance, resolution, or paper - size) take different values, create one subdirectory per package to - make it easier for users to see what to do, but try to share as many - files as possible between ports. Typically 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>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>PKGNAMESUFFIX</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>PORTNAME= xdvi -PORTVERSION= 17 -PKGNAMEPREFIX= ja- -PKGNAMESUFFIX= ${RESOLUTION} - : -# default -RESOLUTION?= 300 -.if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \ - ${RESOLUTION} != 300 && ${RESOLUTION} != 400 - @${ECHO} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\"" - @${ECHO} "Possible values are: 118, 240, 300 (default) and 400." - @${FALSE} -.endif</programlisting> - - <para><filename>japanese/xdvi300</filename> 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> - - <para>As for other resolutions, this is the <emphasis>entire</emphasis> - <filename>xdvi118/Makefile</filename>:</para> - - <programlisting>RESOLUTION= 118 -MASTERDIR= ${.CURDIR}/../xdvi300 - -.include ${MASTERDIR}/Makefile</programlisting> - - <para>(<filename>xdvi240/Makefile</filename> and - <filename>xdvi400/Makefile</filename> are similar). The - <makevar>MASTERDIR</makevar> 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 - <filename>xdvi300</filename>. The <literal>RESOLUTION=118</literal> - line will override the <literal>RESOLUTION=300</literal> line in - <filename>xdvi300/Makefile</filename> and the port will be built with - resolution set to 118.</para> - </chapter> - - <chapter> - <title>Shared library versions</title> - - <para>Please read our <ulink url="../handbook/policies-shlib.html">policy on - shared library versioning</ulink> 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 - quite a unique situation where we are trying to have dozens of - 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?). 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 - specify to the linker which version of shared library to link against - (the linker will always pick the highest numbered version). This - means, if there is a <filename>libfoo.so.3.2</filename> and - <filename>libfoo.so.4.0</filename> in the system, there is no way to - tell the linker to link a particular application to - <filename>libfoo.so.3.2</filename>. It is essentially completely - overshadowed in terms of compilation-time linkage. In this case, the - only solution is to rename the <emphasis>base</emphasis> part of the - shared library. For instance, change - <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> ---> - </chapter> - - <chapter id="porting-manpages"> - <title>Manpages</title> - - <para>The <makevar>MAN[1-9LN]</makevar> variables will automatically add - any manpages to <filename>pkg-plist</filename> (this means you must - <emphasis>not</emphasis> list manpages in the - <filename>pkg-plist</filename>—see <link - linkend="porting-plist">generating PLIST</link> for more). It also - makes the install stage automatically compress or uncompress manpages - depending on the setting of <makevar>NOMANCOMPRESS</makevar> in - <filename>/etc/make.conf</filename>.</para> - - <para>If your port tries to install multiple names for manpages using - symlinks or hardlinks, you must use the <makevar>MLINKS</makevar> - variable to identify these. The link installed by your port will - be destroyed and recreated by <filename>bsd.port.mk</filename> - to make sure it points to the correct file. Any manpages - listed in MLINKS must not be listed in the - <filename>pkg-plist</filename>.</para> - - <para>To specify whether the manpages are compressed upon installation, - use the <makevar>MANCOMPRESSED</makevar> variable. This variable can - take three values, <literal>yes</literal>, <literal>no</literal> and - <literal>maybe</literal>. <literal>yes</literal> means manpages are - already installed compressed, <literal>no</literal> means they are - not, and <literal>maybe</literal> means the software already respects - the value of <makevar>NOMANCOMPRESS</makevar> so - <filename>bsd.port.mk</filename> does not have to do anything - special.</para> - - <para><makevar>MANCOMPRESSED</makevar> is automatically set to - <literal>yes</literal> if <makevar>USE_IMAKE</makevar> is set and - <makevar>NO_INSTALL_MANPAGES</makevar> is not set, and to - <literal>no</literal> otherwise. You do not have to explicitly define - it unless the default is not suitable for your port.</para> - - <para>If your port anchors its man tree somewhere other than - <makevar>PREFIX</makevar>, you can use the - <makevar>MANPREFIX</makevar> to set it. Also, if only manpages in - certain sections go in a non-standard place, such as some Perl modules - ports, you can set individual man paths using - <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> (where - <replaceable>sect</replaceable> is one of <literal>1-9</literal>, - <literal>L</literal> or <literal>N</literal>).</para> - - <para>If your manpages go to language-specific subdirectories, set the - name of the languages to <makevar>MANLANG</makevar>. The value of - this variable defaults to <literal>""</literal> (i.e., English - only).</para> - - <para>Here is an example that puts it all together.</para> - - <programlisting>MAN1= foo.1 -MAN3= bar.3 -MAN4= baz.4 -MLINKS= foo.1 alt-name.8 -MANLANG= "" ja -MAN3PREFIX= ${PREFIX}/share/foobar -MANCOMPRESSED= yes</programlisting> - - <para>This states that six files are installed by this port;</para> - - <programlisting>${PREFIX}/man/man1/foo.1.gz -${PREFIX}/man/ja/man1/foo.1.gz -${PREFIX}/share/foobar/man/man3/bar.3.gz -${PREFIX}/share/foobar/man/ja/man3/bar.3.gz -${PREFIX}/man/man4/baz.4.gz -${PREFIX}/man/ja/man4/baz.4.gz</programlisting> - - <para>Additionally <filename>${PREFIX}/man/man8/alt-name.8.gz</filename> - may or may not be installed by your port. Regardless, a - symlink will be made to join the foo(1) manpage and - alt-name(8) manpage.</para> - - </chapter> - - <chapter id="porting-motif"> - <title>Ports that require Motif</title> - - <para>There are many programs that require a Motif library (available - from several commercial vendors, while there is a free clone reported - to be able to run many applications in - <filename>x11-toolkits/lesstif</filename>) to compile. Since it is a - popular toolkit and their licenses usually permit redistribution of - statically linked binaries, we have made special provisions for - handling ports that require Motif in a way that we can easily compile - binaries linked either dynamically (for people who are compiling from - the port) or statically (for people who distribute packages).</para> - - <sect1> - <title><makevar>REQUIRES_MOTIF</makevar></title> - - <para>If your port requires Motif, define this variable in the - Makefile. This will prevent people who do not own a copy of Motif - from even attempting to build it.</para> - </sect1> - - <sect1> - <title><makevar>MOTIFLIB</makevar></title> - - <para>This variable will be set by <filename>bsd.port.mk</filename> to - be the appropriate reference to the Motif library. Please patch the - source to use this wherever the Motif library is referenced in the - <filename>Makefile</filename> or - <filename>Imakefile</filename>.</para> - - <para>There are two common cases:</para> - - <itemizedlist> - <listitem> - <para>If the port refers to the Motif library as - <literal>-lXm</literal> in its <filename>Makefile</filename> or - <filename>Imakefile</filename>, simply substitute - <literal>${MOTIFLIB}</literal> for it.</para> - </listitem> - - <listitem> - <para>If the port uses <literal>XmClientLibs</literal> in its - <filename>Imakefile</filename>, change it to - <literal>${MOTIFLIB} ${XTOOLLIB} - ${XLIB}</literal>.</para> - </listitem> - - </itemizedlist> - - <para>Note that <makevar>MOTIFLIB</makevar> (usually) expands to - <literal>-L/usr/X11R6/lib -lXm</literal> or - <literal>/usr/X11R6/lib/libXm.a</literal>, so there is no need to - add <literal>-L</literal> or <literal>-l</literal> in front.</para> - </sect1> - </chapter> - - <chapter> - <title>X11 fonts</title> - - <para>If your port installs fonts for the X Window system, put them in - <filename><makevar>X11BASE</makevar>/lib/X11/fonts/local</filename>. - This directory is new to XFree86 release 3.3.3. If it does not exist, - please create it, and print out a message urging the user to update - their XFree86 to 3.3.3 or newer, or at least add this directory to the - font path in <filename>/etc/XF86Config</filename>.</para> - </chapter> - - <chapter id="porting-info"> - <title>Info files</title> - - <para>The new version of texinfo (included in 2.2.2-RELEASE and onwards) - contains a utility called <command>install-info</command> to add and - delete entries to the <filename>dir</filename> file. If your port - installs any info documents, please follow these instructions so your - port/package will correctly update the user's - <filename><makevar>PREFIX</makevar>/info/dir</filename> file. (Sorry - for the length of this section, but is it imperative to weave all the - info files together. If done correctly, it will produce a - <emphasis>beautiful</emphasis> listing, so please bear with me!</para> - - <para>First, this is what you (as a porter) need to know</para> - - <screen>&prompt.user; <userinput>install-info --help</userinput> -install-info [OPTION]... [INFO-FILE [DIR-FILE]] - Install INFO-FILE in the Info directory file DIR-FILE. - -Options: ---delete Delete existing entries in INFO-FILE; - don't insert any new entries. - : ---entry=TEXT Insert TEXT as an Info directory entry. - : ---section=SEC Put this file's entries in section SEC of the directory. :</screen> - - <note> - <para>This program will not actually <emphasis>install</emphasis> info - files; it merely inserts or deletes entries in the - <filename>dir</filename> file.</para> - </note> - - <para>Here's a seven-step procedure to convert ports to use - <command>install-info</command>. - <filename>editors/emacs</filename> will be used as an - example.</para> - - <procedure> - <step> - <para>Look at the texinfo sources and make a patch to insert - <literal>@dircategory</literal> and <literal>@direntry</literal> - statements to files that do not have them. This is part of my - patch:</para> - - <programlisting>--- ./man/vip.texi.org Fri Jun 16 15:31:11 1995 -+++ ./man/vip.texi Tue May 20 01:28:33 1997 -@@ -2,6 +2,10 @@ - - @setfilename ../info/vip - @settitle VIP -+@dircategory The Emacs editor and associated tools -+@direntry -+* VIP: (vip). A VI-emulation for Emacs. -+@end direntry - - @iftex - @finalout - :</programlisting> - - <para>The format should be self-explanatory. Many authors leave a - <filename>dir</filename> file in the source tree that contains all - the entries you need, so look around before you try to write your - own. Also, make sure you look into related ports and make the - section names and entry indentations consistent (we recommend that - all entry text start at the 4th tab stop).</para> - - <note> - <para>Note that you can put only one info entry per file because - of a bug in <command>install-info --delete</command> that - deletes only the first entry if you specify multiple entries in - the <email>@direntry</email> section.</para> - </note> - - <para>You can give the <literal>dir</literal> entries to - <command>install-info</command> as arguments - (<option>--section</option> and <option>--entry</option>) instead - of patching the texinfo sources. This probably is not a good - idea for ports because you need to duplicate the same information - in <emphasis>three</emphasis> places - (<filename>Makefile</filename> and - <literal>@exec</literal>/<literal>@unexec</literal> of - <filename>pkg-plist</filename>; see below). However, if you have - Japanese (or other multibyte encoding) info files, you will have - to use the extra arguments to <command>install-info</command> - because <command>makeinfo</command> cannot handle those texinfo - sources. (See <filename>Makefile</filename> and - <filename>pkg-plist</filename> of <filename>japanese/skk</filename> - for examples on how to do this).</para> - </step> - - <step> - <para>Go back to the port directory and do a <command>make clean; - make</command> and verify that the info files are regenerated - from the texinfo sources. Since the texinfo sources are newer than - the info files, they should be rebuilt when you type - <command>make</command>; but many <filename>Makefile</filename>s - do not include correct dependencies for info files. In - <command>emacs</command>' case, it was necessary to patch the main - <filename>Makefile.in</filename> so it would descend into the - <filename>man</filename> subdirectory to rebuild the info - pages.</para> - - <programlisting>--- ./Makefile.in.org Mon Aug 19 21:12:19 1996 -+++ ./Makefile.in Tue Apr 15 00:15:28 1997 -@@ -184,7 +184,7 @@ - # Subdirectories to make recursively. `lisp' is not included - # because the compiled lisp files are part of the distribution - # and you cannot remake them without installing Emacs first. --SUBDIR = lib-src src -+SUBDIR = lib-src src man - - # The makefiles of the directories in $SUBDIR. - SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile - lwlib/Makefile ---- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996 -+++ ./man/Makefile.in Tue Apr 15 00:29:52 1997 -@@ -66,6 +66,7 @@ - ${srcdir}/gnu1.texi \ - ${srcdir}/glossary.texi - -+all: info - info: $(INFO_TARGETS) - - dvi: $(DVI_TARGETS)</programlisting> - - <para>The second hunk was necessary because the default target in - the <filename>man</filename> subdir is called - <maketarget>info</maketarget>, while the main - <filename>Makefile</filename> wants to call - <maketarget>all</maketarget>. The installation of the - <filename>info</filename> info file was also removed because we - already have one with the same name in - <filename>/usr/share/info</filename> (that patch is not shown - here).</para> - </step> - - <step> - <para>If there is a place in the <filename>Makefile</filename> that - is installing the <filename>dir</filename> file, delete it. Your - port may not be doing it. Also, remove any commands that are - otherwise mucking around with the <filename>dir</filename> - file.</para> - - <programlisting>--- ./Makefile.in.org Mon Aug 19 21:12:19 1996 -+++ ./Makefile.in Mon Apr 14 23:38:07 1997 -@@ -368,14 +368,8 @@ - if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \ - then \ - (cd ${infodir}; \ -- if [ -f dir ]; then \ -- if [ ! -f dir.old ]; then mv -f dir dir.old; \ -- else mv -f dir dir.bak; fi; \ -- fi; \ - cd ${srcdir}/info ; \ -- (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); -\ -- (cd $${thisdir}; chmod a+r ${infodir}/dir); \ - for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \ - (cd $${thisdir}; \ - ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \ - chmod a+r ${infodir}/$$f); \</programlisting> - </step> - - <step> - <para>(This step is only necessary if you are modifying an existing - port.) Take a look at <filename>pkg-plist</filename> and delete - anything that is trying to patch up <filename>info/dir</filename>. - They may be in <filename>pkg-install</filename> or some other - file, so search extensively.</para> - - <programlisting>Index: pkg-plist -=================================================================== -RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v -retrieving revision 1.15 -diff -u -r1.15 pkg-plist ---- pkg-plist 1997/03/04 08:04:00 1.15 -+++ pkg-plist 1997/04/15 06:32:12 -@@ -15,9 +15,6 @@ - man/man1/emacs.1.gz - man/man1/etags.1.gz - man/man1/ctags.1.gz --@unexec cp %D/info/dir %D/info/dir.bak --info/dir --@unexec cp %D/info/dir.bak %D/info/dir - info/cl - info/cl-1 - info/cl-2</programlisting> - </step> - - <step> - <para>Add a <maketarget>post-install</maketarget> target to the - <filename>Makefile</filename> to call - <maketarget>install-info</maketarget> with the installed - info files. (It is no longer necessary to create the - <filename>dir</filename> file yourself; - <command>install-info</command> automatically creates this - file if it does not exist.)</para> - - <programlisting>Index: Makefile -=================================================================== -RCS file: /usr/cvs/ports/editors/emacs/Makefile,v -retrieving revision 1.26 -diff -u -r1.26 Makefile ---- Makefile 1996/11/19 13:14:40 1.26 -+++ Makefile 1997/05/20 10:25:09 1.28 -@@ -20,5 +20,8 @@ - post-install: - .for file in emacs-19.34 emacsclient etags ctags b2m - strip ${PREFIX}/bin/${file} - .endfor -+.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode -+ install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir -+.endfor - - .include <bsd.port.mk></programlisting> - </step> - - <step> - <para>Edit <filename>pkg-plist</filename> and add equivalent - <literal>@exec</literal> statements and also - <literal>@unexec</literal> for - <command>pkg_delete</command>.</para> - - <programlisting>Index: pkg-plist -=================================================================== -RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v -retrieving revision 1.15 -diff -u -r1.15 pkg-plist ---- pkg-plist 1997/03/04 08:04:00 1.15 -+++ pkg-plist 1997/05/20 10:25:12 1.17 -@@ -16,7 +14,14 @@ - man/man1/etags.1.gz - man/man1/ctags.1.gz -+@unexec install-info --delete %D/info/emacs %D/info/dir - : -+@unexec install-info --delete %D/info/ccmode %D/info/dir - info/cl - info/cl-1 -@@ -87,6 +94,18 @@ - info/viper-3 - info/viper-4 -+@exec install-info %D/info/emacs %D/info/dir - : -+@exec install-info %D/info/ccmode %D/info/dir - libexec/emacs/19.34/i386--freebsd/cvtmail - libexec/emacs/19.34/i386--freebsd/digest-doc</programlisting> - - <note> - <para>The <literal>@unexec install-info --delete</literal> - commands have to be listed before the info files themselves so - they can read the files. Also, the <literal>@exec - install-info</literal> commands have to be after the info - files and the <literal>@exec</literal> command that creates the - the <filename>dir</filename> file.</para> - </note> - </step> - - <step> - <para><link linkend="porting-testing">Test</link> and admire your - work. <!-- smiley --><emphasis>:-)</emphasis>. Check the - <filename>dir</filename> file before and after each step.</para> - </step> - </procedure> - </chapter> - - <chapter> - <title>The <filename>pkg-<replaceable>*</replaceable></filename> files</title> - - <para>There are some tricks we have not mentioned yet about the - <filename>pkg-<replaceable>*</replaceable></filename> files - that come in handy sometimes.</para> - - <sect1 id="porting-message"> - <title><filename>pkg-message</filename></title> - - <para>If you need to display a message to the installer, you may place - the message in <filename>pkg-message</filename>. This capability is - often useful to display additional installation steps to be taken - after a <command>pkg_add</command> or to display licensing - information.</para> - - <note> - <para>The <filename>pkg-message</filename> file does not need to be - added to <filename>pkg-plist</filename>. Also, it will not get - automatically printed if the user is using the port, not the - package, so you should probably display it from the - <maketarget>post-install</maketarget> target yourself.</para> - </note> - </sect1> - - <sect1> - <title><filename>pkg-install</filename></title> - - <para>If your port needs to execute commands when the binary package - is installed with <command>pkg_add</command> you can do this via the - <filename>pkg-install</filename> script. This script will - automatically be added to the package, and will be run twice by - <command>pkg_add</command>. The first time as - <literal>${SH} pkg-install ${PKGNAME} - PRE-INSTALL</literal> and the second time as - <literal>${SH} pkg-install ${PKGNAME} POST-INSTALL</literal>. - <literal>$2</literal> can be tested to determine which mode - the script is being run in. The <envar>PKG_PREFIX</envar> - environmental variable will be set to the package installation - directory. See &man.pkg.add.1; for - additional information.</para> - - <note> - <para>This script is not run automatically if you install the port - with <command>make install</command>. If you are depending on it - being run, you will have to explicitly call it from your port's - <filename>Makefile</filename>.</para> - </note> - </sect1> - - <sect1> - <title><filename>pkg-req</filename></title> - - <para>If your port needs to determine if it should install or not, you - can create a <filename>pkg-req</filename> “requirements” - script. It will be invoked automatically at - installation/deinstallation time to determine whether or not - installation/deinstallation should proceed.</para> - </sect1> - - <sect1 id="porting-plist"> - <title>Changing <filename>pkg-plist</filename> based on make - variables</title> - - <para>Some ports, particularly the p5- ports, need to change their - <filename>pkg-plist</filename> depending on what options they are - configured with (or version of perl, in the case of p5- ports). To - make this easy, any instances in the <filename>pkg-plist</filename> of - <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, and - <literal>%%PERL_VERSION%%</literal> will be substituted for - appropriately. The value of <literal>%%OSREL%%</literal> is the - numeric revision of the operating system (e.g., - <literal>2.2.7</literal>). <literal>%%PERL_VERSION%%</literal> is - the full version number of perl (e.g., <literal>5.00502</literal>) - and <literal>%%PERL_VER%%</literal> is the perl version number minus - the patchlevel (e.g., <literal>5.005</literal>).</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> - pairs and instances of - <literal>%%<replaceable>VAR</replaceable>%%</literal>' will be - substituted with <replaceable>VALUE</replaceable> in the - <filename>pkg-plist</filename>.</para> - - <para>For instance, if you have a port that installs many files in a - version-specific subdirectory, you can put something like - - <programlisting>OCTAVE_VERSION= 2.0.13 -PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting> - - in the <filename>Makefile</filename> and use - <literal>%%OCTAVE_VERSION%%</literal> wherever the version shows up - in <filename>pkg-plist</filename>. That way, when you upgrade the port, - you will not have to change dozens (or in some cases, hundreds) of - lines in the <filename>pkg-plist</filename>.</para> - - <para>This substitution (as well as addition of any <link - linkend="porting-manpages">man pages</link>) will be done between - the <maketarget>do-install</maketarget> and - <maketarget>post-install</maketarget> targets, by reading from - <makevar>PLIST</makevar> and writing to <makevar>TMPPLIST</makevar> - (default: - <filename><makevar>WRKDIR</makevar>/.PLIST.mktmp</filename>). So if - your port builds <makevar>PLIST</makevar> on the fly, do so in or - before <maketarget>do-install</maketarget>. Also, if your port - needs to edit the resulting file, do so in - <maketarget>post-install</maketarget> to a file named - <makevar>TMPPLIST</makevar>.</para> - </sect1> - - <sect1> - <title id="porting-pkgfiles">Changing the names of - <filename>pkg-<replaceable>*</replaceable></filename> files</title> - - <para>All the names of <filename>pkg-<replaceable>*</replaceable></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 - 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 idea to write - directly in to the <filename>pkg-<replaceable>*</replaceable></filename> subdirectory).</para> - - <para>Here is a list of variable names and their default - values. (<makevar>PKGDIR</makevar> defaults to - <makevar>${MASTERDIR}</makevar>.)</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Variable</entry> - <entry>Default value</entry> - </row> - </thead> - - <tbody> - <row> - <entry><makevar>COMMENT</makevar></entry> - <entry><literal>${PKGDIR}/pkg-comment</literal></entry> - </row> - - <row> - <entry><makevar>DESCR</makevar></entry> - <entry><literal>${PKGDIR}/pkg-descr</literal></entry> - </row> - - <row> - <entry><makevar>PLIST</makevar></entry> - <entry><literal>${PKGDIR}/pkg-plist</literal></entry> - </row> - - <row> - <entry><makevar>PKGINSTALL</makevar></entry> - <entry><literal>${PKGDIR}/pkg-install</literal></entry> - </row> - - <row> - <entry><makevar>PKGDEINSTALL</makevar></entry> - <entry><literal>${PKGDIR}/pkg-deinstall</literal></entry> - </row> - - <row> - <entry><makevar>PKGREQ</makevar></entry> - <entry><literal>${PKGDIR}/pkg-req</literal></entry> - </row> - - <row> - <entry><makevar>PKGMESSAGE</makevar></entry> - <entry><literal>${PKGDIR}/pkg-message</literal></entry> - </row> - </tbody> - </tgroup> - </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 - installed in <filename>/var/db/pkg</filename> upon install from a - port.</para> - </sect1> - </chapter> - - <chapter> - <title>Licensing Problems</title> - - <para>Some software packages have restrictive licenses or can be in - violation of the law in some countries (such as violating a patent). - What we can do with - them varies a lot, depending on the exact wordings of the respective - licenses.</para> - - <note> - <para>It is your responsibility as a porter to read the licensing - terms of the software and make sure that the FreeBSD project will - not be held accountable for violating them by redistributing the - source or compiled binaries either via ftp or CD-ROM. If in doubt, - please contact the &a.ports;.</para> - </note> - - <para>There are two variables you can set in the Makefile to handle the - situations that arise frequently:</para> - - <orderedlist> - <listitem> - <para>If the port has a “do not sell for profit” type of - license, set the variable <makevar>NO_CDROM</makevar> to a string - describing the reason why. We will make sure such ports will not go - into the CD-ROM come release time. The distfile and package will - still be available via ftp.</para> - </listitem> - - <listitem> - <para>If the resulting package needs to be built uniquely for each - site, or the resulting binary package cannot be distributed due to - licensing; set the variable <makevar>NO_PACKAGE</makevar> to a - string describing the reason why. We will make sure such packages - will not go on the ftp site, nor into the CD-ROM come release time. - The distfile will still be included on both however.</para> - </listitem> - - <listitem> - <para>If the port has legal restrictions on who can use it (e.g., - patented stuff) or has a “no commercial use” license, - set the variable <makevar>RESTRICTED</makevar> to be the string - describing the reason why. For such ports, the distfiles/packages - will not be available even from our ftp sites.</para> - </listitem> - </orderedlist> - - <note> - <para>The GNU General Public License (GPL), both version 1 and 2, - should not be a problem for ports.</para> - </note> - - <note> - <para>If you are a committer, make sure you update the - <filename>ports/LEGAL</filename> file too.</para> - </note> - </chapter> - - <chapter id="port-upgrading"> - <title>Upgrading</title> - - <para>When you notice that a port is out of date compared to the latest - version from the original authors, first make sure you have the latest - port. You can find them in the - <filename>ports/ports-current</filename> directory of the ftp mirror - sites. You may also use CVSup to keep your whole ports collection - up-to-date, as described in <ulink url="../handbook/synching.html#CVSUP-CONFIG">the Handbook</ulink>.</para> - - <para>The next step is to send a mail to the maintainer, if one is - listed in the port's <filename>Makefile</filename>. That person may - already be working on an upgrade, or have a reason to not upgrade the - port right now (because of, for example, stability problems of the new - version).</para> - - <para>If the maintainer asks you to do the upgrade or there is not any - such person to begin with, please make the upgrade and send the - recursive diff (either unified or context diff is fine, but port - committers appear to prefer unified diff more) of the new and old - ports directories to us (e.g., if your modified port directory is - called <filename>superedit</filename> and the original as in our tree - is <filename>superedit.bak</filename>, then send us the result of - <command>diff -ruN superedit.bak superedit</command>). Please examine - the output to make sure all the changes make sense. The best way to - send us the diff is by including it via &man.send-pr.1; (category - <literal>ports</literal>). Please mention any added or deleted files - in the message, as they have to be explicitly specified to CVS when - doing a commit. If the diff is more than about 20KB, please compress - and uuencode it; otherwise, just include it in the PR as is.</para> - - <note> - <para>Once again, please use &man.diff.1; and not &man.shar.1; to send - updates to existing ports!</para> - </note> - </chapter> - - <chapter> - <title><anchor id="porting-dads">Dos and Don'ts</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 PR database that others have - submitted. Submit any comments on ports you check as described in - <ulink url="../handbook/contrib-how.html#CONTRIB-GENERAL">Bug Reports and General - Commentary</ulink>. 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> - <title>Strip Binaries</title> - - <para>Do strip binaries. If the original source already strips the - binaries, fine; otherwise you should add a - <literal>post-install</literal> rule to to it yourself. Here is an - example:</para> - - <programlisting>post-install: - strip ${PREFIX}/bin/xdl</programlisting> - - <para>Use the &man.file.1; command on the installed executable to - check whether the binary is stripped or not. If it does not say - <literal>not stripped</literal>, it is stripped.</para> - </sect1> - - <sect1> - <title>INSTALL_* macros</title> - - <para>Do use the macros provided in <filename>bsd.port.mk</filename> - to ensure correct modes and ownership of files in your own - <maketarget>*-install</maketarget> targets.</para> - - <itemizedlist> - <listitem> - <para><makevar>INSTALL_PROGRAM</makevar> is a command to install - binary executables.</para> - </listitem> - - <listitem> - <para><makevar>INSTALL_SCRIPT</makevar> is a command to install - executable scripts.</para> - </listitem> - - <listitem> - <para><makevar>INSTALL_DATA</makevar> is a command to install - sharable data.</para> - </listitem> - - <listitem> - <para><makevar>INSTALL_MAN</makevar> is a command to install - manpages and other documentation (it does not compress - anything).</para> - </listitem> - </itemizedlist> - - <para>These are basically the <command>install</command> command with - all the appropriate flags. See below for an example on how to use - them.</para> - </sect1> - - <sect1 id="porting-wrkdir"> - <title><makevar>WRKDIR</makevar></title> - - <para>Do not write anything to files outside - <makevar>WRKDIR</makevar>. <makevar>WRKDIR</makevar> is the only - place that is guaranteed to be writable during the port build (see - <ulink url="../handbook/ports-using.html#PORTS-CD">compiling ports from CDROM</ulink> 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, 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> - - <para>Make sure your port honors <makevar>WRKDIRPREFIX</makevar>. - 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 correct location is - <filename><makevar>WRKDIRPREFIX</makevar><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> not <filename><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> or <filename><makevar>.CURDIR</makevar>/../../<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> or some such.</para> - - <para>Also, if you are defining <makevar>WRKDIR</makevar> yourself, - make sure you prepend - <literal>${WRKDIRPREFIX}${.CURDIR}</literal> in the - front.</para> - </sect1> - - <sect1 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 UNIX it is running under. If - you need to make such changes to the code for conditional - compilation, make sure you make the changes as general as possible - so that we can back-port code to FreeBSD 1.x systems and cross-port - to other BSD systems such as 4.4BSD from CSRG, BSD/386, 386BSD, - NetBSD, and OpenBSD.</para> - - <para>The preferred way to tell 4.3BSD/Reno (1990) and newer versions - of the BSD code apart is by using the <literal>BSD</literal> macro - defined in <filename><sys/param.h></filename>. Hopefully that - file is already included; if not, add the code:</para> - - <programlisting>#if (defined(__unix__) || defined(unix)) && !defined(USG) -#include <sys/param.h> -#endif</programlisting> - - <para>to the proper place in the <filename>.c</filename> file. We - believe that every system that defines these two symbols has - <filename>sys/param.h</filename>. If you find a system that - does not, we would like to know. Please send mail to the - &a.ports;.</para> - - <para>Another way is to use the GNU Autoconf style of doing - this:</para> - - <programlisting>#ifdef HAVE_SYS_PARAM_H -#include <sys/param.h> -#endif</programlisting> - - <para>Do not forget to add <literal>-DHAVE_SYS_PARAM_H</literal> to the - <makevar>CFLAGS</makevar> in the <filename>Makefile</filename> for - this method.</para> - - <para>Once you have <filename>sys/param.h</filename> included, you may - use:</para> - - <programlisting>#if (defined(BSD) && (BSD >= 199103))</programlisting> - - <para>to detect if the code is being compiled on a 4.3 Net2 code base - or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD, BSD/386 - 1.1 and below).</para> - - <para>Use:</para> - - <programlisting>#if (defined(BSD) && (BSD >= 199306))</programlisting> - - <para>to detect if the code is being compiled on a 4.4 code base or - newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or - above).</para> - - <para>The value of the <literal>BSD</literal> macro is - <literal>199506</literal> for the 4.4BSD-Lite2 code base. This is - stated for informational purposes only. It should not be used to - distinguish between versions of FreeBSD based only on 4.4-Lite vs. - versions that have merged in changes from 4.4-Lite2. The - <literal>__FreeBSD__</literal> macro should be used instead.</para> - - <para>Use sparingly:</para> - - <itemizedlist> - <listitem> - <para><literal>__FreeBSD__</literal> is defined in all versions of - FreeBSD. Use it if the change you are making - <emphasis>only</emphasis> affects FreeBSD. Porting gotchas like - the use of <literal>sys_errlist[]</literal> vs - <function>strerror()</function> are Berkeleyisms, not FreeBSD - changes.</para> - </listitem> - - <listitem> - <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is defined to - be <literal>2</literal>. In earlier versions, it is - <literal>1</literal>. Later versions will bump it to match - their major version number.</para> - </listitem> - - <listitem> - <para>If you need to tell the difference between a FreeBSD 1.x - system and a FreeBSD 2.x or 3.x system, usually the right answer - is to use the <literal>BSD</literal> macros described above. If - there actually is a FreeBSD specific change (such as special - shared library options when using <command>ld</command>) then it - is OK to use <literal>__FreeBSD__</literal> and <literal>#if - __FreeBSD__ > 1</literal> to detect a FreeBSD 2.x and later - system. If you need more granularity in detecting FreeBSD - systems since 2.0-RELEASE you can use the following:</para> - - <programlisting>#if __FreeBSD__ >= 2 -#include <osreldate.h> -# if __FreeBSD_version >= 199504 - /* 2.0.5+ release specific code here */ -# endif -#endif</programlisting> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Release</entry> - <entry><literal>__FreeBSD_version</literal></entry> - </row> - </thead> - - <tbody> - <row> - <entry>2.0-RELEASE</entry> - <entry>119411</entry> - </row> - - <row> - <entry>2.1-CURRENT</entry> - <entry>199501, 199503</entry> - </row> - - <row> - <entry>2.0.5-RELEASE</entry> - <entry>199504</entry> - </row> - - <row> - <entry>2.2-CURRENT before 2.1</entry> - <entry>199508</entry> - </row> - - <row> - <entry>2.1.0-RELEASE</entry> - <entry>199511</entry> - </row> - - <row> - <entry>2.2-CURRENT before 2.1.5</entry> - <entry>199512</entry> - </row> - - <row> - <entry>2.1.5-RELEASE</entry> - <entry>199607</entry> - </row> - - <row> - <entry>2.2-CURRENT before 2.1.6</entry> - <entry>199608</entry> - </row> - - <row> - <entry>2.1.6-RELEASE</entry> - <entry>199612</entry> - </row> - - <row> - <entry>2.1.7-RELEASE</entry> - <entry>199612</entry> - </row> - - <row> - <entry>2.2-RELEASE</entry> - <entry>220000</entry> - </row> - - <row> - <entry>2.2.1-RELEASE</entry> - <entry>220000 (no change)</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.1-RELEASE</entry> - <entry>220000 (no change)</entry> - </row> - - <row> - <entry>2.2-STABLE after texinfo-3.9</entry> - <entry>221001</entry> - </row> - - <row> - <entry>2.2-STABLE after top</entry> - <entry>221002</entry> - </row> - - <row> - <entry>2.2.2-RELEASE</entry> - <entry>222000</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.2-RELEASE</entry> - <entry>222001</entry> - </row> - - <row> - <entry>2.2.5-RELEASE</entry> - <entry>225000</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.5-RELEASE</entry> - <entry>225001</entry> - </row> - - <row> - <entry>2.2-STABLE after ldconfig -R merge</entry> - <entry>225002</entry> - </row> - - <row> - <entry>2.2.6-RELEASE</entry> - <entry>226000</entry> - </row> - - <row> - <entry>2.2.7-RELEASE</entry> - <entry>227000</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.7-RELEASE</entry> - <entry>227001</entry> - </row> - - <row> - <entry>2.2-STABLE after semctl(2) change</entry> - <entry>227002</entry> - </row> - - <row> - <entry>2.2.8-RELEASE</entry> - <entry>228000</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.8-RELEASE</entry> - <entry>228001</entry> - </row> - - <row> - <entry>3.0-CURRENT before mount(2) change</entry> - <entry>300000</entry> - </row> - - <row> - <entry>3.0-CURRENT after mount(2) change</entry> - <entry>300001</entry> - </row> - - <row> - <entry>3.0-CURRENT after semctl(2) change</entry> - <entry>300002</entry> - </row> - - <row> - <entry>3.0-CURRENT after ioctl arg changes</entry> - <entry>300003</entry> - </row> - - <row> - <entry>3.0-CURRENT after ELF conversion</entry> - <entry>300004</entry> - </row> - - <row> - <entry>3.0-RELEASE</entry> - <entry>300005</entry> - </row> - - <row> - <entry>3.0-CURRENT after 3.0-RELEASE</entry> - <entry>300006</entry> - </row> - - <row> - <entry>3.0-STABLE after 3/4 branch</entry> - <entry>300007</entry> - </row> - - <row> - <entry>3.1-RELEASE</entry> - <entry>310000</entry> - </row> - - <row> - <entry>3.1-STABLE after 3.1-RELEASE</entry> - <entry>310001</entry> - </row> - - <row> - <entry>3.1-STABLE after C++ constructor/destructor order - change</entry> - <entry>310002</entry> - </row> - - <row> - <entry>3.2-RELEASE</entry> - <entry>320000</entry> - </row> - - <row> - <entry>3.2-STABLE</entry> - <entry>320001</entry> - </row> - - <row> - <entry>3.2-STABLE after binary-incompatible IPFW and - socket changes</entry> - <entry>320002</entry> - </row> - - <row> - <entry>3.3-RELEASE</entry> - <entry>330000</entry> - </row> - - <row> - <entry>3.3-STABLE</entry> - <entry>330001</entry> - </row> - - <row> - <entry>3.3-STABLE after adding mkstemps() to libc</entry> - <entry>330002</entry> - </row> - - <row> - <entry>3.4-RELEASE</entry> - <entry>340000</entry> - </row> - - <row> - <entry>3.4-STABLE</entry> - <entry>340001</entry> - </row> - - <row> - <entry>4.0-CURRENT after 3.4 branch</entry> - <entry>400000</entry> - </row> - - <row> - <entry>4.0-CURRENT after change in dynamic linker - handling</entry> - <entry>400001</entry> - </row> - - <row> - <entry>4.0-CURRENT after C++ constructor/destructor - order change</entry> - <entry>400002</entry> - </row> - - <row> - <entry>4.0-CURRENT after functioning dladdr(3)</entry> - <entry>400003</entry> - </row> - - <row> - <entry>4.0-CURRENT after __deregister_frame_info dynamic - linker bug fix (also 4.0-CURRENT after EGCS 1.1.2 - integration) - </entry> - <entry>400004</entry> - </row> - - <row> - <entry>4.0-CURRENT after suser(9) API change - (also 4.0-CURRENT after newbus)</entry> - <entry>400005</entry> - </row> - - <row> - <entry>4.0-CURRENT after cdevsw registration change</entry> - <entry>400006</entry> - </row> - - <row> - <entry>4.0-CURRENT after the addition of so_cred for - socket level credentials</entry> - <entry>400007</entry> - </row> - - <row> - <entry>4.0-CURRENT after the addition of a poll syscall - wrapper to libc_r</entry> - <entry>400008</entry> - </row> - - <row> - <entry>4.0-CURRENT after the change of the kernel's - <literal>dev_t</literal> type to <literal>struct - specinfo</literal> pointer</entry> - <entry>400009</entry> - </row> - - <row> - <entry>4.0-CURRENT after fixing a hole in jail(2)</entry> - <entry>400010</entry> - </row> - - <row> - <entry>4.0-CURRENT after the <literal>sigset_t</literal> - datatype change</entry> - <entry>400011</entry> - </row> - - <row> - <entry>4.0-CURRENT after the cutover to the GCC 2.95.2 - compiler</entry> - <entry>400012</entry> - </row> - - <row> - <entry>4.0-CURRENT after adding pluggable linux-mode - ioctl handlers</entry> - <entry>400013</entry> - </row> - - <row> - <entry>4.0-CURRENT after importing OpenSSL</entry> - <entry>400014</entry> - </row> - - <row> - <entry>4.0-CURRENT after the C++ ABI change in GCC 2.95.2 - from -fvtable-thunks to -fno-vtable-thunks by - default</entry> - <entry>400015</entry> - </row> - - <row> - <entry>4.0-CURRENT after importing OpenSSH</entry> - <entry>400016</entry> - </row> - - <row> - <entry>4.0-RELEASE</entry> - <entry>400017</entry> - </row> - - <row> - <entry>4.0-STABLE after 4.0-RELEASE</entry> - <entry>400018</entry> - </row> - - <row> - <entry>4.0-STABLE after merging libxpg4 code into - libc.</entry> - <entry>400020</entry> - </row> - - <row> - <entry>4.0-STABLE after upgrading Binutils to 2.10.0, ELF - branding changes, and tcsh in the base system.</entry> - <entry>400021</entry> - </row> - - <row> - <entry>4.1-RELEASE</entry> - <entry>410000</entry> - </row> - - <row> - <entry>4.1-STABLE after 4.1-RELEASE</entry> - <entry>410001</entry> - </row> - - <row> - <entry>4.1-STABLE after setproctitle() moved from - libutil to libc.</entry> - <entry>410002</entry> - </row> - - <row> - <entry>4.1.1-RELEASE</entry> - <entry>411000</entry> - </row> - - <row> - <entry>4.1.1-STABLE after 4.1.1-RELEASE</entry> - <entry>411001</entry> - </row> - - <row> - <entry>4.2-RELEASE</entry> - <entry>420000</entry> - </row> - - <row> - <entry>4.2-STABLE after combining libgcc.a and - libgcc_r.a, and associated GCC linkage changes.</entry> - <entry>420001</entry> - </row> - - <row> - <entry>5.0-CURRENT</entry> - <entry>500000</entry> - </row> - - <row> - <entry>5.0-CURRENT after adding addition ELF header fields, - and changing our ELF binary branding method.</entry> - <entry>500001</entry> - </row> - - <row> - <entry>5.0-CURRENT after kld metadata changes.</entry> - <entry>500002</entry> - </row> - - <row> - <entry>5.0-CURRENT after buf/bio changes.</entry> - <entry>500003</entry> - </row> - - <row> - <entry>5.0-CURRENT after binutils upgrade.</entry> - <entry>500004</entry> - </row> - - <row> - <entry>5.0-CURRENT after merging libxpg4 code into - libc and after TASKQ interface introduction.</entry> - <entry>500005</entry> - </row> - - <row> - <entry>5.0-CURRENT after the addition of AGP - interfaces.</entry> - <entry>500006</entry> - </row> - - <row> - <entry>5.0-CURRENT after Perl upgrade to 5.6.0</entry> - <entry>500007</entry> - </row> - - <row> - <entry>5.0-CURRENT after the update of KAME code to - 2000/07 sources.</entry> - <entry>500008</entry> - </row> - - <row> - <entry>5.0-CURRENT after ether_ifattach() and - ether_ifdetach() changes.</entry> - <entry>500009</entry> - </row> - - <row> - <entry>5.0-CURRENT after changing mtree defaults - back to original variant, adding -L to follow - symlinks.</entry> - <entry>500010</entry> - </row> - - <row> - <entry>5.0-CURRENT after kqueue API changed.</entry> - <entry>500011</entry> - </row> - - <row> - <entry>5.0-CURRENT after setproctitle() moved from - libutil to libc.</entry> - <entry>500012</entry> - </row> - - <row> - <entry>5.0-CURRENT after the first SMPng commit.</entry> - <entry>500013</entry> - </row> - - <row> - <entry>5.0-CURRENT after <sys/select.h> moved to - <sys/selinfo.h>.</entry> - <entry>500014</entry> - </row> - - <row> - <entry>5.0-CURRENT after combining libgcc.a and - libgcc_r.a, and associated GCC linkage changes.</entry> - <entry>500015</entry> - </row> - - <row> - <entry>5.0-CURRENT after change allowing libc and libc_r - to be linked together, deprecating -pthread option.</entry> - <entry>500016</entry> - </row> - - <row> - <entry>5.0-CURRENT after switch from struct ucred to - struct xucred to stabilize kernel-exported API for - mountd et al.</entry> - <entry>500017</entry> - </row> - - <row> - <entry>5.0-CURRENT after addition of CPUTYPE make variable - for controlling CPU-specific optimizations.</entry> - <entry>500018</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </listitem> - </itemizedlist> - - <note> - <para>Note that 2.2-STABLE sometimes identifies itself as - “2.2.5-STABLE” after the 2.2.5-RELEASE. The pattern - used to be year followed by the month, but we decided to change it - to a more straightforward major/minor system starting from 2.2. - This is because the parallel development on several branches made - it infeasible to classify the releases simply by their real - release dates. If you are making a port now, you do not have to - worry about old -CURRENTs; they are listed here just for your - reference.</para> - </note> - - <para>In the hundreds of ports that have been done, there have only - been one or two cases where <literal>__FreeBSD__</literal> should - have been used. Just because an earlier port screwed up and used it - in the wrong place does not mean you should do so too.</para> - </sect1> - - <sect1> - <title>Writing something after - <filename>bsd.port.mk</filename></title> - - <para>Do not write anything after the <literal>.include - <bsd.port.mk></literal> line. It usually can be avoided by - including <filename>bsd.port.pre.mk</filename> somewhere in the - middle of your <filename>Makefile</filename> and - <filename>bsd.port.post.mk</filename> at the end.</para> - - <note> - <para>You need to include either the - <filename>pre.mk</filename>/<filename>post.mk</filename> pair or - <filename>bsd.port.mk</filename> only; do not mix these two.</para> - </note> - - <para><filename>bsd.port.pre.mk</filename> only defines a few - variables, which can be used in tests in the - <filename>Makefile</filename>, <filename>bsd.port.post.mk</filename> - defines the rest.</para> - - <para>Here are some important variables defined in - <filename>bsd.port.pre.mk</filename> (this is not the complete list, - please read <filename>bsd.port.mk</filename> for the complete - list).</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Variable</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><makevar>ARCH</makevar></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>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>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>The numeric version of the operating system, same as - <link - linkend="porting-versions"><literal>__FreeBSD_version</literal></link>.</entry> - </row> - - <row> - <entry><makevar>PORTOBJFORMAT</makevar></entry> - <entry>The object format of the system - (<literal>aout</literal> or <literal>elf</literal>)</entry> - </row> - - <row> - <entry><makevar>LOCALBASE</makevar></entry> - <entry>The base of the “local” tree (e.g., - <literal>/usr/local/</literal>)</entry> - </row> - - <row> - <entry><makevar>X11BASE</makevar></entry> - <entry>The base of the “X11” tree (e.g., - <literal>/usr/X11R6</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> - </row> - </tbody> - </tgroup> - </informaltable> - - <note> - <para>If you have to define the variables - <makevar>USE_IMAKE</makevar>, <makevar>USE_X_PREFIX</makevar>, or - <makevar>MASTERDIR</makevar>, do so before including - <filename>bsd.port.pre.mk</filename>.</para> - </note> - - <para>Here are some examples of things you can write after - <filename>bsd.port.pre.mk</filename>:</para> - - <programlisting># no need to compile lang/perl5 if perl5 is already in system -.if ${OSVERSION} > 300003 -BROKEN= perl is in system -.endif - -# only one shlib version number for ELF -.if ${PORTOBJFORMAT} == "elf" -TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR} -.else -TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR} -.endif - -# software already makes link for ELF, but not for a.out -post-install: -.if ${PORTOBJFORMAT} == "aout" - ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so -.endif</programlisting> - </sect1> - - <sect1> - <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>. - This can be done, like the previous item, in the - <maketarget>post-install</maketarget> 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 might want different versions of the port to be - installed at the same time, you can use the whole - <makevar>PKGNAME</makevar>.</para> - - <para>Make the installation dependent to the variable - <makevar>NOPORTDOCS</makevar> so that users can disable it in - <filename>/etc/make.conf</filename>, like this:</para> - - <programlisting>post-install: -.if !defined(NOPORTDOCS) - ${MKDIR} ${PREFIX}/share/doc/xv - ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv -.endif</programlisting> - - <para>Do not forget to add them to <filename>pkg-plist</filename> too. - (Do not worry about <makevar>NOPORTDOCS</makevar> here; there is - currently no way for the packages to read variables from - <filename>/etc/make.conf</filename>.)</para> - - <para>You can also use the <filename>pkg-message</filename> file to - display messages upon installation. See the <link - linkend="porting-message">using - <filename>pkg-message</filename></link> section for - details.</para> - - <note> - <para><filename>pkg-message</filename> does not need to be added to - <filename>pkg-plist</filename>.</para> - </note> - </sect1> - - <sect1> - <title><makevar>DIST_SUBDIR</makevar></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 (<literal>${PORTNAME}</literal> or - <literal>${PKGNAMEPREFIX}${PORTNAME}</literal> - 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>, - 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> - - <note> - <para>This does not affect the <makevar>MASTER_SITES</makevar> you - define in your Makefile.</para> - </note> - </sect1> - - <sect1> - <title>Package information</title> - - <para>Do include package information, i.e. - <filename>pkg-comment</filename>, <filename>pkg-descr</filename>, and - <filename>pkg-plist</filename>.</para> - - <note> - <para>Note that these files are not used only for packaging anymore, - and are <emphasis>mandatory</emphasis> now, even if - <makevar>NO_PACKAGE</makevar> is set.</para> - </note> - </sect1> - - <sect1> - <title>RCS strings</title> - - <para>Do not put RCS strings in patches. CVS will mangle them when we - put the files into the ports tree, and when we check them out again, - they will come out different and the patch will fail. RCS strings - are surrounded by dollar (<literal>$</literal>) signs, and - typically start with <literal>$Id</literal> or - <literal>$RCS</literal>.</para> - </sect1> - - <sect1> - <title>Recursive diff</title> - - <para>Using the recurse (<option>-r</option>) option to - <command>diff</command> to generate patches is fine, but please take - a look at the resulting patches to make sure you do not have any - unnecessary junk in there. In particular, diffs between two backup - files, <filename>Makefiles</filename> when the port uses - <command>Imake</command> or GNU <command>configure</command>, etc., - are unnecessary and should be deleted. If you had to edit - <filename>configure.in</filename> and run - <command>autoconf</command> to regenerate - <command>configure</command>, do not take the diffs of - <command>configure</command> (it often grows to a few thousand - lines!); define <literal>USE_AUTOCONF=yes</literal> and take the - diffs of <filename>configure.in</filename>.</para> - - <para>Also, if you had to delete a file, then you can do it in the - <maketarget>post-extract</maketarget> target rather than as part of - the patch. Once you are happy with the resulting diff, please split - it up into one source file per patch file.</para> - </sect1> - - <sect1 id="porting-prefix"> - <title><makevar>PREFIX</makevar></title> - - <para>Do try to make your port install relative to - <makevar>PREFIX</makevar>. (The value of this variable will be set - to <makevar>LOCALBASE</makevar> (default - <filename>/usr/local</filename>), unless - <makevar>USE_X_PREFIX</makevar> or <makevar>USE_IMAKE</makevar> is - set, in which case it will be <makevar>X11BASE</makevar> (default - <filename>/usr/X11R6</filename>).)</para> - - <para>Not hard-coding <filename>/usr/local</filename> or - <filename>/usr/X11R6</filename> anywhere in the source will make the - port much more flexible and able to cater to the needs of other - sites. For X ports that use <command>imake</command>, this is - automatic; otherwise, this can often be done by simply replacing the - occurrences of <filename>/usr/local</filename> (or - <filename>/usr/X11R6</filename> for X ports that do not use imake) - in the various scripts/Makefiles in the port to read - <makevar>PREFIX</makevar>, as this variable is automatically passed - down to every stage of the build and install processes.</para> - - <para>Make sure your application isn't installing things in - <filename>/usr/local</filename> instead of <makevar>PREFIX</makevar>. - A quick test for this is to do this is:</para> - - <screen>&prompt.root; <userinput>make clean; make package PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput></screen> - - <para>If anything is installed outside of <makevar>PREFIX</makevar>, - making the package creation process will complain that it - can't find the files.</para> - - <para>This does not test for the existence of internal references, - or correct use of <makevar>LOCALBASE</makevar> for references to - files from other ports. Testing the installation in - <filename>/var/tmp/<replaceable>port-name</replaceable></filename> - to do that that while you have it installed would do that.</para> - - <para>Do not set <makevar>USE_X_PREFIX</makevar> unless your port - truly requires it (i.e., it links against X libs or it needs to - reference files in <makevar>X11BASE</makevar>).</para> - - <para>The variable <makevar>PREFIX</makevar> can be reassigned in your - <filename>Makefile</filename> or in the user's environment. - However, it is strongly discouraged for individual ports to set this - variable explicitly in the <filename>Makefiles</filename>.</para> - - <para>Also, refer to programs/files from other ports with the - variables mentioned above, not explicit pathnames. For instance, if - your port requires a macro <literal>PAGER</literal> to be the full - pathname of <command>less</command>, use the compiler flag: - - <programlisting>-DPAGER=\"${PREFIX}/bin/less\"</programlisting> - - or - - <programlisting>-DPAGER=\"${LOCALBASE}/bin/less\"</programlisting> - - if this is an X port, instead of - <literal>-DPAGER=\"/usr/local/bin/less\".</literal> This way it will - have a better chance of working if the system administrator has - moved the whole `/usr/local' tree somewhere else.</para> - </sect1> - - <sect1> - <title>Subdirectories</title> - - <para>Try to let the port put things in the right subdirectories of - <makevar>PREFIX</makevar>. 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 the a subdirectory of <filename>lib</filename>, which does - not bode well with the BSD paradigm. Many of the files should be - moved to one of the following: <filename>etc</filename> - (setup/configuration files), <filename>libexec</filename> - (executables started internally), <filename>sbin</filename> - (executables for superusers/managers), <filename>info</filename> - (documentation for info browser) or <filename>share</filename> - (architecture independent files). See man &man.hier.7; for details, - the rules governing - <filename>/usr</filename> pretty much apply to - <filename>/usr/local</filename> too. The exception are ports - dealing with USENET “news”. They may use - <filename><makevar>PREFIX</makevar>/news</filename> as a destination - for their files.</para> - </sect1> - - <sect1 id="porting-cleaning"> - <title>Cleaning up empty directories</title> - - <para>Do make your ports clean up after themselves when they are - deinstalled. This is usually accomplished by adding - <literal>@dirrm</literal> lines for all directories that are - specifically created by the port. You need to delete subdirectories - before you can delete parent directories.</para> - - <programlisting> : -lib/X11/oneko/pixmaps/cat.xpm -lib/X11/oneko/sounds/cat.au - : -@dirrm lib/X11/oneko/pixmaps -@dirrm lib/X11/oneko/sounds -@dirrm lib/X11/oneko</programlisting> - - <para>However, sometimes <literal>@dirrm</literal> will give you - errors because other ports also share the same subdirectory. You - can call <command>rmdir</command> from <literal>@unexec</literal> to - remove only empty directories without warning.</para> - - <programlisting>@unexec rmdir %D/share/doc/gimp 2>/dev/null || true</programlisting> - - <para>This will neither print any error messages nor cause - <command>pkg_delete</command> to exit abnormally even if - <filename><makevar>PREFIX</makevar>/share/doc/gimp</filename> is not - empty due to other ports installing some files in there.</para> - </sect1> - - <sect1> - <title>UIDs</title> - - <para>If your port requires a certain user to be on the installed - system, let the <filename>pkg-install</filename> script call - <command>pw</command> to create it automatically. Look at - <filename>net/cvsup-mirror</filename> for an example.</para> - - <para>If your port must use the same user/group ID number when it is - installed as a binary package as when it was compiled, then you must - choose a free UID from 50 to 99 and register it below. Look at - <filename>japanese/Wnn</filename> for an example.</para> - - <para>Make sure you do not use a UID already used by the system or - other ports. This is the current list of UIDs between 50 and - 99.</para> - - <programlisting>majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent -cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent -gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh -uucp:*:66:66:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico -xten:*:67:67:X-10 daemon:/usr/local/xten:/nonexistent -pop:*:68:6:Post Office Owner (popper):/nonexistent:/nonexistent -wnn:*:69:7:Wnn:/nonexistent:/nonexistent -ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent -pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh -ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent -alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent -qmaill:*:83:81:QMail user:/var/qmail:/nonexistent -qmaild:*:82:81:QMail user:/var/qmail:/nonexistent -qmailq:*:85:82:QMail user:/var/qmail:/nonexistent -qmails:*:87:82:QMail user:/var/qmail:/nonexistent -qmailp:*:84:81:QMail user:/var/qmail:/nonexistent -qmailr:*:86:82:QMail user:/var/qmail:/nonexistent -msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh -mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin -vpopmail:*:89:89::0:0:User &:/usr/local/vpopmail:/nonexistent</programlisting> - - <para>Please include a notice when you submit a port (or an upgrade) - that reserves a new UID or GID in this range. This allows us to - keep the list of reserved IDs up to date.</para> - </sect1> - - <sect1> - <title>Do things rationally</title> - - <para>The <filename>Makefile</filename> should do things simply and - reasonably. If you can make it a couple of lines shorter 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 <literal>CONFIGURE_ARGS - += --prefix=${PREFIX}</literal>.</para> - </sect1> - - <sect1> - <title>Respect <makevar>CFLAGS</makevar></title> - - <para>The port should respect the <makevar>CFLAGS</makevar> variable. - If it does not, please add <literal>NO_PACKAGE=ignores - cflags</literal> to the <filename>Makefile</filename>.</para> - - <para>An example of a <filename>Makefile</filename> respecting - the <makevar>CFLAGS</makevar> variable follows. Note the - <makevar>+=</makevar>:</para> - - <programlisting>CFLAGS += -Wall -Werror</programlisting> - - <para>Here is an example which does not respect the - <makevar>CFLAGS</makevar> variable:</para> - - <programlisting>CFLAGS = -Wall -Werror</programlisting> - - <para>The <makevar>CFLAGS</makevar> 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 - definitions. The second example clobbers anything previously - defined.</para> - </sect1> - - <sect1> - <title>Configuration files</title> - - <para>If your port requires some configuration files in - <filename><makevar>PREFIX</makevar>/etc</filename>, do - <emphasis>not</emphasis> just install them and list them in - <filename>pkg-plist</filename>. That will cause - <command>pkg_delete</command> to delete files carefully edited by - the user and a new installation to wipe them out.</para> - - <para>Instead, install sample files with a suffix - (<filename><replaceable>filename</replaceable>.sample</filename> - will work well) and print out a <link - linkend="porting-message">message</link> pointing out that the - user has to copy and edit the file before the software can be made - to work.</para> - </sect1> - - <sect1> - <title>Portlint</title> - - <para>Do check your work with <link - linkend="porting-portlint"><command>portlint</command></link> - before you submit or commit it.</para> - </sect1> - - <sect1> - <title>Feedback</title> - - <para>Do send applicable changes/patches to the original - author/maintainer for inclusion in next release of the code. This - will only make your job that much easier for the next - release.</para> - </sect1> - - <sect1> - <title><filename>README.html</filename></title> - - <para>Do not include the <filename>README.html</filename> file. This - file is not part of the cvs collection but is generated using the - <command>make readme</command> command. - </para> - </sect1> - - <sect1> - <title>Miscellanea</title> - - <para>The files <filename>pkg-comment</filename>, - <filename>pkg-descr</filename>, and <filename>pkg-plist</filename> - should each be double-checked. If you are reviewing a port and feel - they can be worded better, do so.</para> - - <para>Do not copy more copies of the GNU General Public License into - our system, please.</para> - - <para>Please be careful to note any legal issues! Do not let us - illegally distribute software!</para> - </sect1> - - <sect1> - <title>If you are stuck…</title> - - <para>Do look at existing examples and the - <filename>bsd.port.mk</filename> file before asking us questions! - <!-- smiley --><emphasis>;-)</emphasis></para> - - <para>Do ask us questions if you have any trouble! Do not just beat - your head against a wall! <!-- smiley - --><emphasis>:-)</emphasis></para> - </sect1> - </chapter> - - <chapter id="porting-samplem"> - <title>A Sample <filename>Makefile</filename></title> - - <para>Here is a sample <filename>Makefile</filename> that you can use to - create a new port. Make sure you remove all the extra comments (ones - between brackets)!</para> - - <para>It is recommended that you follow this format (ordering of - variables, empty lines between sections, etc.). This format is - designed so that the most important information is easy to locate. We - recommend that you use <link - linkend="porting-portlint">portlint</link> to check the - <filename>Makefile</filename>.</para> - - <programlisting>[the header...just to make it easier for us to identify the ports.] -# New ports collection makefile for: xdvi -[the "version required" line is only needed when the PORTVERSION - variable is not specific enough to describe the port.] -# Date created: 26 May 1995 -[this is the person who did the original port to FreeBSD, in particular, the -person who wrote the first version of this Makefile. Remember, this should -not be changed when upgrading the port later.] -# Whom: Satoshi Asami <asami@FreeBSD.org> -# -# $FreeBSD$ -[ ^^^^^^^^^ This will be automatically replaced with RCS ID string by CVS -when it is committed to our repository. If upgrading a port, do not alter -this line back to "$FreeBSD$". CVS deals with it automatically.] -# - -[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. - PKGNAMEPREFIX and PKGNAMESUFFIX, if needed, will be after that. - 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 -PKGNAMEPREFIX= ja- -DISTNAME= xdvi-pl18 -[set this if the source is not in the standard ".tar.gz" form] -EXTRACT_SUFX= .tar.Z - -[section for distributed patches -- can be empty] -PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/ -PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz - -[maintainer; *mandatory*! This is the person (preferably with commit - privileges) whom a user can contact for questions and bug reports - this - person should be the porter or someone who can forward questions to the - original porter reasonably promptly. If you really do not want to have - your address here, set it to "ports@FreeBSD.org".] -MAINTAINER= asami@FreeBSD.org - -[dependencies -- can be empty] -RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript -LIB_DEPENDS= Xpm.5:${PORTSDIR}/graphics/xpm - -[this section is for other standard bsd.port.mk variables that do not - belong to any of the above] -[If it asks questions during configure, build, install...] -IS_INTERACTIVE= yes -[If it extracts to a directory other than ${DISTNAME}...] -WRKSRC= ${WRKDIR}/xdvi-new -[If the distributed patches were not made relative to ${WRKSRC}, you - may need to tweak this] -PATCH_DIST_STRIP= -p1 -[If it requires a "configure" script generated by GNU autoconf to be run] -GNU_CONFIGURE= yes -[If it requires GNU make, not /usr/bin/make, to build...] -USE_GMAKE= yes -[If it is an X application and requires "xmkmf -a" to be run...] -USE_IMAKE= yes -[et cetera.] - -[non-standard variables to be used in the rules below] -MY_FAVORITE_RESPONSE= "yeah, right" - -[then the special rules, in the order they are called] -pre-fetch: - i go fetch something, yeah - -post-patch: - i need to do something after patch, great - -pre-install: - and then some more stuff before installing, wow - -[and then the epilogue] -.include <bsd.port.mk></programlisting> - </chapter> - - <chapter id="porting-autoplist"> - <title>Automated package list creation</title> - - <para>First, make sure your port is almost complete, with only - <filename>pkg-plist</filename> missing. Create an empty - <filename>pkg-plist</filename>.</para> - - <screen>&prompt.root; <userinput>touch pkg-plist</userinput></screen> - - <para>Next, create a new set of directories which your port can be - installed, and install any dependencies.</para> - - <screen>&prompt.root; <userinput>mtree -U -f /etc/mtree/BSD.local.dist -d -e -p /var/tmp/<replaceable>port-name</replaceable></userinput> -&prompt.root; <userinput>make depends PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput></screen> - - <para>Store the directory structure in a new file.</para> - - <screen>&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name</replaceable> && find * -type d) > OLD-DIRS</userinput></screen> - - <para>If your port honors <makevar>PREFIX</makevar> (which it should) - you can then install the port and create the package list.</para> - - <screen>&prompt.root; <userinput>make install PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput> -&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name</replaceable> && find * \! -type d) > pkg-plist</userinput></screen> - - <para>You must also add any newly created directories to the packing - list.</para> - - <screen>&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name && find * -type d) | comm -13 OLD-DIRS - | sed -e 's#^#@dirrm #' >> pkg-plist</replaceable></userinput></screen> - - <para>Finally, you need to tidy up the packing list by hand; it isn't - <emphasis>all</emphasis> automated. Manual pages should be listed in - the port's <filename>Makefile</filename> under - <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>. - 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-shlibs">shared libraries</link> section.</para> - </chapter> - - <chapter id="porting-pkgname"> - <title>Package Names</title> - - <para>The following are the conventions you should follow in naming your - packages. This is to have our package directory easy to scan, as - there are already lots and lots of packages and 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> - - <para>The package name is defined as - <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>. - Make sure to set the variables to conform to that format.</para> - - <orderedlist> - <listitem> - <para>FreeBSD strives to support the native language of its users. - The <replaceable>language-</replaceable> part should be a two - letter abbreviation of the natural language defined by ISO-639 if - the port is specific to a certain language. Examples are - <literal>ja</literal> for Japanese, <literal>ru</literal> for - Russian, <literal>vi</literal> for Vietnamese, - <literal>zh</literal> for Chinese, <literal>ko</literal> for - Korean and <literal>de</literal> for German.</para> - - <para>If the port is specific to a certain region within the - language area, add the two letter country code as well. - Examples are <literal>en_US</literal> for US English and - <literal>fr_CH</literal> for Swiss French.</para> - - <para>The <replaceable>language-</replaceable> part should - be set in the <makevar>PKGNAMEPREFIX</makevar> variable.</para> - </listitem> - - <listitem> - <para>The first letter of <filename>name</filename> part - should be lowercase. (The rest of the name can 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 Perl 5 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> - </listitem> - - <listitem> - <para>If the port can be built with different <link - linkend="porting-masterdir">hardcoded defaults</link> (usually - part of the directory name in a family of ports), the - <replaceable>-compiled.specifics</replaceable> part should state - the compiled-in defaults (the hyphen is optional). Examples are - papersize and font units.</para> - - <para>The <replaceable>compiled.specifics</replaceable> part - should be set in the <makevar>PKGNAMESUFFIX</makevar> - variable.</para> - </listitem> - - <listitem> - <para>The version string should follow a dash - (<literal>-</literal>) and be a period-separated list of - integers and single lowercase alphabetics. In particular, - it is not permissible to have another dash inside the - 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. If the software - version has strings like "alpha", "beta", "rc", 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 the name - as called by the software authors to a suitable package - name:</para> - - <informaltable frame="none"> - <tgroup cols="6"> - <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>Reason</entry> - </row> - </thead> - - <tbody> - <row> - <entry>mule-2.2.2</entry> - <entry>(empty)</entry> - <entry>mule</entry> - <entry>(empty)</entry> - <entry>2.2.2</entry> - <entry>No changes required</entry> - </row> - - <row> - <entry>XFree86-3.3.6</entry> - <entry>(empty)</entry> - <entry>XFree86</entry> - <entry>(empty)</entry> - <entry>3.3.6</entry> - <entry>No changes required</entry> - </row> - - <row> - <entry>EmiClock-1.0.2</entry> - <entry>(empty)</entry> - <entry>emiclock</entry> - <entry>(empty)</entry> - <entry>1.0.2</entry> - <entry>No uppercase names for single programs</entry> - </row> - - <row> - <entry>rdist-1.3alpha</entry> - <entry>(empty)</entry> - <entry>rdist</entry> - <entry>(empty)</entry> - <entry>1.3.a</entry> - <entry>No strings like <literal>alpha</literal> - allowed</entry> - </row> - - <row> - <entry>es-0.9-beta1</entry> - <entry>(empty)</entry> - <entry>es</entry> - <entry>(empty)</entry> - <entry>0.9.b1</entry> - <entry>No strings like <literal>beta</literal> - allowed</entry> - </row> - - <row> - <entry>mailman-2.0rc3</entry> - <entry>(empty)</entry> - <entry>mailman</entry> - <entry>(empty)</entry> - <entry>2.0.r3</entry> - <entry>No strings like <literal>rc</literal> - allowed</entry> - </row> - - <row> - <entry>v3.3beta021.src</entry> - <entry>(empty)</entry> - <entry>tiff</entry> - <entry>(empty)</entry> - <entry>3.3</entry> - <entry>What the heck was that anyway?</entry> - </row> - - <row> - <entry>tvtwm</entry> - <entry>(empty)</entry> - <entry>tvtwm</entry> - <entry>(empty)</entry> - <entry>pl11</entry> - <entry>Version string always required</entry> - </row> - - <row> - <entry>piewm</entry> - <entry>(empty)</entry> - <entry>piewm</entry> - <entry>(empty)</entry> - <entry>1.0</entry> - <entry>Version string always required</entry> - </row> - - <row> - <entry>xvgr-2.10pl1</entry> - <entry>(empty)</entry> - <entry>xvgr</entry> - <entry>(empty)</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-</entry> - <entry>gawk</entry> - <entry>(empty)</entry> - <entry>2.15.6</entry> - <entry>Japanese language version</entry> - </row> - - <row> - <entry>psutils-1.13</entry> - <entry>(empty)</entry> - <entry>psutils</entry> - <entry>-letter</entry> - <entry>1.13</entry> - <entry>Papersize hardcoded at package build time</entry> - </row> - - <row> - <entry>pkfonts</entry> - <entry>(empty)</entry> - <entry>pkfonts</entry> - <entry>300</entry> - <entry>1.0</entry> - <entry>Package for 300dpi fonts</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>If there is absolutely no trace of version information in the - original source and it is unlikely that the original author will ever - 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>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) - as the version.</para> - </chapter> - - <chapter id="porting-categories"> - <title>Categories</title> - - <para>As you already know, ports are classified in several categories. - But for this to work, it is important that porters and users understand - what each category is for and how we decide what to put in each - category.</para> - - <sect1> - <title>Current list of categories</title> - - <para>First, this is the current list of port categories. Those - marked with an asterisk (<literal>*</literal>) are - <emphasis>virtual</emphasis> categories—those that do not have - a corresponding subdirectory in the ports tree.</para> - - <note> - <para>For non-virtual categories, you will find a one-line - description in the <filename>pkg/COMMENT</filename> file in that - subdirectory (e.g., - <filename>archivers/pkg/COMMENT</filename>).</para> - </note> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Category</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><filename>afterstep*</filename></entry> - <entry>Ports to support the AfterStep window manager.</entry> - </row> - - <row> - <entry><filename>archivers</filename></entry> - <entry>Archiving tools.</entry> - </row> - - <row> - <entry><filename>astro</filename></entry> - <entry>Astronomical ports.</entry> - </row> - - <row> - <entry><filename>audio</filename></entry> - <entry>Sound support.</entry> - </row> - - <row> - <entry><filename>benchmarks</filename></entry> - <entry>Benchmarking utilities.</entry> - </row> - - <row> - <entry><filename>biology</filename></entry> - <entry>Biology-related software.</entry> - </row> - - <row> - <entry><filename>cad</filename></entry> - <entry>Computer aided design tools.</entry> - </row> - - <row> - <entry><filename>chinese</filename></entry> - <entry>Chinese language support.</entry> - </row> - - <row> - <entry><filename>comms</filename></entry> - <entry>Communication software. Mostly software to talk to - your serial port.</entry> - </row> - - <row> - <entry><filename>converters</filename></entry> - <entry>Character code converters.</entry> - </row> - - <row> - <entry><filename>databases</filename></entry> - <entry>Databases.</entry> - </row> - - <row> - <entry><filename>deskutils</filename></entry> - <entry>Things that used to be on the desktop before - computers were invented.</entry> - </row> - - <row> - <entry><filename>devel</filename></entry> - <entry>Development utilities. Do not put libraries here just - because they are libraries—unless they truly do not - belong anywhere else, they should not be in this - category.</entry> - </row> - - <row> - <entry><filename>editors</filename></entry> - <entry>General editors. Specialized editors go in the section - for those tools (e.g., a mathematical-formula editor will go - in <filename>math</filename>).</entry> - </row> - - <row> - <entry><filename>elisp*</filename></entry> - <entry>Emacs-lisp ports.</entry> - </row> - - <row> - <entry><filename>emulators</filename></entry> - <entry>Emulators for other operating systems. Terminal - emulators do <emphasis>not</emphasis> belong - here—X-based ones should go to - <filename>x11</filename> and text-based ones to either - <filename>comms</filename> or <filename>misc</filename>, - depending on the exact functionality.</entry> - </row> - - <row> - <entry><filename>french</filename></entry> - <entry>French language support.</entry> - </row> - - <row> - <entry><filename>ftp</filename></entry> - <entry>FTP client and server utilities. If your - port speaks both FTP and HTTP, put it in - <filename>ftp</filename> with a secondary - category of <filename>www</filename>.</entry> - </row> - - <row> - <entry><filename>games</filename></entry> - <entry>Games.</entry> - </row> - - <row> - <entry><filename>german</filename></entry> - <entry>German language support.</entry> - </row> - - <row> - <entry><filename>gnome*</filename></entry> - <entry>Ports from the GNU Object Model Environment (GNOME) - Project.</entry> - </row> - - <row> - <entry><filename>graphics</filename></entry> - <entry>Graphics utilities.</entry> - </row> - - <row> - <entry><filename>hebrew</filename></entry> - <entry>Hebrew language support.</entry> - </row> - - <row> - <entry><filename>irc</filename></entry> - <entry>Internet Relay Chat utilities.</entry> - </row> - - <row> - <entry><filename>ipv6*</filename></entry> - <entry>IPv6 related software.</entry> - </row> - - <row> - <entry><filename>japanese</filename></entry> - <entry>Japanese language support.</entry> - </row> - - <row> - <entry><filename>java</filename></entry> - <entry>Java language support.</entry> - </row> - - <row> - <entry><filename>kde*</filename></entry> - <entry>Ports from the K Desktop Environment (KDE) - Project.</entry> - </row> - - <row> - <entry><filename>korean</filename></entry> - <entry>Korean language support.</entry> - </row> - - <row> - <entry><filename>lang</filename></entry> - <entry>Programming languages.</entry> - </row> - - <row> - <entry><filename>linux*</filename></entry> - <entry>Linux applications and support utilities.</entry> - </row> - - <row> - <entry><filename>mail</filename></entry> - <entry>Mail software.</entry> - </row> - - <row> - <entry><filename>math</filename></entry> - <entry>Numerical computation software and other utilities - for mathematics.</entry> - </row> - - <row> - <entry><filename>mbone</filename></entry> - <entry>MBone applications.</entry> - </row> - - <row> - <entry><filename>misc</filename></entry> - <entry>Miscellaneous utilities—basically things that - do not belong anywhere else. This is the only category - that 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 - safely delete <literal>misc</literal> and just put the port - in that other subdirectory!</entry> - </row> - - <row> - <entry><filename>net</filename></entry> - <entry>Miscellaneous networking software.</entry> - </row> - - <row> - <entry><filename>news</filename></entry> - <entry>USENET news software.</entry> - </row> - - <row> - <entry><filename>offix*</filename></entry> - <entry>Ports from the OffiX suite.</entry> - </row> - - <row> - <entry><filename>palm</filename></entry> - <entry>Software support for the 3Com Palm(tm) series.</entry> - </row> - - <row> - <entry><filename>perl5*</filename></entry> - <entry>Ports that require perl version 5 to run.</entry> - </row> - - <row> - <entry><filename>plan9*</filename></entry> - <entry>Various programs from Plan9.</entry> - </row> - - <row> - <entry><filename>print</filename></entry> - <entry>Printing software. Desktop publishing tools - (previewers, etc.) belong here too.</entry> - </row> - - <row> - <entry><filename>python*</filename></entry> - <entry>Software written in python.</entry> - </row> - - <row> - <entry><filename>ruby*</filename></entry> - <entry>Software written in ruby.</entry> - </row> - - <row> - <entry><filename>russian</filename></entry> - <entry>Russian language support.</entry> - </row> - - <row> - <entry><filename>science</filename></entry> - <entry>Scientific ports that don't fit into other - categories such as <filename>astro</filename>, - <filename>biology</filename> and - <filename>math</filename>.</entry> - </row> - - <row> - <entry><filename>security</filename></entry> - <entry>Security utilities.</entry> - </row> - - <row> - <entry><filename>shells</filename></entry> - <entry>Command line shells.</entry> - </row> - - <row> - <entry><filename>sysutils</filename></entry> - <entry>System utilities.</entry> - </row> - - <row> - <entry><filename>tcl76*</filename></entry> - <entry>Ports that use Tcl version 7.6 to run.</entry> - </row> - - <row> - <entry><filename>tcl80*</filename></entry> - <entry>Ports that use Tcl version 8.0 to run.</entry> - </row> - - <row> - <entry><filename>tcl81*</filename></entry> - <entry>Ports that use Tcl version 8.1 to run.</entry> - </row> - - <row> - <entry><filename>tcl82*</filename></entry> - <entry>Ports that use Tcl version 8.2 to run.</entry> - </row> - - <row> - <entry><filename>textproc</filename></entry> - <entry>Text processing utilities. It does not include - desktop publishing tools, which go to print/.</entry> - </row> - - <row> - <entry><filename>tk42*</filename></entry> - <entry>Ports that use Tk version 4.2 to run.</entry> - </row> - - <row> - <entry><filename>tk80*</filename></entry> - <entry>Ports that use Tk version 8.0 to run.</entry> - </row> - - <row> - <entry><filename>tk81*</filename></entry> - <entry>Ports that use Tk version 8.1 to run.</entry> - </row> - - <row> - <entry><filename>tk82*</filename></entry> - <entry>Ports that use Tk version 8.2 to run.</entry> - </row> - - <row> - <entry><filename>tkstep80*</filename></entry> - <entry>Ports that use TkSTEP version 8.0 to run.</entry> - </row> - - <row> - <entry><filename>ukrainian</filename></entry> - <entry>Ukrainian language support.</entry> - </row> - - <row> - <entry><filename>vietnamese</filename></entry> - <entry>Vietnamese language support.</entry> - </row> - - <row> - <entry><filename>windowmaker*</filename></entry> - <entry>Ports to support the WindowMaker window - manager</entry> - </row> - - <row> - <entry><filename>www</filename></entry> - <entry>Software related to the World Wide Web. HTML language - support belongs here too.</entry> - </row> - - <row> - <entry>x11</entry> - <entry>The X window system and friends. This category is only - for software that directly supports the window system. Do not - put regular X applications here. If your port is an X - application, define <makevar>USE_XLIB</makevar> (implied by - <makevar>USE_IMAKE</makevar>) and put it in the appropriate - categories. Also, many of them go into other - <filename>x11-*</filename> categories (see below).</entry> - </row> - - <row> - <entry><filename>x11-clocks</filename></entry> - <entry>X11 clocks.</entry> - </row> - - <row> - <entry><filename>x11-fm</filename></entry> - <entry>X11 file managers.</entry> - </row> - - <row> - <entry><filename>x11-fonts</filename></entry> - <entry>X11 fonts and font utilities.</entry> - </row> - - <row> - <entry><filename>x11-servers</filename></entry> - <entry>X11 servers.</entry> - </row> - - <row> - <entry><filename>x11-toolkits</filename></entry> - <entry>X11 toolkits.</entry> - </row> - - <row> - <entry><filename>x11-wm</filename></entry> - <entry>X11 window managers.</entry> - </row> - - <row> - <entry><filename>zope*</filename></entry> - <entry>Zope support.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1> - <title>Choosing the right category</title> - - <para>As many of the categories overlap, you often have to choose - which of the categories should be the primary category of your port. - There are several rules that govern this issue. Here is the list of - priorities, in decreasing order of precedence.</para> - - <itemizedlist> - <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 <literal>japanese - x11-fonts</literal>.</para> - </listitem> - - <listitem> - <para>Specific categories win over less-specific ones. For - instance, an HTML editor should be listed as <literal>www - editors</literal>, not the other way around. Also, you do not - need to list <literal>net</literal> when the port belongs to - any of <literal>irc</literal>, <literal>mail</literal>, - <literal>mbone</literal>, <literal>news</literal>, - <literal>security</literal>, or <literal>www</literal>.</para> - </listitem> - - <listitem> - <para><literal>x11</literal> is used as a secondary category only - when the primary category is a natural language. In particular, - you should not put <literal>x11</literal> in the category line - for X applications.</para> - </listitem> - - <listitem> - <para><application>Emacs</application> modes should be - placed in the same ports category as the application - supported by the mode, not in - <filename>editors</filename>. For example, an - <application>Emacs</application> mode to edit source - files of some programming language should go into - <filename>lang</filename>. - </para> - </listitem> - - <listitem> - <para>If your port truly does not belong anywhere else, put it in - <literal>misc</literal>.</para> - </listitem> - </itemizedlist> - - <para>If you are not sure about the category, please put a comment to - that effect in your <command>send-pr</command> submission so we can - discuss it before we import it. If you are a committer, send a note - to the &a.ports; so we can discuss it first—too often new ports are - imported to the wrong category only to be moved right away.</para> - </sect1> - </chapter> - - <chapter> - <title>Changes to this document and the ports system</title> - - <para>If you maintain a lot of ports, you should consider following the - &a.ports;. Important changes to the way ports work will be announced - there. You can always find more detailed information on the latest - changes by looking at <ulink - url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/Mk/bsd.port.mk"> the - bsd.port.mk CVS log</ulink>.</para> - </chapter> - - <chapter> - <title>That is It, Folks!</title> - - <para>Boy, this sure was a long tutorial, wasn't it? Thanks for - following us to here, really. Now that you know how to do a port, - have at it and convert everything in the world into ports! That - is the easiest way to start contributing to the FreeBSD Project! - <!-- smiley --><emphasis>:-)</emphasis></para> - </chapter> -</book> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> |