diff options
Diffstat (limited to 'en_US.ISO_8859-1/books/porters-handbook/book.sgml')
| -rw-r--r-- | en_US.ISO_8859-1/books/porters-handbook/book.sgml | 4672 |
1 files changed, 0 insertions, 4672 deletions
diff --git a/en_US.ISO_8859-1/books/porters-handbook/book.sgml b/en_US.ISO_8859-1/books/porters-handbook/book.sgml deleted file mode 100644 index 2712be81df..0000000000 --- a/en_US.ISO_8859-1/books/porters-handbook/book.sgml +++ /dev/null @@ -1,4672 +0,0 @@ - <chapter id="ports"> - <title>Installing Applications: The Ports collection</title> - - <para><emphasis>Contributed by &a.jraynard;.</emphasis></para> - - <para>The FreeBSD Ports collection allows you to compile and install a - very wide range of applications with a minimum of effort.</para> - - <para>For all the hype about open standards, getting a program to work - on different versions of Unix in the real world can be a tedious and - tricky business, as anyone who has tried it will know. You may be - lucky enough to find that the program you want will compile cleanly on - your system, install itself in all the right places and run flawlessly - “out of the box”, but this is unfortunately rather rare. With most - programs, you will find yourself doing a fair bit of head-scratching, - and there are quite a few programs that will result in premature - greying, or even chronic alopecia...</para> - - <para>Some software distributions have attacked this problem by - providing configuration scripts. Some of these are very clever, but - they have an unfortunate tendency to triumphantly announce that your - system is something you have never heard of and then ask you lots of - questions that sound like a final exam in system-level Unix - programming (<literal>Does your system's gethitlist function return a const - pointer to a fromboz or a pointer to a const fromboz? Do you have - Foonix style unacceptable exception handling? And if not, why - not?</literal>).</para> - - <para>Fortunately, with the Ports collection, all the hard work - involved has already been done, and you can just type <command>make install</command> - and get a working program.</para> - - - <sect1> - <title>Why Have a Ports Collection?</title> - - <para>The base FreeBSD system comes with a very wide range of tools - and system utilities, but a lot of popular programs are not in the - base system, for good reasons:-</para> - - - <orderedlist> - - <listitem> - <para>Programs that some people cannot live without and other - people cannot stand, such as a certain Lisp-based editor.</para> - </listitem> - - <listitem> - <para>Programs which are too specialised to put in the base - system (CAD, databases).</para> - </listitem> - - <listitem> - <para>Programs which fall into the “I must have a look at that - when I get a spare minute” category, rather than - system-critical ones (some languages, perhaps).</para> - </listitem> - - <listitem> - <para>Programs that are far too much fun to be supplied with a - serious operating system like FreeBSD ;-)</para> - </listitem> - - <listitem> - <para>However many programs you put in the base system, people - will always want more, and a line has to be drawn somewhere - (otherwise FreeBSD distributions would become absolutely - enormous).</para> - </listitem> - - </orderedlist> - - - <para>Obviously it would be unreasonable to expect everyone to port - their favourite programs by hand (not to mention a tremendous amount - of duplicated work), so the FreeBSD Project came up with an - ingenious way of using standard tools that would automate the - process.</para> - - <para>Incidentally, this is an excellent illustration of how “the - Unix way” works in practice by combining a set of simple but very - flexible tools into something very powerful.</para> - - </sect1> - - <sect1> - <title>How Does the Ports Collection Work?</title> - - <para>Programs are typically distributed on the Internet as a - <link linkend="ports-tarball">tarball</link> consisting of a - Makefile and the source code for the program and usually some - instructions (which are unfortunately not always as instructive as - they could be), with perhaps a configuration script.</para> - - <para>The standard scenario is that you FTP down the tarball, extract - it somewhere, glance through the instructions, make any changes - that seem necessary, run the configure script to set things up and - use the standard <command>make</command> program to compile and install the program - from the source.</para> - - <para>FreeBSD ports still use the tarball mechanism, but use a - <link linkend="ports-skeleton">skeleton</link> to hold the - "knowledge" of how to get the program working on FreeBSD, - rather than expecting the user to be able to work it out. They also - supply their own customised - <link linkend="ports-makefile">Makefile</link>, so that almost - every port can be built in the same way.</para> - - <para>If you look at a port skeleton (either on <ulink - URL="file://localhost/usr/ports/devel/ElectricFence">your FreeBSD - system</ulink> or <ulink - URL="ftp://ftp.freebsd.org/pub/FreeBSD/ports/ports/devel/ElectricFence">the FTP site</ulink>) and expect to find all sorts of pointy-headed rocket science lurking there, you may be disappointed by the one or two rather unexciting-looking files and directories you find there. (We will discuss in a minute how to go about <link - linkend="ports-getting">Getting a port</link>).</para> - - <para>“How on earth can this do anything?” I hear you cry. “There - is no source code there!”</para> - - <para>Fear not, gentle reader, all will become clear (hopefully). - Let's see what happens if we try and install a port. I have chosen - <application>ElectricFence</application>, a useful tool for developers, as the skeleton is - more straightforward than most.</para> - - <note> - <para>If you are trying this at home, you - will need to be root.</para> - </note> - - - <screen>&prompt.root; <userinput>cd /usr/ports/devel/ElectricFence</userinput> -&prompt.root; <userinput>make install</userinput> ->> Checksum OK for ElectricFence-2.0.5.tar.gz. -===> Extracting for ElectricFence-2.0.5 -===> Patching for ElectricFence-2.0.5 -===> Applying FreeBSD patches for ElectricFence-2.0.5 -===> Configuring for ElectricFence-2.0.5 -===> Building for ElectricFence-2.0.5 -[lots of compiler output...] -===> Installing for ElectricFence-2.0.5 -===> Warning: your umask is "0002". If this is not desired, set it to - an appropriate value and install this port again by ``make reinstall''. -install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFence-2.0.5/libefence.a /usr/local/lib -install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFence-2.0.5/libefence.3 /usr/local/man/man3 -===> Compressing manual pages for ElectricFence-2.0.5 -===> Registering installation for ElectricFence-2.0.5</screen> - - - <para>To avoid confusing the issue, I have completely removed the - build output.</para> - - <para>If you tried this yourself, you may well have got something like - this at the start:-</para> - - - <screen id="ports-fetch">&prompt.root; <userinput>make install</userinput> ->> ElectricFence-2.0.5.tar.gz doesn't seem to exist on this system. ->> Attempting to fetch from ftp://ftp.doc.ic.ac.uk/Mirrors/sunsite.unc.edu/pub/Linux/devel/lang/c/.</screen> - - - - <para>The <command>make</command> program has noticed that you did not have a local - copy of the source code and tried to FTP it down so it could get the - job done. I already had the source handy in my example, so it did - not need to fetch it.</para> - - <para>Let's go through this and see what the <command>make</command> program was - doing.</para> - - - <procedure> - - <step> - <para>Locate the source code <link linkend="ports-tarball">tarball.</link> If it is not available locally, try to - grab it from an FTP site.</para> - </step> - - <step> - <para>Run a <link linkend="ports-checksum">checksum</link> - test on the tarball to make sure it has not been tampered - with, accidentally truncated, downloaded in ASCII mode, struck - by neutrinos while in transit, etc.</para> - </step> - - <step> - <para>Extract the tarball into a temporary work directory.</para> - </step> - - <step> - <para>Apply any <link linkend="ports-patch">patches</link> - needed to get the source to compile and run under FreeBSD.</para> - </step> - - <step> - <para>Run any configuration script required by the build - process and correctly answer any questions it asks.</para> - </step> - - <step> - <para>(Finally!) Compile the code.</para> - </step> - - <step> - <para>Install the program executable and other supporting - files, man pages, etc. under the - <filename>/usr/local</filename> hierarchy, where they will not - get mixed up with system programs. This also makes sure that - all the ports you install will go in the same place, instead - of being flung all over your system.</para> - </step> - - <step> - <para>Register the installation in a database. This means that, - if you do not like the program, you can cleanly <link - linkend="ports-remove">remove</link> all traces of it from - your system.</para> - </step> - - </procedure> - - - <para>Scroll up to the <command>make</command> output and see if you can match these - steps to it. And if you were not impressed before, you should be by - now!</para> - - </sect1> - - <sect1 id="ports-getting"> - <title>Getting a FreeBSD Port</title> - - <para>There are two ways of getting hold of the FreeBSD port for a - program. One requires a <link linkend="ports-cd">FreeBSD - CDROM</link>, the other involves using an <link linkend="ports-inet">Internet Connection.</link></para> - - - <sect2 id="ports-cd"> - <title>Compiling ports from CDROM</title> - - <para>Assuming that your FreeBSD CDROM is in the drive and mounted on - <filename>/cdrom</filename> (and the mount point - <emphasis>must</emphasis> be <filename>/cdrom</filename>), you should - then be able to build ports just as you normally do and the port - collection's built in search path should find the tarballs in - <filename>/cdrom/ports/distfiles/</filename> (if they exist there) - rather than downloading them over the net.</para> - - <para>Another way of doing this, if you want to just use the port - skeletons on the CDROM, is to set these variables in - <filename>/etc/make.conf</filename>:</para> - - <programlisting> -PORTSDIR= /cdrom/ports -DISTDIR= /tmp/distfiles -WRKDIRPREFIX= /tmp</programlisting> - - <para>Substitute <literal>/tmp</literal> for any place you have enough - free space. Then, just <command>cd</command> to the appropriate - subdirectory under <filename>/cdrom/ports</filename> and type - <command>make install</command> as - usual. <makevar>WRKDIRPREFIX</makevar> will cause the port to be - build under <filename>/tmp/cdrom/ports</filename>; for instance, - <filename>games/oneko</filename> will be built under - <filename>/tmp/cdrom/ports/games/oneko</filename>.</para> - - <note> - <para>There are some ports for which we cannot provide the - original source in the CDROM due to licensing limitations. In - that case, you will need to look at the section on <link - linkend="ports-inet">Compiling ports using an Internet connection.</link></para> - </note> - </sect2> - - <sect2 id="ports-inet"> - <title>Compiling ports from the Internet</title> - - <para>If you do not have a CDROM, or you want to make sure you get - the very latest version of the port you want, you will need to - download the - <link linkend="ports-skeleton">skeleton</link> for the port. Now - this might sound like rather a fiddly job full of pitfalls, but - it is actually very easy.</para> - - <para>First, if you are running a release version of FreeBSD, make - sure you get the appropriate “upgradekiet” for your - replease from the <ulink url="http://www.freebsd.org/ports/">ports - web page</ulink>. These packages include files that have been - updated since the release that you may need to compile new - ports.</para> - - <para>The key to the skeletons is that the FreeBSD FTP server can create - on-the-fly - <link linkend="ports-tarball">tarballs</link> for you. Here is - how it works, with the gnats program in the databases directory as - an example (the bits in square brackets are comments. Do not type - them in if you are trying this yourself!):-</para> - - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>mkdir databases</userinput> -&prompt.root; <userinput>cd databases</userinput> -&prompt.root; <userinput>ftp ftp.freebsd.org</userinput> -[log in as `ftp' and give your email address when asked for a -password. Remember to use binary (also known as image) mode!] -<prompt>></prompt> <userinput>cd /pub/FreeBSD/ports/ports/databases</userinput> -<prompt>></prompt> <userinput>get gnats.tar</userinput> -[tars up the gnats skeleton for us] -<prompt>></prompt> <userinput>quit</userinput> -&prompt.root; <userinput>tar xf gnats.tar</userinput> -[extract the gnats skeleton] -&prompt.root; <userinput>cd gnats</userinput> -&prompt.root; <userinput>make install</userinput> -[build and install gnats]</screen> - - - <para>What happened here? We connected to the FTP server in the - usual way and went to its <filename>databases</filename> sub-directory. When we gave it - the command <command>get gnats.tar</command>, the FTP server <link - linkend="ports-tarball">tarred</link> up the gnats directory for us.</para> - - <para>We then extracted the gnats skeleton and went into the gnats - directory to build the port. As we explained <link - linkend="ports-fetch">earlier</link>, the make process noticed we did not have a - copy of the source locally, so it fetched one before extracting, - patching and building it.</para> - - <para>Let's try something more ambitious now. Instead of getting a - single port skeleton, let's get a whole sub-directory, for example - all the database skeletons in the ports collection. It looks - almost the same:-</para> - - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>ftp ftp.freebsd.org</userinput> -[log in as `ftp' and give your email address when asked for a -password. Remember to use binary (also known as image) mode!] -<prompt>></prompt> <userinput>cd /pub/FreeBSD/ports/ports</userinput> -<prompt>></prompt> <userinput>get databases.tar</userinput> -[tars up the databases directory for us] -<prompt>></prompt> <userinput>quit</userinput> -&prompt.root; <userinput>tar xf databases.tar</userinput> -[extract all the database skeletons] -&prompt.root; <userinput>cd databases</userinput> -&prompt.root; <userinput>make install</userinput> -[build and install all the database ports]</screen> - - - <para>With half a dozen straightforward commands, we have now got a - set of database programs on our FreeBSD machine! All we did that - was different from getting a single port skeleton and building it - was that we got a whole directory at once, and compiled everything - in it at once. Pretty impressive, no?</para> - - <para>If you expect to be installing many ports, it is probably - worth downloading all the ports directories.</para> - - </sect2> - </sect1> - - <sect1 id="ports-skeleton"> - <title>Skeletons</title> - - <para>A team of compulsive hackers who have forgotten to eat in a - frantic attempt to make a deadline? Something unpleasant lurking in - the FreeBSD attic? No, a skeleton here is a minimal framework that - supplies everything needed to make the ports magic work.</para> - - - <sect2 id="ports-makefile"> - <title><filename>Makefile</filename></title> - - <para>The most important component of a skeleton is the Makefile. - This contains various statements that specify how the port should - be compiled and installed. Here is the Makefile for - ElectricFence:-</para> - - <programlisting> -# New ports collection makefile for: Electric Fence -# Version required: 2.0.5 -# Date created: 13 November 1997 -# Whom: jraynard -# -# $Id$ -# - -DISTNAME= ElectricFence-2.0.5 -CATEGORIES= devel -MASTER_SITES= ${MASTER_SITE_SUNSITE} -MASTER_SITE_SUBDIR= devel/lang/c - -MAINTAINER= jraynard@freebsd.org - -MAN3= libefence.3 - -do-install: - ${INSTALL_DATA} ${WRKSRC}/libefence.a ${PREFIX}/lib - ${INSTALL_MAN} ${WRKSRC}/libefence.3 ${PREFIX}/man/man3 - -.include <bsd.port.mk></programlisting> - - <para>The lines beginning with a "#" sign are comments for - the benefit of human readers (as in most Unix script - files).</para> - - <para><literal>DISTNAME</literal> specifies the name of the <link - linkend="ports-tarball">tarball</link>, but without the - extension.</para> - - <para><literal>CATEGORIES</literal> states what kind of program this is. In - this case, a utility for developers. See the <link - linkend="porting-categories">categories</link> section of this - handbook for a complete list.</para> - - <para><literal>MASTER_SITES</literal> is the URL(s) of the master FTP site, - which is used to retrieve the <link linkend="ports-tarball">tarball</link> if it is not available on the local system. - This is a site which is regarded as reputable, and is normally the - one from which the program is officially distributed (in so far - as any software is "officially" distributed on the - Internet).</para> - - <para><literal>MAINTAINER</literal> is the email address of the person who is - responsible for updating the skeleton if, for example a new - version of the program comes out.</para> - - <para>Skipping over the next few lines for a minute, the line - <literal>.include <bsd.port.mk></literal> says - that the other statements and commands needed for this port are - in a standard file called <filename>bsd.port.mk</filename>. As - these are the same for all ports, there is no point in duplicating - them all over the place, so they are kept in a single standard - file.</para> - - <para>This is probably not the place to go into a detailed - examination of how Makefiles work; suffice it to say that the line - starting with <literal>MAN3</literal> ensures that the ElectricFence man page is - compressed after installation, to help conserve your precious disk - space. The original port did not provide an <maketarget>install</maketarget> target, - so the three lines from <maketarget>do-install</maketarget> ensure that the files - produced by this port are placed in the correct - destination.</para> - - </sect2> - - <sect2> - <title>The <filename>files</filename> directory</title> - - <para>The file containing the <link linkend="ports-checksum">checksum</link> for the port is called - <filename>md5</filename>, after the MD5 algorithm used for ports - checksums. It lives in a directory with the slightly confusing - name of <filename>files</filename>.</para> - - <para>This directory can also contain other miscellaneous files that - are required by the port and do not belong anywhere else.</para> - - </sect2> - - <sect2> - <title>The <filename>patches</filename> directory</title> - - <para>This directory contains the <link linkend="ports-patch">patches</link> needed to make everything work properly under - FreeBSD.</para> - - </sect2> - - <sect2> - <title>The <filename>pkg</filename> directory</title> - - <para>This program contains three quite useful files:-</para> - - - <itemizedlist> - - <listitem> - <para><filename>COMMENT</filename> — a one-line description of - the program.</para> - </listitem> - - <listitem> - <para><filename>DESCR</filename> — a more detailed description.</para> - </listitem> - - <listitem> - <para><filename>PLIST</filename> — a list of all the files - that will be created when the program is installed.</para> - </listitem> - - </itemizedlist> - - - </sect2> - </sect1> - - <sect1 id="ports-troubleshooting"> - <title>What to do when a port does not work.</title> - - <para>Oh. You can do one of four (4) things :</para> - - - <orderedlist> - - <listitem> - <para>Fix it yourself. Technical details on how ports work can - be found in - <link linkend="porting">Porting applications.</link></para> - </listitem> - - <listitem> - <para>Gripe. This is done by e-mail <emphasis>only</emphasis>! Send such e-mail to - the &a.ports; and please include the name/version of the port, - where you got both the port source & distfile(s) from, and - what the text of the error was.</para> - </listitem> - - <listitem> - <para>Forget it. This is the easiest for most — very few of the - programs in ports can be classified as essential!</para> - </listitem> - - <listitem> - <para>Grab the pre-compiled package from a ftp server. The - “master” package collection is on FreeBSD's FTP server in - the <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">packages - directory</ulink>, though check your local mirror first, - please! These are more likely to work (on the whole) than - trying to compile from source and a lot faster besides! Use - the <citerefentry><refentrytitle>pkg_add</refentrytitle><manvolnum>1</manvolnum></citerefentry> program to install a - package file on your system.</para> - </listitem> - - </orderedlist> - - - </sect1> - - <sect1> - <title>Some Questions and Answers</title> - - - <itemizedlist> - - <listitem> - <para>Q. I thought this was going to be a discussion about - modems??!</para> - - <para>A. Ah. You must be thinking of the serial ports on the - back of your computer. We are using “port” here to mean the - result of “porting” a program from one version of Unix to - another. (It is an unfortunate bad habit of computer people to - use the same word to refer to several completely different - things).</para> - </listitem> - - <listitem> - <para>Q. I thought you were supposed to use packages to install - extra programs?</para> - - <para>A. Yes, that is usually the quickest and easiest way of - doing it.</para> - </listitem> - - <listitem> - <para>Q. So why bother with ports then?</para> - - <para>A. Several reasons:-</para> - - - <orderedlist> - - <listitem> - <para>The licensing conditions on some software - distributions require that they be distributed as source - code, not binaries.</para> - </listitem> - - <listitem> - <para>Some people do not trust binary distributions. At - least with source code you can (in theory) read through - it and look for potential problems yourself.</para> - </listitem> - - <listitem> - <para>If you have some local patches, you will need the - source to add them yourself.</para> - </listitem> - - <listitem> - <para>You might have opinions on how a program should be - compiled that differ from the person who did the package - — some people have strong views on what optimisation - setting should be used, whether to build debug versions - and then strip them or not, etc. etc.</para> - </listitem> - - <listitem> - <para>Some people like having code around, so they can - read it if they get bored, hack around with it, borrow - from it (licence terms permitting, of course!) and so - on.</para> - </listitem> - - <listitem> - <para>If you ain't got the source, it ain't software! - <!-- smiley -->;-)</para> - </listitem> - - </orderedlist> - - </listitem> - - <listitem> - <para><anchor id="ports-patch"> Q. What is a patch?</para> - - <para>A. A patch is a small (usually) file that specifies how to - go from one version of a file to another. It contains text - that says, in effect, things like “delete line 23”, “add - these two lines after line 468” or “change line 197 to - this”. Also known as a “diff”, since it is generated by a - program of that name.</para> - </listitem> - - <listitem> - <para><anchor id="ports-tarball"> Q. What is all this about - tarballs?</para> - - <para>A. It is a file ending in <filename>.tar</filename> or - <filename>.tar.gz</filename> (with variations like - <filename>.tar.Z</filename>, or even <filename>.tgz</filename> - if you are trying to squeeze the names into a DOS - filesystem).</para> - - <para>Basically, it is a directory tree that has been archived - into a single file (<filename>.tar</filename>) and optionally - compressed (<filename>.gz</filename>). This technique was - originally used for <emphasis>T</emphasis>ape - <emphasis>AR</emphasis>chives (hence the name <command>tar</command>), but it is - a widely used way of distributing program source code around - the Internet.</para> - - <para>You can see what files are in them, or even extract them - yourself, by using the standard Unix tar program, which comes - with the base FreeBSD system, like this:-</para> - - - <screen>&prompt.user; <userinput>tar tvzf foobar.tar.gz</userinput> -&prompt.user; <userinput>tar xzvf foobar.tar.gz</userinput> -&prompt.user; <userinput>tar tvf foobar.tar</userinput> -&prompt.user; <userinput>tar xvf foobar.tar</userinput> - </screen> - - </listitem> - - <listitem> - <para><anchor id="ports-checksum"> Q. And a checksum?</para> - - <para>A. It is a number generated by adding up all the data in - the file you want to check. If any of the characters change, - the checksum will no longer be equal to the total, so a simple - comparison will allow you to spot the difference. (In - practice, it is done in a more complicated way to spot - problems like position-swapping, which will not show up with a - simplistic addition).</para> - </listitem> - - <listitem> - <para>Q. I did what you said for <link linkend="ports-cd">compiling ports from a CDROM</link> and it worked great - until I tried to install the kermit port:-</para> - - - <screen>&prompt.root; <userinput>make install</userinput> ->> cku190.tar.gz doesn't seem to exist on this system. ->> Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/.</screen> - - <para>Why can it not be found? Have I got a dud CDROM?</para> - - <para>A. The licensing terms for kermit do not allow us to put - the tarball for it on the CDROM, so you will have to fetch it - by hand — sorry! The reason why you got all those error - messages was because you were not connected to the Internet at - the time. Once you have downloaded it from any of the sites - above, you can re-start the process (try and choose the - nearest site to you, though, to save your time and the - Internet's bandwidth).</para> - </listitem> - - <listitem> - <para>Q. I did that, but when I tried to put it into - <filename>/usr/ports/distfiles</filename> I got some error - about not having permission.</para> - - <para>A. The ports mechanism looks for the tarball in - <filename>/usr/ports/distfiles</filename>, but you will not be - able to copy anything there because it is sym-linked to the - CDROM, which is read-only. You can tell it to look somewhere - else by doing</para> - - - <screen>&prompt.root; <userinput>make DISTDIR=/where/you/put/it install</userinput></screen> - - </listitem> - - <listitem> - <para>Q. Does the ports scheme only work if you have everything - in <filename>/usr/ports</filename>? My system administrator - says I must put everything under - <filename>/u/people/guests/wurzburger</filename>, but it does - not seem to work.</para> - - <para>A. You can use the <makevar>PORTSDIR</makevar> and <makevar>PREFIX</makevar> variables to tell - the ports mechanism to use different directories. For - instance,</para> - - - <screen>&prompt.root; <userinput>make PORTSDIR=/u/people/guests/wurzburger/ports install</userinput></screen> - - - <para>will compile the port in - <filename>/u/people/guests/wurzburger/ports</filename> and - install everything under <filename>/usr/local</filename>.</para> - - - <screen>&prompt.root; <userinput>make PREFIX=/u/people/guests/wurzburger/local install</userinput></screen> - - - <para>will compile it in <filename>/usr/ports</filename> and - install it in - <filename>/u/people/guests/wurzburger/local</filename>.</para> - - <para>And of course</para> - - - <screen>&prompt.root; <userinput>make PORTSDIR=.../ports PREFIX=.../local install</userinput></screen> - - - <para>will combine the two (it is too long to fit on the page if - I write it in full, but I am sure you get the idea).</para> - - <para>If you do not fancy typing all that in every time you - install a port (and to be honest, who would?), it is a good - idea to put these variables into your environment.</para> - </listitem> - - <listitem> - <para>Q. I do not have a FreeBSD CDROM, but I would like to have - all the tarballs handy on my system so I do not have to wait - for a download every time I install a port. Is there an easy - way to get them all at once?</para> - - <para>A. To get every single tarball for the ports collection, - do</para> - - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make fetch</userinput></screen> - - - <para>For all the tarballs for a single ports directory, - do</para> - - - <screen>&prompt.root; <userinput>cd /usr/ports/directory</userinput> -&prompt.root; <userinput>make fetch</userinput></screen> - - - <para>and for just one port — well, I think you have guessed - already.</para> - </listitem> - - <listitem> - <para>Q. I know it is probably faster to fetch the tarballs from - one of the FreeBSD mirror sites close by. Is there any way to - tell the port to fetch them from servers other than ones - listed in the MASTER_SITES?</para> - - <para>A. Yes. If you know, for example, <hostid role="fqdn">ftp.FreeBSD.ORG</hostid> is much - closer than sites listed in <makevar>MASTER_SITES</makevar>, do as following - example.</para> - - - <screen>&prompt.root; <userinput>cd /usr/ports/directory</userinput> -&prompt.root; <userinput>make MASTER_SITE_OVERRIDE=ftp://ftp.FreeBSD.ORG/pub/FreeBSD/ports/distfiles/ fetch</userinput></screen> - - </listitem> - - <listitem> - <para>Q. I want to know what files make is going to need before - it tries to pull them down.</para> - - <para>A. <command>make fetch-list</command> will display a list of the files - needed for a port.</para> - </listitem> - - <listitem> - <para>Q. Is there any way to stop the port from compiling? I - want to do some hacking on the source before I install it, but - it is a bit tiresome having to watch it and hit control-C - every time.</para> - - <para>A. Doing <command>make extract</command> will stop it after it has fetched - and extracted the source code.</para> - </listitem> - - <listitem> - <para>Q. I am trying to make my own port and I want to be able - to stop it compiling until I have had a chance to see if my - patches worked properly. Is there something like <command>make - extract</command>, but for patches?</para> - - <para>A. Yep, <command>make patch</command> is what you want. You will probably - find the <makevar>PATCH_DEBUG</makevar> option useful as well. And by the way, - thank you for your efforts!</para> - </listitem> - - <listitem> - <para>Q. I have heard that some compiler options can cause bugs. - Is this true? How can I make sure that I compile ports with - the right settings?</para> - - <para>A. Yes, with version 2.6.3 of <command>gcc</command> (the version shipped - with FreeBSD 2.1.0 and 2.1.5), the <option>-O2</option> option could result in - buggy code unless you used the <option>-fno-strength-reduce</option> option as - well. (Most of the ports don't use <option>-O2</option>). You - <emphasis>should</emphasis> be able to specify the compiler - options used by something like</para> - - - <screen>&prompt.root; <userinput>make CFLAGS='-O2 -fno-strength-reduce' install</userinput></screen> - - - <para>or by editing <filename>/etc/make.conf</filename>, but - unfortunately not all ports respect this. The surest way is to - do <command>make configure</command>, then go into the source directory and - inspect the Makefiles by hand, but this can get tedious if the - source has lots of sub-directories, each with their own - Makefiles.</para> - </listitem> - - <listitem> - <para>Q. There are so many ports it is hard to find the one I - want. Is there a list anywhere of what ports are available?</para> - - <para>A. Look in the <filename>INDEX</filename> file in - <filename>/usr/ports</filename>. If you would like to search the - ports collection for a keyword, you can do that too. For example, - you can find ports relevant to the LISP programming language - using:</para> - - - <screen>&prompt.user; <userinput>cd /usr/ports</userinput> -&prompt.user; <userinput>make search key=lisp</userinput></screen> - - </listitem> - - <listitem> - <para>Q. I went to install the <literal>foo</literal> port but the system - suddenly stopped compiling it and starting compiling the - <literal>bar</literal> - port. What's going on?</para> - - <para>A. The <literal>foo</literal> port needs something that is supplied with - <literal>bar</literal> — for instance, if <literal>foo</literal> uses graphics, <literal>bar</literal> might have - a library with useful graphics processing routines. Or <literal>bar</literal> - might be a tool that is needed to compile the <literal>foo</literal> - port.</para> - </listitem> - - <listitem> - <para><anchor id="ports-remove"> Q. I installed the <literal>grizzle</literal> - program from the ports and frankly it is a complete waste of - disk space. I want to delete it but I do not know where it put - all the files. Any clues?</para> - - <para>A. No problem, just do</para> - - - <screen>&prompt.root; <userinput>pkg_delete grizzle-6.5</userinput></screen> - - </listitem> - - <listitem> - <para> - Q. Hang on a minute, you have to know the version number to - use that command. You do not seriously expect me to remember - that, do you??</para> - - <para>A. Not at all, you can find it out by doing</para> - - - <screen>&prompt.root; <userinput>pkg_info -a | grep grizzle</userinput> -Information for grizzle-6.5: -grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arcade game.</screen> - - </listitem> - - <listitem> - <para>Q. Talking of disk space, the ports directory seems to be - taking up an awful lot of room. Is it safe to go in there and - delete things?</para> - - <para>A. Yes, if you have installed the program and are fairly - certain you will not need the source again, there is no point - in keeping it hanging around. The best way to do this - is</para> - - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make clean</userinput></screen> - - - <para>which will go through all the ports subdirectories and - delete everything except the skeletons for each port.</para> - </listitem> - - <listitem> - <para>Q. I tried that and it still left all those tarballs or - whatever you called them in the <filename>distfiles</filename> - directory. Can I delete those as well?</para> - - <para>A. Yes, if you are sure you have finished with them, those - can go as well.</para> - </listitem> - - <listitem> - <para>Q. I like having lots and lots of programs to play with. - Is there any way of installing all the ports in one go?</para> - - <para>A. Just do</para> - - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make install</userinput></screen> - - </listitem> - - <listitem> - <para>Q. OK, I tried that, but I thought it would take a very - long time so I went to bed and left it to get on with it. When - I looked at the computer this morning, it had only done three - and a half ports. Did something go wrong?</para> - - <para>A. No, the problem is that some of the ports need to ask - you questions that we cannot answer for you (eg “Do you want - to print on A4 or US letter sized paper?”) and they need to - have someone on hand to answer them.</para> - </listitem> - - <listitem> - <para>Q. I really do not want to spend all day staring at the - monitor. Any better ideas?</para> - - <para>A. OK, do this before you go to bed/work/the local - park:-</para> - - - <screen>&prompt.root <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make -DBATCH install</userinput></screen> - - - <para>This will install every port that does - <emphasis>not</emphasis> require user input. Then, when you - come back, do</para> - - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make -DIS_INTERACTIVE install</userinput></screen> - - - <para>to finish the job.</para> - </listitem> - - <listitem> - <para>Q. At work, we are using <literal>frobble</literal>, which is in your ports - collection, but we have altered it quite a bit to get it to do - what we need. Is there any way of making our own packages, so - we can distribute it more easily around our sites?</para> - - <para>A. No problem, assuming you know how to make patches for - your changes:-</para> - - - <screen>&prompt.root; <userinput>cd /usr/ports/somewhere/frobble</userinput> -&prompt.root; <userinput>make extract</userinput> -&prompt.root; <userinput>cd work/frobble-2.8</userinput> -[Apply your patches] -&prompt.root; <userinput>cd ../..</userinput> -&prompt.root; <userinput>make package</userinput></screen> - - </listitem> - - <listitem> - <para>Q. This ports stuff is really clever. I am desperate to - find out how you did it. What is the secret?</para> - - <para>A. Nothing secret about it at all, just look at the - <filename>bsd.ports.mk</filename> and - <filename>bsd.ports.subdir.mk</filename> files in your <ulink - URL="file://localhost/usr/share/mk/">makefiles - directory.</ulink></para> - - <note> - <para>Readers with an aversion to intricate shell-scripts are - advised not to follow this link...)</para> - </note> - </listitem> - - </itemizedlist> - - - - </sect1> - - <sect1 id="porting"> - <title>Making a port yourself</title> - - <para><emphasis>Contributed by &a.jkh;, &a.gpalmer;, &a.asami; - &a.obrien; and &a.hoek;. 28 August 1996.</emphasis></para> - - <para>So, now you are interested in making your own port? - Great!</para> - - <para>What follows are some guidelines for creating a new port for - FreeBSD. The bulk of the work is done by - <filename>/usr/share/mk/bsd.port.mk</filename>, which all port - Makefiles include. Please refer to that file for more details on - the inner workings of the ports collection. Even if you don't - hack Makefiles daily, it is well commented, and you will still - gain much knowledge from it.</para> - - <note> - <para>Only a fraction of the overridable variables - (<makevar><replaceable>VAR</replaceable></makevar>) are mentioned - in this document. Most (if not all) are documented at the start of - <filename>bsd.port.mk</filename>. This file users a non-standard - tab setting. <application>Emacs</application> and - <application>Vim</application> should recognise the setting on - loading the file. <command>vi</command> or <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> - - <sect2> - <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> - - <sect3> - <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 -# Version required: 1.1b -# Date created: 5 December 1994 -# Whom: asami -# -# $Id$ -# - -DISTNAME= oneko-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>$Id$</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> - - </sect3> - - <sect3> - <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>COMMENT</filename>, - <filename>DESCR</filename>, and <filename>PLIST</filename>, - and reside in the <filename>pkg</filename> - subdirectory.</para> - - - <sect4> - <title><filename>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. Here is - an example:</para> - - <programlisting> -A cat chasing a mouse all over the screen.</programlisting> - - </sect4> - - <sect4> - <title><filename>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.</para> - </note> - - <para>It is recommended that you sign the 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.) - -http://www.oneko.org/ - -- Satoshi -asami@cs.berkeley.edu</programlisting> - - </sect4> - - <sect4> - <title><filename>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 <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> 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 installtion, 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> - </note> - </sect4> - </sect3> - - <sect3> - <title>Creating the checksum file</title> - - <para>Just type <command>make makesum</command>. - The ports make rules will automatically generate the file - <filename>files/md5</filename>.</para> - - </sect3> - - <sect3 id="porting-testing"> - <title>Testing the port</title> - - <para>You should make sure that the port rules do exactly what - you want it to do, including packaging up the port. These are - the important points you need to verify.</para> - - <itemizedlist> - <listitem> - <para><filename>PLIST</filename> does not contain anything not - installed by your port</para> - </listitem> - - <listitem> - <para><filename>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 `make package-name`</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 aren't 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 is works - correctly when installed from a package.</para> - </sect3> - - <sect3 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, your 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> - </sect3> - - <sect3 id="porting-submitting"> - <title>Submitting the port</title> - - <para>First, make sure you have read the <link - linkend="porting-dads">Do's and Dont's</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 - <citerefentry> - <refentrytitle>send-pr</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry> program (see <link linkend="contrib-general">Bug - Reports and General Commentary</link> for more information - about <citerefentry> - <refentrytitle>send-pr</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry>. If the uncompressed port is larger than - 20KB, you should compress it into a tarfile and use <citerefentry> - <refentrytitle>uuencode</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry> 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>!)</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 that - <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” on the FreeBSD Handbook and other files. - Isn't that great?!? <!-- smiley -->:)</para> - - </sect3> - </sect2> - - <sect2> - <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> - - - <sect3> - <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, and 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 patches are found in <makevar>PATCHDIR</makevar> (defaults to the - <filename>patches</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> - - </sect3> - - <sect3> - <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 - (if you are a FreeBSD committer, you can just put it in your - <filename>public_html/</filename> directory on - <hostid>freefall</hostid>), - we can “house” it ourselves by putting - it on <filename>ftp://ftp.freebsd.org/pub/FreeBSD/ports/distfiles/LOCAL_PORTS/</filename> as the last resort. Please refer to this - location as <makevar>MASTER_SITE_LOCAL</makevar>. Send mail to - the &a.ports;if you are not sure what to do.</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 isonly 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> - - </sect3> - - <sect3> - <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> - </sect3> - - <sect3> - <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>xx</replaceable></filename> where - <replaceable>xx</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. 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> - - </sect3> - - <sect3> - <title>Configuring</title> - - <para>Include any additional customization commands to your - <filename>configure</filename> script and save it in the - <filename>scripts</filename> subdirectory. As mentioned - above, you can also do this as <filename>Makefile</filename> - targets and/or scripts with the name - <filename>pre-configure</filename> or - <filename>post-configure</filename>.</para> - - </sect3> - - <sect3> - <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> - </sect3> - </sect2> - - <sect2> - <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> - - - <sect3> - <title>The original source</title> - - <para>Does it live in <makevar>DISTDIR</makevar> as a standard gzip'd - tarball? If so, you can go on to the next step. If not, you - should look at overriding any of the <makevar>EXTRACT_CMD</makevar>, <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 compress, not - gzip.)</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> - - </sect3> - - <sect3> - <title><makevar>DISTNAME</makevar></title> - - <para>You should set <makevar>DISTNAME</makevar> to be the base name of - your port. The default rules expect the distribution file - list (<makevar>DISTFILES</makevar>) to be - named <makevar>DISTNAME</makevar><makevar>EXTRACT_SUFX</makevar> which, if it is a normal tarball, is going to be - something like <literal>foozolix-1.0.tar.gz</literal> for a setting of <literal>DISTNAME=foozolix-1.0</literal>.</para> - - <para>The default rules also expect the tarball(s) to extract - into a subdirectory called - <filename>work/<makevar>DISTNAME</makevar></filename>, e.g. <filename>work/foozolix-1.0/</filename>.</para> - - <para>All this behavior can be overridden, of course; it simply - represents the most common time-saving defaults. For a port - requiring multiple distribution files, simply set <makevar>DISTFILES</makevar> explicitly. If only a - subset of <makevar>DISTFILES</makevar> are - actual extractable archives, then set them up in <makevar>EXTRACT_ONLY</makevar>, which will override - the <makevar>DISTFILES</makevar> list when - it comes to extraction, and the rest will be just left in - <makevar>DISTDIR</makevar> for later - use.</para> - - </sect3> - - <sect3> - <title><makevar>PKGNAME</makevar></title> - - <para>If <makevar>DISTNAME</makevar> does not conform to our <link - linkend="porting-pkgname">guidelines for a good package - name</link>, you should set the <makevar>PKGNAME</makevar> - variable to something better. See the abovementioned guidelines - for more details.</para> - </sect3> - - <sect3> - <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 you 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> - - <note> - <para>There is no error checking for category - names. <command>make package</command> will happily create a - new directory if you mustype the category name, so be - careful!</para> - </note> - </sect3> - - <sect3> - <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 following - popular archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or - Linux Sunsite, you refer to those sites in an easy compact - form using <makevar>MASTER_SITE_XCONTRIB</makevar>, <makevar>MASTER_SITE_GNU</makevar>, - <makevar>MASTER_SITE_PERL_CPAN</makevar>, <makevar>MASTER_SITE_TEX_CTAN</makevar>, and - <makevar>MASTER_SITE_SUNSITE</makevar>. Simply set <makevar>MASTER_SITE_SUBDIR</makevar> to the - path with in the archive. Here is an example:</para> - - <programlisting> -MASTER_SITES= ${MASTER_SITE_XCONTRIB} -MASTER_SITE_SUBDIR= applications</programlisting> - - <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> - - </sect3> - - <sect3 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>WKRSRC</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 can't 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, from - the <maketarget>pre-patch</maketarget> target, apply the - patch either by running the patch command from there, or - copying the patch file into the <makevar>PATCHDIR</makevar> directory and calling it - <filename>patch-<replaceable>xx</replaceable></filename>.</para> - - <note> - <para>Note 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> - - </sect3> - - <sect3> - <title><makevar>MAINTAINER</makevar></title> - - <para>Set your mail-address here. Please. <!-- smiley --><emphasis>:)</emphasis></para> - - <para>For detailed description of the responsibility of - maintainers, refer to <link - linkend="policies-maintainer">MAINTAINER - on Makefiles</link> section.</para> - - </sect3> - - <sect3> - <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> - - - <sect4> - <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, - and <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 reqular 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 in to the package so that - <command>pkg_add</command> will automatically install it if it - is not on the user's system.</para> - - </sect4> - - <sect4> - <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, and <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, - - <programlisting> -RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \ - wish8.0:${PORTSDIR}/x11-toolkits/tk80</programlisting> - - 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 <makevar>DEPENDS_TARGET</makevar>.</para> - - </sect4> - - <sect4> - <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 extracting 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> - </sect4> - - <sect4> - <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> - - </sect4> - - <sect4> - <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 to have - the source of the other port extracted in addition to having - them 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> - </sect4> - - <sect4> - <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 has perl5 as part of the base system - while others don't.)</para> - </sect4> - - <sect4> - <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; is 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, it is customary - to use the string <literal>nonexistent</literal> 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 be always build (and installed, by - default), and the dependency will go into the packages as - well. If this is really what you need, I recommend you - write it as <literal>BUILD_DEPENDS</literal> and - <literal>RUN_DEPENDS</literal> instead—at least the - intention will be clear.</para> - </sect4> - </sect3> - - <sect3> - <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> - </sect3> - </sect2> - - <sect2> - <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> - - <sect3> - <title><command>ldconfig</command></title> - - <para>If your port installs a shared library, add a - <maketarget>post-install</maketarget> target to your - <filename>Makefile</filename> that runs - <literal>${LDCONFIG} -m</literal> on the directory where - the new library is installed (usually - <filename><makevar>PREFIX</makevar>/lib</filename>) to register - it into the shared library cache.</para> - - <para>Also, add a matching <literal>@exec /sbin/ldconfig - -m</literal> and <literal>@unexec /sbin/ldconfig -R</literal> - pair to your <filename>pkg/PLIST</filename> file so that a user - who installed the package can start using teh shared libraru - immediately and deinstallation will not cause the system to - still believe the library is there. These lines should - immediately follow the line for the shared library itself, as - in:</para> - - <programlisting> -lib/libtvl80.so.1 -@exec /sbin/ldconfig -m %D/lib -@unexec /sbin/ldconfig -R</programlisting> - - <para>Never, ever, <emphasis>ever</emphasis> add a line that says - <literal>ldconfig</literal> without any arguments to your - <filename>Makefile</filename> or - <filename>pkg/PLIST</filename>. This will reset the shared - libraru cache to the contents of <filename>/usr/lib</filename> - only, and will royally screw up the user's machine ("Help, xinit - does not run anymore after I install this port!"). Anybody who - does this will be shot and cut in 65,536 pieces by a rusty knife - and have is liver chopped out by a bunch of crows and will - eternally rot to death in the deepest bowels of hell (not - necessarily in that order…)</para> - </sect3> - </sect2> - - <sect2> - <title>ELF support</title> - - <para>Since FreeBSD is moving to ELF 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 that there will - be one more release (2.2.8) from the 2.2 branch. 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 awhile for reference - in case you have come across some old port you wish to - upgrade.</para> - - <sect3> - <title>Moving a.out libraries out of the way</title> - - <para>A.out libraries should be moved out of - <filename>/usr/local/lib</filename> and similar to an - <filename>aout</filename> subdirectory. (If you don't move them - out of the way, ELF ports will happily overwrite a.out libraries.) - The <maketarget>move-aout-libs</maketarget> target in the -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> - </sect3> - - <sect3> - <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> - </sect3> - - <sect3> - <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 -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> - </sect3> - - <sect3> - <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>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> - </sect3> - - <sect3> - <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> - </sect3> - - <sect3> - <title><filename>PLIST</filename></title> - - <para><filename>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>PLIST</filename> mentioned in the previous - paragraph.</para> - </sect3> - - <sect3> - <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>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> - </sect3> - </sect2> - - <sect2 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 forusers 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>PKGNAME</makevar></link> - so the packages will have different names.</para> - - <para>This will be best demonstrated by an example. This is part of - <filename>japanese/xdvi300/Makefile</filename>;</para> - - <programlisting> -PKGNAME= ja-xdvi${RESOLUTION}-17 - : -# 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 refulat set of - subdirectories like <makevar>PATCHDIR</makevar> and - <makevar>PKGDIR</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> - </sect2> - - <sect2> - <title>Shared library versions</title> - - <para>First, please read our <link linkend="policies-shlib">policy - on shared library versioning</link> to understand - what to do with 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.0?). - 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> - </sect2> - - <sect2 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>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>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 don't 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 -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> - </sect2> - - <sect2> - <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> - - <sect3> - <title><makevar>REQUIRES_MOTIF</makevar></title> - - <para>If your port requires Motif, define this variable in the - Makefile. This will prevent people who don't own a copy of - Motif from even attempting to build it.</para> - </sect3> - - <sect3> - <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> - </sect3> - </sect2> - - <sect2> - <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> - </sect2> - - <sect2> - <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 this - 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>. I will use - <filename>editors/emacs</filename> 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 don't 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. I do not think this is 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>PLIST</filename>; see below). However, if you - have a Japanese (or other multibyte encoding) info files, - you will have to use the extra arguments to <command>install-info</command> because <command>makeinfo</command> can't handle those texinfo - sources. (See <filename>Makefile</filename> and - <filename>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 don't include correct - dependencies for info files. In <command>emacs</command>' case, I had to - patch the main <filename>Makefile.in</filename> so it will - 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>. I also deleted the installation - of the <filename>info</filename> info file - 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 PLIST ---- PLIST 1997/03/04 08:04:00 1.15 -+++ 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 create a - <filename>dir</filename> file if it is not there. Also, - call <maketarget>install-info</maketarget> with the - installed info files.</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,11 @@ - post-install: - .for file in emacs-19.34 emacsclient etags ctags b2m - strip ${PREFIX}/bin/${file} - .endfor -+ if [ ! -f ${PREFIX}/info/dir ]; then \ -+ ${SED} -ne '1,/Menu:/p' /usr/share/info/dir > ${PREFIX}/info/dir; \ -+ fi -+.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> - - <para>Do not use anything other than - <filename>/usr/share/info/dir</filename> and the above - command to create a new info file. In fact, I'd add the - first three lines of the above patch to - <filename>bsd.port.mk</filename> if you (the porter) - wouldn't have to do it in <filename>PLIST</filename> by - yourself anyway.</para> - </step> - - <step> - <para>Edit <filename>PLIST</filename> and add equivalent - <literal>@exec</literal> statements and also - <literal>@unexec</literal> for <command>pkg_delete</command>. - You do not need to delete <filename>info/dir</filename> - with <literal>@unexec</literal>.</para> - - <programlisting> -Index: pkg/PLIST -=================================================================== -RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v -retrieving revision 1.15 -diff -u -r1.15 PLIST ---- PLIST 1997/03/04 08:04:00 1.15 -+++ PLIST 1997/05/20 10:25:12 1.17 -@@ -16,7 +14,15 @@ - 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 [ -f %D/info/dir ] || sed -ne '1,/Menu:/p' /usr/share/info/dir > %D/info/dir -+@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> - - </sect2> - - <sect2> - <title>The <filename>pkg/</filename> subdirectory</title> - - <para>There are some tricks we haven't mentioned yet about the - <filename>pkg/</filename> subdirectory that come in handy - sometimes.</para> - - <sect3 id="porting-message"> - <title><filename>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> - </sect3> - - <sect3> - <title><filename>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 will as - <literal>INSTALL ${PKGNAME} PRE-INSTALL</literal> and the - second time as <literal>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 <citerefentry> - <refentrytitle>pkg_add</refentrytitle> - <manvolnum>1</manvolnum></citerefentry> 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> - </sect3> - - <sect3> - <title><filename>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> - </sect3> - - <sect3 id="porting-plist"> - <title>Changing <filename>PLIST</filename> based on make variables</title> - - <para>Some ports, particularly the p5- ports, need to change their - <filename>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>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>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>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>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> - </sect3> - - <sect3> - <title id="porting-pkgsubdir">Changing the names of files in the - <filename>pkg</filename> subdirectory</title> - - <para>All the filenames in the <filename>pkg</filename> subdirectory - 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</filename> subdirectory 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</filename> - subdirectory.</para> - - <para>Here is a list of variable names and their default - values.</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}/DESCR</literal></entry> - </row> - - <row> - <entry><makevar>DESCR</makevar></entry> - <entry><literal>${PKGDIR}/DESCR</literal></entry> - </row> - - <row> - <entry><makevar>PLIST</makevar></entry> - <entry><literal>${PKGDIR}/PLIST</literal></entry> - </row> - - <row> - <entry><makevar>PKGINSTALL</makevar></entry> - <entry><literal>${PKGDIR}/PKGINSTALL</literal></entry> - </row> - - <row> - <entry><makevar>PKGDEINSTALL</makevar></entry> - <entry><literal>${PKGDIR}/PKGDEINSTALL</literal></entry> - </row> - - <row> - <entry><makevar>PKGREQ</makevar></entry> - <entry><literal>${PKGDIR}/REQ</literal></entry> - </row> - - <row> - <entry><makevar>PKGMESSAGE</makevar></entry> - <entry><literal>${PKGDIR}/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> - </sect3> - </sect2> - - <sect2> - <title>Licensing Problems</title> - - <para>Some software packages have restrictive licenses or can be - in violation to the law (PKP's patent on public key crypto, ITAR - (export of crypto software) to name just two of them). 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 of 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 won't 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 can't 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 won't 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., crypto 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> - </sect2> - - <sect2> - <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-current</filename> directory of the ftp mirror - sites.</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 isn't - 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 to <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry> - (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 as is in - the PR.</para> - - </sect2> - - <sect2> - <title><anchor id="porting-dads">Do's and Dont's</title> - - <para>Here is a list of common do's and dont's 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 <link linkend="contrib-general">Bug - Reports and General Commentary</link>. 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> - - <sect3> - <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 <citerefentry> - <refentrytitle>file</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry> 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> - </sect3> - - <sect3> - <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. They are:</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 doesn't 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> - </sect3> - - <sect3 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 - <link linkend="ports-cd">compiling ports from CDROM</link> for an - example of building ports from a read-only tree). If you need to - modigy some file in <makevar>PKGDIR</makevar>, do so by <link - linkend="porting-pkgsubdir">redefining a variable</link>, not by - writing over it.</para> - </sect3> - - <sect3> - <title><makevar>WRKDIRPREFIX</makevar></title> - - <para>Make sure your port honors - <makevar>WRKDIRPREFIX</makevar>. Most ports don't 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>${WKRDIRPREFIX}${.CURDIR}</literal> in the - front.</para> - </sect3> - - <sect3 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 - doesn't, 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>Don't 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-currents</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>4.0-current after 3/4 branch</entry> - <entry>400000</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 don't have to worry about old -current's; 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> - </sect3> - - <sect3> - <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; don't 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> - </sect3> - - <sect3> - <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>PKGNAME</makevar> minus the version part. - 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>Also you can 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>MESSAGE</filename> does not need to be added - to <filename>pkg/PLIST</filename>).</para> - </note> - </sect3> - - <sect3> - <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 (<makevar>PKGNAME</makevar> without the - version part 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> - </sect3> - - <sect3> - <title>Package information</title> - - <para>Do include package information, i.e. - <filename>COMMENT</filename>, <filename>DESCR</filename>, and - <filename>PLIST</filename>, in <filename>pkg</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> - </sect3> - - <sect3> - <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> - - </sect3> - - <sect3> - <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 don't 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 - diffsof <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> - - </sect3> - - <sect3 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>Do not set <makevar>USE_X_PREFIX</makevar> unless your port - truly require 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> - - </sect3> - - <sect3> - <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 <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry> 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> - - </sect3> - - <sect3 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/pixmals -@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> - </sect3> - - - <sect3> - <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 a binarypackage as when it was compiled, then you mus - 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 don't 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</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> - - </sect3> - - <sect3> - <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> - </sect3> - - <sect3> - <title>Respect <makevar>CFLAGS</makevar></title> - - <para>The port should respect the <makevar>CFLAGS</makevar> - variable. If it doesn't, please add <literal>NO_PACKAGE=ignores - cflags</literal> to the <filename>Makefile</filename>.</para> - </sect3> - - <sect3> - <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> - </sect3> - - <sect3> - <title>Portlint</title> - - <para>Do check your work with <link - linkend="porting-portlint"><command>portlint</command></link> - before you submit or commit it.</para> - </sect3> - - <sect3> - <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> - </sect3> - - <sect3> - <title>Miscellanea</title> - - <para>The files <filename>pkg/DESCR</filename>, - <filename>pkg/COMMENT</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>Don't copy more copies of the GNU General Public License into - our system, please.</para> - - <para>Please be careful to note any legal issues! Don't let us - illegally distribute software!</para> - </sect3> - - <sect3> - <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> - - </sect3> - </sect2> - - <sect2 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 header should updated when upgrading a port.] -# Version required: pl18 [things like "1.5alpha" are fine here too] -[this is the date when the first version of this Makefile was created. -Never change this when doing an update of the port.] -# Date created: 26 May 1995 -[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> -# -# $Id$ -[ ^^^^ This will be automatically replaced with RCS ID string by CVS -when it is committed to our repository.] -# - -[section to describe the port itself and the master site - DISTNAME - is always first, followed by PKGNAME (if necessary), CATEGORIES, - and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR. - After those, one of EXTRACT_SUFX or DISTFILES can be specified too.] -DISTNAME= xdvi -PKGNAME= xdvi-pl18 -CATEGORIES= print -[do not forget the trailing slash ("/")! - if you aren't using MASTER_SITE_* macros] -MASTER_SITES= ${MASTER_SITE_XCONTRIB} -MASTER_SITE_SUBDIR= applications -[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) who 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> - - </sect2> - - <sect2 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>language-</replaceable>name<replaceable>-compiled.specifics</replaceable><replaceable>-version.numbers</replaceable></filename>.</para> - - <para>If your <makevar>DISTNAME</makevar> - doesn't look like that, set <makevar>PKGNAME</makevar> to something in 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> - </listitem> - - <listitem> - <para>The <filename>name</filename> part - should be all lowercases, except for a really large - package (with lots of programs in it). Things like - XFree86 (yes there really is a port of it, check it - out) and ImageMagick fall into this category. Otherwise, - convert the name (or at least the first letter) to - lowercase. If the capital letters are - important to the name (for example, with one-letter names - like <literal>R</literal> or <literal>V</literal>) you may use capital letters at your discretion. - 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> - </listitem> - - <listitem> - <para>The version string should be a period-separated list - of integers and single lowercase alphabetics. The only - exception is the string <literal>pl</literal> (meaning `patchlevel'), which - can be used <emphasis>only</emphasis> when there are no - major and minor version numbers in the software.</para> - </listitem> - - </orderedlist> - - - <para>Here are some (real) examples on how to convert a <makevar>DISTNAME</makevar> into a suitable <makevar>PKGNAME</makevar>:</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>Distribution Name</entry> - <entry>Package Name</entry> - <entry>Reason</entry> - </row> - </thead> - - <tbody> - <row> - <entry>mule-2.2.2.</entry> - <entry>mule-2.2.2</entry> - <entry>No changes required</entry> - </row> - - <row> - <entry>XFree86-3.1.2</entry> - <entry>XFree86-3.1.2</entry> - <entry>No changes required</entry> - </row> - - <row> - <entry>EmiClock-1.0.2</entry> - <entry>emiclock-1.0.2</entry> - <entry>No uppercase names for single programs</entry> - </row> - - <row> - <entry>gmod1.4</entry> - <entry>gmod-1.4</entry> - <entry>Need a hyphen before version numbers</entry> - </row> - - <row> - <entry>xmris.4.0.2</entry> - <entry>xmris-4.0.2</entry> - <entry>Need a hyphen before version numbers</entry> - </row> - - <row> - <entry>rdist-1.3alpha</entry> - <entry>rdist-1.3a</entry> - <entry>No strings like <literal>alpha</literal> - allowed</entry> - </row> - - <row> - <entry>es-0.9-beta1</entry> - <entry>es-0.9b1</entry> - <entry>No strings like <literal>beta</literal> - allowed</entry> - </row> - - <row> - <entry>v3.3beta021.src</entry> - <entry>tiff-3.3</entry> - <entry>What the heck was that anyway?</entry> - </row> - - <row> - <entry>tvtwm</entry> - <entry>tvtwm-pl11</entry> - <entry>Version string always required</entry> - </row> - - <row> - <entry>piewm</entry> - <entry>piewm-1.0</entry> - <entry>Version string always required</entry> - </row> - - <row> - <entry>xvgr-2.10pl1</entry> - <entry>xvgr-2.10.1</entry> - <entry><literal>pl</literal> allowed only when no - major/minor version numbers</entry> - </row> - - <row> - <entry>gawk-2.15.6</entry> - <entry>ja-gawk-2.15.6</entry> - <entry>Japanese language version</entry> - </row> - - <row> - <entry>psutils-1.13</entry> - <entry>psutils-letter-1.13</entry> - <entry>Papersize hardcoded at package build time</entry> - </row> - - <row> - <entry>pkfonts</entry> - <entry>pkfonts300-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>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) as the - version.</para> - - </sect2> - - <sect2 id="porting-categories"> - <title>Categories</title> - - <para>As you already know, ports are classified in several - categories. But for this to wor, it is important that porters and - users understand what each category and how we deicde what to put in - each category.</para> - - <sect3> - <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 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 don't - belong to anywhere else, they shouldn't 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>games</filename></entry> - <entry>Games.</entry> - </row> - - <row> - <entry><filename>german</filename></entry> - <entry>German language support.</entry> - </row> - - <row> - <entry><filename>graphics</filename></entry> - <entry>Graphics utilities.</entry> - </row> - - <row> - <entry><filename>japanese</filename></entry> - <entry>Japanese language support.</entry> - </row> - - <row> - <entry><filename>kde*</filename></entry> - <entry>Ports that form the K Desktop Environment - (kde).</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>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 - doesn't belong to 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>russian</filename></entry> - <entry>Russian language support.</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>tcl75*</filename></entry> - <entry>Ports that use tcl version 7.5 to run.</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>textproc</filename></entry> - <entry>Text processing utilities. It does not include - desktop publishing tools, which go to print/.</entry> - </row> - - <row> - <entry><filename>tk41*</filename></entry> - <entry>Ports that use tk version 4.1 to run.</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>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 belong here too.</entry> - </row> - - <row> - <entry>x11</entry> - <entry>The X window system and friends. This category is - only for software that directly support 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 - 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-toolkits</filename></entry> - <entry>X11 toolkits.</entry> - </row> - - <row> - <entry><filename>x11-wm</filename></entry> - <entry>X11 window managers.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect3> - - <sect3> - <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 usse. Here is the - list of priorities, in decreasing order of precedence.</para> - - <itemizedlist> - <listitem> - <para>Language specific categories alwasys come first. For - example, if your port installs Japanese X11 fonts, then your - <makevar>CATEGORIES</makevar> line would read - <literal>japanese x11</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 don't - need to list <literal>net</literal> when the port belongs to - either of <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>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 import it. (If you are a committer, send a - note &a.ports; so we can discuss it first—too often new - ports are imported to a wrong category only to be moved right - away.)</para> - </sect3> - </sect2> - - <sect2> - <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/src/share/mk/bsd.port.mk"> - the bsd.port.mk CVS log</ulink>.</para> - </sect2> - - <sect2> - <title>That is It, Folks!</title> - - <para>Boy, this sure was a long tutorial, wasn't it? Thanks for - following us to here, really.</para> - - <para>Well, now that you know how to do a port, let us go 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> - - </sect2> - </sect1> - - </chapter> - - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - |