From 0e0b8f123fd94c5f79bd7502c38e27fe21c55653 Mon Sep 17 00:00:00 2001 From: Nik Clayton Date: Thu, 22 Oct 1998 23:06:05 +0000 Subject: [PATCH] As earlier commits, to line 30118 --- en/handbook/README | 2 + en/handbook/handbook.sgml | 704 +++++++++++----------- en_US.ISO8859-1/books/handbook/book.sgml | 704 +++++++++++----------- en_US.ISO_8859-1/books/handbook/book.sgml | 704 +++++++++++----------- 4 files changed, 1097 insertions(+), 1017 deletions(-) diff --git a/en/handbook/README b/en/handbook/README index edb3f4e310..47ac3e0643 100644 --- a/en/handbook/README +++ b/en/handbook/README @@ -463,3 +463,5 @@ for example, 41. . . . to line 24997 . . . 42. Brief interruption, small changes to keep it validating. + + 43. . . . to line 30118 . . . diff --git a/en/handbook/handbook.sgml b/en/handbook/handbook.sgml index b7df51be2b..dfaa441870 100644 --- a/en/handbook/handbook.sgml +++ b/en/handbook/handbook.sgml @@ -2427,7 +2427,7 @@ password. Remember to use binary (also known as image) mode!] # Date created: 13 November 1997 # Whom: jraynard # -# $Id: handbook.sgml,v 1.1 1998/04/01 18:25:32 nik +# $Id$ # DISTNAME= ElectricFence-2.0.5 @@ -24997,13 +24997,14 @@ an A record in the DNS for "customer.com". Who needs FreeBSD-current? FreeBSD-current is made generally available for 3 primary - interest groups: + interest groups: + Members of the FreeBSD group who are actively working on some part of the source tree and for whom keeping - `current' is an absolute requirement. + current is an absolute requirement. @@ -25023,14 +25024,13 @@ an A record in the DNS for "customer.com". - - What is FreeBSD-current <emphasis>NOT</emphasis>? + What is FreeBSD-current <emphasis>not</emphasis>? + - @@ -25058,14 +25058,14 @@ an A record in the DNS for "customer.com". - + Using FreeBSD-current - + @@ -25080,7 +25080,7 @@ an A record in the DNS for "customer.com". Yo, Everybody! Before you rebuild /usr/src, you must rebuild the kernel or your system will crash horribly!). - The cvs-all mailing list will allow you + The cvs-all mailing list will allow you to see the commit log entry for each change as it is made along with any pertinent information on possible side-effects. To join these lists, send mail to @@ -25089,21 +25089,23 @@ an A record in the DNS for "customer.com". subscribe freebsd-current subscribe cvs-all - In the - body of your message. Optionally, you can also say `help' + + + in the + body of your message. Optionally, you can also say help and Majordomo will send you full help on how to subscribe and unsubscribe to the various other mailing lists we support. - Grab the sources from ftp.FreeBSD.ORG. You can do - this in three ways: + Grab the sources from ftp.FreeBSD.ORG. You can do + this in three ways: - Use the + Use the facility. Unless you have a good TCP/IP connection at a flat rate, this is the way to do it. @@ -25115,29 +25117,33 @@ subscribe cvs-all - Use ftp. The source tree for FreeBSD-current is + Use ftp. The source tree for FreeBSD-current is always exported on: ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current We also use `wu-ftpd' which allows compressed/tar'd grabbing of whole trees. e.g. you see: + URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current">ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current We also use wu-ftpd which allows compressed/tar'd grabbing of whole trees. e.g. you see: usr.bin/lex - You can do: + + + You can do: ftp> cd usr.bin ftp> get lex.tar.Z - And it will get the whole directory for you as a compressed tar file. + + + and it will get the whole directory for you as a compressed tar file. - + Essentially, if you need rapid on-demand access to the source and communications bandwidth is not a consideration, - use cvsup or ftp. Otherwise, use CTM. + use cvsup or ftp. Otherwise, use CTM. @@ -25170,8 +25176,6 @@ subscribe cvs-all - - @@ -25242,13 +25246,13 @@ subscribe freebsd-stable - Grab the sources from ftp.FreeBSD.ORG. You can do + Grab the sources from ftp.FreeBSD.ORG. You can do this in three ways: - Use the + Use the facility. Unless you have a good TCP/IP connection at a flat rate, this is the way to do it. @@ -25260,22 +25264,26 @@ subscribe freebsd-stable - Use ftp. The source tree for FreeBSD-stable is + Use ftp. The source tree for FreeBSD-stable is always exported on: ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-stable - We also use `wu-ftpd' which allows + We also use wu-ftpd which allows compressed/tar'd grabbing of whole trees. e.g. you - see: + see: usr.bin/lex - You can do: + + + You can do: ftp> cd usr.bin ftp> get lex.tar.Z - And it will get the + + + and it will get the whole directory for you as a compressed tar file. @@ -25288,7 +25296,7 @@ subscribe freebsd-stable Essentially, if you need rapid on-demand access to the source and communications bandwidth is not a consideration, - use cvsup or ftp. Otherwise, use CTM. + use cvsup or ftp. Otherwise, use CTM. @@ -25318,9 +25326,9 @@ subscribe freebsd-stable There are various ways of using an Internet (or email) connection to stay up-to-date with any given area of the FreeBSD project sources, or all areas, depending on what interests you. The - primary services we offer are CVSup and CTM. + primary services we offer are CVSup and CTM. - CVSup uses the + CVSup uses the pull model of updating. The user (or a cron script) invokes the cvsup program, and it interacts with a cvsupd server @@ -25337,27 +25345,27 @@ subscribe freebsd-stable its previous run is executed several times a day on the master archive, any detected changes being compressed, stamped with a sequence-number and encoded for transmission over email (printable - ASCII only). Once received, these "CTM deltas" can then be handed + ASCII only). Once received, these CTM deltas can then be handed to the ctm_rmail1 utility which will automatically decode, verify and apply the changes to the user's copy of the sources. This - process is far more efficient than CVSup, and places less strain on + process is far more efficient than CVSup, and places less strain on our server resources since it is a push rather than a pull model. There are other trade-offs, of course. If you inadvertently - wipe out portions of your archive, CVSup will detect and rebuild the - damaged portions for you. CTM won't do this, and if you wipe some + wipe out portions of your archive, CVSup will detect and rebuild the + damaged portions for you. CTM won't do this, and if you wipe some portion of your source tree out (and don't have it backed up) then - you will have to start from scratch (from the most recent CVS "base - delta") and rebuild it all. + you will have to start from scratch (from the most recent CVS base + delta) and rebuild it all. - For more information on CTM and CVSup, please see one of the + For more information on CTM and CVSup, please see one of the following sections: - CTM + <application>CTM</application> Contributed by &a.phk;. Updated 19-October-1997. @@ -25472,7 +25480,7 @@ subscribe freebsd-stable produced subsequently to it. First you should determine what you already have. Everyone - can start from an Empty directory. However, since the trees + can start from an empty directory. However, since the trees are many tens of megabytes, you should prefer to start from something already at hand. If you have a RELEASE CD, you can copy or extract an initial source from it. This will save a @@ -25483,7 +25491,7 @@ subscribe freebsd-stable into a CTM supported tree. You can recognize these transition deltas by the - X appended to the number + X appended to the number (src-cur.3210XEmpty.gz for instance). The designation following the X corresponds to the origin of your initial seed. Empty is @@ -25501,11 +25509,12 @@ subscribe freebsd-stable Using <application>CTM</application> in your daily life - To apply the deltas, simply say: + To apply the deltas, simply say: + &prompt.root; cd /where/ever/you/want/the/stuff &prompt.root; ctm -v -v /where/you/store/your/deltas/src-xxx.* - + CTM understands deltas which have been put through gzip, so you do not @@ -25542,7 +25551,7 @@ subscribe freebsd-stable Keeping your local changes As a developer one would like to experiment with and change - files in the source tree. CTM supports local modifications in a + files in the source tree. CTM supports local modifications in a limited way: before checking for the presence of a file foo, it first looks for foo.ctm. If this file exists, CTM will @@ -25557,20 +25566,20 @@ subscribe freebsd-stable - Other interesting CTM options + Other interesting <application>CTM</application> options Finding out exactly what would be touched by an update - You can determine the list of changes that CTM will make + You can determine the list of changes that CTM will make on your source repository using the - option to CTM. + option to CTM. This is useful if you would like to keep logs of the changes, pre- or post- process the modified files in any - manner, or just are feeling a tad paranoid :-). + manner, or just are feeling a tad paranoid :-). @@ -25578,11 +25587,11 @@ subscribe freebsd-stable Making backups before updating Sometimes you may want to backup all the files that would - be changed by a CTM update. + be changed by a CTM update. Specifying the option - causes CTM to backup all files that would be touched by a - given CTM delta to backup-file. + causes CTM to backup all files that would be touched by a + given CTM delta to backup-file. @@ -25590,26 +25599,27 @@ subscribe freebsd-stable Restricting the files touched by an update Sometimes you would be interested in restricting the scope - of a given CTM update, or may be interested in extracting just + of a given CTM update, or may be interested in extracting just a few files from a sequence of deltas. - You can control the list of files that CTM would operate + You can control the list of files that CTM would operate on by specifying filtering regular expressions using the and options. For example, to extract an up-to-date copy of lib/libc/Makefile from your collection of - saved CTM deltas, run the commands: + saved CTM deltas, run the commands: + &prompt.root; cd /where/ever/you/want/to/extract/it/ &prompt.root; ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.* - + - For every file specified in a CTM delta, the + For every file specified in a CTM delta, the and options are applied in the order given on the command line. The file - is processed by CTM only if it is marked as eligible after all + is processed by CTM only if it is marked as eligible after all the and options are applied to it. @@ -25619,7 +25629,8 @@ subscribe freebsd-stable Future plans for <application>CTM</application> - Tons of them: + Tons of them: + @@ -25633,7 +25644,6 @@ subscribe freebsd-stable - The bad news is that I am very busy, so any help in doing this will be most welcome. And do not forget to tell me what @@ -25646,9 +25656,8 @@ subscribe freebsd-stable All the DES infected (e.g. export controlled) source is not included. You will get the international version only. - If sufficient interest appears, we will set up a sec-cur sequence too. There is a - sequence of deltas for the ports + If sufficient interest appears, we will set up a sec-cur sequence too. There is a + sequence of deltas for the ports collection too, but interest has not been all that high yet. Tell me if you want an email list for that too and we will consider setting it up. @@ -25658,7 +25667,7 @@ subscribe freebsd-stable Thanks! - + &a.bde; @@ -25678,7 +25687,7 @@ subscribe freebsd-stable Stephen McKay - wrote ctm_[rs]mail, + wrote ctm_[rs]mail, much appreciated. @@ -25701,14 +25710,14 @@ subscribe freebsd-stable - + - CVSup + <application>CVSup</application> Contributed by &a.jdp;. @@ -25717,20 +25726,20 @@ subscribe freebsd-stable id="cvsup-intro"> Introduction - CVSup is a software package for distributing and updating + CVSup is a software package for distributing and updating source trees from a master CVS repository on a remote server host. The FreeBSD sources are maintained in a CVS repository on - a central development machine in California. With CVSup, + a central development machine in California. With CVSup, FreeBSD users can easily keep their own source trees up to date. - CVSup uses the so-called pull model of + CVSup uses the so-called pull model of updating. Under the pull model, each client asks the server for updates, if and when they are wanted. The server waits passively for update requests from its clients. Thus all updates are instigated by the client. The server never sends - unsolicited updates. Users must either run the CVSup client - manually to get an update, or they must set up a cron job to run + unsolicited updates. Users must either run the CVSup client + manually to get an update, or they must set up a cron job to run it automatically on a regular basis. The term CVSup, capitalized just so, refers to the entire @@ -25739,11 +25748,11 @@ subscribe freebsd-stable runs at each of the FreeBSD mirror sites. As you read the FreeBSD documentation and mailing lists, you - may see references to sup. Sup was the - predecessor of CVSup, and it served a similar purpose. CVSup is + may see references to sup. Sup was the + predecessor of CVSup, and it served a similar purpose. CVSup is in used in much the same way as sup and, in fact, uses - configuration files which are backward-compatible with sup's. - Sup is no longer used in the FreeBSD project, because CVSup is + configuration files which are backward-compatible with sup's. + Sup is no longer used in the FreeBSD project, because CVSup is both faster and more flexible. @@ -25752,7 +25761,7 @@ subscribe freebsd-stable id="cvsup-install"> Installation - The easiest way to install CVSup if you are running FreeBSD + The easiest way to install CVSup if you are running FreeBSD 2.2 or later is to use either the port from the FreeBSD or the corresponding binary package, depending on whether you prefer to roll your own or not. @@ -25762,16 +25771,16 @@ subscribe freebsd-stable FreeBSD-2.1.{6,7}. You can easily use the port, however, just as with FreeBSD 2.2. Simply unpack the tar file, cd to the cvsup subdirectory and type make install. - Because CVSup is written in Modula-3, both the package and the port require that the Modula-3 runtime libraries be installed. These are available as the lang/modula-3-lib port and the lang/modula-3-lib-3.6 package. If you follow the same directions as for cvsup, these libraries will be compiled and/or installed automatically when you install the CVSup port or package. + Because CVSup is written in Modula-3, both the package and the port require that the Modula-3 runtime libraries be installed. These are available as the lang/modula-3-lib port and the lang/modula-3-lib-3.6 package. If you follow the same directions as for cvsup, these libraries will be compiled and/or installed automatically when you install the CVSup port or package. The Modula-3 libraries are rather large, and fetching and compiling them is not an instantaneous process. For that reason, a third option is provided. You can get statically linked FreeBSD executables for - CVSup from either the USA distribution site: + CVSup from either the USA distribution site: + - @@ -25790,11 +25799,11 @@ subscribe freebsd-stable - + or the German mirror: - + @@ -25813,7 +25822,7 @@ subscribe freebsd-stable - + Most users will need only the client. These executables are entirely self-contained, and they will run on any version of @@ -25821,7 +25830,7 @@ subscribe freebsd-stable In summary, your options for installing CVSup are: - + @@ -25839,7 +25848,7 @@ subscribe freebsd-stable - + @@ -25847,7 +25856,7 @@ subscribe freebsd-stable id="cvsup-config"> Configuration - CVSup's operation is controlled by a configuration file + CVSup's operation is controlled by a configuration file called the supfile. Beginning with FreeBSD-2.2, there are some sample supfiles in the directory The information in a supfile answers the following questions for cvsup: - + @@ -25885,7 +25894,7 @@ subscribe freebsd-stable - + In the following sections, we will construct a typical supfile by answering each of these @@ -25899,16 +25908,16 @@ subscribe freebsd-stable Each remaining line describes a set of files that the user wishes to receive. The line begins with the name of a - "collection", a logical grouping of files defined by the server. + collection, a logical grouping of files defined by the server. The name of the collection tells the server which files you want. After the collection name come zero or more fields, separated by white space. These fields answer the questions listed above. There are two types of fields: flag fields and value fields. A flag field consists of a keyword standing - alone, e.g., or . A value field also begins + alone, e.g., delete or compress. A value field also begins with a keyword, but the keyword is followed without intervening white space by = and a second word. For example, - is a value field. + release=cvs is a value field. A supfile typically specifies more than one collection to receive. One way to structure a @@ -25916,38 +25925,38 @@ subscribe freebsd-stable fields explicitly for each collection. However, that tends to make the supfile lines quite long, and it is inconvenient because most fields are the same for all of the - collections in a supfile. CVSup provides a + collections in a supfile. CVSup provides a defaulting mechanism to avoid these problems. Lines beginning - with the special pseudo-collection name can be used + with the special pseudo-collection name *default can be used to set flags and values which will be used as defaults for the subsequent collections in the supfile. A default value can be overridden for an individual collection, by specifying a different value with the collection itself. Defaults can also be changed or augmented in mid-supfile by - additional lines. + additional *default lines. With this background, we will now proceed to construct a supfile for receiving and updating the main source tree of . - + Which files do you want to receive? - The files available via CVSup are organized into named - groups called "collections". The collections that are + The files available via CVSup are organized into named + groups called collections. The collections that are available are described . In this example, we wish to receive the entire main source tree for the FreeBSD system. There is - a single large collection which will give us all + a single large collection src-all which will give us all of that, except the export-controlled cryptography support. Let us assume for this example that we are in the USA or Canada. Then we can get the cryptography code - with one additional collection, . As a first + with one additional collection, cvs-crypto. As a first step toward constructing our supfile, we simply list these collections, one per line: @@ -25961,23 +25970,25 @@ cvs-crypto Which version(s) of them do you want? - With CVSup, you can receive virtually any version of + With CVSup, you can receive virtually any version of the sources that ever existed. That is possible because the cvsupd server works directly from the CVS repository, which contains all of the versions. You specify which one - of them you want using the and value + of them you want using the tag= and value fields. - WARNING: Be very - careful to specify any fields correctly. Some tags + + e very + careful to specify any tag= fields correctly. Some tags are valid only for certain collections of files. If you specify an incorrect or misspelled tag, CVSup will delete files which you probably do not want deleted. In particular, use only - tag=. for the + tag=. for the ports-* collections. - - The field names a symbolic tag in the + + + The tag= field names a symbolic tag in the repository. There are two kinds of tags, revision tags and branch tags. A revision tag refers to a specific revision. Its meaning stays the same from day to day. A @@ -25990,7 +26001,7 @@ cvs-crypto Here are the branch tags that users might be interested in: - + tag=. @@ -25998,7 +26009,7 @@ cvs-crypto FreeBSD-current. - The is not punctuation; it is the name + The . is not punctuation; it is the name of the tag. Valid for all collections. @@ -26024,7 +26035,7 @@ cvs-crypto - + Here are the revision tags that users might be interested in: @@ -26122,14 +26133,16 @@ cvs-crypto - WARNING: Be very - careful to type the tag name exactly as shown. CVSup + + Be very + careful to type the tag name exactly as shown. CVSup cannot distinguish between valid and invalid tags. If you - misspell the tag, CVSup will behave as though you had + misspell the tag, CVSup will behave as though you had specified a valid tag which happens to refer to no files at all. It will delete your existing sources in that case. - + + When you specify a branch tag, you normally receive the latest versions of the files on that line of development. If you wish to receive some past version, @@ -26146,7 +26159,8 @@ cvs-crypto There is an important special case that comes into - play if you specify neither a field nor a + play if you specify neither a tag= + field nor a date= field. In that case, you receive the actual RCS files directly from the server's CVS repository, rather than receiving a particular version. Developers generally @@ -26161,27 +26175,27 @@ cvs-crypto Where do you want to get them from? - We use the field to tell cvsup where to obtain + We use the host= field to tell cvsup where to obtain its updates. Any of the will do, though you should try to select one that's near to you. In this example, we'll use the primary FreeBSD distribution site, - "cvsup.FreeBSD.org": + cvsup.FreeBSD.org: *default host=cvsup.FreeBSD.org - On any particular run of cvsup, you can override this - setting on the command line, with . + On any particular run of cvsup, you can override this + setting on the command line, with . Where do you want to put them on your own machine? - The field tells cvsup where to put the files + The prefix= field tells cvsup where to put the files it receives. In this example, we will put the source files directly into our main source tree, /usr/src. The src directory is already implicit in the collections we have @@ -26194,12 +26208,12 @@ cvs-crypto - Where should cvsup maintain its status files?Where should cvsup maintain its status files? The cvsup client maintains certain status files in what is called the base directory. These files help - CVSup to work more efficiently, by keeping track of which + CVSup to work more efficiently, by keeping track of which updates you have already received. We will use the standard base directory, /usr/local/etc/cvsup: @@ -26212,7 +26226,7 @@ cvs-crypto need the above line. If your base directory does not already exist, now - would be a good time to create it. The cvsup client will + would be a good time to create it. The cvsup client will refuse to run if the base directory does not exist. @@ -26232,9 +26246,9 @@ cvs-crypto possibilities which are beyond the scope of this discussion. - delete gives CVSup permission to delete files. You - should always specify this, so that CVSup can keep your - source tree fully up to date. CVSup is careful to delete + delete gives CVSup permission to delete files. You + should always specify this, so that CVSup can keep your + source tree fully up to date. CVSup is careful to delete only those files for which it is responsible. Any extra files you happen to have will be left strictly alone. @@ -26268,27 +26282,27 @@ cvs-crypto - + - Running CVSup + Running <application>CVSup</application> You are now ready to try an update. The command line for doing this is quite simple: - &prompt.root; cvsup supfile + &prompt.root; cvsup supfile - where supfile is of course the name of the supfile you - have just created. Assuming you are running under X11, cvsup + where supfile is of course the name of the supfile you + have just created. Assuming you are running under X11, cvsup will display a GUI window with some buttons to do the usual - things. Press the "go" button, and watch it run. + things. Press the go button, and watch it run. Since you are updating your actual /usr/src tree in this - example, you will need to run the program as root so that cvsup + example, you will need to run the program as root so that cvsup has the permissions it needs to update your files. Having just created your configuration file, and having never used this program before, that might understandably make you nervous. @@ -26303,10 +26317,10 @@ cvs-crypto The directory you specify will be used as the destination - directory for all file updates. CVSup will examine your usual + directory for all file updates. CVSup will examine your usual files in /usr/src, but it will not modify or delete any of them. Any file updates will instead land in - /var/tmp/dest/usr/src. CVSup will also + /var/tmp/dest/usr/src. CVSup will also leave its base directory status files untouched when run this way. The new versions of those files will be written into the specified directory. As long as you have read access to @@ -26343,9 +26357,9 @@ cvs-crypto - CVSup File Collections + <application>CVSup</application> File Collections - The file collections available via CVSup are organized + The file collections available via CVSup are organized hierarchically. There are a few large collections, and they are divided into smaller sub-collections. Receiving a large collection is equivalent to receiving each of its @@ -26357,7 +26371,7 @@ cvs-crypto only by small groups of people for specialized purposes, and some mirror sites may not carry all of them. - + cvs-all release=cvs @@ -27016,14 +27030,14 @@ cvs-crypto - + Announcements, Questions, and Bug Reports - Most FreeBSD-related discussion of CVSup takes place on the + Most FreeBSD-related discussion of CVSup takes place on the &a.hackers;. New versions of the software are announced there, as well as on the &a.announce;. @@ -27114,7 +27128,8 @@ cvs-crypto The following tasks are considered to be urgent, usually because they represent something that is badly broken or sorely - needed: + needed: + @@ -27256,7 +27271,6 @@ cvs-crypto - @@ -27264,14 +27278,15 @@ cvs-crypto Medium priority tasks The following tasks need to be done, but not with any - particular urgency: + particular urgency: + Port AFS (Andrew File System) to FreeBSD Coordinator: - Alexander Seth - Jones + Jones @@ -27367,7 +27382,6 @@ cvs-crypto - @@ -27379,7 +27393,8 @@ cvs-crypto done anytime soon: The first 20 items are from Terry Lambert - <terry@lambert.org> + terry@lambert.org + @@ -27518,7 +27533,6 @@ cvs-crypto - @@ -27531,19 +27545,19 @@ cvs-crypto useful tasks which are suitable for "weekend hackers", or people without programming skills. - + If you run FreeBSD-current and have a good Internet - connection, there is a machine current.freebsd.org which + connection, there is a machine current.freebsd.org which builds a full release once a day - every now and again, try and install the latest release from it and report any failures in the process. - Read the freebsd-bugs mailing list. There might be a + Read the freebsd-bugs mailing list. There might be a problem you can comment constructively on or with patches you can test. Or you could even try to fix one of the problems yourself. @@ -27569,7 +27583,7 @@ cvs-crypto Read the freebsd-questions mailing list and the - newsgroup comp.unix.bsd.freebsd.misc occasionally (or even + newsgroup comp.unix.bsd.freebsd.misc occasionally (or even regularly). It can be very satisfying to share your expertise and help people solve their problems; sometimes you may even learn something new yourself! These forums can @@ -27618,7 +27632,7 @@ cvs-crypto - + @@ -27669,7 +27683,7 @@ cvs-crypto Changes to the documentation are overseen by the &a.doc;. Send submissions and changes (even small ones are welcome!) using - send-pr as described in + send-pr as described in . @@ -27698,14 +27712,20 @@ cvs-crypto Assuming that you can manage to secure fairly up-to-date sources to base your changes on, the next step is to produce a set of diffs to send to the FreeBSD maintainers. This is done with - the diff1 command, with the `context diff' - form being preferred. For example: - + the diff1 command, with the context diff + form being preferred. For example: + + &prompt.user; diff -c oldfile newfile - or + + + or + &prompt.user; diff -c -r olddir newdir - would generate such a set of context diffs for + + + would generate such a set of context diffs for the given source file or directory hierarchy. See the man page for diff1 for more details. @@ -27735,8 +27755,8 @@ cvs-crypto very busy and so you should only send mail to them where it is truly necessary. - Please refer to man 9 intro and - man 9 style for some information on + Please refer to man 9 intro and + man 9 style for some information on coding style. We would appreciate it if you were at least aware of this information before submitting code. @@ -27755,7 +27775,7 @@ cvs-crypto copyrights also invariably comes up. Acceptable copyrights for code included in FreeBSD are: - + @@ -27783,7 +27803,7 @@ cvs-crypto - + Contributions coming under any other type of copyright must be carefully reviewed before their inclusion into FreeBSD will be @@ -27795,7 +27815,7 @@ cvs-crypto To place a BSD-style copyright on your work, include the following text at the very beginning of every source code file you wish to protect, replacing the text between the - %% with the appropriate information. + %% with the appropriate information. Copyright (c) %%proper_years_here%% @@ -27823,7 +27843,9 @@ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. $Id$ - For your convenience, a copy of this text can + + + For your convenience, a copy of this text can be found in /usr/share/examples/etc/bsd-style-copyright. @@ -27907,8 +27929,8 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. #endif - Don't forget to add -DHAVE_SYS_PARAM_H to - the CFLAGS in the Makefile for this + Don't forget to add -DHAVE_SYS_PARAM_H to + the CFLAGS in the Makefile for this method. Once you have sys/param.h @@ -27941,7 +27963,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Use sparingly: - + @@ -27990,6 +28012,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. _FreeBSD_version + 2.0-RELEASE @@ -28133,10 +28156,10 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. you don't have to worry about old -current's; they are listed here just for your reference. - + In the hundreds of ports that have been done, there have - only been one or two cases where __FreeBSD__ + only 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. @@ -28172,7 +28195,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # Date created: 5 December 1994 # Whom: asami # -# $Id: handbook.sgml,v 1.42 1998-10-22 23:03:48 nik Exp $ +# $Id: handbook.sgml,v 1.43 1998-10-22 23:06:00 nik Exp $ # DISTNAME= oneko-1.1b @@ -28213,13 +28236,13 @@ USE_IMAKE= yes <filename>COMMENT</filename> This is the one-line description of the port. - PLEASE do not include the package name (or version - number of the software) in the comment. Here is - an example: + Please do not include the package name (or version + number of the software) in the comment. Here is + an example: A cat chasing a mouse all over the screen. - + @@ -28319,12 +28342,12 @@ lib/X11/oneko/mouse.xpm .tar.gz file, stick it in the directory ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/ and send mail to us using send-pr1 (please classify it as category - `ports' and class `change-request'). There is no need to + ports and class change-request). There is no need to upload the package, we will build it by ourselves. We will take a look, 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?!? :) + tree. Your name will also appear in the list of Additional + FreeBSD contributors on the FreeBSD Handbook and other files. + Isn't that great?!? :) @@ -28349,12 +28372,12 @@ lib/X11/oneko/mouse.xpm But do not worry if you do not really understand what bsd.port.mk is doing, not many people - do... :> + do... :> - - + + - + The fetch target is run. The fetch target is responsible for making sure that the tarball exists locally in ${DISTDIR}. @@ -28363,25 +28386,25 @@ lib/X11/oneko/mouse.xpm which is set in the Makefile, as well as our main ftp site at ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/, where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with ${FETCH}, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in ${DISTDIR} for future use and proceed. - + - + The extract target is run. It looks for your ports' distribution file in ${DISTDIR} (typically a gzip'd tarball) and unpacks it into a temporary subdirectory specified by ${WRKDIR} (defaults to work). - + - + The patch target is run. First, any patches defined in ${PATCHFILES} are applied. Second, if any patches are found in ${PATCHDIR} (defaults to the patches subdirectory), they are applied at this time in alphabetical order. - + - + The configure target is run. This can do any one of many different things. @@ -28410,9 +28433,9 @@ lib/X11/oneko/mouse.xpm - + - + The build target is run. This is responsible for descending into the ports' private working directory (${WRKSRC}) and @@ -28420,10 +28443,10 @@ lib/X11/oneko/mouse.xpm make will be used, otherwise the system make will be used. - + - - + + The above are the default actions. In addition, you can define targets pre-something or post-something, or put scripts @@ -28450,7 +28473,7 @@ lib/X11/oneko/mouse.xpm your Makefile. - The `main' targets (e.g., extract, configure, etc.) do nothing more than + The main targets (e.g., extract, configure, etc.) do nothing more than make sure all the stages up to that one is completed and call the real targets or scripts, and they are not intended to be changed. If you want to fix the extraction, fix @@ -28476,7 +28499,7 @@ lib/X11/oneko/mouse.xpm 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, we can `house' it ourselves by putting + non-standard formats, we can house it ourselves by putting it on ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/ as the last resort. Please refer to this location as ${MASTER_SITE_LOCAL}. Send mail to the &a.ports;if you are not sure what to do. @@ -28505,9 +28528,9 @@ lib/X11/oneko/mouse.xpm If your port requires significant user interaction/customization to compile or install, you should - take a look at one of Larry Wall's classic Configure scripts + take a look at one of Larry Wall's classic Configure scripts and perhaps do something similar yourself. The goal of the - new ports collection is to make each port as `plug-and-play' + 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. @@ -28558,8 +28581,8 @@ lib/X11/oneko/mouse.xpm Handling user input If your port requires user input to build, configure or - install, then set IS_INTERACTIVE in your - Makefile. This will allow `overnight builds' to skip your port + install, then set IS_INTERACTIVE in your + Makefile. This will allow overnight builds to skip your port if the user sets the variable BATCH in his environment (and if the user sets the variable INTERACTIVE, then only @@ -28601,7 +28624,7 @@ lib/X11/oneko/mouse.xpm - DISTNAME + <makevar>DISTNAME</makevar> You should set ${DISTNAME} to be the base name of your port. The default rules expect the distribution file @@ -28630,7 +28653,7 @@ DISTNAME=foozolix-1.0 - CATEGORIES + <makevar>CATEGORIES</makevar> When a package is created, it is put under /usr/ports/packages/All and links are @@ -28649,13 +28672,13 @@ DISTNAME=foozolix-1.0 - MASTER_SITES + <makevar>MASTER_SITES</makevar> Record the directory part of the ftp/http-URL pointing at the original tarball in ${MASTER_SITES}. Do not forget the trailing slash (/)! - The make macros will try to use this specification for + The make macros will try to use this specification for grabbing the distribution file with ${FETCH} if they cannot find it already on the system. @@ -28668,17 +28691,17 @@ DISTNAME=foozolix-1.0 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 MASTER_SITE_XCONTRIB, MASTER_SITE_GNU, - MASTER_SITE_PERL_CPAN, MASTER_SITE_TEX_CTAN, and - MASTER_SITE_SUNSITE. Simply set MASTER_SITE_SUBDIR to the - path with in the archive. Here is an example: + form using MASTER_SITE_XCONTRIB, MASTER_SITE_GNU, + MASTER_SITE_PERL_CPAN, MASTER_SITE_TEX_CTAN, and + MASTER_SITE_SUNSITE. Simply set MASTER_SITE_SUBDIR to the + path with in the archive. Here is an example: MASTER_SITES= ${MASTER_SITE_XCONTRIB} MASTER_SITE_SUBDIR= applications - + - The user can also set the MASTER_SITE_* variables in + The user can also set the MASTER_SITE_* variables in /etc/make.conf to override our choices, and use their favorite mirrors of these popular archives instead. @@ -28687,7 +28710,7 @@ MASTER_SITE_SUBDIR= applications - PATCHFILES + <makevar>PATCHFILES</makevar> If your port requires some additional patches that are available by ftp or http, set ${PATCHFILES} to the names of the @@ -28699,7 +28722,7 @@ MASTER_SITE_SUBDIR= applications (i.e., ${WKRSRC}) because it contains some extra pathnames, set ${PATCH_DIST_STRIP} accordingly. For instance, if all the pathnames in the patch has an extra - foozolix-1.0/ in front of the + foozolix-1.0/ in front of the filenames, then set PATCH_DIST_STRIP=-p1. @@ -28732,10 +28755,9 @@ MASTER_SITE_SUBDIR= applications - MAINTAINER + <makevar>MAINTAINER</makevar> - Set your mail-address here. Please. :) + Set your mail-address here. Please. :) For detailed description of the responsibility of maintainers, refer to - LIB_DEPENDS + <makevar>LIB_DEPENDS</makevar> This variable specifies the shared libraries this port - depends on. It is a list of lib:dir pairs where - lib is the name of the shared library, - and dir is the directory in which to + depends on. It is a list of lib:dir pairs where + lib is the name of the shared library, + and dir is the directory in which to find it in case it is not available. For example, LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg - will check for a shared jpeg library with + + + will check for a shared jpeg library with major version 6, and descend into the graphics/jpeg subdirectory of your ports tree to build and install it if it is not found. - The lib part is just an argument + The lib part is just an argument given to ldconfig -r | grep, so periods should be escaped by two backslashes like in the example above. @@ -28785,16 +28808,15 @@ LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg - RUN_DEPENDS + <makevar>RUN_DEPENDS</makevar> This variable specifies executables or files this port - depends on during run-time. It is a list of path:dir pairs where - path is the name of the executable or - file, and dir is the directory in which + depends on during run-time. It is a list of path:dir pairs where + path is the name of the executable or + file, and dir is the directory in which to find it in case it is not available. If - path starts with a slash - (/), it is treated as a file and its + path starts with a slash + (/), it is treated as a file and its existence is tested with test -e; otherwise, it is assumed to be an executable, and which -s is used to determine if the @@ -28805,7 +28827,9 @@ LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \ wish:${PORTSDIR}/x11/tk - will check if the file + + + will check if the file /usr/local/etc/innd exists, and build and install it from the news/inn subdirectory of the ports tree if it is not found. It will @@ -28823,45 +28847,49 @@ RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \ The dependency is checked from within the install target. Also, the name of the dependency is put in to the package so that - pkg_add will automatically install it if it + pkg_add will automatically install it if it is not on the user's system. - BUILD_DEPENDS + <makevar>BUILD_DEPENDS</makevar> This variable specifies executables or files this port - requires to build. Like RUN_DEPENDS, it is - a list of path:dir pairs. + requires to build. Like RUN_DEPENDS, it is + a list of path:dir pairs. For example, BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip - will check for an executable called + + + will check for an executable called unzip, and descend into the archivers/unzip subdirectory of your ports tree to build and install it if it is not found. - `build' here means everything from extracting to + build here means everything from extracting to compilation. The dependency is checked from within the extract target. - FETCH_DEPENDS + <makevar>FETCH_DEPENDS</makevar> This variable specifies executables or files this port requires to fetch. Like the previous two, it is a list of - path:dir pairs. For + path:dir pairs. For example, FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - will check for an executable called + + + will check for an executable called ncftp2, and descend into the net/ncftp2 subdirectory of your ports tree to build and install it if it is not found. @@ -28871,7 +28899,7 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - DEPENDS + <makevar>DEPENDS</makevar> If there is a dependency that does not fall into either of the above four categories, or your port requires to have @@ -28911,13 +28939,13 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - NO_INSTALL_MANPAGES + <makevar>NO_INSTALL_MANPAGES</makevar> - If the port uses imake but does not understand the + If the port uses imake but does not understand the install.man target, NO_INSTALL_MANPAGES=yes should be set. In addition, the author of the original port should be shot. - :> + :> @@ -28936,7 +28964,7 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - REQUIRES_MOTIF + <makevar>REQUIRES_MOTIF</makevar> If your port requires Motif, define this variable in the Makefile. This will prevent people who don't own a copy of @@ -28945,7 +28973,7 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - ${MOTIFLIB} + <makevar>${MOTIFLIB}</makevar> This variable will be set by bsd.port.mk to be the appropriate @@ -28953,7 +28981,8 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 use this wherever the Motif library is referenced in the Makefile or Imakefile. - There are two common cases: + There are two common cases: + @@ -28969,12 +28998,11 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - ${MOTIFLIB} (usually) - expands to or - /usr/X11R6/lib/libXm.a, so there is + expands to -L/usr/X11R6/lib -lXm or + /usr/X11R6/lib/libXm.a, so there is no need to add or in front. @@ -28993,7 +29021,7 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 the length of this section, but it is imperative to weave all the info files together. If done correctly, it will produce a beautiful listing, so please bear with me! - :) + :) First, this is what you (as a porter) need to know: @@ -29024,7 +29052,7 @@ Options: Look at the texinfo sources and make a patch to insert - @dircategory and @direntry + @dircategory and @direntry statements to files that don't have them. This is part of my patch: @@ -29061,7 +29089,7 @@ Options: @direntry section. - You can give the dir + You can give the dir entries to install-info as arguments ( and ) instead of patching the texinfo @@ -29069,7 +29097,7 @@ Options: because you need to duplicate the same information in three places (Makefile and - @exec/@unexec of + @exec/@unexec of PLIST; see below). However, if you have a Japanese (or other multibyte encoding) info files, you will have to use the extra arguments to install-info because makeinfo can't handle those texinfo @@ -29085,10 +29113,10 @@ Options: Since the texinfo sources are newer than the info files, they should be rebuilt when you type make; but many Makefiles don't include correct - dependencies for info files. In emacs' case, I had to + dependencies for info files. In emacs' case, I had to patch the main Makefile.in so it will descend into the man - subdirectory to rebuild the info pages. + subdirectory to rebuild the info pages. --- ./Makefile.in.org Mon Aug 19 21:12:19 1996 @@ -29112,7 +29140,7 @@ Options: info: $(INFO_TARGETS) dvi: $(DVI_TARGETS) - + The second hunk was necessary because the default target in the man subdir is called @@ -29130,7 +29158,7 @@ Options: dir file, delete it. Your port may not be doing it. Also, remove any commands that are otherwise mucking around with the - dir file. + dir file. --- ./Makefile.in.org Mon Aug 19 21:12:19 1996 @@ -29150,12 +29178,12 @@ Options: (cd $${thisdir}; \ ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \ chmod a+r ${infodir}/$$f); \ - + (This step is only necessary if you are modifying an - existing port.) Take a look at + existing port.) Take a look at pkg/PLIST and delete anything that is trying to patch up info/dir. They may be in pkg/INSTALL or some other @@ -29187,7 +29215,7 @@ diff -u -r1.15 PLIST target to the Makefile to create a dir file if it is not there. Also, call install-info with the - installed info files. + installed info files. Index: Makefile @@ -29210,7 +29238,7 @@ diff -u -r1.26 Makefile +.endfor .include <bsd.port.mk> - + Do not use anything other than /usr/share/info/dir and the above @@ -29223,10 +29251,10 @@ diff -u -r1.26 Makefile Edit PLIST and add equivalent - @exec statements and also - @unexec for pkg_delete. + @exec statements and also + @unexec for pkg_delete. You do not need to delete info/dir - with @unexec. + with @unexec. Index: pkg/PLIST @@ -29253,26 +29281,25 @@ diff -u -r1.15 PLIST +@exec install-info %D/info/ccmode %D/info/dir libexec/emacs/19.34/i386--freebsd/cvtmail libexec/emacs/19.34/i386--freebsd/digest-doc - + - The @unexec install-info - --delete commands have to be listed before + The @unexec install-info + --delete commands have to be listed before the info files themselves so they can read the files. - Also, the @exec install-info commands + Also, the @exec install-info commands have to be after the info files and the - @exec command that creates the the + @exec command that creates the the dir file. - Test and admire your work. Test and admire your work. :) The sequence I recommend is: make package, - pkg_delete, then - pkg_add. Check the dir file before and after each + pkg_delete, then + pkg_add. Check the dir file before and after each step. @@ -29301,12 +29328,12 @@ diff -u -r1.15 PLIST There are two variables you can set in the Makefile to handle the situations that arise frequently: - + - If the port has a `do not sell for profit' type of - license, set the variable NO_CDROM. We + If the port has a do not sell for profit type of + license, set the variable NO_CDROM. 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. @@ -29316,7 +29343,7 @@ diff -u -r1.15 PLIST 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 - NO_PACKAGE. We will make sure such + NO_PACKAGE. 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. @@ -29324,15 +29351,15 @@ diff -u -r1.15 PLIST 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 RESTRICTED to be the + (e.g., crypto stuff) or has a no commercial use license, + set the variable RESTRICTED to be the string describing the reason why. For such ports, the distfiles/packages will not be available even from our ftp sites. - + The GNU General Public License (GPL), both version 1 @@ -29355,7 +29382,7 @@ diff -u -r1.15 PLIST sites. The next step is to send a mail to the maintainer, if one is - listed in the port's Makefile. That person may already be + listed in the port's Makefile. 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). @@ -29365,14 +29392,14 @@ diff -u -r1.15 PLIST 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 (i.e., if your modified ports - directory is called superedit + directory is called superedit and the original as in our tree is superedit.bak, then send us the result of - diff -ruN superedit.bak - superedit). Please examine the output to make + diff -ruN superedit.bak + superedit). 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 send-pr1 - (category `ports'). Please mention any added or deleted files + (category ports). 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 @@ -29388,7 +29415,7 @@ diff -u -r1.15 PLIST - WRKDIR + <makevar>WRKDIR</makevar> Do not leave anything valuable lying around in the work subdirectory, make clean will @@ -29406,8 +29433,7 @@ diff -u -r1.15 PLIST Do include package information, i.e. COMMENT, DESCR, and - PLIST, in pkg. + PLIST, in pkg. Note that these files are not used only for packaging @@ -29423,30 +29449,30 @@ diff -u -r1.15 PLIST Do compress manpages and strip binaries. If the original source already strips the binary, fine; otherwise, you can add a post-install rule to do it - yourself. Here is an example: + yourself. Here is an example: post-install: strip ${PREFIX}/bin/xdl - + - Use the file command on the + Use the file command on the installed executable to check whether the binary is stripped or not. If it does not say `not stripped', it is stripped. - To automagically compress the manpages, use the MAN[1-9LN] + To automagically compress the manpages, use the MAN[1-9LN] variables. They will check the variable - NOMANCOMPRESS that the user can set in + NOMANCOMPRESS that the user can set in /etc/make.conf to disable man page compression. Place them last in the section below the - MAINTAINER variable. Here is an example: + MAINTAINER variable. Here is an example: MAN1= foo.1 bar.1 MAN5= foo.conf.5 MAN8= baz.8 - + This is not usually necessary with ports that are X @@ -29454,25 +29480,25 @@ MAN8= baz.8 If your port anchors its man tree somewhere other than - PREFIX, you can use the - MANPREFIX to set it. Also, if only manpages + PREFIX, you can use the + MANPREFIX to set it. Also, if only manpages in certain section go in a non-standard place, such as many Perl modules ports, you can set individual man paths using - MANsectPREFIX - (where sect is one of 1-9, L or + MANsectPREFIX + (where sect is one of 1-9, L or N). - INSTALL_* macros + <makevar>INSTALL_*</makevar> macros Do use the macros provided in bsd.port.mk to ensure correct modes and ownership of files in your own *-install targets. They are: - + @@ -29497,7 +29523,7 @@ MAN8= baz.8 - + These are basically the install command with all the appropriate flags. See below for an example on how to use them. @@ -29511,13 +29537,11 @@ MAN8= baz.8 package is installed with pkg_add you can do with via the pkg/INSTALL script. This script will automatically be added to the package, and will be run twice - by pkg_add. The first time will as INSTALL ${PKGNAME} PRE-INSTALL and the - second time as INSTALL ${PKGNAME} - POST-INSTALL. $2 can be tested to determine which + by pkg_add. The first time will as INSTALL ${PKGNAME} PRE-INSTALL and the + second time as INSTALL ${PKGNAME} + POST-INSTALL. $2 can be tested to determine which mode the script is being run in. The - PKG_PREFIX environmental variable will be + PKG_PREFIX environmental variable will be set to the package installation directory. See man pkg_add1 for additional information. @@ -29559,8 +29583,8 @@ MAN8= baz.8 whole ${PKGNAME}. Make the installation dependent to the variable - NOPORTDOCS so that users can disable it in - /etc/make.conf, like this: + NOPORTDOCS so that users can disable it in + /etc/make.conf, like this: post-install: @@ -29568,11 +29592,11 @@ post-install: ${MKDIR}${PREFIX}/share/doc/xv ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv .endif - + Do not forget to add them to pkg/PLIST too! (Do not worry about - NOPORTDOCS here; there is currently no way + NOPORTDOCS here; there is currently no way for the packages to read variables from /etc/make.conf.) @@ -29589,13 +29613,13 @@ post-install: - DIST_SUBDIR + <makevar>DIST_SUBDIR</makevar> Do not let your port clutter /usr/ports/distfiles. 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., - `Makefile'), set ${DIST_SUBDIR} to the name of the + Makefile), set ${DIST_SUBDIR} to the name of the port (${PKGNAME} without the version part should work fine). This will change ${DISTDIR} from the default /usr/ports/distfiles to @@ -29606,7 +29630,7 @@ post-install: It will also look at the subdirectory with the same name on the backup master site at ftp.freebsd.org. (Setting ${DISTDIR} explicitly in your - Makefile will not accomplish this, so please use ${DIST_SUBDIR}.) + Makefile will not accomplish this, so please use ${DIST_SUBDIR}.) This does not affect the ${MASTER_SITES} you define in your @@ -29630,10 +29654,8 @@ post-install: 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 ($) signs, and typically start with - $Id or $RCS. + will fail. RCS strings are surrounded by dollar ($) signs, and typically start with + $Id or $RCS. @@ -29644,8 +29666,8 @@ post-install: diff 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, Makefiles when the - port uses Imake or GNU configure, etc., are unnecessary and + particular, diffs between two backup files, Makefiles when the + port uses Imake or GNU configure, etc., are unnecessary and should be deleted. Also, if you had to delete a file, then you can do it in the post-extract target rather than as part of the patch. Once you are happy @@ -29655,7 +29677,7 @@ post-install: - PREFIX + <makevar>PREFIX</makevar> Do try to make your port install relative to ${PREFIX}. (The value of this variable will be set to ${LOCALBASE} (default @@ -29666,7 +29688,7 @@ post-install: Not hard-coding /usr/local or /usr/X11R6 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 imake, this is + needs of other sites. For X ports that use imake, this is automatic; otherwise, this can often be done by simply replacing the occurrences of /usr/local (or /usr/X11R6 for X ports that do not @@ -29679,22 +29701,26 @@ post-install: can be reassigned in your Makefile or in the user's environment. However, it is strongly discouraged for individual ports to set this variable explicitly in the - Makefiles. (If your port is an X port but does not use imake, + Makefiles. (If your port is an X port but does not use imake, set USE_X11=yes; this is quite different from setting PREFIX=/usr/X11R6.) Also, refer to programs/files from other ports with the variables mentioned above, not explicit pathnames. For instance, if your port requires a macro - PAGER to be the full pathname of less, use the compiler flag: + PAGER to be the full pathname of less, use the compiler flag: -DPAGER=\"${PREFIX}/bin/less\" - or + + + or -DPAGER=\"${LOCALBASE}/bin/less\" - if this is an X port, instead of -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. + + + if this is an X port, instead of -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. @@ -29717,7 +29743,7 @@ post-install: files). See man hier7 for details, the rule governing /usr pretty much applies to /usr/local too. The - exception are ports dealing with USENET `news'. They may use + exception are ports dealing with USENET news. They may use ${PREFIX}/news as a destination for their files. @@ -29732,20 +29758,20 @@ post-install: ${PREFIX}/lib) to register it into the shared library cache. - Also, add an @exec line to your + Also, add an @exec line to your pkg/PLIST file so that a user who installed the package can start using the shared library immediately. This line should immediately follow the line - for the shared library itself, as in: + for the shared library itself, as in: lib/libtcl80.so.1.0 @exec /sbin/ldconfig -m %D/lib - + Never, ever, ever add a line that says ldconfig without any - arguments to your Makefile or pkg/PLIST. This will reset the + arguments to your Makefile or pkg/PLIST. This will reset the shared library cache to the contents of /usr/lib only, and will royally screw up the user's machine (Help, xinit does not run anymore after I @@ -29804,11 +29830,10 @@ msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh Do look at existing examples and the bsd.port.mk file before asking us - questions! ;) + questions! ;) Do ask us questions if you have any trouble! Do not just - beat your head against a wall! :) + beat your head against a wall! :) @@ -29925,7 +29950,7 @@ pre-install: doesn't look like that, set ${PKGNAME} to something in that format. - + @@ -29946,7 +29971,7 @@ pre-install: convert the name (or at least the first letter) to lowercase. If the software in question really is called that way, you can have numbers, hyphens and underscores in - the name too (like `kinput2'). + the name too (like kinput2). @@ -29967,7 +29992,7 @@ pre-install: - + Here are some (real) examples on how to convert a ${DISTNAME} into a suitable ${PKGNAME}: @@ -29980,6 +30005,7 @@ pre-install: Reason + mule-2.2.2. @@ -30089,7 +30115,7 @@ pre-install: 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! - :) + :) diff --git a/en_US.ISO8859-1/books/handbook/book.sgml b/en_US.ISO8859-1/books/handbook/book.sgml index 273b43fa79..784b90754b 100644 --- a/en_US.ISO8859-1/books/handbook/book.sgml +++ b/en_US.ISO8859-1/books/handbook/book.sgml @@ -2427,7 +2427,7 @@ password. Remember to use binary (also known as image) mode!] # Date created: 13 November 1997 # Whom: jraynard # -# $Id: handbook.sgml,v 1.1 1998/04/01 18:25:32 nik +# $Id$ # DISTNAME= ElectricFence-2.0.5 @@ -24997,13 +24997,14 @@ an A record in the DNS for "customer.com". Who needs FreeBSD-current? FreeBSD-current is made generally available for 3 primary - interest groups: + interest groups: + Members of the FreeBSD group who are actively working on some part of the source tree and for whom keeping - `current' is an absolute requirement. + current is an absolute requirement. @@ -25023,14 +25024,13 @@ an A record in the DNS for "customer.com". - - What is FreeBSD-current <emphasis>NOT</emphasis>? + What is FreeBSD-current <emphasis>not</emphasis>? + - @@ -25058,14 +25058,14 @@ an A record in the DNS for "customer.com". - + Using FreeBSD-current - + @@ -25080,7 +25080,7 @@ an A record in the DNS for "customer.com". Yo, Everybody! Before you rebuild /usr/src, you must rebuild the kernel or your system will crash horribly!). - The cvs-all mailing list will allow you + The cvs-all mailing list will allow you to see the commit log entry for each change as it is made along with any pertinent information on possible side-effects. To join these lists, send mail to @@ -25089,21 +25089,23 @@ an A record in the DNS for "customer.com". subscribe freebsd-current subscribe cvs-all - In the - body of your message. Optionally, you can also say `help' + + + in the + body of your message. Optionally, you can also say help and Majordomo will send you full help on how to subscribe and unsubscribe to the various other mailing lists we support. - Grab the sources from ftp.FreeBSD.ORG. You can do - this in three ways: + Grab the sources from ftp.FreeBSD.ORG. You can do + this in three ways: - Use the + Use the facility. Unless you have a good TCP/IP connection at a flat rate, this is the way to do it. @@ -25115,29 +25117,33 @@ subscribe cvs-all - Use ftp. The source tree for FreeBSD-current is + Use ftp. The source tree for FreeBSD-current is always exported on: ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current We also use `wu-ftpd' which allows compressed/tar'd grabbing of whole trees. e.g. you see: + URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current">ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current We also use wu-ftpd which allows compressed/tar'd grabbing of whole trees. e.g. you see: usr.bin/lex - You can do: + + + You can do: ftp> cd usr.bin ftp> get lex.tar.Z - And it will get the whole directory for you as a compressed tar file. + + + and it will get the whole directory for you as a compressed tar file. - + Essentially, if you need rapid on-demand access to the source and communications bandwidth is not a consideration, - use cvsup or ftp. Otherwise, use CTM. + use cvsup or ftp. Otherwise, use CTM. @@ -25170,8 +25176,6 @@ subscribe cvs-all - - @@ -25242,13 +25246,13 @@ subscribe freebsd-stable - Grab the sources from ftp.FreeBSD.ORG. You can do + Grab the sources from ftp.FreeBSD.ORG. You can do this in three ways: - Use the + Use the facility. Unless you have a good TCP/IP connection at a flat rate, this is the way to do it. @@ -25260,22 +25264,26 @@ subscribe freebsd-stable - Use ftp. The source tree for FreeBSD-stable is + Use ftp. The source tree for FreeBSD-stable is always exported on: ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-stable - We also use `wu-ftpd' which allows + We also use wu-ftpd which allows compressed/tar'd grabbing of whole trees. e.g. you - see: + see: usr.bin/lex - You can do: + + + You can do: ftp> cd usr.bin ftp> get lex.tar.Z - And it will get the + + + and it will get the whole directory for you as a compressed tar file. @@ -25288,7 +25296,7 @@ subscribe freebsd-stable Essentially, if you need rapid on-demand access to the source and communications bandwidth is not a consideration, - use cvsup or ftp. Otherwise, use CTM. + use cvsup or ftp. Otherwise, use CTM. @@ -25318,9 +25326,9 @@ subscribe freebsd-stable There are various ways of using an Internet (or email) connection to stay up-to-date with any given area of the FreeBSD project sources, or all areas, depending on what interests you. The - primary services we offer are CVSup and CTM. + primary services we offer are CVSup and CTM. - CVSup uses the + CVSup uses the pull model of updating. The user (or a cron script) invokes the cvsup program, and it interacts with a cvsupd server @@ -25337,27 +25345,27 @@ subscribe freebsd-stable its previous run is executed several times a day on the master archive, any detected changes being compressed, stamped with a sequence-number and encoded for transmission over email (printable - ASCII only). Once received, these "CTM deltas" can then be handed + ASCII only). Once received, these CTM deltas can then be handed to the ctm_rmail1 utility which will automatically decode, verify and apply the changes to the user's copy of the sources. This - process is far more efficient than CVSup, and places less strain on + process is far more efficient than CVSup, and places less strain on our server resources since it is a push rather than a pull model. There are other trade-offs, of course. If you inadvertently - wipe out portions of your archive, CVSup will detect and rebuild the - damaged portions for you. CTM won't do this, and if you wipe some + wipe out portions of your archive, CVSup will detect and rebuild the + damaged portions for you. CTM won't do this, and if you wipe some portion of your source tree out (and don't have it backed up) then - you will have to start from scratch (from the most recent CVS "base - delta") and rebuild it all. + you will have to start from scratch (from the most recent CVS base + delta) and rebuild it all. - For more information on CTM and CVSup, please see one of the + For more information on CTM and CVSup, please see one of the following sections: - CTM + <application>CTM</application> Contributed by &a.phk;. Updated 19-October-1997. @@ -25472,7 +25480,7 @@ subscribe freebsd-stable produced subsequently to it. First you should determine what you already have. Everyone - can start from an Empty directory. However, since the trees + can start from an empty directory. However, since the trees are many tens of megabytes, you should prefer to start from something already at hand. If you have a RELEASE CD, you can copy or extract an initial source from it. This will save a @@ -25483,7 +25491,7 @@ subscribe freebsd-stable into a CTM supported tree. You can recognize these transition deltas by the - X appended to the number + X appended to the number (src-cur.3210XEmpty.gz for instance). The designation following the X corresponds to the origin of your initial seed. Empty is @@ -25501,11 +25509,12 @@ subscribe freebsd-stable Using <application>CTM</application> in your daily life - To apply the deltas, simply say: + To apply the deltas, simply say: + &prompt.root; cd /where/ever/you/want/the/stuff &prompt.root; ctm -v -v /where/you/store/your/deltas/src-xxx.* - + CTM understands deltas which have been put through gzip, so you do not @@ -25542,7 +25551,7 @@ subscribe freebsd-stable Keeping your local changes As a developer one would like to experiment with and change - files in the source tree. CTM supports local modifications in a + files in the source tree. CTM supports local modifications in a limited way: before checking for the presence of a file foo, it first looks for foo.ctm. If this file exists, CTM will @@ -25557,20 +25566,20 @@ subscribe freebsd-stable - Other interesting CTM options + Other interesting <application>CTM</application> options Finding out exactly what would be touched by an update - You can determine the list of changes that CTM will make + You can determine the list of changes that CTM will make on your source repository using the - option to CTM. + option to CTM. This is useful if you would like to keep logs of the changes, pre- or post- process the modified files in any - manner, or just are feeling a tad paranoid :-). + manner, or just are feeling a tad paranoid :-). @@ -25578,11 +25587,11 @@ subscribe freebsd-stable Making backups before updating Sometimes you may want to backup all the files that would - be changed by a CTM update. + be changed by a CTM update. Specifying the option - causes CTM to backup all files that would be touched by a - given CTM delta to backup-file. + causes CTM to backup all files that would be touched by a + given CTM delta to backup-file. @@ -25590,26 +25599,27 @@ subscribe freebsd-stable Restricting the files touched by an update Sometimes you would be interested in restricting the scope - of a given CTM update, or may be interested in extracting just + of a given CTM update, or may be interested in extracting just a few files from a sequence of deltas. - You can control the list of files that CTM would operate + You can control the list of files that CTM would operate on by specifying filtering regular expressions using the and options. For example, to extract an up-to-date copy of lib/libc/Makefile from your collection of - saved CTM deltas, run the commands: + saved CTM deltas, run the commands: + &prompt.root; cd /where/ever/you/want/to/extract/it/ &prompt.root; ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.* - + - For every file specified in a CTM delta, the + For every file specified in a CTM delta, the and options are applied in the order given on the command line. The file - is processed by CTM only if it is marked as eligible after all + is processed by CTM only if it is marked as eligible after all the and options are applied to it. @@ -25619,7 +25629,8 @@ subscribe freebsd-stable Future plans for <application>CTM</application> - Tons of them: + Tons of them: + @@ -25633,7 +25644,6 @@ subscribe freebsd-stable - The bad news is that I am very busy, so any help in doing this will be most welcome. And do not forget to tell me what @@ -25646,9 +25656,8 @@ subscribe freebsd-stable All the DES infected (e.g. export controlled) source is not included. You will get the international version only. - If sufficient interest appears, we will set up a sec-cur sequence too. There is a - sequence of deltas for the ports + If sufficient interest appears, we will set up a sec-cur sequence too. There is a + sequence of deltas for the ports collection too, but interest has not been all that high yet. Tell me if you want an email list for that too and we will consider setting it up. @@ -25658,7 +25667,7 @@ subscribe freebsd-stable Thanks! - + &a.bde; @@ -25678,7 +25687,7 @@ subscribe freebsd-stable Stephen McKay - wrote ctm_[rs]mail, + wrote ctm_[rs]mail, much appreciated. @@ -25701,14 +25710,14 @@ subscribe freebsd-stable - + - CVSup + <application>CVSup</application> Contributed by &a.jdp;. @@ -25717,20 +25726,20 @@ subscribe freebsd-stable id="cvsup-intro"> Introduction - CVSup is a software package for distributing and updating + CVSup is a software package for distributing and updating source trees from a master CVS repository on a remote server host. The FreeBSD sources are maintained in a CVS repository on - a central development machine in California. With CVSup, + a central development machine in California. With CVSup, FreeBSD users can easily keep their own source trees up to date. - CVSup uses the so-called pull model of + CVSup uses the so-called pull model of updating. Under the pull model, each client asks the server for updates, if and when they are wanted. The server waits passively for update requests from its clients. Thus all updates are instigated by the client. The server never sends - unsolicited updates. Users must either run the CVSup client - manually to get an update, or they must set up a cron job to run + unsolicited updates. Users must either run the CVSup client + manually to get an update, or they must set up a cron job to run it automatically on a regular basis. The term CVSup, capitalized just so, refers to the entire @@ -25739,11 +25748,11 @@ subscribe freebsd-stable runs at each of the FreeBSD mirror sites. As you read the FreeBSD documentation and mailing lists, you - may see references to sup. Sup was the - predecessor of CVSup, and it served a similar purpose. CVSup is + may see references to sup. Sup was the + predecessor of CVSup, and it served a similar purpose. CVSup is in used in much the same way as sup and, in fact, uses - configuration files which are backward-compatible with sup's. - Sup is no longer used in the FreeBSD project, because CVSup is + configuration files which are backward-compatible with sup's. + Sup is no longer used in the FreeBSD project, because CVSup is both faster and more flexible. @@ -25752,7 +25761,7 @@ subscribe freebsd-stable id="cvsup-install"> Installation - The easiest way to install CVSup if you are running FreeBSD + The easiest way to install CVSup if you are running FreeBSD 2.2 or later is to use either the port from the FreeBSD or the corresponding binary package, depending on whether you prefer to roll your own or not. @@ -25762,16 +25771,16 @@ subscribe freebsd-stable FreeBSD-2.1.{6,7}. You can easily use the port, however, just as with FreeBSD 2.2. Simply unpack the tar file, cd to the cvsup subdirectory and type make install. - Because CVSup is written in Modula-3, both the package and the port require that the Modula-3 runtime libraries be installed. These are available as the lang/modula-3-lib port and the lang/modula-3-lib-3.6 package. If you follow the same directions as for cvsup, these libraries will be compiled and/or installed automatically when you install the CVSup port or package. + Because CVSup is written in Modula-3, both the package and the port require that the Modula-3 runtime libraries be installed. These are available as the lang/modula-3-lib port and the lang/modula-3-lib-3.6 package. If you follow the same directions as for cvsup, these libraries will be compiled and/or installed automatically when you install the CVSup port or package. The Modula-3 libraries are rather large, and fetching and compiling them is not an instantaneous process. For that reason, a third option is provided. You can get statically linked FreeBSD executables for - CVSup from either the USA distribution site: + CVSup from either the USA distribution site: + - @@ -25790,11 +25799,11 @@ subscribe freebsd-stable - + or the German mirror: - + @@ -25813,7 +25822,7 @@ subscribe freebsd-stable - + Most users will need only the client. These executables are entirely self-contained, and they will run on any version of @@ -25821,7 +25830,7 @@ subscribe freebsd-stable In summary, your options for installing CVSup are: - + @@ -25839,7 +25848,7 @@ subscribe freebsd-stable - + @@ -25847,7 +25856,7 @@ subscribe freebsd-stable id="cvsup-config"> Configuration - CVSup's operation is controlled by a configuration file + CVSup's operation is controlled by a configuration file called the supfile. Beginning with FreeBSD-2.2, there are some sample supfiles in the directory The information in a supfile answers the following questions for cvsup: - + @@ -25885,7 +25894,7 @@ subscribe freebsd-stable - + In the following sections, we will construct a typical supfile by answering each of these @@ -25899,16 +25908,16 @@ subscribe freebsd-stable Each remaining line describes a set of files that the user wishes to receive. The line begins with the name of a - "collection", a logical grouping of files defined by the server. + collection, a logical grouping of files defined by the server. The name of the collection tells the server which files you want. After the collection name come zero or more fields, separated by white space. These fields answer the questions listed above. There are two types of fields: flag fields and value fields. A flag field consists of a keyword standing - alone, e.g., or . A value field also begins + alone, e.g., delete or compress. A value field also begins with a keyword, but the keyword is followed without intervening white space by = and a second word. For example, - is a value field. + release=cvs is a value field. A supfile typically specifies more than one collection to receive. One way to structure a @@ -25916,38 +25925,38 @@ subscribe freebsd-stable fields explicitly for each collection. However, that tends to make the supfile lines quite long, and it is inconvenient because most fields are the same for all of the - collections in a supfile. CVSup provides a + collections in a supfile. CVSup provides a defaulting mechanism to avoid these problems. Lines beginning - with the special pseudo-collection name can be used + with the special pseudo-collection name *default can be used to set flags and values which will be used as defaults for the subsequent collections in the supfile. A default value can be overridden for an individual collection, by specifying a different value with the collection itself. Defaults can also be changed or augmented in mid-supfile by - additional lines. + additional *default lines. With this background, we will now proceed to construct a supfile for receiving and updating the main source tree of . - + Which files do you want to receive? - The files available via CVSup are organized into named - groups called "collections". The collections that are + The files available via CVSup are organized into named + groups called collections. The collections that are available are described . In this example, we wish to receive the entire main source tree for the FreeBSD system. There is - a single large collection which will give us all + a single large collection src-all which will give us all of that, except the export-controlled cryptography support. Let us assume for this example that we are in the USA or Canada. Then we can get the cryptography code - with one additional collection, . As a first + with one additional collection, cvs-crypto. As a first step toward constructing our supfile, we simply list these collections, one per line: @@ -25961,23 +25970,25 @@ cvs-crypto Which version(s) of them do you want? - With CVSup, you can receive virtually any version of + With CVSup, you can receive virtually any version of the sources that ever existed. That is possible because the cvsupd server works directly from the CVS repository, which contains all of the versions. You specify which one - of them you want using the and value + of them you want using the tag= and value fields. - WARNING: Be very - careful to specify any fields correctly. Some tags + + e very + careful to specify any tag= fields correctly. Some tags are valid only for certain collections of files. If you specify an incorrect or misspelled tag, CVSup will delete files which you probably do not want deleted. In particular, use only - tag=. for the + tag=. for the ports-* collections. - - The field names a symbolic tag in the + + + The tag= field names a symbolic tag in the repository. There are two kinds of tags, revision tags and branch tags. A revision tag refers to a specific revision. Its meaning stays the same from day to day. A @@ -25990,7 +26001,7 @@ cvs-crypto Here are the branch tags that users might be interested in: - + tag=. @@ -25998,7 +26009,7 @@ cvs-crypto FreeBSD-current. - The is not punctuation; it is the name + The . is not punctuation; it is the name of the tag. Valid for all collections. @@ -26024,7 +26035,7 @@ cvs-crypto - + Here are the revision tags that users might be interested in: @@ -26122,14 +26133,16 @@ cvs-crypto - WARNING: Be very - careful to type the tag name exactly as shown. CVSup + + Be very + careful to type the tag name exactly as shown. CVSup cannot distinguish between valid and invalid tags. If you - misspell the tag, CVSup will behave as though you had + misspell the tag, CVSup will behave as though you had specified a valid tag which happens to refer to no files at all. It will delete your existing sources in that case. - + + When you specify a branch tag, you normally receive the latest versions of the files on that line of development. If you wish to receive some past version, @@ -26146,7 +26159,8 @@ cvs-crypto There is an important special case that comes into - play if you specify neither a field nor a + play if you specify neither a tag= + field nor a date= field. In that case, you receive the actual RCS files directly from the server's CVS repository, rather than receiving a particular version. Developers generally @@ -26161,27 +26175,27 @@ cvs-crypto Where do you want to get them from? - We use the field to tell cvsup where to obtain + We use the host= field to tell cvsup where to obtain its updates. Any of the will do, though you should try to select one that's near to you. In this example, we'll use the primary FreeBSD distribution site, - "cvsup.FreeBSD.org": + cvsup.FreeBSD.org: *default host=cvsup.FreeBSD.org - On any particular run of cvsup, you can override this - setting on the command line, with . + On any particular run of cvsup, you can override this + setting on the command line, with . Where do you want to put them on your own machine? - The field tells cvsup where to put the files + The prefix= field tells cvsup where to put the files it receives. In this example, we will put the source files directly into our main source tree, /usr/src. The src directory is already implicit in the collections we have @@ -26194,12 +26208,12 @@ cvs-crypto - Where should cvsup maintain its status files?Where should cvsup maintain its status files? The cvsup client maintains certain status files in what is called the base directory. These files help - CVSup to work more efficiently, by keeping track of which + CVSup to work more efficiently, by keeping track of which updates you have already received. We will use the standard base directory, /usr/local/etc/cvsup: @@ -26212,7 +26226,7 @@ cvs-crypto need the above line. If your base directory does not already exist, now - would be a good time to create it. The cvsup client will + would be a good time to create it. The cvsup client will refuse to run if the base directory does not exist. @@ -26232,9 +26246,9 @@ cvs-crypto possibilities which are beyond the scope of this discussion. - delete gives CVSup permission to delete files. You - should always specify this, so that CVSup can keep your - source tree fully up to date. CVSup is careful to delete + delete gives CVSup permission to delete files. You + should always specify this, so that CVSup can keep your + source tree fully up to date. CVSup is careful to delete only those files for which it is responsible. Any extra files you happen to have will be left strictly alone. @@ -26268,27 +26282,27 @@ cvs-crypto - + - Running CVSup + Running <application>CVSup</application> You are now ready to try an update. The command line for doing this is quite simple: - &prompt.root; cvsup supfile + &prompt.root; cvsup supfile - where supfile is of course the name of the supfile you - have just created. Assuming you are running under X11, cvsup + where supfile is of course the name of the supfile you + have just created. Assuming you are running under X11, cvsup will display a GUI window with some buttons to do the usual - things. Press the "go" button, and watch it run. + things. Press the go button, and watch it run. Since you are updating your actual /usr/src tree in this - example, you will need to run the program as root so that cvsup + example, you will need to run the program as root so that cvsup has the permissions it needs to update your files. Having just created your configuration file, and having never used this program before, that might understandably make you nervous. @@ -26303,10 +26317,10 @@ cvs-crypto The directory you specify will be used as the destination - directory for all file updates. CVSup will examine your usual + directory for all file updates. CVSup will examine your usual files in /usr/src, but it will not modify or delete any of them. Any file updates will instead land in - /var/tmp/dest/usr/src. CVSup will also + /var/tmp/dest/usr/src. CVSup will also leave its base directory status files untouched when run this way. The new versions of those files will be written into the specified directory. As long as you have read access to @@ -26343,9 +26357,9 @@ cvs-crypto - CVSup File Collections + <application>CVSup</application> File Collections - The file collections available via CVSup are organized + The file collections available via CVSup are organized hierarchically. There are a few large collections, and they are divided into smaller sub-collections. Receiving a large collection is equivalent to receiving each of its @@ -26357,7 +26371,7 @@ cvs-crypto only by small groups of people for specialized purposes, and some mirror sites may not carry all of them. - + cvs-all release=cvs @@ -27016,14 +27030,14 @@ cvs-crypto - + Announcements, Questions, and Bug Reports - Most FreeBSD-related discussion of CVSup takes place on the + Most FreeBSD-related discussion of CVSup takes place on the &a.hackers;. New versions of the software are announced there, as well as on the &a.announce;. @@ -27114,7 +27128,8 @@ cvs-crypto The following tasks are considered to be urgent, usually because they represent something that is badly broken or sorely - needed: + needed: + @@ -27256,7 +27271,6 @@ cvs-crypto - @@ -27264,14 +27278,15 @@ cvs-crypto Medium priority tasks The following tasks need to be done, but not with any - particular urgency: + particular urgency: + Port AFS (Andrew File System) to FreeBSD Coordinator: - Alexander Seth - Jones + Jones @@ -27367,7 +27382,6 @@ cvs-crypto - @@ -27379,7 +27393,8 @@ cvs-crypto done anytime soon: The first 20 items are from Terry Lambert - <terry@lambert.org> + terry@lambert.org + @@ -27518,7 +27533,6 @@ cvs-crypto - @@ -27531,19 +27545,19 @@ cvs-crypto useful tasks which are suitable for "weekend hackers", or people without programming skills. - + If you run FreeBSD-current and have a good Internet - connection, there is a machine current.freebsd.org which + connection, there is a machine current.freebsd.org which builds a full release once a day - every now and again, try and install the latest release from it and report any failures in the process. - Read the freebsd-bugs mailing list. There might be a + Read the freebsd-bugs mailing list. There might be a problem you can comment constructively on or with patches you can test. Or you could even try to fix one of the problems yourself. @@ -27569,7 +27583,7 @@ cvs-crypto Read the freebsd-questions mailing list and the - newsgroup comp.unix.bsd.freebsd.misc occasionally (or even + newsgroup comp.unix.bsd.freebsd.misc occasionally (or even regularly). It can be very satisfying to share your expertise and help people solve their problems; sometimes you may even learn something new yourself! These forums can @@ -27618,7 +27632,7 @@ cvs-crypto - + @@ -27669,7 +27683,7 @@ cvs-crypto Changes to the documentation are overseen by the &a.doc;. Send submissions and changes (even small ones are welcome!) using - send-pr as described in + send-pr as described in . @@ -27698,14 +27712,20 @@ cvs-crypto Assuming that you can manage to secure fairly up-to-date sources to base your changes on, the next step is to produce a set of diffs to send to the FreeBSD maintainers. This is done with - the diff1 command, with the `context diff' - form being preferred. For example: - + the diff1 command, with the context diff + form being preferred. For example: + + &prompt.user; diff -c oldfile newfile - or + + + or + &prompt.user; diff -c -r olddir newdir - would generate such a set of context diffs for + + + would generate such a set of context diffs for the given source file or directory hierarchy. See the man page for diff1 for more details. @@ -27735,8 +27755,8 @@ cvs-crypto very busy and so you should only send mail to them where it is truly necessary. - Please refer to man 9 intro and - man 9 style for some information on + Please refer to man 9 intro and + man 9 style for some information on coding style. We would appreciate it if you were at least aware of this information before submitting code. @@ -27755,7 +27775,7 @@ cvs-crypto copyrights also invariably comes up. Acceptable copyrights for code included in FreeBSD are: - + @@ -27783,7 +27803,7 @@ cvs-crypto - + Contributions coming under any other type of copyright must be carefully reviewed before their inclusion into FreeBSD will be @@ -27795,7 +27815,7 @@ cvs-crypto To place a BSD-style copyright on your work, include the following text at the very beginning of every source code file you wish to protect, replacing the text between the - %% with the appropriate information. + %% with the appropriate information. Copyright (c) %%proper_years_here%% @@ -27823,7 +27843,9 @@ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. $Id$ - For your convenience, a copy of this text can + + + For your convenience, a copy of this text can be found in /usr/share/examples/etc/bsd-style-copyright. @@ -27907,8 +27929,8 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. #endif - Don't forget to add -DHAVE_SYS_PARAM_H to - the CFLAGS in the Makefile for this + Don't forget to add -DHAVE_SYS_PARAM_H to + the CFLAGS in the Makefile for this method. Once you have sys/param.h @@ -27941,7 +27963,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Use sparingly: - + @@ -27990,6 +28012,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. _FreeBSD_version + 2.0-RELEASE @@ -28133,10 +28156,10 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. you don't have to worry about old -current's; they are listed here just for your reference. - + In the hundreds of ports that have been done, there have - only been one or two cases where __FreeBSD__ + only 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. @@ -28172,7 +28195,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # Date created: 5 December 1994 # Whom: asami # -# $Id: book.sgml,v 1.42 1998-10-22 23:03:48 nik Exp $ +# $Id: book.sgml,v 1.43 1998-10-22 23:06:00 nik Exp $ # DISTNAME= oneko-1.1b @@ -28213,13 +28236,13 @@ USE_IMAKE= yes <filename>COMMENT</filename> This is the one-line description of the port. - PLEASE do not include the package name (or version - number of the software) in the comment. Here is - an example: + Please do not include the package name (or version + number of the software) in the comment. Here is + an example: A cat chasing a mouse all over the screen. - + @@ -28319,12 +28342,12 @@ lib/X11/oneko/mouse.xpm .tar.gz file, stick it in the directory ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/ and send mail to us using send-pr1 (please classify it as category - `ports' and class `change-request'). There is no need to + ports and class change-request). There is no need to upload the package, we will build it by ourselves. We will take a look, 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?!? :) + tree. Your name will also appear in the list of Additional + FreeBSD contributors on the FreeBSD Handbook and other files. + Isn't that great?!? :) @@ -28349,12 +28372,12 @@ lib/X11/oneko/mouse.xpm But do not worry if you do not really understand what bsd.port.mk is doing, not many people - do... :> + do... :> - - + + - + The fetch target is run. The fetch target is responsible for making sure that the tarball exists locally in ${DISTDIR}. @@ -28363,25 +28386,25 @@ lib/X11/oneko/mouse.xpm which is set in the Makefile, as well as our main ftp site at ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/, where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with ${FETCH}, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in ${DISTDIR} for future use and proceed. - + - + The extract target is run. It looks for your ports' distribution file in ${DISTDIR} (typically a gzip'd tarball) and unpacks it into a temporary subdirectory specified by ${WRKDIR} (defaults to work). - + - + The patch target is run. First, any patches defined in ${PATCHFILES} are applied. Second, if any patches are found in ${PATCHDIR} (defaults to the patches subdirectory), they are applied at this time in alphabetical order. - + - + The configure target is run. This can do any one of many different things. @@ -28410,9 +28433,9 @@ lib/X11/oneko/mouse.xpm - + - + The build target is run. This is responsible for descending into the ports' private working directory (${WRKSRC}) and @@ -28420,10 +28443,10 @@ lib/X11/oneko/mouse.xpm make will be used, otherwise the system make will be used. - + - - + + The above are the default actions. In addition, you can define targets pre-something or post-something, or put scripts @@ -28450,7 +28473,7 @@ lib/X11/oneko/mouse.xpm your Makefile. - The `main' targets (e.g., extract, configure, etc.) do nothing more than + The main targets (e.g., extract, configure, etc.) do nothing more than make sure all the stages up to that one is completed and call the real targets or scripts, and they are not intended to be changed. If you want to fix the extraction, fix @@ -28476,7 +28499,7 @@ lib/X11/oneko/mouse.xpm 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, we can `house' it ourselves by putting + non-standard formats, we can house it ourselves by putting it on ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/ as the last resort. Please refer to this location as ${MASTER_SITE_LOCAL}. Send mail to the &a.ports;if you are not sure what to do. @@ -28505,9 +28528,9 @@ lib/X11/oneko/mouse.xpm If your port requires significant user interaction/customization to compile or install, you should - take a look at one of Larry Wall's classic Configure scripts + take a look at one of Larry Wall's classic Configure scripts and perhaps do something similar yourself. The goal of the - new ports collection is to make each port as `plug-and-play' + 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. @@ -28558,8 +28581,8 @@ lib/X11/oneko/mouse.xpm Handling user input If your port requires user input to build, configure or - install, then set IS_INTERACTIVE in your - Makefile. This will allow `overnight builds' to skip your port + install, then set IS_INTERACTIVE in your + Makefile. This will allow overnight builds to skip your port if the user sets the variable BATCH in his environment (and if the user sets the variable INTERACTIVE, then only @@ -28601,7 +28624,7 @@ lib/X11/oneko/mouse.xpm - DISTNAME + <makevar>DISTNAME</makevar> You should set ${DISTNAME} to be the base name of your port. The default rules expect the distribution file @@ -28630,7 +28653,7 @@ DISTNAME=foozolix-1.0 - CATEGORIES + <makevar>CATEGORIES</makevar> When a package is created, it is put under /usr/ports/packages/All and links are @@ -28649,13 +28672,13 @@ DISTNAME=foozolix-1.0 - MASTER_SITES + <makevar>MASTER_SITES</makevar> Record the directory part of the ftp/http-URL pointing at the original tarball in ${MASTER_SITES}. Do not forget the trailing slash (/)! - The make macros will try to use this specification for + The make macros will try to use this specification for grabbing the distribution file with ${FETCH} if they cannot find it already on the system. @@ -28668,17 +28691,17 @@ DISTNAME=foozolix-1.0 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 MASTER_SITE_XCONTRIB, MASTER_SITE_GNU, - MASTER_SITE_PERL_CPAN, MASTER_SITE_TEX_CTAN, and - MASTER_SITE_SUNSITE. Simply set MASTER_SITE_SUBDIR to the - path with in the archive. Here is an example: + form using MASTER_SITE_XCONTRIB, MASTER_SITE_GNU, + MASTER_SITE_PERL_CPAN, MASTER_SITE_TEX_CTAN, and + MASTER_SITE_SUNSITE. Simply set MASTER_SITE_SUBDIR to the + path with in the archive. Here is an example: MASTER_SITES= ${MASTER_SITE_XCONTRIB} MASTER_SITE_SUBDIR= applications - + - The user can also set the MASTER_SITE_* variables in + The user can also set the MASTER_SITE_* variables in /etc/make.conf to override our choices, and use their favorite mirrors of these popular archives instead. @@ -28687,7 +28710,7 @@ MASTER_SITE_SUBDIR= applications - PATCHFILES + <makevar>PATCHFILES</makevar> If your port requires some additional patches that are available by ftp or http, set ${PATCHFILES} to the names of the @@ -28699,7 +28722,7 @@ MASTER_SITE_SUBDIR= applications (i.e., ${WKRSRC}) because it contains some extra pathnames, set ${PATCH_DIST_STRIP} accordingly. For instance, if all the pathnames in the patch has an extra - foozolix-1.0/ in front of the + foozolix-1.0/ in front of the filenames, then set PATCH_DIST_STRIP=-p1. @@ -28732,10 +28755,9 @@ MASTER_SITE_SUBDIR= applications - MAINTAINER + <makevar>MAINTAINER</makevar> - Set your mail-address here. Please. :) + Set your mail-address here. Please. :) For detailed description of the responsibility of maintainers, refer to - LIB_DEPENDS + <makevar>LIB_DEPENDS</makevar> This variable specifies the shared libraries this port - depends on. It is a list of lib:dir pairs where - lib is the name of the shared library, - and dir is the directory in which to + depends on. It is a list of lib:dir pairs where + lib is the name of the shared library, + and dir is the directory in which to find it in case it is not available. For example, LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg - will check for a shared jpeg library with + + + will check for a shared jpeg library with major version 6, and descend into the graphics/jpeg subdirectory of your ports tree to build and install it if it is not found. - The lib part is just an argument + The lib part is just an argument given to ldconfig -r | grep, so periods should be escaped by two backslashes like in the example above. @@ -28785,16 +28808,15 @@ LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg - RUN_DEPENDS + <makevar>RUN_DEPENDS</makevar> This variable specifies executables or files this port - depends on during run-time. It is a list of path:dir pairs where - path is the name of the executable or - file, and dir is the directory in which + depends on during run-time. It is a list of path:dir pairs where + path is the name of the executable or + file, and dir is the directory in which to find it in case it is not available. If - path starts with a slash - (/), it is treated as a file and its + path starts with a slash + (/), it is treated as a file and its existence is tested with test -e; otherwise, it is assumed to be an executable, and which -s is used to determine if the @@ -28805,7 +28827,9 @@ LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \ wish:${PORTSDIR}/x11/tk - will check if the file + + + will check if the file /usr/local/etc/innd exists, and build and install it from the news/inn subdirectory of the ports tree if it is not found. It will @@ -28823,45 +28847,49 @@ RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \ The dependency is checked from within the install target. Also, the name of the dependency is put in to the package so that - pkg_add will automatically install it if it + pkg_add will automatically install it if it is not on the user's system. - BUILD_DEPENDS + <makevar>BUILD_DEPENDS</makevar> This variable specifies executables or files this port - requires to build. Like RUN_DEPENDS, it is - a list of path:dir pairs. + requires to build. Like RUN_DEPENDS, it is + a list of path:dir pairs. For example, BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip - will check for an executable called + + + will check for an executable called unzip, and descend into the archivers/unzip subdirectory of your ports tree to build and install it if it is not found. - `build' here means everything from extracting to + build here means everything from extracting to compilation. The dependency is checked from within the extract target. - FETCH_DEPENDS + <makevar>FETCH_DEPENDS</makevar> This variable specifies executables or files this port requires to fetch. Like the previous two, it is a list of - path:dir pairs. For + path:dir pairs. For example, FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - will check for an executable called + + + will check for an executable called ncftp2, and descend into the net/ncftp2 subdirectory of your ports tree to build and install it if it is not found. @@ -28871,7 +28899,7 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - DEPENDS + <makevar>DEPENDS</makevar> If there is a dependency that does not fall into either of the above four categories, or your port requires to have @@ -28911,13 +28939,13 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - NO_INSTALL_MANPAGES + <makevar>NO_INSTALL_MANPAGES</makevar> - If the port uses imake but does not understand the + If the port uses imake but does not understand the install.man target, NO_INSTALL_MANPAGES=yes should be set. In addition, the author of the original port should be shot. - :> + :> @@ -28936,7 +28964,7 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - REQUIRES_MOTIF + <makevar>REQUIRES_MOTIF</makevar> If your port requires Motif, define this variable in the Makefile. This will prevent people who don't own a copy of @@ -28945,7 +28973,7 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - ${MOTIFLIB} + <makevar>${MOTIFLIB}</makevar> This variable will be set by bsd.port.mk to be the appropriate @@ -28953,7 +28981,8 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 use this wherever the Motif library is referenced in the Makefile or Imakefile. - There are two common cases: + There are two common cases: + @@ -28969,12 +28998,11 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - ${MOTIFLIB} (usually) - expands to or - /usr/X11R6/lib/libXm.a, so there is + expands to -L/usr/X11R6/lib -lXm or + /usr/X11R6/lib/libXm.a, so there is no need to add or in front. @@ -28993,7 +29021,7 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 the length of this section, but it is imperative to weave all the info files together. If done correctly, it will produce a beautiful listing, so please bear with me! - :) + :) First, this is what you (as a porter) need to know: @@ -29024,7 +29052,7 @@ Options: Look at the texinfo sources and make a patch to insert - @dircategory and @direntry + @dircategory and @direntry statements to files that don't have them. This is part of my patch: @@ -29061,7 +29089,7 @@ Options: @direntry section. - You can give the dir + You can give the dir entries to install-info as arguments ( and ) instead of patching the texinfo @@ -29069,7 +29097,7 @@ Options: because you need to duplicate the same information in three places (Makefile and - @exec/@unexec of + @exec/@unexec of PLIST; see below). However, if you have a Japanese (or other multibyte encoding) info files, you will have to use the extra arguments to install-info because makeinfo can't handle those texinfo @@ -29085,10 +29113,10 @@ Options: Since the texinfo sources are newer than the info files, they should be rebuilt when you type make; but many Makefiles don't include correct - dependencies for info files. In emacs' case, I had to + dependencies for info files. In emacs' case, I had to patch the main Makefile.in so it will descend into the man - subdirectory to rebuild the info pages. + subdirectory to rebuild the info pages. --- ./Makefile.in.org Mon Aug 19 21:12:19 1996 @@ -29112,7 +29140,7 @@ Options: info: $(INFO_TARGETS) dvi: $(DVI_TARGETS) - + The second hunk was necessary because the default target in the man subdir is called @@ -29130,7 +29158,7 @@ Options: dir file, delete it. Your port may not be doing it. Also, remove any commands that are otherwise mucking around with the - dir file. + dir file. --- ./Makefile.in.org Mon Aug 19 21:12:19 1996 @@ -29150,12 +29178,12 @@ Options: (cd $${thisdir}; \ ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \ chmod a+r ${infodir}/$$f); \ - + (This step is only necessary if you are modifying an - existing port.) Take a look at + existing port.) Take a look at pkg/PLIST and delete anything that is trying to patch up info/dir. They may be in pkg/INSTALL or some other @@ -29187,7 +29215,7 @@ diff -u -r1.15 PLIST target to the Makefile to create a dir file if it is not there. Also, call install-info with the - installed info files. + installed info files. Index: Makefile @@ -29210,7 +29238,7 @@ diff -u -r1.26 Makefile +.endfor .include <bsd.port.mk> - + Do not use anything other than /usr/share/info/dir and the above @@ -29223,10 +29251,10 @@ diff -u -r1.26 Makefile Edit PLIST and add equivalent - @exec statements and also - @unexec for pkg_delete. + @exec statements and also + @unexec for pkg_delete. You do not need to delete info/dir - with @unexec. + with @unexec. Index: pkg/PLIST @@ -29253,26 +29281,25 @@ diff -u -r1.15 PLIST +@exec install-info %D/info/ccmode %D/info/dir libexec/emacs/19.34/i386--freebsd/cvtmail libexec/emacs/19.34/i386--freebsd/digest-doc - + - The @unexec install-info - --delete commands have to be listed before + The @unexec install-info + --delete commands have to be listed before the info files themselves so they can read the files. - Also, the @exec install-info commands + Also, the @exec install-info commands have to be after the info files and the - @exec command that creates the the + @exec command that creates the the dir file. - Test and admire your work. Test and admire your work. :) The sequence I recommend is: make package, - pkg_delete, then - pkg_add. Check the dir file before and after each + pkg_delete, then + pkg_add. Check the dir file before and after each step. @@ -29301,12 +29328,12 @@ diff -u -r1.15 PLIST There are two variables you can set in the Makefile to handle the situations that arise frequently: - + - If the port has a `do not sell for profit' type of - license, set the variable NO_CDROM. We + If the port has a do not sell for profit type of + license, set the variable NO_CDROM. 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. @@ -29316,7 +29343,7 @@ diff -u -r1.15 PLIST 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 - NO_PACKAGE. We will make sure such + NO_PACKAGE. 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. @@ -29324,15 +29351,15 @@ diff -u -r1.15 PLIST 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 RESTRICTED to be the + (e.g., crypto stuff) or has a no commercial use license, + set the variable RESTRICTED to be the string describing the reason why. For such ports, the distfiles/packages will not be available even from our ftp sites. - + The GNU General Public License (GPL), both version 1 @@ -29355,7 +29382,7 @@ diff -u -r1.15 PLIST sites. The next step is to send a mail to the maintainer, if one is - listed in the port's Makefile. That person may already be + listed in the port's Makefile. 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). @@ -29365,14 +29392,14 @@ diff -u -r1.15 PLIST 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 (i.e., if your modified ports - directory is called superedit + directory is called superedit and the original as in our tree is superedit.bak, then send us the result of - diff -ruN superedit.bak - superedit). Please examine the output to make + diff -ruN superedit.bak + superedit). 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 send-pr1 - (category `ports'). Please mention any added or deleted files + (category ports). 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 @@ -29388,7 +29415,7 @@ diff -u -r1.15 PLIST - WRKDIR + <makevar>WRKDIR</makevar> Do not leave anything valuable lying around in the work subdirectory, make clean will @@ -29406,8 +29433,7 @@ diff -u -r1.15 PLIST Do include package information, i.e. COMMENT, DESCR, and - PLIST, in pkg. + PLIST, in pkg. Note that these files are not used only for packaging @@ -29423,30 +29449,30 @@ diff -u -r1.15 PLIST Do compress manpages and strip binaries. If the original source already strips the binary, fine; otherwise, you can add a post-install rule to do it - yourself. Here is an example: + yourself. Here is an example: post-install: strip ${PREFIX}/bin/xdl - + - Use the file command on the + Use the file command on the installed executable to check whether the binary is stripped or not. If it does not say `not stripped', it is stripped. - To automagically compress the manpages, use the MAN[1-9LN] + To automagically compress the manpages, use the MAN[1-9LN] variables. They will check the variable - NOMANCOMPRESS that the user can set in + NOMANCOMPRESS that the user can set in /etc/make.conf to disable man page compression. Place them last in the section below the - MAINTAINER variable. Here is an example: + MAINTAINER variable. Here is an example: MAN1= foo.1 bar.1 MAN5= foo.conf.5 MAN8= baz.8 - + This is not usually necessary with ports that are X @@ -29454,25 +29480,25 @@ MAN8= baz.8 If your port anchors its man tree somewhere other than - PREFIX, you can use the - MANPREFIX to set it. Also, if only manpages + PREFIX, you can use the + MANPREFIX to set it. Also, if only manpages in certain section go in a non-standard place, such as many Perl modules ports, you can set individual man paths using - MANsectPREFIX - (where sect is one of 1-9, L or + MANsectPREFIX + (where sect is one of 1-9, L or N). - INSTALL_* macros + <makevar>INSTALL_*</makevar> macros Do use the macros provided in bsd.port.mk to ensure correct modes and ownership of files in your own *-install targets. They are: - + @@ -29497,7 +29523,7 @@ MAN8= baz.8 - + These are basically the install command with all the appropriate flags. See below for an example on how to use them. @@ -29511,13 +29537,11 @@ MAN8= baz.8 package is installed with pkg_add you can do with via the pkg/INSTALL script. This script will automatically be added to the package, and will be run twice - by pkg_add. The first time will as INSTALL ${PKGNAME} PRE-INSTALL and the - second time as INSTALL ${PKGNAME} - POST-INSTALL. $2 can be tested to determine which + by pkg_add. The first time will as INSTALL ${PKGNAME} PRE-INSTALL and the + second time as INSTALL ${PKGNAME} + POST-INSTALL. $2 can be tested to determine which mode the script is being run in. The - PKG_PREFIX environmental variable will be + PKG_PREFIX environmental variable will be set to the package installation directory. See man pkg_add1 for additional information. @@ -29559,8 +29583,8 @@ MAN8= baz.8 whole ${PKGNAME}. Make the installation dependent to the variable - NOPORTDOCS so that users can disable it in - /etc/make.conf, like this: + NOPORTDOCS so that users can disable it in + /etc/make.conf, like this: post-install: @@ -29568,11 +29592,11 @@ post-install: ${MKDIR}${PREFIX}/share/doc/xv ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv .endif - + Do not forget to add them to pkg/PLIST too! (Do not worry about - NOPORTDOCS here; there is currently no way + NOPORTDOCS here; there is currently no way for the packages to read variables from /etc/make.conf.) @@ -29589,13 +29613,13 @@ post-install: - DIST_SUBDIR + <makevar>DIST_SUBDIR</makevar> Do not let your port clutter /usr/ports/distfiles. 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., - `Makefile'), set ${DIST_SUBDIR} to the name of the + Makefile), set ${DIST_SUBDIR} to the name of the port (${PKGNAME} without the version part should work fine). This will change ${DISTDIR} from the default /usr/ports/distfiles to @@ -29606,7 +29630,7 @@ post-install: It will also look at the subdirectory with the same name on the backup master site at ftp.freebsd.org. (Setting ${DISTDIR} explicitly in your - Makefile will not accomplish this, so please use ${DIST_SUBDIR}.) + Makefile will not accomplish this, so please use ${DIST_SUBDIR}.) This does not affect the ${MASTER_SITES} you define in your @@ -29630,10 +29654,8 @@ post-install: 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 ($) signs, and typically start with - $Id or $RCS. + will fail. RCS strings are surrounded by dollar ($) signs, and typically start with + $Id or $RCS. @@ -29644,8 +29666,8 @@ post-install: diff 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, Makefiles when the - port uses Imake or GNU configure, etc., are unnecessary and + particular, diffs between two backup files, Makefiles when the + port uses Imake or GNU configure, etc., are unnecessary and should be deleted. Also, if you had to delete a file, then you can do it in the post-extract target rather than as part of the patch. Once you are happy @@ -29655,7 +29677,7 @@ post-install: - PREFIX + <makevar>PREFIX</makevar> Do try to make your port install relative to ${PREFIX}. (The value of this variable will be set to ${LOCALBASE} (default @@ -29666,7 +29688,7 @@ post-install: Not hard-coding /usr/local or /usr/X11R6 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 imake, this is + needs of other sites. For X ports that use imake, this is automatic; otherwise, this can often be done by simply replacing the occurrences of /usr/local (or /usr/X11R6 for X ports that do not @@ -29679,22 +29701,26 @@ post-install: can be reassigned in your Makefile or in the user's environment. However, it is strongly discouraged for individual ports to set this variable explicitly in the - Makefiles. (If your port is an X port but does not use imake, + Makefiles. (If your port is an X port but does not use imake, set USE_X11=yes; this is quite different from setting PREFIX=/usr/X11R6.) Also, refer to programs/files from other ports with the variables mentioned above, not explicit pathnames. For instance, if your port requires a macro - PAGER to be the full pathname of less, use the compiler flag: + PAGER to be the full pathname of less, use the compiler flag: -DPAGER=\"${PREFIX}/bin/less\" - or + + + or -DPAGER=\"${LOCALBASE}/bin/less\" - if this is an X port, instead of -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. + + + if this is an X port, instead of -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. @@ -29717,7 +29743,7 @@ post-install: files). See man hier7 for details, the rule governing /usr pretty much applies to /usr/local too. The - exception are ports dealing with USENET `news'. They may use + exception are ports dealing with USENET news. They may use ${PREFIX}/news as a destination for their files. @@ -29732,20 +29758,20 @@ post-install: ${PREFIX}/lib) to register it into the shared library cache. - Also, add an @exec line to your + Also, add an @exec line to your pkg/PLIST file so that a user who installed the package can start using the shared library immediately. This line should immediately follow the line - for the shared library itself, as in: + for the shared library itself, as in: lib/libtcl80.so.1.0 @exec /sbin/ldconfig -m %D/lib - + Never, ever, ever add a line that says ldconfig without any - arguments to your Makefile or pkg/PLIST. This will reset the + arguments to your Makefile or pkg/PLIST. This will reset the shared library cache to the contents of /usr/lib only, and will royally screw up the user's machine (Help, xinit does not run anymore after I @@ -29804,11 +29830,10 @@ msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh Do look at existing examples and the bsd.port.mk file before asking us - questions! ;) + questions! ;) Do ask us questions if you have any trouble! Do not just - beat your head against a wall! :) + beat your head against a wall! :) @@ -29925,7 +29950,7 @@ pre-install: doesn't look like that, set ${PKGNAME} to something in that format. - + @@ -29946,7 +29971,7 @@ pre-install: convert the name (or at least the first letter) to lowercase. If the software in question really is called that way, you can have numbers, hyphens and underscores in - the name too (like `kinput2'). + the name too (like kinput2). @@ -29967,7 +29992,7 @@ pre-install: - + Here are some (real) examples on how to convert a ${DISTNAME} into a suitable ${PKGNAME}: @@ -29980,6 +30005,7 @@ pre-install: Reason + mule-2.2.2. @@ -30089,7 +30115,7 @@ pre-install: 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! - :) + :) diff --git a/en_US.ISO_8859-1/books/handbook/book.sgml b/en_US.ISO_8859-1/books/handbook/book.sgml index 273b43fa79..784b90754b 100644 --- a/en_US.ISO_8859-1/books/handbook/book.sgml +++ b/en_US.ISO_8859-1/books/handbook/book.sgml @@ -2427,7 +2427,7 @@ password. Remember to use binary (also known as image) mode!] # Date created: 13 November 1997 # Whom: jraynard # -# $Id: handbook.sgml,v 1.1 1998/04/01 18:25:32 nik +# $Id$ # DISTNAME= ElectricFence-2.0.5 @@ -24997,13 +24997,14 @@ an A record in the DNS for "customer.com". Who needs FreeBSD-current? FreeBSD-current is made generally available for 3 primary - interest groups: + interest groups: + Members of the FreeBSD group who are actively working on some part of the source tree and for whom keeping - `current' is an absolute requirement. + current is an absolute requirement. @@ -25023,14 +25024,13 @@ an A record in the DNS for "customer.com". - - What is FreeBSD-current <emphasis>NOT</emphasis>? + What is FreeBSD-current <emphasis>not</emphasis>? + - @@ -25058,14 +25058,14 @@ an A record in the DNS for "customer.com". - + Using FreeBSD-current - + @@ -25080,7 +25080,7 @@ an A record in the DNS for "customer.com". Yo, Everybody! Before you rebuild /usr/src, you must rebuild the kernel or your system will crash horribly!). - The cvs-all mailing list will allow you + The cvs-all mailing list will allow you to see the commit log entry for each change as it is made along with any pertinent information on possible side-effects. To join these lists, send mail to @@ -25089,21 +25089,23 @@ an A record in the DNS for "customer.com". subscribe freebsd-current subscribe cvs-all - In the - body of your message. Optionally, you can also say `help' + + + in the + body of your message. Optionally, you can also say help and Majordomo will send you full help on how to subscribe and unsubscribe to the various other mailing lists we support. - Grab the sources from ftp.FreeBSD.ORG. You can do - this in three ways: + Grab the sources from ftp.FreeBSD.ORG. You can do + this in three ways: - Use the + Use the facility. Unless you have a good TCP/IP connection at a flat rate, this is the way to do it. @@ -25115,29 +25117,33 @@ subscribe cvs-all - Use ftp. The source tree for FreeBSD-current is + Use ftp. The source tree for FreeBSD-current is always exported on: ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current We also use `wu-ftpd' which allows compressed/tar'd grabbing of whole trees. e.g. you see: + URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current">ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current We also use wu-ftpd which allows compressed/tar'd grabbing of whole trees. e.g. you see: usr.bin/lex - You can do: + + + You can do: ftp> cd usr.bin ftp> get lex.tar.Z - And it will get the whole directory for you as a compressed tar file. + + + and it will get the whole directory for you as a compressed tar file. - + Essentially, if you need rapid on-demand access to the source and communications bandwidth is not a consideration, - use cvsup or ftp. Otherwise, use CTM. + use cvsup or ftp. Otherwise, use CTM. @@ -25170,8 +25176,6 @@ subscribe cvs-all - - @@ -25242,13 +25246,13 @@ subscribe freebsd-stable - Grab the sources from ftp.FreeBSD.ORG. You can do + Grab the sources from ftp.FreeBSD.ORG. You can do this in three ways: - Use the + Use the facility. Unless you have a good TCP/IP connection at a flat rate, this is the way to do it. @@ -25260,22 +25264,26 @@ subscribe freebsd-stable - Use ftp. The source tree for FreeBSD-stable is + Use ftp. The source tree for FreeBSD-stable is always exported on: ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-stable - We also use `wu-ftpd' which allows + We also use wu-ftpd which allows compressed/tar'd grabbing of whole trees. e.g. you - see: + see: usr.bin/lex - You can do: + + + You can do: ftp> cd usr.bin ftp> get lex.tar.Z - And it will get the + + + and it will get the whole directory for you as a compressed tar file. @@ -25288,7 +25296,7 @@ subscribe freebsd-stable Essentially, if you need rapid on-demand access to the source and communications bandwidth is not a consideration, - use cvsup or ftp. Otherwise, use CTM. + use cvsup or ftp. Otherwise, use CTM. @@ -25318,9 +25326,9 @@ subscribe freebsd-stable There are various ways of using an Internet (or email) connection to stay up-to-date with any given area of the FreeBSD project sources, or all areas, depending on what interests you. The - primary services we offer are CVSup and CTM. + primary services we offer are CVSup and CTM. - CVSup uses the + CVSup uses the pull model of updating. The user (or a cron script) invokes the cvsup program, and it interacts with a cvsupd server @@ -25337,27 +25345,27 @@ subscribe freebsd-stable its previous run is executed several times a day on the master archive, any detected changes being compressed, stamped with a sequence-number and encoded for transmission over email (printable - ASCII only). Once received, these "CTM deltas" can then be handed + ASCII only). Once received, these CTM deltas can then be handed to the ctm_rmail1 utility which will automatically decode, verify and apply the changes to the user's copy of the sources. This - process is far more efficient than CVSup, and places less strain on + process is far more efficient than CVSup, and places less strain on our server resources since it is a push rather than a pull model. There are other trade-offs, of course. If you inadvertently - wipe out portions of your archive, CVSup will detect and rebuild the - damaged portions for you. CTM won't do this, and if you wipe some + wipe out portions of your archive, CVSup will detect and rebuild the + damaged portions for you. CTM won't do this, and if you wipe some portion of your source tree out (and don't have it backed up) then - you will have to start from scratch (from the most recent CVS "base - delta") and rebuild it all. + you will have to start from scratch (from the most recent CVS base + delta) and rebuild it all. - For more information on CTM and CVSup, please see one of the + For more information on CTM and CVSup, please see one of the following sections: - CTM + <application>CTM</application> Contributed by &a.phk;. Updated 19-October-1997. @@ -25472,7 +25480,7 @@ subscribe freebsd-stable produced subsequently to it. First you should determine what you already have. Everyone - can start from an Empty directory. However, since the trees + can start from an empty directory. However, since the trees are many tens of megabytes, you should prefer to start from something already at hand. If you have a RELEASE CD, you can copy or extract an initial source from it. This will save a @@ -25483,7 +25491,7 @@ subscribe freebsd-stable into a CTM supported tree. You can recognize these transition deltas by the - X appended to the number + X appended to the number (src-cur.3210XEmpty.gz for instance). The designation following the X corresponds to the origin of your initial seed. Empty is @@ -25501,11 +25509,12 @@ subscribe freebsd-stable Using <application>CTM</application> in your daily life - To apply the deltas, simply say: + To apply the deltas, simply say: + &prompt.root; cd /where/ever/you/want/the/stuff &prompt.root; ctm -v -v /where/you/store/your/deltas/src-xxx.* - + CTM understands deltas which have been put through gzip, so you do not @@ -25542,7 +25551,7 @@ subscribe freebsd-stable Keeping your local changes As a developer one would like to experiment with and change - files in the source tree. CTM supports local modifications in a + files in the source tree. CTM supports local modifications in a limited way: before checking for the presence of a file foo, it first looks for foo.ctm. If this file exists, CTM will @@ -25557,20 +25566,20 @@ subscribe freebsd-stable - Other interesting CTM options + Other interesting <application>CTM</application> options Finding out exactly what would be touched by an update - You can determine the list of changes that CTM will make + You can determine the list of changes that CTM will make on your source repository using the - option to CTM. + option to CTM. This is useful if you would like to keep logs of the changes, pre- or post- process the modified files in any - manner, or just are feeling a tad paranoid :-). + manner, or just are feeling a tad paranoid :-). @@ -25578,11 +25587,11 @@ subscribe freebsd-stable Making backups before updating Sometimes you may want to backup all the files that would - be changed by a CTM update. + be changed by a CTM update. Specifying the option - causes CTM to backup all files that would be touched by a - given CTM delta to backup-file. + causes CTM to backup all files that would be touched by a + given CTM delta to backup-file. @@ -25590,26 +25599,27 @@ subscribe freebsd-stable Restricting the files touched by an update Sometimes you would be interested in restricting the scope - of a given CTM update, or may be interested in extracting just + of a given CTM update, or may be interested in extracting just a few files from a sequence of deltas. - You can control the list of files that CTM would operate + You can control the list of files that CTM would operate on by specifying filtering regular expressions using the and options. For example, to extract an up-to-date copy of lib/libc/Makefile from your collection of - saved CTM deltas, run the commands: + saved CTM deltas, run the commands: + &prompt.root; cd /where/ever/you/want/to/extract/it/ &prompt.root; ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.* - + - For every file specified in a CTM delta, the + For every file specified in a CTM delta, the and options are applied in the order given on the command line. The file - is processed by CTM only if it is marked as eligible after all + is processed by CTM only if it is marked as eligible after all the and options are applied to it. @@ -25619,7 +25629,8 @@ subscribe freebsd-stable Future plans for <application>CTM</application> - Tons of them: + Tons of them: + @@ -25633,7 +25644,6 @@ subscribe freebsd-stable - The bad news is that I am very busy, so any help in doing this will be most welcome. And do not forget to tell me what @@ -25646,9 +25656,8 @@ subscribe freebsd-stable All the DES infected (e.g. export controlled) source is not included. You will get the international version only. - If sufficient interest appears, we will set up a sec-cur sequence too. There is a - sequence of deltas for the ports + If sufficient interest appears, we will set up a sec-cur sequence too. There is a + sequence of deltas for the ports collection too, but interest has not been all that high yet. Tell me if you want an email list for that too and we will consider setting it up. @@ -25658,7 +25667,7 @@ subscribe freebsd-stable Thanks! - + &a.bde; @@ -25678,7 +25687,7 @@ subscribe freebsd-stable Stephen McKay - wrote ctm_[rs]mail, + wrote ctm_[rs]mail, much appreciated. @@ -25701,14 +25710,14 @@ subscribe freebsd-stable - + - CVSup + <application>CVSup</application> Contributed by &a.jdp;. @@ -25717,20 +25726,20 @@ subscribe freebsd-stable id="cvsup-intro"> Introduction - CVSup is a software package for distributing and updating + CVSup is a software package for distributing and updating source trees from a master CVS repository on a remote server host. The FreeBSD sources are maintained in a CVS repository on - a central development machine in California. With CVSup, + a central development machine in California. With CVSup, FreeBSD users can easily keep their own source trees up to date. - CVSup uses the so-called pull model of + CVSup uses the so-called pull model of updating. Under the pull model, each client asks the server for updates, if and when they are wanted. The server waits passively for update requests from its clients. Thus all updates are instigated by the client. The server never sends - unsolicited updates. Users must either run the CVSup client - manually to get an update, or they must set up a cron job to run + unsolicited updates. Users must either run the CVSup client + manually to get an update, or they must set up a cron job to run it automatically on a regular basis. The term CVSup, capitalized just so, refers to the entire @@ -25739,11 +25748,11 @@ subscribe freebsd-stable runs at each of the FreeBSD mirror sites. As you read the FreeBSD documentation and mailing lists, you - may see references to sup. Sup was the - predecessor of CVSup, and it served a similar purpose. CVSup is + may see references to sup. Sup was the + predecessor of CVSup, and it served a similar purpose. CVSup is in used in much the same way as sup and, in fact, uses - configuration files which are backward-compatible with sup's. - Sup is no longer used in the FreeBSD project, because CVSup is + configuration files which are backward-compatible with sup's. + Sup is no longer used in the FreeBSD project, because CVSup is both faster and more flexible. @@ -25752,7 +25761,7 @@ subscribe freebsd-stable id="cvsup-install"> Installation - The easiest way to install CVSup if you are running FreeBSD + The easiest way to install CVSup if you are running FreeBSD 2.2 or later is to use either the port from the FreeBSD or the corresponding binary package, depending on whether you prefer to roll your own or not. @@ -25762,16 +25771,16 @@ subscribe freebsd-stable FreeBSD-2.1.{6,7}. You can easily use the port, however, just as with FreeBSD 2.2. Simply unpack the tar file, cd to the cvsup subdirectory and type make install. - Because CVSup is written in Modula-3, both the package and the port require that the Modula-3 runtime libraries be installed. These are available as the lang/modula-3-lib port and the lang/modula-3-lib-3.6 package. If you follow the same directions as for cvsup, these libraries will be compiled and/or installed automatically when you install the CVSup port or package. + Because CVSup is written in Modula-3, both the package and the port require that the Modula-3 runtime libraries be installed. These are available as the lang/modula-3-lib port and the lang/modula-3-lib-3.6 package. If you follow the same directions as for cvsup, these libraries will be compiled and/or installed automatically when you install the CVSup port or package. The Modula-3 libraries are rather large, and fetching and compiling them is not an instantaneous process. For that reason, a third option is provided. You can get statically linked FreeBSD executables for - CVSup from either the USA distribution site: + CVSup from either the USA distribution site: + - @@ -25790,11 +25799,11 @@ subscribe freebsd-stable - + or the German mirror: - + @@ -25813,7 +25822,7 @@ subscribe freebsd-stable - + Most users will need only the client. These executables are entirely self-contained, and they will run on any version of @@ -25821,7 +25830,7 @@ subscribe freebsd-stable In summary, your options for installing CVSup are: - + @@ -25839,7 +25848,7 @@ subscribe freebsd-stable - + @@ -25847,7 +25856,7 @@ subscribe freebsd-stable id="cvsup-config"> Configuration - CVSup's operation is controlled by a configuration file + CVSup's operation is controlled by a configuration file called the supfile. Beginning with FreeBSD-2.2, there are some sample supfiles in the directory The information in a supfile answers the following questions for cvsup: - + @@ -25885,7 +25894,7 @@ subscribe freebsd-stable - + In the following sections, we will construct a typical supfile by answering each of these @@ -25899,16 +25908,16 @@ subscribe freebsd-stable Each remaining line describes a set of files that the user wishes to receive. The line begins with the name of a - "collection", a logical grouping of files defined by the server. + collection, a logical grouping of files defined by the server. The name of the collection tells the server which files you want. After the collection name come zero or more fields, separated by white space. These fields answer the questions listed above. There are two types of fields: flag fields and value fields. A flag field consists of a keyword standing - alone, e.g., or . A value field also begins + alone, e.g., delete or compress. A value field also begins with a keyword, but the keyword is followed without intervening white space by = and a second word. For example, - is a value field. + release=cvs is a value field. A supfile typically specifies more than one collection to receive. One way to structure a @@ -25916,38 +25925,38 @@ subscribe freebsd-stable fields explicitly for each collection. However, that tends to make the supfile lines quite long, and it is inconvenient because most fields are the same for all of the - collections in a supfile. CVSup provides a + collections in a supfile. CVSup provides a defaulting mechanism to avoid these problems. Lines beginning - with the special pseudo-collection name can be used + with the special pseudo-collection name *default can be used to set flags and values which will be used as defaults for the subsequent collections in the supfile. A default value can be overridden for an individual collection, by specifying a different value with the collection itself. Defaults can also be changed or augmented in mid-supfile by - additional lines. + additional *default lines. With this background, we will now proceed to construct a supfile for receiving and updating the main source tree of . - + Which files do you want to receive? - The files available via CVSup are organized into named - groups called "collections". The collections that are + The files available via CVSup are organized into named + groups called collections. The collections that are available are described . In this example, we wish to receive the entire main source tree for the FreeBSD system. There is - a single large collection which will give us all + a single large collection src-all which will give us all of that, except the export-controlled cryptography support. Let us assume for this example that we are in the USA or Canada. Then we can get the cryptography code - with one additional collection, . As a first + with one additional collection, cvs-crypto. As a first step toward constructing our supfile, we simply list these collections, one per line: @@ -25961,23 +25970,25 @@ cvs-crypto Which version(s) of them do you want? - With CVSup, you can receive virtually any version of + With CVSup, you can receive virtually any version of the sources that ever existed. That is possible because the cvsupd server works directly from the CVS repository, which contains all of the versions. You specify which one - of them you want using the and value + of them you want using the tag= and value fields. - WARNING: Be very - careful to specify any fields correctly. Some tags + + e very + careful to specify any tag= fields correctly. Some tags are valid only for certain collections of files. If you specify an incorrect or misspelled tag, CVSup will delete files which you probably do not want deleted. In particular, use only - tag=. for the + tag=. for the ports-* collections. - - The field names a symbolic tag in the + + + The tag= field names a symbolic tag in the repository. There are two kinds of tags, revision tags and branch tags. A revision tag refers to a specific revision. Its meaning stays the same from day to day. A @@ -25990,7 +26001,7 @@ cvs-crypto Here are the branch tags that users might be interested in: - + tag=. @@ -25998,7 +26009,7 @@ cvs-crypto FreeBSD-current. - The is not punctuation; it is the name + The . is not punctuation; it is the name of the tag. Valid for all collections. @@ -26024,7 +26035,7 @@ cvs-crypto - + Here are the revision tags that users might be interested in: @@ -26122,14 +26133,16 @@ cvs-crypto - WARNING: Be very - careful to type the tag name exactly as shown. CVSup + + Be very + careful to type the tag name exactly as shown. CVSup cannot distinguish between valid and invalid tags. If you - misspell the tag, CVSup will behave as though you had + misspell the tag, CVSup will behave as though you had specified a valid tag which happens to refer to no files at all. It will delete your existing sources in that case. - + + When you specify a branch tag, you normally receive the latest versions of the files on that line of development. If you wish to receive some past version, @@ -26146,7 +26159,8 @@ cvs-crypto There is an important special case that comes into - play if you specify neither a field nor a + play if you specify neither a tag= + field nor a date= field. In that case, you receive the actual RCS files directly from the server's CVS repository, rather than receiving a particular version. Developers generally @@ -26161,27 +26175,27 @@ cvs-crypto Where do you want to get them from? - We use the field to tell cvsup where to obtain + We use the host= field to tell cvsup where to obtain its updates. Any of the will do, though you should try to select one that's near to you. In this example, we'll use the primary FreeBSD distribution site, - "cvsup.FreeBSD.org": + cvsup.FreeBSD.org: *default host=cvsup.FreeBSD.org - On any particular run of cvsup, you can override this - setting on the command line, with . + On any particular run of cvsup, you can override this + setting on the command line, with . Where do you want to put them on your own machine? - The field tells cvsup where to put the files + The prefix= field tells cvsup where to put the files it receives. In this example, we will put the source files directly into our main source tree, /usr/src. The src directory is already implicit in the collections we have @@ -26194,12 +26208,12 @@ cvs-crypto - Where should cvsup maintain its status files?Where should cvsup maintain its status files? The cvsup client maintains certain status files in what is called the base directory. These files help - CVSup to work more efficiently, by keeping track of which + CVSup to work more efficiently, by keeping track of which updates you have already received. We will use the standard base directory, /usr/local/etc/cvsup: @@ -26212,7 +26226,7 @@ cvs-crypto need the above line. If your base directory does not already exist, now - would be a good time to create it. The cvsup client will + would be a good time to create it. The cvsup client will refuse to run if the base directory does not exist. @@ -26232,9 +26246,9 @@ cvs-crypto possibilities which are beyond the scope of this discussion. - delete gives CVSup permission to delete files. You - should always specify this, so that CVSup can keep your - source tree fully up to date. CVSup is careful to delete + delete gives CVSup permission to delete files. You + should always specify this, so that CVSup can keep your + source tree fully up to date. CVSup is careful to delete only those files for which it is responsible. Any extra files you happen to have will be left strictly alone. @@ -26268,27 +26282,27 @@ cvs-crypto - + - Running CVSup + Running <application>CVSup</application> You are now ready to try an update. The command line for doing this is quite simple: - &prompt.root; cvsup supfile + &prompt.root; cvsup supfile - where supfile is of course the name of the supfile you - have just created. Assuming you are running under X11, cvsup + where supfile is of course the name of the supfile you + have just created. Assuming you are running under X11, cvsup will display a GUI window with some buttons to do the usual - things. Press the "go" button, and watch it run. + things. Press the go button, and watch it run. Since you are updating your actual /usr/src tree in this - example, you will need to run the program as root so that cvsup + example, you will need to run the program as root so that cvsup has the permissions it needs to update your files. Having just created your configuration file, and having never used this program before, that might understandably make you nervous. @@ -26303,10 +26317,10 @@ cvs-crypto The directory you specify will be used as the destination - directory for all file updates. CVSup will examine your usual + directory for all file updates. CVSup will examine your usual files in /usr/src, but it will not modify or delete any of them. Any file updates will instead land in - /var/tmp/dest/usr/src. CVSup will also + /var/tmp/dest/usr/src. CVSup will also leave its base directory status files untouched when run this way. The new versions of those files will be written into the specified directory. As long as you have read access to @@ -26343,9 +26357,9 @@ cvs-crypto - CVSup File Collections + <application>CVSup</application> File Collections - The file collections available via CVSup are organized + The file collections available via CVSup are organized hierarchically. There are a few large collections, and they are divided into smaller sub-collections. Receiving a large collection is equivalent to receiving each of its @@ -26357,7 +26371,7 @@ cvs-crypto only by small groups of people for specialized purposes, and some mirror sites may not carry all of them. - + cvs-all release=cvs @@ -27016,14 +27030,14 @@ cvs-crypto - + Announcements, Questions, and Bug Reports - Most FreeBSD-related discussion of CVSup takes place on the + Most FreeBSD-related discussion of CVSup takes place on the &a.hackers;. New versions of the software are announced there, as well as on the &a.announce;. @@ -27114,7 +27128,8 @@ cvs-crypto The following tasks are considered to be urgent, usually because they represent something that is badly broken or sorely - needed: + needed: + @@ -27256,7 +27271,6 @@ cvs-crypto - @@ -27264,14 +27278,15 @@ cvs-crypto Medium priority tasks The following tasks need to be done, but not with any - particular urgency: + particular urgency: + Port AFS (Andrew File System) to FreeBSD Coordinator: - Alexander Seth - Jones + Jones @@ -27367,7 +27382,6 @@ cvs-crypto - @@ -27379,7 +27393,8 @@ cvs-crypto done anytime soon: The first 20 items are from Terry Lambert - <terry@lambert.org> + terry@lambert.org + @@ -27518,7 +27533,6 @@ cvs-crypto - @@ -27531,19 +27545,19 @@ cvs-crypto useful tasks which are suitable for "weekend hackers", or people without programming skills. - + If you run FreeBSD-current and have a good Internet - connection, there is a machine current.freebsd.org which + connection, there is a machine current.freebsd.org which builds a full release once a day - every now and again, try and install the latest release from it and report any failures in the process. - Read the freebsd-bugs mailing list. There might be a + Read the freebsd-bugs mailing list. There might be a problem you can comment constructively on or with patches you can test. Or you could even try to fix one of the problems yourself. @@ -27569,7 +27583,7 @@ cvs-crypto Read the freebsd-questions mailing list and the - newsgroup comp.unix.bsd.freebsd.misc occasionally (or even + newsgroup comp.unix.bsd.freebsd.misc occasionally (or even regularly). It can be very satisfying to share your expertise and help people solve their problems; sometimes you may even learn something new yourself! These forums can @@ -27618,7 +27632,7 @@ cvs-crypto - + @@ -27669,7 +27683,7 @@ cvs-crypto Changes to the documentation are overseen by the &a.doc;. Send submissions and changes (even small ones are welcome!) using - send-pr as described in + send-pr as described in . @@ -27698,14 +27712,20 @@ cvs-crypto Assuming that you can manage to secure fairly up-to-date sources to base your changes on, the next step is to produce a set of diffs to send to the FreeBSD maintainers. This is done with - the diff1 command, with the `context diff' - form being preferred. For example: - + the diff1 command, with the context diff + form being preferred. For example: + + &prompt.user; diff -c oldfile newfile - or + + + or + &prompt.user; diff -c -r olddir newdir - would generate such a set of context diffs for + + + would generate such a set of context diffs for the given source file or directory hierarchy. See the man page for diff1 for more details. @@ -27735,8 +27755,8 @@ cvs-crypto very busy and so you should only send mail to them where it is truly necessary. - Please refer to man 9 intro and - man 9 style for some information on + Please refer to man 9 intro and + man 9 style for some information on coding style. We would appreciate it if you were at least aware of this information before submitting code. @@ -27755,7 +27775,7 @@ cvs-crypto copyrights also invariably comes up. Acceptable copyrights for code included in FreeBSD are: - + @@ -27783,7 +27803,7 @@ cvs-crypto - + Contributions coming under any other type of copyright must be carefully reviewed before their inclusion into FreeBSD will be @@ -27795,7 +27815,7 @@ cvs-crypto To place a BSD-style copyright on your work, include the following text at the very beginning of every source code file you wish to protect, replacing the text between the - %% with the appropriate information. + %% with the appropriate information. Copyright (c) %%proper_years_here%% @@ -27823,7 +27843,9 @@ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. $Id$ - For your convenience, a copy of this text can + + + For your convenience, a copy of this text can be found in /usr/share/examples/etc/bsd-style-copyright. @@ -27907,8 +27929,8 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. #endif - Don't forget to add -DHAVE_SYS_PARAM_H to - the CFLAGS in the Makefile for this + Don't forget to add -DHAVE_SYS_PARAM_H to + the CFLAGS in the Makefile for this method. Once you have sys/param.h @@ -27941,7 +27963,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Use sparingly: - + @@ -27990,6 +28012,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. _FreeBSD_version + 2.0-RELEASE @@ -28133,10 +28156,10 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. you don't have to worry about old -current's; they are listed here just for your reference. - + In the hundreds of ports that have been done, there have - only been one or two cases where __FreeBSD__ + only 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. @@ -28172,7 +28195,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # Date created: 5 December 1994 # Whom: asami # -# $Id: book.sgml,v 1.42 1998-10-22 23:03:48 nik Exp $ +# $Id: book.sgml,v 1.43 1998-10-22 23:06:00 nik Exp $ # DISTNAME= oneko-1.1b @@ -28213,13 +28236,13 @@ USE_IMAKE= yes <filename>COMMENT</filename> This is the one-line description of the port. - PLEASE do not include the package name (or version - number of the software) in the comment. Here is - an example: + Please do not include the package name (or version + number of the software) in the comment. Here is + an example: A cat chasing a mouse all over the screen. - + @@ -28319,12 +28342,12 @@ lib/X11/oneko/mouse.xpm .tar.gz file, stick it in the directory ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/ and send mail to us using send-pr1 (please classify it as category - `ports' and class `change-request'). There is no need to + ports and class change-request). There is no need to upload the package, we will build it by ourselves. We will take a look, 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?!? :) + tree. Your name will also appear in the list of Additional + FreeBSD contributors on the FreeBSD Handbook and other files. + Isn't that great?!? :) @@ -28349,12 +28372,12 @@ lib/X11/oneko/mouse.xpm But do not worry if you do not really understand what bsd.port.mk is doing, not many people - do... :> + do... :> - - + + - + The fetch target is run. The fetch target is responsible for making sure that the tarball exists locally in ${DISTDIR}. @@ -28363,25 +28386,25 @@ lib/X11/oneko/mouse.xpm which is set in the Makefile, as well as our main ftp site at ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/, where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with ${FETCH}, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in ${DISTDIR} for future use and proceed. - + - + The extract target is run. It looks for your ports' distribution file in ${DISTDIR} (typically a gzip'd tarball) and unpacks it into a temporary subdirectory specified by ${WRKDIR} (defaults to work). - + - + The patch target is run. First, any patches defined in ${PATCHFILES} are applied. Second, if any patches are found in ${PATCHDIR} (defaults to the patches subdirectory), they are applied at this time in alphabetical order. - + - + The configure target is run. This can do any one of many different things. @@ -28410,9 +28433,9 @@ lib/X11/oneko/mouse.xpm - + - + The build target is run. This is responsible for descending into the ports' private working directory (${WRKSRC}) and @@ -28420,10 +28443,10 @@ lib/X11/oneko/mouse.xpm make will be used, otherwise the system make will be used. - + - - + + The above are the default actions. In addition, you can define targets pre-something or post-something, or put scripts @@ -28450,7 +28473,7 @@ lib/X11/oneko/mouse.xpm your Makefile. - The `main' targets (e.g., extract, configure, etc.) do nothing more than + The main targets (e.g., extract, configure, etc.) do nothing more than make sure all the stages up to that one is completed and call the real targets or scripts, and they are not intended to be changed. If you want to fix the extraction, fix @@ -28476,7 +28499,7 @@ lib/X11/oneko/mouse.xpm 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, we can `house' it ourselves by putting + non-standard formats, we can house it ourselves by putting it on ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/ as the last resort. Please refer to this location as ${MASTER_SITE_LOCAL}. Send mail to the &a.ports;if you are not sure what to do. @@ -28505,9 +28528,9 @@ lib/X11/oneko/mouse.xpm If your port requires significant user interaction/customization to compile or install, you should - take a look at one of Larry Wall's classic Configure scripts + take a look at one of Larry Wall's classic Configure scripts and perhaps do something similar yourself. The goal of the - new ports collection is to make each port as `plug-and-play' + 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. @@ -28558,8 +28581,8 @@ lib/X11/oneko/mouse.xpm Handling user input If your port requires user input to build, configure or - install, then set IS_INTERACTIVE in your - Makefile. This will allow `overnight builds' to skip your port + install, then set IS_INTERACTIVE in your + Makefile. This will allow overnight builds to skip your port if the user sets the variable BATCH in his environment (and if the user sets the variable INTERACTIVE, then only @@ -28601,7 +28624,7 @@ lib/X11/oneko/mouse.xpm - DISTNAME + <makevar>DISTNAME</makevar> You should set ${DISTNAME} to be the base name of your port. The default rules expect the distribution file @@ -28630,7 +28653,7 @@ DISTNAME=foozolix-1.0 - CATEGORIES + <makevar>CATEGORIES</makevar> When a package is created, it is put under /usr/ports/packages/All and links are @@ -28649,13 +28672,13 @@ DISTNAME=foozolix-1.0 - MASTER_SITES + <makevar>MASTER_SITES</makevar> Record the directory part of the ftp/http-URL pointing at the original tarball in ${MASTER_SITES}. Do not forget the trailing slash (/)! - The make macros will try to use this specification for + The make macros will try to use this specification for grabbing the distribution file with ${FETCH} if they cannot find it already on the system. @@ -28668,17 +28691,17 @@ DISTNAME=foozolix-1.0 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 MASTER_SITE_XCONTRIB, MASTER_SITE_GNU, - MASTER_SITE_PERL_CPAN, MASTER_SITE_TEX_CTAN, and - MASTER_SITE_SUNSITE. Simply set MASTER_SITE_SUBDIR to the - path with in the archive. Here is an example: + form using MASTER_SITE_XCONTRIB, MASTER_SITE_GNU, + MASTER_SITE_PERL_CPAN, MASTER_SITE_TEX_CTAN, and + MASTER_SITE_SUNSITE. Simply set MASTER_SITE_SUBDIR to the + path with in the archive. Here is an example: MASTER_SITES= ${MASTER_SITE_XCONTRIB} MASTER_SITE_SUBDIR= applications - + - The user can also set the MASTER_SITE_* variables in + The user can also set the MASTER_SITE_* variables in /etc/make.conf to override our choices, and use their favorite mirrors of these popular archives instead. @@ -28687,7 +28710,7 @@ MASTER_SITE_SUBDIR= applications - PATCHFILES + <makevar>PATCHFILES</makevar> If your port requires some additional patches that are available by ftp or http, set ${PATCHFILES} to the names of the @@ -28699,7 +28722,7 @@ MASTER_SITE_SUBDIR= applications (i.e., ${WKRSRC}) because it contains some extra pathnames, set ${PATCH_DIST_STRIP} accordingly. For instance, if all the pathnames in the patch has an extra - foozolix-1.0/ in front of the + foozolix-1.0/ in front of the filenames, then set PATCH_DIST_STRIP=-p1. @@ -28732,10 +28755,9 @@ MASTER_SITE_SUBDIR= applications - MAINTAINER + <makevar>MAINTAINER</makevar> - Set your mail-address here. Please. :) + Set your mail-address here. Please. :) For detailed description of the responsibility of maintainers, refer to - LIB_DEPENDS + <makevar>LIB_DEPENDS</makevar> This variable specifies the shared libraries this port - depends on. It is a list of lib:dir pairs where - lib is the name of the shared library, - and dir is the directory in which to + depends on. It is a list of lib:dir pairs where + lib is the name of the shared library, + and dir is the directory in which to find it in case it is not available. For example, LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg - will check for a shared jpeg library with + + + will check for a shared jpeg library with major version 6, and descend into the graphics/jpeg subdirectory of your ports tree to build and install it if it is not found. - The lib part is just an argument + The lib part is just an argument given to ldconfig -r | grep, so periods should be escaped by two backslashes like in the example above. @@ -28785,16 +28808,15 @@ LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg - RUN_DEPENDS + <makevar>RUN_DEPENDS</makevar> This variable specifies executables or files this port - depends on during run-time. It is a list of path:dir pairs where - path is the name of the executable or - file, and dir is the directory in which + depends on during run-time. It is a list of path:dir pairs where + path is the name of the executable or + file, and dir is the directory in which to find it in case it is not available. If - path starts with a slash - (/), it is treated as a file and its + path starts with a slash + (/), it is treated as a file and its existence is tested with test -e; otherwise, it is assumed to be an executable, and which -s is used to determine if the @@ -28805,7 +28827,9 @@ LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \ wish:${PORTSDIR}/x11/tk - will check if the file + + + will check if the file /usr/local/etc/innd exists, and build and install it from the news/inn subdirectory of the ports tree if it is not found. It will @@ -28823,45 +28847,49 @@ RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \ The dependency is checked from within the install target. Also, the name of the dependency is put in to the package so that - pkg_add will automatically install it if it + pkg_add will automatically install it if it is not on the user's system. - BUILD_DEPENDS + <makevar>BUILD_DEPENDS</makevar> This variable specifies executables or files this port - requires to build. Like RUN_DEPENDS, it is - a list of path:dir pairs. + requires to build. Like RUN_DEPENDS, it is + a list of path:dir pairs. For example, BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip - will check for an executable called + + + will check for an executable called unzip, and descend into the archivers/unzip subdirectory of your ports tree to build and install it if it is not found. - `build' here means everything from extracting to + build here means everything from extracting to compilation. The dependency is checked from within the extract target. - FETCH_DEPENDS + <makevar>FETCH_DEPENDS</makevar> This variable specifies executables or files this port requires to fetch. Like the previous two, it is a list of - path:dir pairs. For + path:dir pairs. For example, FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - will check for an executable called + + + will check for an executable called ncftp2, and descend into the net/ncftp2 subdirectory of your ports tree to build and install it if it is not found. @@ -28871,7 +28899,7 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - DEPENDS + <makevar>DEPENDS</makevar> If there is a dependency that does not fall into either of the above four categories, or your port requires to have @@ -28911,13 +28939,13 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - NO_INSTALL_MANPAGES + <makevar>NO_INSTALL_MANPAGES</makevar> - If the port uses imake but does not understand the + If the port uses imake but does not understand the install.man target, NO_INSTALL_MANPAGES=yes should be set. In addition, the author of the original port should be shot. - :> + :> @@ -28936,7 +28964,7 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - REQUIRES_MOTIF + <makevar>REQUIRES_MOTIF</makevar> If your port requires Motif, define this variable in the Makefile. This will prevent people who don't own a copy of @@ -28945,7 +28973,7 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - ${MOTIFLIB} + <makevar>${MOTIFLIB}</makevar> This variable will be set by bsd.port.mk to be the appropriate @@ -28953,7 +28981,8 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 use this wherever the Motif library is referenced in the Makefile or Imakefile. - There are two common cases: + There are two common cases: + @@ -28969,12 +28998,11 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 - ${MOTIFLIB} (usually) - expands to or - /usr/X11R6/lib/libXm.a, so there is + expands to -L/usr/X11R6/lib -lXm or + /usr/X11R6/lib/libXm.a, so there is no need to add or in front. @@ -28993,7 +29021,7 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 the length of this section, but it is imperative to weave all the info files together. If done correctly, it will produce a beautiful listing, so please bear with me! - :) + :) First, this is what you (as a porter) need to know: @@ -29024,7 +29052,7 @@ Options: Look at the texinfo sources and make a patch to insert - @dircategory and @direntry + @dircategory and @direntry statements to files that don't have them. This is part of my patch: @@ -29061,7 +29089,7 @@ Options: @direntry section. - You can give the dir + You can give the dir entries to install-info as arguments ( and ) instead of patching the texinfo @@ -29069,7 +29097,7 @@ Options: because you need to duplicate the same information in three places (Makefile and - @exec/@unexec of + @exec/@unexec of PLIST; see below). However, if you have a Japanese (or other multibyte encoding) info files, you will have to use the extra arguments to install-info because makeinfo can't handle those texinfo @@ -29085,10 +29113,10 @@ Options: Since the texinfo sources are newer than the info files, they should be rebuilt when you type make; but many Makefiles don't include correct - dependencies for info files. In emacs' case, I had to + dependencies for info files. In emacs' case, I had to patch the main Makefile.in so it will descend into the man - subdirectory to rebuild the info pages. + subdirectory to rebuild the info pages. --- ./Makefile.in.org Mon Aug 19 21:12:19 1996 @@ -29112,7 +29140,7 @@ Options: info: $(INFO_TARGETS) dvi: $(DVI_TARGETS) - + The second hunk was necessary because the default target in the man subdir is called @@ -29130,7 +29158,7 @@ Options: dir file, delete it. Your port may not be doing it. Also, remove any commands that are otherwise mucking around with the - dir file. + dir file. --- ./Makefile.in.org Mon Aug 19 21:12:19 1996 @@ -29150,12 +29178,12 @@ Options: (cd $${thisdir}; \ ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \ chmod a+r ${infodir}/$$f); \ - + (This step is only necessary if you are modifying an - existing port.) Take a look at + existing port.) Take a look at pkg/PLIST and delete anything that is trying to patch up info/dir. They may be in pkg/INSTALL or some other @@ -29187,7 +29215,7 @@ diff -u -r1.15 PLIST target to the Makefile to create a dir file if it is not there. Also, call install-info with the - installed info files. + installed info files. Index: Makefile @@ -29210,7 +29238,7 @@ diff -u -r1.26 Makefile +.endfor .include <bsd.port.mk> - + Do not use anything other than /usr/share/info/dir and the above @@ -29223,10 +29251,10 @@ diff -u -r1.26 Makefile Edit PLIST and add equivalent - @exec statements and also - @unexec for pkg_delete. + @exec statements and also + @unexec for pkg_delete. You do not need to delete info/dir - with @unexec. + with @unexec. Index: pkg/PLIST @@ -29253,26 +29281,25 @@ diff -u -r1.15 PLIST +@exec install-info %D/info/ccmode %D/info/dir libexec/emacs/19.34/i386--freebsd/cvtmail libexec/emacs/19.34/i386--freebsd/digest-doc - + - The @unexec install-info - --delete commands have to be listed before + The @unexec install-info + --delete commands have to be listed before the info files themselves so they can read the files. - Also, the @exec install-info commands + Also, the @exec install-info commands have to be after the info files and the - @exec command that creates the the + @exec command that creates the the dir file. - Test and admire your work. Test and admire your work. :) The sequence I recommend is: make package, - pkg_delete, then - pkg_add. Check the dir file before and after each + pkg_delete, then + pkg_add. Check the dir file before and after each step. @@ -29301,12 +29328,12 @@ diff -u -r1.15 PLIST There are two variables you can set in the Makefile to handle the situations that arise frequently: - + - If the port has a `do not sell for profit' type of - license, set the variable NO_CDROM. We + If the port has a do not sell for profit type of + license, set the variable NO_CDROM. 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. @@ -29316,7 +29343,7 @@ diff -u -r1.15 PLIST 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 - NO_PACKAGE. We will make sure such + NO_PACKAGE. 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. @@ -29324,15 +29351,15 @@ diff -u -r1.15 PLIST 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 RESTRICTED to be the + (e.g., crypto stuff) or has a no commercial use license, + set the variable RESTRICTED to be the string describing the reason why. For such ports, the distfiles/packages will not be available even from our ftp sites. - + The GNU General Public License (GPL), both version 1 @@ -29355,7 +29382,7 @@ diff -u -r1.15 PLIST sites. The next step is to send a mail to the maintainer, if one is - listed in the port's Makefile. That person may already be + listed in the port's Makefile. 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). @@ -29365,14 +29392,14 @@ diff -u -r1.15 PLIST 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 (i.e., if your modified ports - directory is called superedit + directory is called superedit and the original as in our tree is superedit.bak, then send us the result of - diff -ruN superedit.bak - superedit). Please examine the output to make + diff -ruN superedit.bak + superedit). 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 send-pr1 - (category `ports'). Please mention any added or deleted files + (category ports). 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 @@ -29388,7 +29415,7 @@ diff -u -r1.15 PLIST - WRKDIR + <makevar>WRKDIR</makevar> Do not leave anything valuable lying around in the work subdirectory, make clean will @@ -29406,8 +29433,7 @@ diff -u -r1.15 PLIST Do include package information, i.e. COMMENT, DESCR, and - PLIST, in pkg. + PLIST, in pkg. Note that these files are not used only for packaging @@ -29423,30 +29449,30 @@ diff -u -r1.15 PLIST Do compress manpages and strip binaries. If the original source already strips the binary, fine; otherwise, you can add a post-install rule to do it - yourself. Here is an example: + yourself. Here is an example: post-install: strip ${PREFIX}/bin/xdl - + - Use the file command on the + Use the file command on the installed executable to check whether the binary is stripped or not. If it does not say `not stripped', it is stripped. - To automagically compress the manpages, use the MAN[1-9LN] + To automagically compress the manpages, use the MAN[1-9LN] variables. They will check the variable - NOMANCOMPRESS that the user can set in + NOMANCOMPRESS that the user can set in /etc/make.conf to disable man page compression. Place them last in the section below the - MAINTAINER variable. Here is an example: + MAINTAINER variable. Here is an example: MAN1= foo.1 bar.1 MAN5= foo.conf.5 MAN8= baz.8 - + This is not usually necessary with ports that are X @@ -29454,25 +29480,25 @@ MAN8= baz.8 If your port anchors its man tree somewhere other than - PREFIX, you can use the - MANPREFIX to set it. Also, if only manpages + PREFIX, you can use the + MANPREFIX to set it. Also, if only manpages in certain section go in a non-standard place, such as many Perl modules ports, you can set individual man paths using - MANsectPREFIX - (where sect is one of 1-9, L or + MANsectPREFIX + (where sect is one of 1-9, L or N). - INSTALL_* macros + <makevar>INSTALL_*</makevar> macros Do use the macros provided in bsd.port.mk to ensure correct modes and ownership of files in your own *-install targets. They are: - + @@ -29497,7 +29523,7 @@ MAN8= baz.8 - + These are basically the install command with all the appropriate flags. See below for an example on how to use them. @@ -29511,13 +29537,11 @@ MAN8= baz.8 package is installed with pkg_add you can do with via the pkg/INSTALL script. This script will automatically be added to the package, and will be run twice - by pkg_add. The first time will as INSTALL ${PKGNAME} PRE-INSTALL and the - second time as INSTALL ${PKGNAME} - POST-INSTALL. $2 can be tested to determine which + by pkg_add. The first time will as INSTALL ${PKGNAME} PRE-INSTALL and the + second time as INSTALL ${PKGNAME} + POST-INSTALL. $2 can be tested to determine which mode the script is being run in. The - PKG_PREFIX environmental variable will be + PKG_PREFIX environmental variable will be set to the package installation directory. See man pkg_add1 for additional information. @@ -29559,8 +29583,8 @@ MAN8= baz.8 whole ${PKGNAME}. Make the installation dependent to the variable - NOPORTDOCS so that users can disable it in - /etc/make.conf, like this: + NOPORTDOCS so that users can disable it in + /etc/make.conf, like this: post-install: @@ -29568,11 +29592,11 @@ post-install: ${MKDIR}${PREFIX}/share/doc/xv ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv .endif - + Do not forget to add them to pkg/PLIST too! (Do not worry about - NOPORTDOCS here; there is currently no way + NOPORTDOCS here; there is currently no way for the packages to read variables from /etc/make.conf.) @@ -29589,13 +29613,13 @@ post-install: - DIST_SUBDIR + <makevar>DIST_SUBDIR</makevar> Do not let your port clutter /usr/ports/distfiles. 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., - `Makefile'), set ${DIST_SUBDIR} to the name of the + Makefile), set ${DIST_SUBDIR} to the name of the port (${PKGNAME} without the version part should work fine). This will change ${DISTDIR} from the default /usr/ports/distfiles to @@ -29606,7 +29630,7 @@ post-install: It will also look at the subdirectory with the same name on the backup master site at ftp.freebsd.org. (Setting ${DISTDIR} explicitly in your - Makefile will not accomplish this, so please use ${DIST_SUBDIR}.) + Makefile will not accomplish this, so please use ${DIST_SUBDIR}.) This does not affect the ${MASTER_SITES} you define in your @@ -29630,10 +29654,8 @@ post-install: 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 ($) signs, and typically start with - $Id or $RCS. + will fail. RCS strings are surrounded by dollar ($) signs, and typically start with + $Id or $RCS. @@ -29644,8 +29666,8 @@ post-install: diff 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, Makefiles when the - port uses Imake or GNU configure, etc., are unnecessary and + particular, diffs between two backup files, Makefiles when the + port uses Imake or GNU configure, etc., are unnecessary and should be deleted. Also, if you had to delete a file, then you can do it in the post-extract target rather than as part of the patch. Once you are happy @@ -29655,7 +29677,7 @@ post-install: - PREFIX + <makevar>PREFIX</makevar> Do try to make your port install relative to ${PREFIX}. (The value of this variable will be set to ${LOCALBASE} (default @@ -29666,7 +29688,7 @@ post-install: Not hard-coding /usr/local or /usr/X11R6 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 imake, this is + needs of other sites. For X ports that use imake, this is automatic; otherwise, this can often be done by simply replacing the occurrences of /usr/local (or /usr/X11R6 for X ports that do not @@ -29679,22 +29701,26 @@ post-install: can be reassigned in your Makefile or in the user's environment. However, it is strongly discouraged for individual ports to set this variable explicitly in the - Makefiles. (If your port is an X port but does not use imake, + Makefiles. (If your port is an X port but does not use imake, set USE_X11=yes; this is quite different from setting PREFIX=/usr/X11R6.) Also, refer to programs/files from other ports with the variables mentioned above, not explicit pathnames. For instance, if your port requires a macro - PAGER to be the full pathname of less, use the compiler flag: + PAGER to be the full pathname of less, use the compiler flag: -DPAGER=\"${PREFIX}/bin/less\" - or + + + or -DPAGER=\"${LOCALBASE}/bin/less\" - if this is an X port, instead of -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. + + + if this is an X port, instead of -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. @@ -29717,7 +29743,7 @@ post-install: files). See man hier7 for details, the rule governing /usr pretty much applies to /usr/local too. The - exception are ports dealing with USENET `news'. They may use + exception are ports dealing with USENET news. They may use ${PREFIX}/news as a destination for their files. @@ -29732,20 +29758,20 @@ post-install: ${PREFIX}/lib) to register it into the shared library cache. - Also, add an @exec line to your + Also, add an @exec line to your pkg/PLIST file so that a user who installed the package can start using the shared library immediately. This line should immediately follow the line - for the shared library itself, as in: + for the shared library itself, as in: lib/libtcl80.so.1.0 @exec /sbin/ldconfig -m %D/lib - + Never, ever, ever add a line that says ldconfig without any - arguments to your Makefile or pkg/PLIST. This will reset the + arguments to your Makefile or pkg/PLIST. This will reset the shared library cache to the contents of /usr/lib only, and will royally screw up the user's machine (Help, xinit does not run anymore after I @@ -29804,11 +29830,10 @@ msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh Do look at existing examples and the bsd.port.mk file before asking us - questions! ;) + questions! ;) Do ask us questions if you have any trouble! Do not just - beat your head against a wall! :) + beat your head against a wall! :) @@ -29925,7 +29950,7 @@ pre-install: doesn't look like that, set ${PKGNAME} to something in that format. - + @@ -29946,7 +29971,7 @@ pre-install: convert the name (or at least the first letter) to lowercase. If the software in question really is called that way, you can have numbers, hyphens and underscores in - the name too (like `kinput2'). + the name too (like kinput2). @@ -29967,7 +29992,7 @@ pre-install: - + Here are some (real) examples on how to convert a ${DISTNAME} into a suitable ${PKGNAME}: @@ -29980,6 +30005,7 @@ pre-install: Reason + mule-2.2.2. @@ -30089,7 +30115,7 @@ pre-install: 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! - :) + :)