From 69d3531da9a25db69b157d79c43d2f5fa65f0958 Mon Sep 17 00:00:00 2001 From: Nik Clayton Date: Tue, 9 May 2000 00:26:12 +0000 Subject: [PATCH] [ Once more, but this time, with feeling. Oh, "Hello Paul" :-) ] Welcome to the porter's handbook, based on section 4.4 from the Handbook. To do this for your language, checkout a copy of the docs, and: cd doc//books/ mkdir porter-handbook cd porter-handbook cp ../handbook/ports/chapter.sgml book.sgml Now edit book.sgml. Add the following just after the comment at the top of the file (and before the element (everything between the two '===') === %man; %bookinfo; %authors; %mailing-lists; ]> FreeBSD Porter's Handbook The FreeBSD Documentation Project
doc@@FreeBSD.org
April 2000 2000 &bookinfo.legalnotice; == Delete all the text from to *and* the for that section. You should be left with <sect2> <title>Making a port yourself ... (obviously, translated to your language). Next, do a search and replace of the various sectional elements, replacing them with the element two-up in the hierarchy. In other words, sect2 becomes chapter sect3 becomes sect1 sect4 becomes sect2 There's nothing below in that document. Go to the bottom of the file, you'll see Delete the last two lines, and add a "" to close off the content properly. Finally, in the comment section at the end delete the sgml-declaration: "../chapter.decl" and sgml-parent-document: ("../book.sgml" "part" "chapter") lines. Finally, copy over the "Makefile" and "freebsd.dsl" file from the English directory. You will need to translate the two lines of text in freebsd.dsl Once you've done that your copy of the file will be the same as the one I committed as version 1.1 in the English directory. This file won't build cleanly. This is because there are still some s and s which point back to chapters in the Handbook. We'll clean those up shortly. When that's done, and the doc is linked in to the website we can remove the text from the main Handbook. We're also sharing some entity files with the Handbook as well. At the moment those are SYSTEM entities pointing back to the Handbook copies. I'm going to shift them in to doc/share/sgml/, with the other language independent entities. Oh, and the structure needs looking at. Some of the things that are chapters now could probably be sections inside another chapter. This is why I haven't changed the indentation yet, as it'll only change as we sort out the structure. --- .../books/porters-handbook/book.sgml | 1406 +++-------------- .../books/porters-handbook/book.sgml | 1406 +++-------------- 2 files changed, 452 insertions(+), 2360 deletions(-) diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml index a269a7c635..618a360a07 100644 --- a/en_US.ISO8859-1/books/porters-handbook/book.sgml +++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml @@ -1,994 +1,48 @@ - - Installing Applications: The Ports collection - - Rewritten by &a.jim;, 22 November 1999. Original work - by various people. - - - Synopsis - - The FreeBSD Ports collection allows you to compile and install a - very wide range of applications with a minimum amount of - effort. - - In general, it is a group of skeletons - which contain a minimal set of items needed to make an application - compile and install cleanly on FreeBSD. - - Even with all the hype about open standards, getting a program - to compile on various UNIX platforms can be a tricky task. - Occasionally, you might be lucky enough to find that the program you - want compiles cleanly on your system, install everything into all - the right directories, and run flawlessly - “out-of-the-box”, but this behavior is somewhat rare. - Most of the time, you find yourself needing to make modifications in - order to get the program to work. This is where the FreeBSD Ports - collection comes to the rescue. - - The general idea behind the Ports collection is to eliminate all - of the messy steps involved with making things work properly so that - the installation is simple and very painless. With the Ports - collection, all of the hard work has already been done for you, and - you are able to install any of the Ports collection ports by simply - typing make install. - - - - Using the Ports Collection - - The following sections provide basic instructions on using the - ports collection to install or remove programs from your - system. - - - Installing Ports - - The first thing that should be explained - when it comes to the Ports collection is what is actually meant - by a “skeleton”. In a nutshell, a port skeleton is a - minimal set of files that are needed for a program to compile and - install cleanly on FreeBSD. Each port skeleton includes: - - - - A Makefile. The - Makefile contains various statements that - specify how the application should be compiled and where it - should be installed on your system - - - - A files directory. The - files directory contains a file named - md5. This file is named after the MD5 - algorithm used to determine ports checksums. A checksum is a - number generated by adding up all the data in the file you - want to check. If any characters change, the checksum will - differ from the original and an error message will be - displayed so you are able to investigate the changes. - - The files directory can also contain - other files that are required by the port but do not belong - elsewhere in the directory structure. - - - - A patches directory. This directory - contains patches to make the program compile and install on - your FreeBSD system. Patches are basically small files that - specify changes to particular files. They are in plain text - format, and basically say “Remove line 10” or - “Change line 26 to this ...”. Patches are also - known as “diffs” because they are generated by the - diff program. - - - - A pkg directory. This directory - normally contains three files. Occasionally, there will be - more than three, but it depends on the port. Most only - require three. The files are: - - - - COMMENT. This is a one-line - description of the program. - - - - DESCR. This is a more detailed, - often multiple-line, description of the program. - - - - PLIST. This is a list of all the - files that will be installed by the port. It also tells - the ports system what files to remove upon - deinstallation. - - - - - - Now that you have enough background information to know what - the Ports collection is used for, you are ready to install your - first port. There are two ways this can be done, and each is - explained below. - - Before we get into that however, you will need to choose a - port to install. There are a few ways to do this, with the - easiest method being the ports listing on the FreeBSD - web site. You can browse through the ports listed there - or use the search function on the site. Each port also includes - a description so you can read a bit about each port before - deciding to install it. - - Another method is to use the whereis - command. To use whereis, simply type - “whereis <program you want to - install>” at the prompt, and if it is found on - your system, you will be told where it is, like so: - - &prompt.root; whereis xchat -xchat: /usr/ports/irc/xchat -&prompt.root; - - This tells us that xchat (an irc client) can be found in the - /usr/ports/irc/xchat directory. - - Yet another way of finding a particular port is by using the - Ports collection's built-in search mechanism. To use the search - feature, you will need to be in the - /usr/ports directory. Once in that - directory, run make search key=program-name - where “program-name” is the name of the program you - want to find. For example, if you were looking for xchat: - - &prompt.root; cd /usr/ports -&prompt.root; make search key=xchat -Port: xchat-1.3.8 -Path: /usr/ports/irc/xchat -Info: An X11 IRC client using the GTK+ toolkit, and optionally, GNOME -Maint: jim@FreeBSD.org -Index: irc -B-deps: XFree86-3.3.5 bzip2-0.9.5d gettext-0.10.35 giflib-4.1.0 glib-1.2.6 gmake-3.77 gtk-1.2.6 - imlib-1.9.8 jpeg-6b png-1.0.3 tiff-3.5.1 -R-deps: XFree86-3.3.5 gettext-0.10.35 giflib-4.1.0 glib-1.2.6 gtk-1.2.6 imlib-1.9.8 jpeg-6b - png-1.0.3 tiff-3.5.1 - - The part of the output you want to pay particular attention - to is the “Path:” line, since that tells you where to - find it. The other information provided is not needed in order - to install the port directly, so it will not be covered - here. - - - You must be the root user to install - ports. - - - Now that you have found a port you would like to install, you - are ready to do the actual installation. - - - Installing ports from a CDROM - - As you may have guessed from the title, everything - described in this section assumes you have a FreeBSD CDROM set. - If you do not, you can order one from the FreeBSD Mall. - - Assuming that your FreeBSD CDROM is in the drive and is - mounted on /cdrom (and the mount point - must be /cdrom), - you are ready to install the port. To begin, change directories - to the directory where the port you want to install lives: - - &prompt.root; cd /usr/ports/irc/xchat - - Once inside the xchat directory, you will see the port - skeleton. The next step is to compile (also called build) the - port. This is done by simply typing make at - the prompt. Once you have done so, you should see something - like this: - - &prompt.root; make ->> xchat-1.3.8.tar.bz2 doesn't seem to exist on this system. ->> Attempting to fetch from file:/cdrom/ports/distfiles/. -===> Extracting for xchat-1.3.8 ->> Checksum OK for xchat-1.3.8.tar.bz2. -===> xchat-1.3.8 depends on executable: bzip2 - found -===> xchat-1.3.8 depends on executable: gmake - found -===> xchat-1.3.8 depends on shared library: gtk12.2 - found -===> xchat-1.3.8 depends on shared library: Imlib.5 - found -===> xchat-1.3.8 depends on shared library: X11.6 - found -===> Patching for xchat-1.3.8 -===> Applying FreeBSD patches for xchat-1.3.8 -===> Configuring for xchat-1.3.8 -... -[configure output snipped] -... -===> Building for xchat-1.3.8 -... -[compilation snipped] -... -&prompt.root; - - Take notice that once the compile is complete you are - returned to your prompt. The next step is to install the - port. In order to install it, you simply need to tack one word - onto the make command, and that word is - install: - - &prompt.root; make install -===> Installing for xchat-1.3.8 -===> xchat-1.3.8 depends on shared library: gtk12.2 - found -===> xchat-1.3.8 depends on shared library: Imlib.5 - found -===> xchat-1.3.8 depends on shared library: X11.6 - found -... -[install routines snipped] -... -===> Generating temporary packing list -===> Installing xchat docs in /usr/X11R6/share/doc/xchat -===> Registering installation for xchat-1.3.8 -&prompt.root; - - Once you are returned to your prompt, you should be able to - run the application you just installed. - - - You can save an extra step by just running make - install instead of make and - make install as two separate steps. - - - - Please be aware that the licenses of a few ports do not - allow for inclusion on the CDROM. This could be for various - reasons, including things such as as registration form needs - to be filled out before downloading, if redistribution is not - allowed, and so on. If you wish to install a port not - included on the CDROM, you will need to be online in order to - do so (see the next - section). - - - - - Installing ports from the Internet - - As with the last section, this section makes an assumption - that you have a working Internet connection. If you do not, - you will need to do the CDROM - installation. - - Installing a port from the Internet is done exactly the same - way as it would be if you were installing from a CDROM. The - only difference between the two is that the program's source - code is downloaded from the Internet instead of pulled from the - CDROM. - - The steps involved are identical: - - &prompt.root; make install ->> xchat-1.3.8.tar.bz2 doesn't seem to exist on this system. ->> Attempting to fetch from http://xchat.org/files/v1.3/. -Receiving xchat-1.3.8.tar.bz2 (305543 bytes): 100% -305543 bytes transferred in 2.9 seconds (102.81 Kbytes/s) -===> Extracting for xchat-1.3.8 ->> Checksum OK for xchat-1.3.8.tar.bz2. -===> xchat-1.3.8 depends on executable: bzip2 - found -===> xchat-1.3.8 depends on executable: gmake - found -===> xchat-1.3.8 depends on shared library: gtk12.2 - found -===> xchat-1.3.8 depends on shared library: Imlib.5 - found -===> xchat-1.3.8 depends on shared library: X11.6 - found -===> Patching for xchat-1.3.8 -===> Applying FreeBSD patches for xchat-1.3.8 -===> Configuring for xchat-1.3.8 -... -[configure output snipped] -... -===> Building for xchat-1.3.8 -... -[compilation snipped] -... -===> Installing for xchat-1.3.8 -===> xchat-1.3.8 depends on shared library: gtk12.2 - found -===> xchat-1.3.8 depends on shared library: Imlib.5 - found -===> xchat-1.3.8 depends on shared library: X11.6 - found -... -[install routines snipped] -... -===> Generating temporary packing list -===> Installing xchat docs in /usr/X11R6/share/doc/xchat -===> Registering installation for xchat-1.3.8 -&prompt.root; - - As you can see, the only difference is the line that tells - you where the system is fetching the port from. - - That about does it for installing ports onto your system. - In the section you will learn how to remove a port from your - system. - - - - - Removing Installed Ports - - Now that you know how to install ports, you are probably - wondering how to remove them, just in case you install one and - later on you decide that you installed the wrong port. The next - few paragraphs will cover just that. - - Now we will remove our previous example (which was xchat for - those of you not paying attention). As with installing ports, - the first thing you must do is change to the port directory, - which if you remember was - /usr/ports/irc/xchat. After you change - directories, you are ready to uninstall xchat. This is done with - the make deinstall command (makes sense - right?): - - &prompt.root; cd /usr/ports/irc/xchat -&prompt.root; make deinstall -===> Deinstalling for xchat-1.3.8 -&prompt.root; - - That was easy enough. You have now managed to remove xchat - from your system. If you would like to reinstall it, you can do - so by running make reinstall from the - /usr/ports/irc/xchat directory. - - - - - Troubleshooting - - The following sections cover some of the more frequently asked - questions about the Ports collection and some basic troubleshooting - techniques, and what do to if a port is broken. - - - Some Questions and Answers - - - - - I thought this was going to be a discussion about - modems??! - - - - 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. - - - - - - I thought you were supposed to use packages to install - extra programs? - - - - Yes, that is usually the quickest and easiest way of - doing it. - - - - - - So why bother with ports then? - - - - Several reasons: - - - - The licensing conditions of some software - distributions forbid binary distribution. They must be - distributed as source code. - - - - 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. - - - - If you have local patches, you will need the source in - order to apply them. - - - - 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 - optimization settings should be used, whether to build - debug versions and then strip them or not, and so on. - - - - Packages are normally built with quite conservative - settings. If a port has a compilation option to use code - for a specific processor, or a particular add-on board you - can enable this yourself in the port, without the people - making the package having to produce many, many different - packaged versions. - - The most obvious exception to this rule is paper sizes. - If a package can be provided with default support for - different paper sizes we will often provide multiple - packages, one per paper size. - - - - Some people like having code around, so they can read - it if they get bored, hack it, borrow from it (license - permitting, of course), and so on. - - - - If you ain't got the source, it ain't software! - ;-) - - - - - - - - What is a patch? - - - - A patch is a small file that specifies how to go from - one version of a file to another. It contains plain text, - and basically says things like “delete line 23”, - “add these two lines after line 468”, or - “change line 197 to this”. They are also known - as diffs because they are generated by the - diff program. - - - - - - What is all this about - tarballs? - - - - It is a file ending in .tar, or - with variations such as .tar.gz, - .tar.Z, .tar.bz2, - and even .tgz. - - Basically, it is a directory tree that has been archived - into a single file (.tar) and - optionally compressed (.gz). This - technique was originally used for Tape - ARchives (hence the name - tar), but it is a widely used way of - distributing program source code around the Internet. - - 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: - - &prompt.user; tar tvzf foobar.tar.gz -&prompt.user; tar xzvf foobar.tar.gz -&prompt.user; tar tvf foobar.tar -&prompt.user; tar xvf foobar.tar - - - - - - And a checksum? - - - - 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. - - - - - - I did what you said for compiling ports from a CDROM and - it worked great until I tried to install the kermit - port. - - &prompt.root; make install ->> cku190.tar.gz doesn't seem to exist on this system. ->> Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/. - - Why can it not be found? Have I got a dud CDROM? - - - - As was explained in the compiling ports from CDROM - section, some ports cannot be put on the CDROM set - due to licensing restrictions. Kermit is an example of - that. 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 MASTER_SITES - (listed in the Makefile), you can restart the install - process. - - - - - - I did that, but when I tried to put it into - /usr/ports/distfiles I got some error - about not having permission. - - - - The ports mechanism looks for the tarball in - /usr/ports/distfiles, but you will not - be able to copy anything there because it is symlinked to - the CDROM, which is read-only. You can tell it to look - somewhere else by doing: - - &prompt.root; make DISTDIR=/where/you/put/it install - - - - - - Does the ports scheme only work if you have everything - in /usr/ports? My system administrator - says I must put everything under - /u/people/guests/wurzburger, but it - does not seem to work. - - - - You can use the PORTSDIR and - PREFIX variables to tell the ports - mechanism to use different directories. For - instance, - - &prompt.root; make PORTSDIR=/u/people/guests/wurzburger/ports install - - will compile the port in - /u/people/guests/wurzburger/ports and - install everything under - /usr/local. - - &prompt.root; make PREFIX=/u/people/guests/wurzburger/local install - - will compile it in /usr/ports and - install it in - /u/people/guests/wurzburger/local. - - And of course, - - &prompt.root; make PORTSDIR=.../ports PREFIX=.../local install - - will combine the two (it is too long to write fully on - the page, but it should give you the general idea). - - If you do not fancy typing all that in every time you - install a port, it is a good idea to put these variables - into your environment. Read the man page for your shell for - instructions on doing so. - - - - - - 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 any - way to get them all at once? - - - - To get every single tarball for the Ports collection, - do: - - &prompt.root; cd /usr/ports -&prompt.root; make fetch - - For all the tarballs for a single ports directory, - do: - - &prompt.root; cd /usr/ports/directory -&prompt.root; make fetch - - and for just one port—well, I think you have - guessed already. - - - - - - 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 the - ones listed in the MASTER_SITES? - - - - Yes. If you know, for example, that ftp.FreeBSD.org is much closer to you - than the sites listed in MASTER_SITES, - do as follows: - - &prompt.root; cd /usr/ports/directory -&prompt.root; make MASTER_SITE_OVERRIDE= \ -ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch - - - - - - I want to know what files make is - going to need before it tries to pull them down. - - - - make fetch-list will display a list - of the files needed for a port. - - - - - - 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 to watch it and hit control-C every - time. - - - - Doing make extract will stop it - after it has fetched and extracted the source code. - - - - - - 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 - make extract, but for patches? - - - - Yep, make patch is what you want. - You will probably find the PATCH_DEBUG - option useful as well. And by the way, thank you for your - efforts! - - - - - - 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? - - - - Yes, with version 2.6.3 of gcc (the - version shipped with FreeBSD 2.1.0 and 2.1.5), the - option could result in buggy code - unless you used the - option as well. (Most of the ports do not use - ). You should be - able to specify the compiler options used by something - like: - - &prompt.root; make CFLAGS='-O2 -fno-strength-reduce' install - - or by editing /etc/make.conf, but - unfortunately not all ports respect this. The surest way - is to do make configure, 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. - - The default FreeBSD compiler options are quite conservative, - so if you have not changed them you should not have any - problems. - - - - - - There are so many ports it is hard to find the one I - want. Is there a list anywhere of what ports are - available? - - - - Look in the INDEX file in - /usr/ports. 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: - - &prompt.user; cd /usr/ports -&prompt.user; make search key=lisp - - - - - - I went to install the foo port but - the system suddenly stopped compiling it and starting - compiling the bar port. What is going - on? - - - - The foo port needs something that is - supplied with bar — for instance, - if foo uses graphics, - bar might have a library with useful - graphics processing routines. Or bar - might be a tool that is needed to compile the - foo port. - - - - - - I installed the - grizzle 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? - - - - No problem, just do: - - &prompt.root; pkg_delete grizzle-6.5 - - Alternatively, you can do: - - &prompt.root; cd /usr/ports/somewhere/grizzle -&prompt.root; make deinstall - - - - - - 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?? - - - - Not at all, you can find it out by doing: - - &prompt.root; pkg_info -a | grep grizzle -Information for grizzle-6.5: -grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up -arcade game. - - - - - - 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? - - - - 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: - - &prompt.root; cd /usr/ports -&prompt.root; make clean - - which will go through all the ports subdirectories and - delete everything except the skeletons for each - port. - - - - - - I tried that and it still left all those tarballs or - whatever you called them in the - distfiles directory. Can I delete - those as well? - - - - Yes, if you are sure you have finished with them, - those can go as well. They can be removed manually, or by - using make distclean. - - - - - - I like having lots and lots of programs to play with. - Is there any way of installing all the ports in one - go? - - - - Just do: - - &prompt.root; cd /usr/ports -&prompt.root; make install - - Be careful, as some ports may install files with the same - name. If you install two graphics ports and they both install - /usr/local/bin/plot then you will obviously - have problems. - - - - - - 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? - - - - 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. - - - - - - I really do not want to spend all day staring at the - monitor. Any better ideas? - - - - OK, do this before you go to bed/work/the local - park: - - &prompt.root cd /usr/ports -&prompt.root; make -DBATCH install - - This will install every port that does - not require user input. Then, when - you come back, do: - - &prompt.root; cd /usr/ports -&prompt.root; make -DIS_INTERACTIVE install - - to finish the job. - - - - - - At work, we are using frobble, 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? - - - - No problem, assuming you know how to make patches for - your changes: - - &prompt.root; cd /usr/ports/somewhere/frobble -&prompt.root; make extract -&prompt.root; cd work/frobble-2.8 -[Apply your patches] -&prompt.root; cd ../.. -&prompt.root; make package - - - - - - This ports stuff is really clever. I am desperate to - find out how you did it. What is the secret? - - - - Nothing secret about it at all, just look at the - bsd.port.mk and - bsd.port.subdir.mk files in your - makefiles - directory. - - (Readers with an aversion to intricate shell-scripts are - advised not to follow this link...) - - - - - - - Help! This port is broken! - - If you come across a port that doesn't work for you, there are - a few things you can do, including: - - - - Fix it! The “how to make a - port” section should help you do this. - - - - Gripe—by email only! Send - email to the maintainer of the port first. Type make - maintainer or read the Makefile - to find the maintainter's email address. Remember to include - the name and version of the port (send the - $FreeBSD: line from the - Makefile) and the output leading up to the - error when you email the maintainer. If you do not get a - response from the maintainer, you can use - send-pr to submit a bug report. - - - - Forget about it. This is the easiest route—very - few ports can be classified as “essential”. There's - also a good chance any problems will be fixed in the next - version when the port is updated. - - - - Grab the package from an ftp site near you. The - “master” package collection is on ftp.FreeBSD.org in the packages - directory, but be sure to check your local mirror - first! These are more likely to work - than trying to compile from source and are a lot faster as - well. Use the &man.pkg.add.1; program to install the package - on your system. - - - - - - - Advanced Topics - - + +%man; + + +%bookinfo; + + %authors; + +%mailing-lists; + +]> + + + + FreeBSD Porter's Handbook + + + + The FreeBSD Documentation Project + +
+ doc@FreeBSD.org +
+ + + + + April 2000 + + + 2000 + + + &bookinfo.legalnotice; + + + + Making a port yourself So, now you are interested in making your own port or @@ -1018,9 +72,9 @@ arcade game. typing :set tabstop=4 once the file has been loaded. - + - + Quick Porting This section tells you how to do a quick port. In many cases, it @@ -1037,7 +91,7 @@ arcade game. have to refer to the next section too. - + Writing the <filename>Makefile</filename> The minimal Makefile would look something @@ -1069,9 +123,9 @@ USE_IMAKE= yes filled in automatically by CVS when the port is imported to our main ports tree. You can find a more detailed example in the sample Makefile section. - + - + Writing the description files There are three description files that are required for any @@ -1080,7 +134,7 @@ USE_IMAKE= yes PLIST, and reside in the pkg subdirectory. - + <filename>COMMENT</filename> This is the one-line description of the port. @@ -1091,9 +145,9 @@ USE_IMAKE= yes A cat chasing a mouse all over the screen - + - + <filename>DESCR</filename> This is a longer description of the port. One to a few @@ -1126,9 +180,9 @@ WWW: http://www.oneko.org/ - Satoshi asami@cs.berkeley.edu - + - + <filename>PLIST</filename> This file lists all the files installed by the port. It is @@ -1169,18 +223,18 @@ lib/X11/oneko/mouse.xpm linkend="porting-autoplist">creating the packing list automatically might save time. - - + + - + Creating the checksum file Just type make makesum. The ports make rules will automatically generate the file files/md5. - + - + Testing the port You should make sure that the port rules do exactly what you @@ -1248,9 +302,9 @@ lib/X11/oneko/mouse.xpm 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. - + - + Checking your port with <command>portlint</command> Please use portlint to see if your port @@ -1260,9 +314,9 @@ lib/X11/oneko/mouse.xpm the right shape and the package is named appropriately. - + - + Submitting the port First, make sure you have read the :-) - - + + - + Slow Porting Ok, so it was not that simple, and the port required some @@ -1313,7 +367,7 @@ lib/X11/oneko/mouse.xpm step by step, how to modify it to get it to work with the ports paradigm. - + How things work First, this is the sequence of events which occurs when the user @@ -1438,9 +492,9 @@ lib/X11/oneko/mouse.xpm Now that you understand what goes on when the user types make, let us go through the recommended steps to create the perfect port. - + - + Getting the original sources Get the original sources (normally) as a compressed tarball @@ -1481,9 +535,9 @@ lib/X11/oneko/mouse.xpm other than where you got the main source tarball, we have a way to handle these situations (see the description of PATCHFILES below). - + - + Modifying the port Unpack a copy of the tarball in a private directory and make @@ -1507,9 +561,9 @@ lib/X11/oneko/mouse.xpm collection are assumed to be covered by the standard BSD copyright conditions. - + - + Patching In the preparation of the port, files that have been added or @@ -1529,9 +583,9 @@ lib/X11/oneko/mouse.xpm one patch fix the same file (e.g., patch-aa and patch-ab both changing WRKSRC/foobar.c). - + - + Configuring Include any additional customization commands to your @@ -1540,9 +594,9 @@ lib/X11/oneko/mouse.xpm can also do this as Makefile targets and/or scripts with the name pre-configure or post-configure. - + - + Handling user input If your port requires user input to build, configure or install, @@ -1558,10 +612,10 @@ lib/X11/oneko/mouse.xpm PACKAGE_BUILDING variable and turn off the interactive script when it is set. This will allow us to build the packages for CD-ROMs and ftp. - - + + - + Configuring the Makefile Configuring the Makefile is pretty simple, and again we suggest @@ -1574,7 +628,7 @@ lib/X11/oneko/mouse.xpm Now, consider the following problems in sequence as you design your new Makefile: - + The original source Does it live in DISTDIR as a standard @@ -1595,17 +649,17 @@ lib/X11/oneko/mouse.xpm do-extract target to override the default, though this should be rarely, if ever, necessary. - + - + <makevar>PORTNAME</makevar> and <makevar>PORTVERSION</makevar> You should set PORTNAME to be the base name of your port, and PORTVERSION to the version number of the port. - + - + <makevar>PKGNAMEPREFIX</makevar> and <makevar>PKGNAMESUFFIX</makevar> Two optional variables, PKGNAMEPREFIX and @@ -1624,9 +678,9 @@ lib/X11/oneko/mouse.xpm PKGNAMEPREFIX and PKGNAMESUFFIX, respectively. Do not make them part of PORTNAME. - + - + <makevar>DISTNAME</makevar> DISTNAME is the name of the port as @@ -1644,9 +698,9 @@ lib/X11/oneko/mouse.xpm Note that PKGNAMEPREFIX and PKGNAMESUFFIX do not affect DISTNAME. - + - + <makevar>CATEGORIES</makevar> When a package is created, it is put under @@ -1677,9 +731,9 @@ lib/X11/oneko/mouse.xpm package will happily create a new directory if you mistype the category name, so be careful! - + - + <makevar>MASTER_SITES</makevar> Record the directory part of the ftp/http-URL pointing at the @@ -1716,9 +770,9 @@ MASTER_SITE_SUBDIR= applications variables in /etc/make.conf to override our choices, and use their favorite mirrors of these popular archives instead. - + - + <makevar>PATCHFILES</makevar> If your port requires some additional patches that are available @@ -1758,9 +812,9 @@ MASTER_SITE_SUBDIR= applications remove the copied patch in the pre-clean target. - + - + <makevar>MAINTAINER</makevar> Set your mail-address here. Please. - + <makevar>MASTERDIR</makevar> If your port needs to build slightly different versions of @@ -2287,9 +1341,9 @@ MASTERDIR= ${.CURDIR}/../xdvi300 line will override the RESOLUTION=300 line in xdvi300/Makefile and the port will be built with resolution set to 118. - + - + Shared library versions Please read our policy on @@ -2323,9 +1377,9 @@ MASTERDIR= ${.CURDIR}/../xdvi300 libfoo4.so.1.0 so both version 3.2 and 4.0 can be linked from other ports. --> - + - + Manpages The MAN[1-9LN] variables will automatically add @@ -2401,9 +1455,9 @@ ${PREFIX}/man/ja/man4/baz.4.gz symlink will be made to join the foo(1) manpage and alt-name(8) manpage. - + - + Ports that require Motif There are many programs that require a Motif library (available @@ -2416,15 +1470,15 @@ ${PREFIX}/man/ja/man4/baz.4.gz binaries linked either dynamically (for people who are compiling from the port) or statically (for people who distribute packages). - + <makevar>REQUIRES_MOTIF</makevar> If your port requires Motif, define this variable in the Makefile. This will prevent people who do not own a copy of Motif from even attempting to build it. - + - + <makevar>MOTIFLIB</makevar> This variable will be set by bsd.port.mk to @@ -2456,10 +1510,10 @@ ${PREFIX}/man/ja/man4/baz.4.gz -L/usr/X11R6/lib -lXm or /usr/X11R6/lib/libXm.a, so there is no need to add -L or -l in front. - - + + - + X11 fonts If your port installs fonts for the X Window system, put them in @@ -2468,9 +1522,9 @@ ${PREFIX}/man/ja/man4/baz.4.gz 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 /etc/XF86Config. - + - + Info files The new version of texinfo (included in 2.2.2-RELEASE and onwards) @@ -2738,16 +1792,16 @@ diff -u -r1.15 PLIST dir file before and after each step. - + - + The <filename>pkg/</filename> subdirectory There are some tricks we have not mentioned yet about the pkg/ subdirectory that come in handy sometimes. - + <filename>MESSAGE</filename> If you need to display a message to the installer, you may place @@ -2763,9 +1817,9 @@ diff -u -r1.15 PLIST package, so you should probably display it from the post-install target yourself. - + - + <filename>INSTALL</filename> If your port needs to execute commands when the binary package @@ -2787,9 +1841,9 @@ diff -u -r1.15 PLIST being run, you will have to explicitly call it from your port's Makefile. - + - + <filename>REQ</filename> If your port needs to determine if it should install or not, you @@ -2797,9 +1851,9 @@ diff -u -r1.15 PLIST script. It will be invoked automatically at installation/deinstallation time to determine whether or not installation/deinstallation should proceed. - + - + Changing <filename>PLIST</filename> based on make variables @@ -2849,9 +1903,9 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} needs to edit the resulting file, do so in post-install to a file named TMPPLIST. - + - + Changing the names of files in the <filename>pkg</filename> subdirectory @@ -2920,10 +1974,10 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} PKG_ARGS, those files will not correctly be installed in /var/db/pkg upon install from a port. - - + + - + Licensing Problems Some software packages have restrictive licenses or can be in @@ -2979,9 +2033,9 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} If you are a committer, make sure you update the ports/LEGAL file too. - + - + Upgrading When you notice that a port is out of date compared to the latest @@ -3016,9 +2070,9 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} Once again, please use &man.diff.1; and not &man.shar.1; to send updates to existing ports! - + - + <anchor id="porting-dads">Dos and Don'ts Here is a list of common dos and don'ts that you encounter during @@ -3030,7 +2084,7 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} it faster for us to commit them, and prove that you know what you are doing. - + Strip Binaries Do strip binaries. If the original source already strips the @@ -3045,9 +2099,9 @@ post-install: Use the &man.file.1; command on the installed executable to check whether the binary is stripped or not. If it does not say not stripped, it is stripped. - + - + INSTALL_* macros Do use the macros provided in bsd.port.mk @@ -3080,9 +2134,9 @@ post-install: These are basically the install command with all the appropriate flags. See below for an example on how to use them. - + - + <makevar>WRKDIR</makevar> Do not write anything to files outside @@ -3093,9 +2147,9 @@ post-install: modify some file in PKGDIR, do so by redefining a variable, not by writing over it. - + - + <makevar>WRKDIRPREFIX</makevar> Make sure your port honors WRKDIRPREFIX. @@ -3108,9 +2162,9 @@ post-install: make sure you prepend ${WRKDIRPREFIX}${.CURDIR} in the front. - + - + Differentiating operating systems and OS versions You may come across code that needs modifications or conditional @@ -3571,11 +2625,6 @@ post-install: 500001 - - 5.0-CURRENT after kld metadata changes. - 500002 - - @@ -3598,9 +2647,9 @@ post-install: been one or two cases where __FreeBSD__ 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. - + - + Writing something after <filename>bsd.port.mk</filename> @@ -3719,9 +2768,9 @@ post-install: .if ${PORTOBJFORMAT} == "aout" ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so .endif - + - + Install additional documentation If your software has some documentation other than the standard @@ -3763,9 +2812,9 @@ post-install: MESSAGE does not need to be added to pkg/PLIST). - + - + <makevar>DIST_SUBDIR</makevar> Do not let your port clutter @@ -3792,9 +2841,9 @@ post-install: This does not affect the MASTER_SITES you define in your Makefile. - + - + Package information Do include package information, i.e. @@ -3806,9 +2855,9 @@ post-install: and are mandatory now, even if NO_PACKAGE is set. - + - + RCS strings Do not put RCS strings in patches. CVS will mangle them when we @@ -3817,9 +2866,9 @@ post-install: are surrounded by dollar ($) signs, and typically start with $Id or $RCS. - + - + Recursive diff Using the recurse () option to @@ -3840,9 +2889,9 @@ post-install: post-extract 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. - + - + <makevar>PREFIX</makevar> Do try to make your port install relative to @@ -3890,9 +2939,9 @@ post-install: -DPAGER=\"/usr/local/bin/less\". This way it will have a better chance of working if the system administrator has moved the whole `/usr/local' tree somewhere else. - + - + Subdirectories Try to let the port put things in the right subdirectories of @@ -3913,9 +2962,9 @@ post-install: dealing with USENET “news”. They may use PREFIX/news as a destination for their files. - + - + Cleaning up empty directories Do make your ports clean up after themselves when they are @@ -3945,9 +2994,9 @@ lib/X11/oneko/sounds/cat.au pkg_delete to exit abnormally even if PREFIX/share/doc/gimp is not empty due to other ports installing some files in there. - + - + UIDs If your port requires a certain user to be on the installed @@ -3988,9 +3037,9 @@ mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin 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. - + - + Do things rationally The Makefile should do things simply and @@ -4002,17 +3051,17 @@ mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin EXTRACT* instead, and using GNU_CONFIGURE instead of CONFIGURE_ARGS += --prefix=${PREFIX}. - + - + Respect <makevar>CFLAGS</makevar> The port should respect the CFLAGS variable. If it does not, please add NO_PACKAGE=ignores cflags to the Makefile. - + - + Configuration files If your port requires some configuration files in @@ -4028,26 +3077,26 @@ mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin linkend="porting-message">message pointing out that the user has to copy and edit the file before the software can be made to work. - + - + Portlint Do check your work with portlint before you submit or commit it. - + - + Feedback 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. - + - + Miscellanea The files pkg/DESCR, @@ -4060,9 +3109,9 @@ mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin Please be careful to note any legal issues! Do not let us illegally distribute software! - + - + If you are stuck… Do look at existing examples and the @@ -4072,10 +3121,10 @@ mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin Do ask us questions if you have any trouble! Do not just beat your head against a wall! :-) - - + + - + A Sample <filename>Makefile</filename> Here is a sample Makefile that you can use to @@ -4174,9 +3223,9 @@ pre-install: [and then the epilogue] .include <bsd.port.mk> - + - + Automated package list creation First, make sure your port is almost complete, with only @@ -4219,9 +3268,9 @@ pre-install: files section. Any libraries installed by the port should be listed as specified in the ldconfig section. - + - + Package Names The following are the conventions you should follow in naming your @@ -4454,9 +3503,9 @@ pre-install: the original author or use the date string (yyyy.mm.dd) as the version. - + - + Categories As you already know, ports are classified in several categories. @@ -4464,7 +3513,7 @@ pre-install: what each category and how we decide what to put in each category. - + Current list of categories First, this is the current list of port categories. Those @@ -4850,9 +3899,9 @@ pre-install: - + - + Choosing the right category As many of the categories overlap, you often have to choose @@ -4907,10 +3956,10 @@ pre-install: discuss it before we 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. - - + + - + Changes to this document and the ports system If you maintain a lot of ports, you should consider following the @@ -4919,9 +3968,9 @@ pre-install: changes by looking at the bsd.port.mk CVS log. - + - + That is It, Folks! Boy, this sure was a long tutorial, wasn't it? Thanks for @@ -4929,17 +3978,14 @@ pre-install: have at it and convert everything in the world into ports! That is the easiest way to start contributing to the FreeBSD Project! :-) - - - + + diff --git a/en_US.ISO_8859-1/books/porters-handbook/book.sgml b/en_US.ISO_8859-1/books/porters-handbook/book.sgml index a269a7c635..618a360a07 100644 --- a/en_US.ISO_8859-1/books/porters-handbook/book.sgml +++ b/en_US.ISO_8859-1/books/porters-handbook/book.sgml @@ -1,994 +1,48 @@ - - Installing Applications: The Ports collection - - Rewritten by &a.jim;, 22 November 1999. Original work - by various people. - - - Synopsis - - The FreeBSD Ports collection allows you to compile and install a - very wide range of applications with a minimum amount of - effort. - - In general, it is a group of skeletons - which contain a minimal set of items needed to make an application - compile and install cleanly on FreeBSD. - - Even with all the hype about open standards, getting a program - to compile on various UNIX platforms can be a tricky task. - Occasionally, you might be lucky enough to find that the program you - want compiles cleanly on your system, install everything into all - the right directories, and run flawlessly - “out-of-the-box”, but this behavior is somewhat rare. - Most of the time, you find yourself needing to make modifications in - order to get the program to work. This is where the FreeBSD Ports - collection comes to the rescue. - - The general idea behind the Ports collection is to eliminate all - of the messy steps involved with making things work properly so that - the installation is simple and very painless. With the Ports - collection, all of the hard work has already been done for you, and - you are able to install any of the Ports collection ports by simply - typing make install. - - - - Using the Ports Collection - - The following sections provide basic instructions on using the - ports collection to install or remove programs from your - system. - - - Installing Ports - - The first thing that should be explained - when it comes to the Ports collection is what is actually meant - by a “skeleton”. In a nutshell, a port skeleton is a - minimal set of files that are needed for a program to compile and - install cleanly on FreeBSD. Each port skeleton includes: - - - - A Makefile. The - Makefile contains various statements that - specify how the application should be compiled and where it - should be installed on your system - - - - A files directory. The - files directory contains a file named - md5. This file is named after the MD5 - algorithm used to determine ports checksums. A checksum is a - number generated by adding up all the data in the file you - want to check. If any characters change, the checksum will - differ from the original and an error message will be - displayed so you are able to investigate the changes. - - The files directory can also contain - other files that are required by the port but do not belong - elsewhere in the directory structure. - - - - A patches directory. This directory - contains patches to make the program compile and install on - your FreeBSD system. Patches are basically small files that - specify changes to particular files. They are in plain text - format, and basically say “Remove line 10” or - “Change line 26 to this ...”. Patches are also - known as “diffs” because they are generated by the - diff program. - - - - A pkg directory. This directory - normally contains three files. Occasionally, there will be - more than three, but it depends on the port. Most only - require three. The files are: - - - - COMMENT. This is a one-line - description of the program. - - - - DESCR. This is a more detailed, - often multiple-line, description of the program. - - - - PLIST. This is a list of all the - files that will be installed by the port. It also tells - the ports system what files to remove upon - deinstallation. - - - - - - Now that you have enough background information to know what - the Ports collection is used for, you are ready to install your - first port. There are two ways this can be done, and each is - explained below. - - Before we get into that however, you will need to choose a - port to install. There are a few ways to do this, with the - easiest method being the ports listing on the FreeBSD - web site. You can browse through the ports listed there - or use the search function on the site. Each port also includes - a description so you can read a bit about each port before - deciding to install it. - - Another method is to use the whereis - command. To use whereis, simply type - “whereis <program you want to - install>” at the prompt, and if it is found on - your system, you will be told where it is, like so: - - &prompt.root; whereis xchat -xchat: /usr/ports/irc/xchat -&prompt.root; - - This tells us that xchat (an irc client) can be found in the - /usr/ports/irc/xchat directory. - - Yet another way of finding a particular port is by using the - Ports collection's built-in search mechanism. To use the search - feature, you will need to be in the - /usr/ports directory. Once in that - directory, run make search key=program-name - where “program-name” is the name of the program you - want to find. For example, if you were looking for xchat: - - &prompt.root; cd /usr/ports -&prompt.root; make search key=xchat -Port: xchat-1.3.8 -Path: /usr/ports/irc/xchat -Info: An X11 IRC client using the GTK+ toolkit, and optionally, GNOME -Maint: jim@FreeBSD.org -Index: irc -B-deps: XFree86-3.3.5 bzip2-0.9.5d gettext-0.10.35 giflib-4.1.0 glib-1.2.6 gmake-3.77 gtk-1.2.6 - imlib-1.9.8 jpeg-6b png-1.0.3 tiff-3.5.1 -R-deps: XFree86-3.3.5 gettext-0.10.35 giflib-4.1.0 glib-1.2.6 gtk-1.2.6 imlib-1.9.8 jpeg-6b - png-1.0.3 tiff-3.5.1 - - The part of the output you want to pay particular attention - to is the “Path:” line, since that tells you where to - find it. The other information provided is not needed in order - to install the port directly, so it will not be covered - here. - - - You must be the root user to install - ports. - - - Now that you have found a port you would like to install, you - are ready to do the actual installation. - - - Installing ports from a CDROM - - As you may have guessed from the title, everything - described in this section assumes you have a FreeBSD CDROM set. - If you do not, you can order one from the FreeBSD Mall. - - Assuming that your FreeBSD CDROM is in the drive and is - mounted on /cdrom (and the mount point - must be /cdrom), - you are ready to install the port. To begin, change directories - to the directory where the port you want to install lives: - - &prompt.root; cd /usr/ports/irc/xchat - - Once inside the xchat directory, you will see the port - skeleton. The next step is to compile (also called build) the - port. This is done by simply typing make at - the prompt. Once you have done so, you should see something - like this: - - &prompt.root; make ->> xchat-1.3.8.tar.bz2 doesn't seem to exist on this system. ->> Attempting to fetch from file:/cdrom/ports/distfiles/. -===> Extracting for xchat-1.3.8 ->> Checksum OK for xchat-1.3.8.tar.bz2. -===> xchat-1.3.8 depends on executable: bzip2 - found -===> xchat-1.3.8 depends on executable: gmake - found -===> xchat-1.3.8 depends on shared library: gtk12.2 - found -===> xchat-1.3.8 depends on shared library: Imlib.5 - found -===> xchat-1.3.8 depends on shared library: X11.6 - found -===> Patching for xchat-1.3.8 -===> Applying FreeBSD patches for xchat-1.3.8 -===> Configuring for xchat-1.3.8 -... -[configure output snipped] -... -===> Building for xchat-1.3.8 -... -[compilation snipped] -... -&prompt.root; - - Take notice that once the compile is complete you are - returned to your prompt. The next step is to install the - port. In order to install it, you simply need to tack one word - onto the make command, and that word is - install: - - &prompt.root; make install -===> Installing for xchat-1.3.8 -===> xchat-1.3.8 depends on shared library: gtk12.2 - found -===> xchat-1.3.8 depends on shared library: Imlib.5 - found -===> xchat-1.3.8 depends on shared library: X11.6 - found -... -[install routines snipped] -... -===> Generating temporary packing list -===> Installing xchat docs in /usr/X11R6/share/doc/xchat -===> Registering installation for xchat-1.3.8 -&prompt.root; - - Once you are returned to your prompt, you should be able to - run the application you just installed. - - - You can save an extra step by just running make - install instead of make and - make install as two separate steps. - - - - Please be aware that the licenses of a few ports do not - allow for inclusion on the CDROM. This could be for various - reasons, including things such as as registration form needs - to be filled out before downloading, if redistribution is not - allowed, and so on. If you wish to install a port not - included on the CDROM, you will need to be online in order to - do so (see the next - section). - - - - - Installing ports from the Internet - - As with the last section, this section makes an assumption - that you have a working Internet connection. If you do not, - you will need to do the CDROM - installation. - - Installing a port from the Internet is done exactly the same - way as it would be if you were installing from a CDROM. The - only difference between the two is that the program's source - code is downloaded from the Internet instead of pulled from the - CDROM. - - The steps involved are identical: - - &prompt.root; make install ->> xchat-1.3.8.tar.bz2 doesn't seem to exist on this system. ->> Attempting to fetch from http://xchat.org/files/v1.3/. -Receiving xchat-1.3.8.tar.bz2 (305543 bytes): 100% -305543 bytes transferred in 2.9 seconds (102.81 Kbytes/s) -===> Extracting for xchat-1.3.8 ->> Checksum OK for xchat-1.3.8.tar.bz2. -===> xchat-1.3.8 depends on executable: bzip2 - found -===> xchat-1.3.8 depends on executable: gmake - found -===> xchat-1.3.8 depends on shared library: gtk12.2 - found -===> xchat-1.3.8 depends on shared library: Imlib.5 - found -===> xchat-1.3.8 depends on shared library: X11.6 - found -===> Patching for xchat-1.3.8 -===> Applying FreeBSD patches for xchat-1.3.8 -===> Configuring for xchat-1.3.8 -... -[configure output snipped] -... -===> Building for xchat-1.3.8 -... -[compilation snipped] -... -===> Installing for xchat-1.3.8 -===> xchat-1.3.8 depends on shared library: gtk12.2 - found -===> xchat-1.3.8 depends on shared library: Imlib.5 - found -===> xchat-1.3.8 depends on shared library: X11.6 - found -... -[install routines snipped] -... -===> Generating temporary packing list -===> Installing xchat docs in /usr/X11R6/share/doc/xchat -===> Registering installation for xchat-1.3.8 -&prompt.root; - - As you can see, the only difference is the line that tells - you where the system is fetching the port from. - - That about does it for installing ports onto your system. - In the section you will learn how to remove a port from your - system. - - - - - Removing Installed Ports - - Now that you know how to install ports, you are probably - wondering how to remove them, just in case you install one and - later on you decide that you installed the wrong port. The next - few paragraphs will cover just that. - - Now we will remove our previous example (which was xchat for - those of you not paying attention). As with installing ports, - the first thing you must do is change to the port directory, - which if you remember was - /usr/ports/irc/xchat. After you change - directories, you are ready to uninstall xchat. This is done with - the make deinstall command (makes sense - right?): - - &prompt.root; cd /usr/ports/irc/xchat -&prompt.root; make deinstall -===> Deinstalling for xchat-1.3.8 -&prompt.root; - - That was easy enough. You have now managed to remove xchat - from your system. If you would like to reinstall it, you can do - so by running make reinstall from the - /usr/ports/irc/xchat directory. - - - - - Troubleshooting - - The following sections cover some of the more frequently asked - questions about the Ports collection and some basic troubleshooting - techniques, and what do to if a port is broken. - - - Some Questions and Answers - - - - - I thought this was going to be a discussion about - modems??! - - - - 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. - - - - - - I thought you were supposed to use packages to install - extra programs? - - - - Yes, that is usually the quickest and easiest way of - doing it. - - - - - - So why bother with ports then? - - - - Several reasons: - - - - The licensing conditions of some software - distributions forbid binary distribution. They must be - distributed as source code. - - - - 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. - - - - If you have local patches, you will need the source in - order to apply them. - - - - 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 - optimization settings should be used, whether to build - debug versions and then strip them or not, and so on. - - - - Packages are normally built with quite conservative - settings. If a port has a compilation option to use code - for a specific processor, or a particular add-on board you - can enable this yourself in the port, without the people - making the package having to produce many, many different - packaged versions. - - The most obvious exception to this rule is paper sizes. - If a package can be provided with default support for - different paper sizes we will often provide multiple - packages, one per paper size. - - - - Some people like having code around, so they can read - it if they get bored, hack it, borrow from it (license - permitting, of course), and so on. - - - - If you ain't got the source, it ain't software! - ;-) - - - - - - - - What is a patch? - - - - A patch is a small file that specifies how to go from - one version of a file to another. It contains plain text, - and basically says things like “delete line 23”, - “add these two lines after line 468”, or - “change line 197 to this”. They are also known - as diffs because they are generated by the - diff program. - - - - - - What is all this about - tarballs? - - - - It is a file ending in .tar, or - with variations such as .tar.gz, - .tar.Z, .tar.bz2, - and even .tgz. - - Basically, it is a directory tree that has been archived - into a single file (.tar) and - optionally compressed (.gz). This - technique was originally used for Tape - ARchives (hence the name - tar), but it is a widely used way of - distributing program source code around the Internet. - - 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: - - &prompt.user; tar tvzf foobar.tar.gz -&prompt.user; tar xzvf foobar.tar.gz -&prompt.user; tar tvf foobar.tar -&prompt.user; tar xvf foobar.tar - - - - - - And a checksum? - - - - 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. - - - - - - I did what you said for compiling ports from a CDROM and - it worked great until I tried to install the kermit - port. - - &prompt.root; make install ->> cku190.tar.gz doesn't seem to exist on this system. ->> Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/. - - Why can it not be found? Have I got a dud CDROM? - - - - As was explained in the compiling ports from CDROM - section, some ports cannot be put on the CDROM set - due to licensing restrictions. Kermit is an example of - that. 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 MASTER_SITES - (listed in the Makefile), you can restart the install - process. - - - - - - I did that, but when I tried to put it into - /usr/ports/distfiles I got some error - about not having permission. - - - - The ports mechanism looks for the tarball in - /usr/ports/distfiles, but you will not - be able to copy anything there because it is symlinked to - the CDROM, which is read-only. You can tell it to look - somewhere else by doing: - - &prompt.root; make DISTDIR=/where/you/put/it install - - - - - - Does the ports scheme only work if you have everything - in /usr/ports? My system administrator - says I must put everything under - /u/people/guests/wurzburger, but it - does not seem to work. - - - - You can use the PORTSDIR and - PREFIX variables to tell the ports - mechanism to use different directories. For - instance, - - &prompt.root; make PORTSDIR=/u/people/guests/wurzburger/ports install - - will compile the port in - /u/people/guests/wurzburger/ports and - install everything under - /usr/local. - - &prompt.root; make PREFIX=/u/people/guests/wurzburger/local install - - will compile it in /usr/ports and - install it in - /u/people/guests/wurzburger/local. - - And of course, - - &prompt.root; make PORTSDIR=.../ports PREFIX=.../local install - - will combine the two (it is too long to write fully on - the page, but it should give you the general idea). - - If you do not fancy typing all that in every time you - install a port, it is a good idea to put these variables - into your environment. Read the man page for your shell for - instructions on doing so. - - - - - - 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 any - way to get them all at once? - - - - To get every single tarball for the Ports collection, - do: - - &prompt.root; cd /usr/ports -&prompt.root; make fetch - - For all the tarballs for a single ports directory, - do: - - &prompt.root; cd /usr/ports/directory -&prompt.root; make fetch - - and for just one port—well, I think you have - guessed already. - - - - - - 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 the - ones listed in the MASTER_SITES? - - - - Yes. If you know, for example, that ftp.FreeBSD.org is much closer to you - than the sites listed in MASTER_SITES, - do as follows: - - &prompt.root; cd /usr/ports/directory -&prompt.root; make MASTER_SITE_OVERRIDE= \ -ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch - - - - - - I want to know what files make is - going to need before it tries to pull them down. - - - - make fetch-list will display a list - of the files needed for a port. - - - - - - 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 to watch it and hit control-C every - time. - - - - Doing make extract will stop it - after it has fetched and extracted the source code. - - - - - - 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 - make extract, but for patches? - - - - Yep, make patch is what you want. - You will probably find the PATCH_DEBUG - option useful as well. And by the way, thank you for your - efforts! - - - - - - 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? - - - - Yes, with version 2.6.3 of gcc (the - version shipped with FreeBSD 2.1.0 and 2.1.5), the - option could result in buggy code - unless you used the - option as well. (Most of the ports do not use - ). You should be - able to specify the compiler options used by something - like: - - &prompt.root; make CFLAGS='-O2 -fno-strength-reduce' install - - or by editing /etc/make.conf, but - unfortunately not all ports respect this. The surest way - is to do make configure, 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. - - The default FreeBSD compiler options are quite conservative, - so if you have not changed them you should not have any - problems. - - - - - - There are so many ports it is hard to find the one I - want. Is there a list anywhere of what ports are - available? - - - - Look in the INDEX file in - /usr/ports. 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: - - &prompt.user; cd /usr/ports -&prompt.user; make search key=lisp - - - - - - I went to install the foo port but - the system suddenly stopped compiling it and starting - compiling the bar port. What is going - on? - - - - The foo port needs something that is - supplied with bar — for instance, - if foo uses graphics, - bar might have a library with useful - graphics processing routines. Or bar - might be a tool that is needed to compile the - foo port. - - - - - - I installed the - grizzle 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? - - - - No problem, just do: - - &prompt.root; pkg_delete grizzle-6.5 - - Alternatively, you can do: - - &prompt.root; cd /usr/ports/somewhere/grizzle -&prompt.root; make deinstall - - - - - - 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?? - - - - Not at all, you can find it out by doing: - - &prompt.root; pkg_info -a | grep grizzle -Information for grizzle-6.5: -grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up -arcade game. - - - - - - 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? - - - - 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: - - &prompt.root; cd /usr/ports -&prompt.root; make clean - - which will go through all the ports subdirectories and - delete everything except the skeletons for each - port. - - - - - - I tried that and it still left all those tarballs or - whatever you called them in the - distfiles directory. Can I delete - those as well? - - - - Yes, if you are sure you have finished with them, - those can go as well. They can be removed manually, or by - using make distclean. - - - - - - I like having lots and lots of programs to play with. - Is there any way of installing all the ports in one - go? - - - - Just do: - - &prompt.root; cd /usr/ports -&prompt.root; make install - - Be careful, as some ports may install files with the same - name. If you install two graphics ports and they both install - /usr/local/bin/plot then you will obviously - have problems. - - - - - - 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? - - - - 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. - - - - - - I really do not want to spend all day staring at the - monitor. Any better ideas? - - - - OK, do this before you go to bed/work/the local - park: - - &prompt.root cd /usr/ports -&prompt.root; make -DBATCH install - - This will install every port that does - not require user input. Then, when - you come back, do: - - &prompt.root; cd /usr/ports -&prompt.root; make -DIS_INTERACTIVE install - - to finish the job. - - - - - - At work, we are using frobble, 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? - - - - No problem, assuming you know how to make patches for - your changes: - - &prompt.root; cd /usr/ports/somewhere/frobble -&prompt.root; make extract -&prompt.root; cd work/frobble-2.8 -[Apply your patches] -&prompt.root; cd ../.. -&prompt.root; make package - - - - - - This ports stuff is really clever. I am desperate to - find out how you did it. What is the secret? - - - - Nothing secret about it at all, just look at the - bsd.port.mk and - bsd.port.subdir.mk files in your - makefiles - directory. - - (Readers with an aversion to intricate shell-scripts are - advised not to follow this link...) - - - - - - - Help! This port is broken! - - If you come across a port that doesn't work for you, there are - a few things you can do, including: - - - - Fix it! The “how to make a - port” section should help you do this. - - - - Gripe—by email only! Send - email to the maintainer of the port first. Type make - maintainer or read the Makefile - to find the maintainter's email address. Remember to include - the name and version of the port (send the - $FreeBSD: line from the - Makefile) and the output leading up to the - error when you email the maintainer. If you do not get a - response from the maintainer, you can use - send-pr to submit a bug report. - - - - Forget about it. This is the easiest route—very - few ports can be classified as “essential”. There's - also a good chance any problems will be fixed in the next - version when the port is updated. - - - - Grab the package from an ftp site near you. The - “master” package collection is on ftp.FreeBSD.org in the packages - directory, but be sure to check your local mirror - first! These are more likely to work - than trying to compile from source and are a lot faster as - well. Use the &man.pkg.add.1; program to install the package - on your system. - - - - - - - Advanced Topics - - + +%man; + + +%bookinfo; + + %authors; + +%mailing-lists; + +]> + + + + FreeBSD Porter's Handbook + + + + The FreeBSD Documentation Project + +
+ doc@FreeBSD.org +
+ + + + + April 2000 + + + 2000 + + + &bookinfo.legalnotice; + + + + Making a port yourself So, now you are interested in making your own port or @@ -1018,9 +72,9 @@ arcade game. typing :set tabstop=4 once the file has been loaded. - + - + Quick Porting This section tells you how to do a quick port. In many cases, it @@ -1037,7 +91,7 @@ arcade game. have to refer to the next section too. - + Writing the <filename>Makefile</filename> The minimal Makefile would look something @@ -1069,9 +123,9 @@ USE_IMAKE= yes filled in automatically by CVS when the port is imported to our main ports tree. You can find a more detailed example in the sample Makefile section. - + - + Writing the description files There are three description files that are required for any @@ -1080,7 +134,7 @@ USE_IMAKE= yes PLIST, and reside in the pkg subdirectory. - + <filename>COMMENT</filename> This is the one-line description of the port. @@ -1091,9 +145,9 @@ USE_IMAKE= yes A cat chasing a mouse all over the screen - + - + <filename>DESCR</filename> This is a longer description of the port. One to a few @@ -1126,9 +180,9 @@ WWW: http://www.oneko.org/ - Satoshi asami@cs.berkeley.edu - + - + <filename>PLIST</filename> This file lists all the files installed by the port. It is @@ -1169,18 +223,18 @@ lib/X11/oneko/mouse.xpm linkend="porting-autoplist">creating the packing list automatically might save time. - - + + - + Creating the checksum file Just type make makesum. The ports make rules will automatically generate the file files/md5. - + - + Testing the port You should make sure that the port rules do exactly what you @@ -1248,9 +302,9 @@ lib/X11/oneko/mouse.xpm 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. - + - + Checking your port with <command>portlint</command> Please use portlint to see if your port @@ -1260,9 +314,9 @@ lib/X11/oneko/mouse.xpm the right shape and the package is named appropriately. - + - + Submitting the port First, make sure you have read the :-) - - + + - + Slow Porting Ok, so it was not that simple, and the port required some @@ -1313,7 +367,7 @@ lib/X11/oneko/mouse.xpm step by step, how to modify it to get it to work with the ports paradigm. - + How things work First, this is the sequence of events which occurs when the user @@ -1438,9 +492,9 @@ lib/X11/oneko/mouse.xpm Now that you understand what goes on when the user types make, let us go through the recommended steps to create the perfect port. - + - + Getting the original sources Get the original sources (normally) as a compressed tarball @@ -1481,9 +535,9 @@ lib/X11/oneko/mouse.xpm other than where you got the main source tarball, we have a way to handle these situations (see the description of PATCHFILES below). - + - + Modifying the port Unpack a copy of the tarball in a private directory and make @@ -1507,9 +561,9 @@ lib/X11/oneko/mouse.xpm collection are assumed to be covered by the standard BSD copyright conditions. - + - + Patching In the preparation of the port, files that have been added or @@ -1529,9 +583,9 @@ lib/X11/oneko/mouse.xpm one patch fix the same file (e.g., patch-aa and patch-ab both changing WRKSRC/foobar.c). - + - + Configuring Include any additional customization commands to your @@ -1540,9 +594,9 @@ lib/X11/oneko/mouse.xpm can also do this as Makefile targets and/or scripts with the name pre-configure or post-configure. - + - + Handling user input If your port requires user input to build, configure or install, @@ -1558,10 +612,10 @@ lib/X11/oneko/mouse.xpm PACKAGE_BUILDING variable and turn off the interactive script when it is set. This will allow us to build the packages for CD-ROMs and ftp. - - + + - + Configuring the Makefile Configuring the Makefile is pretty simple, and again we suggest @@ -1574,7 +628,7 @@ lib/X11/oneko/mouse.xpm Now, consider the following problems in sequence as you design your new Makefile: - + The original source Does it live in DISTDIR as a standard @@ -1595,17 +649,17 @@ lib/X11/oneko/mouse.xpm do-extract target to override the default, though this should be rarely, if ever, necessary. - + - + <makevar>PORTNAME</makevar> and <makevar>PORTVERSION</makevar> You should set PORTNAME to be the base name of your port, and PORTVERSION to the version number of the port. - + - + <makevar>PKGNAMEPREFIX</makevar> and <makevar>PKGNAMESUFFIX</makevar> Two optional variables, PKGNAMEPREFIX and @@ -1624,9 +678,9 @@ lib/X11/oneko/mouse.xpm PKGNAMEPREFIX and PKGNAMESUFFIX, respectively. Do not make them part of PORTNAME. - + - + <makevar>DISTNAME</makevar> DISTNAME is the name of the port as @@ -1644,9 +698,9 @@ lib/X11/oneko/mouse.xpm Note that PKGNAMEPREFIX and PKGNAMESUFFIX do not affect DISTNAME. - + - + <makevar>CATEGORIES</makevar> When a package is created, it is put under @@ -1677,9 +731,9 @@ lib/X11/oneko/mouse.xpm package will happily create a new directory if you mistype the category name, so be careful! - + - + <makevar>MASTER_SITES</makevar> Record the directory part of the ftp/http-URL pointing at the @@ -1716,9 +770,9 @@ MASTER_SITE_SUBDIR= applications variables in /etc/make.conf to override our choices, and use their favorite mirrors of these popular archives instead. - + - + <makevar>PATCHFILES</makevar> If your port requires some additional patches that are available @@ -1758,9 +812,9 @@ MASTER_SITE_SUBDIR= applications remove the copied patch in the pre-clean target. - + - + <makevar>MAINTAINER</makevar> Set your mail-address here. Please. - + <makevar>MASTERDIR</makevar> If your port needs to build slightly different versions of @@ -2287,9 +1341,9 @@ MASTERDIR= ${.CURDIR}/../xdvi300 line will override the RESOLUTION=300 line in xdvi300/Makefile and the port will be built with resolution set to 118. - + - + Shared library versions Please read our policy on @@ -2323,9 +1377,9 @@ MASTERDIR= ${.CURDIR}/../xdvi300 libfoo4.so.1.0 so both version 3.2 and 4.0 can be linked from other ports. --> - + - + Manpages The MAN[1-9LN] variables will automatically add @@ -2401,9 +1455,9 @@ ${PREFIX}/man/ja/man4/baz.4.gz symlink will be made to join the foo(1) manpage and alt-name(8) manpage. - + - + Ports that require Motif There are many programs that require a Motif library (available @@ -2416,15 +1470,15 @@ ${PREFIX}/man/ja/man4/baz.4.gz binaries linked either dynamically (for people who are compiling from the port) or statically (for people who distribute packages). - + <makevar>REQUIRES_MOTIF</makevar> If your port requires Motif, define this variable in the Makefile. This will prevent people who do not own a copy of Motif from even attempting to build it. - + - + <makevar>MOTIFLIB</makevar> This variable will be set by bsd.port.mk to @@ -2456,10 +1510,10 @@ ${PREFIX}/man/ja/man4/baz.4.gz -L/usr/X11R6/lib -lXm or /usr/X11R6/lib/libXm.a, so there is no need to add -L or -l in front. - - + + - + X11 fonts If your port installs fonts for the X Window system, put them in @@ -2468,9 +1522,9 @@ ${PREFIX}/man/ja/man4/baz.4.gz 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 /etc/XF86Config. - + - + Info files The new version of texinfo (included in 2.2.2-RELEASE and onwards) @@ -2738,16 +1792,16 @@ diff -u -r1.15 PLIST dir file before and after each step. - + - + The <filename>pkg/</filename> subdirectory There are some tricks we have not mentioned yet about the pkg/ subdirectory that come in handy sometimes. - + <filename>MESSAGE</filename> If you need to display a message to the installer, you may place @@ -2763,9 +1817,9 @@ diff -u -r1.15 PLIST package, so you should probably display it from the post-install target yourself. - + - + <filename>INSTALL</filename> If your port needs to execute commands when the binary package @@ -2787,9 +1841,9 @@ diff -u -r1.15 PLIST being run, you will have to explicitly call it from your port's Makefile. - + - + <filename>REQ</filename> If your port needs to determine if it should install or not, you @@ -2797,9 +1851,9 @@ diff -u -r1.15 PLIST script. It will be invoked automatically at installation/deinstallation time to determine whether or not installation/deinstallation should proceed. - + - + Changing <filename>PLIST</filename> based on make variables @@ -2849,9 +1903,9 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} needs to edit the resulting file, do so in post-install to a file named TMPPLIST. - + - + Changing the names of files in the <filename>pkg</filename> subdirectory @@ -2920,10 +1974,10 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} PKG_ARGS, those files will not correctly be installed in /var/db/pkg upon install from a port. - - + + - + Licensing Problems Some software packages have restrictive licenses or can be in @@ -2979,9 +2033,9 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} If you are a committer, make sure you update the ports/LEGAL file too. - + - + Upgrading When you notice that a port is out of date compared to the latest @@ -3016,9 +2070,9 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} Once again, please use &man.diff.1; and not &man.shar.1; to send updates to existing ports! - + - + <anchor id="porting-dads">Dos and Don'ts Here is a list of common dos and don'ts that you encounter during @@ -3030,7 +2084,7 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} it faster for us to commit them, and prove that you know what you are doing. - + Strip Binaries Do strip binaries. If the original source already strips the @@ -3045,9 +2099,9 @@ post-install: Use the &man.file.1; command on the installed executable to check whether the binary is stripped or not. If it does not say not stripped, it is stripped. - + - + INSTALL_* macros Do use the macros provided in bsd.port.mk @@ -3080,9 +2134,9 @@ post-install: These are basically the install command with all the appropriate flags. See below for an example on how to use them. - + - + <makevar>WRKDIR</makevar> Do not write anything to files outside @@ -3093,9 +2147,9 @@ post-install: modify some file in PKGDIR, do so by redefining a variable, not by writing over it. - + - + <makevar>WRKDIRPREFIX</makevar> Make sure your port honors WRKDIRPREFIX. @@ -3108,9 +2162,9 @@ post-install: make sure you prepend ${WRKDIRPREFIX}${.CURDIR} in the front. - + - + Differentiating operating systems and OS versions You may come across code that needs modifications or conditional @@ -3571,11 +2625,6 @@ post-install: 500001 - - 5.0-CURRENT after kld metadata changes. - 500002 - - @@ -3598,9 +2647,9 @@ post-install: been one or two cases where __FreeBSD__ 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. - + - + Writing something after <filename>bsd.port.mk</filename> @@ -3719,9 +2768,9 @@ post-install: .if ${PORTOBJFORMAT} == "aout" ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so .endif - + - + Install additional documentation If your software has some documentation other than the standard @@ -3763,9 +2812,9 @@ post-install: MESSAGE does not need to be added to pkg/PLIST). - + - + <makevar>DIST_SUBDIR</makevar> Do not let your port clutter @@ -3792,9 +2841,9 @@ post-install: This does not affect the MASTER_SITES you define in your Makefile. - + - + Package information Do include package information, i.e. @@ -3806,9 +2855,9 @@ post-install: and are mandatory now, even if NO_PACKAGE is set. - + - + RCS strings Do not put RCS strings in patches. CVS will mangle them when we @@ -3817,9 +2866,9 @@ post-install: are surrounded by dollar ($) signs, and typically start with $Id or $RCS. - + - + Recursive diff Using the recurse () option to @@ -3840,9 +2889,9 @@ post-install: post-extract 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. - + - + <makevar>PREFIX</makevar> Do try to make your port install relative to @@ -3890,9 +2939,9 @@ post-install: -DPAGER=\"/usr/local/bin/less\". This way it will have a better chance of working if the system administrator has moved the whole `/usr/local' tree somewhere else. - + - + Subdirectories Try to let the port put things in the right subdirectories of @@ -3913,9 +2962,9 @@ post-install: dealing with USENET “news”. They may use PREFIX/news as a destination for their files. - + - + Cleaning up empty directories Do make your ports clean up after themselves when they are @@ -3945,9 +2994,9 @@ lib/X11/oneko/sounds/cat.au pkg_delete to exit abnormally even if PREFIX/share/doc/gimp is not empty due to other ports installing some files in there. - + - + UIDs If your port requires a certain user to be on the installed @@ -3988,9 +3037,9 @@ mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin 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. - + - + Do things rationally The Makefile should do things simply and @@ -4002,17 +3051,17 @@ mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin EXTRACT* instead, and using GNU_CONFIGURE instead of CONFIGURE_ARGS += --prefix=${PREFIX}. - + - + Respect <makevar>CFLAGS</makevar> The port should respect the CFLAGS variable. If it does not, please add NO_PACKAGE=ignores cflags to the Makefile. - + - + Configuration files If your port requires some configuration files in @@ -4028,26 +3077,26 @@ mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin linkend="porting-message">message pointing out that the user has to copy and edit the file before the software can be made to work. - + - + Portlint Do check your work with portlint before you submit or commit it. - + - + Feedback 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. - + - + Miscellanea The files pkg/DESCR, @@ -4060,9 +3109,9 @@ mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin Please be careful to note any legal issues! Do not let us illegally distribute software! - + - + If you are stuck… Do look at existing examples and the @@ -4072,10 +3121,10 @@ mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin Do ask us questions if you have any trouble! Do not just beat your head against a wall! :-) - - + + - + A Sample <filename>Makefile</filename> Here is a sample Makefile that you can use to @@ -4174,9 +3223,9 @@ pre-install: [and then the epilogue] .include <bsd.port.mk> - + - + Automated package list creation First, make sure your port is almost complete, with only @@ -4219,9 +3268,9 @@ pre-install: files section. Any libraries installed by the port should be listed as specified in the ldconfig section. - + - + Package Names The following are the conventions you should follow in naming your @@ -4454,9 +3503,9 @@ pre-install: the original author or use the date string (yyyy.mm.dd) as the version. - + - + Categories As you already know, ports are classified in several categories. @@ -4464,7 +3513,7 @@ pre-install: what each category and how we decide what to put in each category. - + Current list of categories First, this is the current list of port categories. Those @@ -4850,9 +3899,9 @@ pre-install: - + - + Choosing the right category As many of the categories overlap, you often have to choose @@ -4907,10 +3956,10 @@ pre-install: discuss it before we 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. - - + + - + Changes to this document and the ports system If you maintain a lot of ports, you should consider following the @@ -4919,9 +3968,9 @@ pre-install: changes by looking at the bsd.port.mk CVS log. - + - + That is It, Folks! Boy, this sure was a long tutorial, wasn't it? Thanks for @@ -4929,17 +3978,14 @@ pre-install: have at it and convert everything in the world into ports! That is the easiest way to start contributing to the FreeBSD Project! :-) - - - + +