From owner-svn-doc-all@FreeBSD.ORG Sun Feb 9 01:50:54 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id EBA47ABD; Sun, 9 Feb 2014 01:50:54 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id D27E71322; Sun, 9 Feb 2014 01:50:54 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s191osnn016340; Sun, 9 Feb 2014 01:50:54 GMT (envelope-from trhodes@svn.freebsd.org) Received: (from trhodes@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s191osWP016334; Sun, 9 Feb 2014 01:50:54 GMT (envelope-from trhodes@svn.freebsd.org) Message-Id: <201402090150.s191osWP016334@svn.freebsd.org> From: Tom Rhodes Date: Sun, 9 Feb 2014 01:50:54 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43840 - in head/en_US.ISO8859-1/books/porters-handbook: . appendices keeping-up makefiles new-port pkg-files plist porting-dads porting-samplem porting-why quick-porting security slow-... X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 09 Feb 2014 01:50:55 -0000 Author: trhodes Date: Sun Feb 9 01:50:53 2014 New Revision: 43840 URL: http://svnweb.freebsd.org/changeset/doc/43840 Log: Break the porters handbook out into individual chapters like our other books (fdp primer, handbook dev handbook, etc). I've done some small naming changes for cleaner chapters but not much. Thumbs up: wblock, mat Added: head/en_US.ISO8859-1/books/porters-handbook/appendices/ head/en_US.ISO8859-1/books/porters-handbook/appendices/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/appendices/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/chapters.ent (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/keeping-up/ head/en_US.ISO8859-1/books/porters-handbook/keeping-up/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/keeping-up/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/makefiles/ head/en_US.ISO8859-1/books/porters-handbook/makefiles/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/new-port/ head/en_US.ISO8859-1/books/porters-handbook/new-port/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/new-port/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/pkg-files/ head/en_US.ISO8859-1/books/porters-handbook/pkg-files/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/plist/ head/en_US.ISO8859-1/books/porters-handbook/plist/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/porting-dads/ head/en_US.ISO8859-1/books/porters-handbook/porting-dads/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/porting-samplem/ head/en_US.ISO8859-1/books/porters-handbook/porting-samplem/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/porting-why/ head/en_US.ISO8859-1/books/porters-handbook/porting-why/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/porting-why/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/quick-porting/ head/en_US.ISO8859-1/books/porters-handbook/quick-porting/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/security/ head/en_US.ISO8859-1/books/porters-handbook/security/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/security/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/slow-porting/ head/en_US.ISO8859-1/books/porters-handbook/slow-porting/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/special/ head/en_US.ISO8859-1/books/porters-handbook/special/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/testing/ head/en_US.ISO8859-1/books/porters-handbook/testing/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/upgrading/ head/en_US.ISO8859-1/books/porters-handbook/upgrading/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml (contents, props changed) Modified: head/en_US.ISO8859-1/books/porters-handbook/Makefile head/en_US.ISO8859-1/books/porters-handbook/book.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/Makefile ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/Makefile Sat Feb 8 22:08:51 2014 (r43839) +++ head/en_US.ISO8859-1/books/porters-handbook/Makefile Sun Feb 9 01:50:53 2014 (r43840) @@ -19,6 +19,22 @@ INSTALL_ONLY_COMPRESSED?= # # XML content +#SRCS+= quick-porting/chapter.xml +#SRCS+= own-port/chapter.xml +#SRCS+= porting-why/chapter.xml +SRCS+= makefiles/chapter.xml +#SRCS+= plist/chapter.xml +#SRCS+= testing/chapter.xml +#SRCS+= security/chapter.xml +#SRCS+= porting-samplem/chapter.xml +#SRCS+= appendices/chapter.xml +#SRCS+= keeping-up/chapter.xml +#SRCS+= porting-dads/chapter.xml +#SRCS+= upgrading/chapter.xml +#SRCS+= pkg-files/chapter.xml +#SRCS+= specials/chapter.xml +#SRCS+= slow-porting/chapter.xml + SRCS= book.xml SRCS+= uses.xml SRCS+= versions.xml @@ -49,4 +65,14 @@ IMAGES_LIB+= callouts/21.png URL_RELPREFIX?= ../../../.. DOC_PREFIX?= ${.CURDIR}/../../.. +# Entities +SRCS+= chapters.ent + +SYMLINKS= ${DESTDIR} index.html handbook.html + +# Turn on all the chapters. +CHAPTERS?= ${SRCS:M*chapter.xml} + +XMLFLAGS+= ${CHAPTERS:S/\/chapter.xml//:S/^/-i chap./} + .include "${DOC_PREFIX}/share/mk/doc.project.mk" Added: head/en_US.ISO8859-1/books/porters-handbook/appendices/Makefile ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/en_US.ISO8859-1/books/porters-handbook/appendices/Makefile Sun Feb 9 01:50:53 2014 (r43840) @@ -0,0 +1,15 @@ +# +# Build the Porters Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= appendices/chapter.xml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" Added: head/en_US.ISO8859-1/books/porters-handbook/appendices/chapter.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/en_US.ISO8859-1/books/porters-handbook/appendices/chapter.xml Sun Feb 9 01:50:53 2014 (r43840) @@ -0,0 +1,72 @@ + + + + + Appendices + + + Values of <varname>USES</varname> + + + Values of <varname>USES</varname> + + + + + Feature + Arguments + Description + + + + + &values.uses; + + +
+ + + + <literal>__FreeBSD_version</literal> Values + + Here is a convenient list of + __FreeBSD_version values as defined in + sys/param.h: + + + <literal>__FreeBSD_version</literal> Values + + + + + Value + Date + Release + + + + + &values.versions; + + +
+ + + Note that 2.2-STABLE sometimes identifies itself as + 2.2.5-STABLE after the 2.2.5-RELEASE. The + pattern used to be year followed by the month, but we + decided to change it to a more straightforward major/minor + system starting from 2.2. This is because the parallel + development on several branches made it infeasible to + classify the releases simply by their real release dates. + If you are making a port now, you do not have to worry about + old -CURRENTs; they are listed here just for your + reference. + + + Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/book.xml Sat Feb 8 22:08:51 2014 (r43839) +++ head/en_US.ISO8859-1/books/porters-handbook/book.xml Sun Feb 9 01:50:53 2014 (r43840) @@ -3,13 +3,17 @@ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ -]> + + +%chapters; +]> + @@ -56,12747 +60,19 @@ $FreeBSD$ - - Introduction - - The &os; Ports Collection is the way almost everyone - installs applications ("ports") on &os;. Like everything - else about &os;, it is primarily a volunteer effort. - It is important to keep this in mind when reading this - document. - - In &os;, anyone may submit a new port, or volunteer - to maintain an existing port if it is unmaintained—you - do not need any special commit privileges to do so. - - - - - Making a New Port Yourself - - So, you are interested in making your own port or - upgrading an existing one? Great! - - What follows are some guidelines for creating a new port for - &os;. If you want to upgrade an existing port, you should - read this and then read . - - When this document is not sufficiently detailed, you should - refer to /usr/ports/Mk/bsd.port.mk, which - all port Makefiles include. Even if you do not hack Makefiles - daily, it is well commented, and you will still gain much - knowledge from it. Additionally, you may send specific - questions to the &a.ports;. - - - Only a fraction of the variables - (VAR) that can - be overridden are mentioned in this document. Most (if not - all) are documented at the start of - /usr/ports/Mk/bsd.port.mk; the others - probably ought to be. Note that this file uses a non-standard - tab setting: Emacs and - Vim should recognize the setting on - loading the file. Both &man.vi.1; and &man.ex.1; can be set - to use the correct value by typing - :set tabstop=4 once the file has been - loaded. - - - - Looking for something easy to start with? Take a look at the - list of - requested ports and see if you can work on one (or - more). - - - - Quick Porting - - This section tells you how to quickly create a new port. In - many cases, it is not sufficient, so you will have to read - further on into the document. - - First, get the original tarball and put it into - DISTDIR, which defaults to - /usr/ports/distfiles. - - - The following assumes that the software compiled - out-of-the-box, i.e., there was absolutely no change required - for the port to work on your &os; box. If you needed to - change something, you will have to refer to the next section - too. - - - - It is recommended to set the DEVELOPER - &man.make.1; variable in /etc/make.conf - before getting into porting. - - &prompt.root; echo DEVELOPER=yes >> /etc/make.conf - - This setting enables the developer mode - that displays deprecation warnings and activates some further - quality checks on calling make. - - - - Writing the <filename>Makefile</filename> - - The minimal Makefile would look - something like this: - - # $FreeBSD$ - -PORTNAME= oneko -PORTVERSION= 1.1b -CATEGORIES= games -MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ - -MAINTAINER= youremail@example.com -COMMENT= Cat chasing a mouse all over the screen - -.include <bsd.port.mk> - - - In some cases, the Makefile of an - existing port may contain additional lines in the header, - such as the name of the port and the date it was created. - This additional information has been declared obsolete, and - is being phased out. - - - See if you can figure it out. Do not worry about the - contents of the $FreeBSD$ - line, it will be filled in automatically by - Subversion when the port is - imported to our main ports tree. You can find a more detailed - example in the - sample Makefile - section. - - - - Writing the Description Files - - There are two description files that are required for - any port, whether they actually package or not. They are - pkg-descr and - pkg-plist. Their - pkg- prefix distinguishes them from other - files. - - - <filename>pkg-descr</filename> - - This is a longer description of the port. One to a few - paragraphs concisely explaining what the port does is - sufficient. - - - This is not a manual or an - in-depth description on how to use or compile the port! - Please be careful if you are copying from the - README or manpage; too - often they are not a concise description of the port or - are in an awkward format (e.g., manpages have justified - spacing, which looks particularly bad with monospaced - fonts). - - - A well-written pkg-descr describes - the port completely enough that users would not have to - consult the documentation or visit the website to understand - what the software does, how it can be useful, or what - particularly nice features it has. Mentioning certain - requirements like a graphical toolkit, heavy dependencies, - runtime environment, or implementation languages help users - decide whether this port will work for them. - - Include a URL to the official WWW homepage. Prepend - one of the websites (pick the most - common one) with WWW: (followed by single - space) so that automated tools will work correctly. If the - URI is the root of the website or directory, it should be - terminated with a slash. - - - If the listed webpage for a port is not available, try - to search the Internet first to see if the official site - moved, was renamed, or is hosted elsewhere. - - - The following example shows how your - pkg-descr should look: - - This is a port of oneko, in which a cat chases a poor mouse all over -the screen. - : -(etc.) - -WWW: http://www.oneko.org/ - - - - <filename>pkg-plist</filename> - - This file lists all the files installed by the port. It - is also called the packing list because the - package is generated by packing the files listed here. The - pathnames are relative to the installation prefix (usually - /usr/local. - If the - port creates directories during installation, make sure to - add @dirrm lines to remove them when the - package is deleted. - - Here is a small example: - - bin/oneko -man/man1/oneko.1.gz -lib/X11/app-defaults/Oneko -lib/X11/oneko/cat1.xpm -lib/X11/oneko/cat2.xpm -lib/X11/oneko/mouse.xpm -@dirrm lib/X11/oneko - - Refer to the &man.pkg-create.8; manual page for details - on the packing list. - - - It is recommended that you keep all the filenames in - this file sorted alphabetically. It will make verifying - the changes when you upgrade the port much easier. - - - - Creating a packing list manually can be a very tedious - task. If the port installs a large numbers of files, - creating the packing list - automatically might save time. - - - There is only one case when - pkg-plist can be omitted from a port. - If the port installs just a handful of files, and perhaps - directories, the files and directories may be listed in the - variables PLIST_FILES and - PLIST_DIRS, respectively, within the - port's Makefile. For instance, we - could get along without pkg-plist in - the above oneko port by adding the - following lines to the Makefile: - - PLIST_FILES= bin/oneko \ - man/man1/oneko.1.gz \ - lib/X11/app-defaults/Oneko \ - lib/X11/oneko/cat1.xpm \ - lib/X11/oneko/cat2.xpm \ - lib/X11/oneko/mouse.xpm -PLIST_DIRS= lib/X11/oneko - - Of course, PLIST_DIRS should be left - unset if a port installs no directories of its own. - - - - Several ports can share a common directory. In that - case, PLIST_DIRS should be replaced by - PLIST_DIRSTRY so that the directory is - removed only if empty, otherwise it is silently ignored. - PLIST_DIRS and - PLIST_DIRSTRY are equivalent to using - @dirrm and @dirrmtry - in pkg-plist, as described in - . - - - The price for this way of listing port's files and - directories is that you cannot use command sequences - described in &man.pkg-create.8;. Therefore, it is suitable - only for simple ports and makes them even simpler. At the - same time, it has the advantage of reducing the number of - files in the ports collection. Please consider using this - technique before you resort to - pkg-plist. - - Later we will see how pkg-plist - and PLIST_FILES can be used to fulfill - more sophisticated - tasks. - - - - - Creating the Checksum File - - Just type make makesum. The ports make - rules will automatically generate the file - distinfo. - - If a file fetched has its checksum changed regularly and - you are certain the source is trusted (i.e., it comes from - manufacturer CDs or documentation generated daily), you should - specify these files in the IGNOREFILES - variable. Then the checksum is not calculated for that file - when you run make makesum, but set to - IGNORE. - - - - Testing the Port - - You should make sure that the port rules do exactly what - you want them to do, including packaging up the port. These - are the important points you need to verify. - - - - pkg-plist does not contain - anything not installed by the port. - - - - pkg-plist contains everything - that is installed by the port. - - - - The port can be installed using the - install target. This verifies - that the install script works correctly. - - - - The port can be deinstalled properly using the - deinstall target. This - verifies that the deinstall script works correctly. - - - - Make sure that make package can be - run as a normal user (that is, not as - root). If that - fails, NEED_ROOT=yes must be added to - the port Makefile. - - - - - Recommended Test Ordering - - - make stage - - - - make check-orphans - - - - make package - - - - make install - - - - make deinstall - - - - pkg add package-filename - - - - make package (as user) - - - - Make certain no warnings are shown in any of - the stages. - - Thorough automated testing can be done with - ports-mgmt/tinderbox or - ports-mgmt/poudriere from the - Ports Collection. These applications maintain - jails where all of the steps shown above - can be tested without affecting the state of the host - system. - - - - Checking Your Port with - <command>portlint</command> - - Please use portlint to see if your port - conforms to our guidelines. The - ports-mgmt/portlint - program is part of the ports collection. In particular, you - may want to check if the - Makefile is in the - right shape and the - package is named - appropriately. - - - - Submitting the New Port - - Before submitting the new port, read - the DOs and DON'Ts - section. - - Once happy with your port, the only thing remaining is to - put it in the main &os; ports tree and make everybody else - happy about it too. We do not need the - work directory or the - pkgname.tgz package, so delete them - now. - - Next, build the &man.shar.1; file. Assuming the port is - called oneko, cd to the - directory above where the oneko directory - is located, and then type: - shar `find oneko` > oneko.shar - - Include oneko.shar in a bug - report and send it with &man.send-pr.1;. See - Bug - Reports and General Commentary for more information - about &man.send-pr.1;. - - Classify the bug report as Category - ports and Class - change-request. Do - not mark the report - confidential! Add a short description of - the program to the Description field of the PR (perhaps a - short version of the COMMENT), and add the - .shar file to the Fix field. - - - Giving a good description in the synopsis of the problem - report makes the work of port committers a lot easier. We - prefer something like New port: - <category>/<portname> <short description of - the port> for new ports. Using this - scheme makes it easier and faster to begin the work of - committing the new port. - - - One more time, do not include the original - source distfile, the work directory, or - the package you built with - make package; and, do use - &man.shar.1; for new ports, not &man.diff.1;. - - After submitting the port, please be patient. The time - needed to include a new port in &os; can vary from a few days - to a few months. The list of pending port - PRs can be viewed at . - - After looking at the new port, we will reply if necessary, - and put it in the tree. Your name will also be added to the - list of Additional - &os; Contributors and other files. - - - - - Slow Porting - - Okay, so it was not that simple, and the port required some - modifications to get it to work. In this section, we will - explain, step by step, how to modify it to get it to work with - the ports paradigm. - - - How Things Work - - First, this is the sequence of events which occurs when - the user first types make in your port's - directory. You may find that having - bsd.port.mk in another window while you - read this really helps to understand it. - - But do not worry if you do not really understand what - bsd.port.mk is doing, not many people - do... :-) - - - - The fetch target is run. - The fetch target is responsible - for making sure that the tarball exists locally in - DISTDIR. If - fetch cannot find the required - files in DISTDIR it will look up the - URL MASTER_SITES, which is set in the - Makefile, as well as our FTP mirrors where we put - 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 port's distribution file (typically a - gzipped tarball) in - DISTDIR 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 - patch files named - patch-* - are found in PATCHDIR (defaults to the - files subdirectory), they are applied - at this time in alphabetical order. - - - - The configure target is - run. This can do any one of many different things. - - - - If it exists, - scripts/configure is run. - - - - If HAS_CONFIGURE or - GNU_CONFIGURE is set, - WRKSRC/configure - is run. - - - - - - - The build target is run. - This is responsible for descending into the port's private - working directory (WRKSRC) and building - it. - - - - The stage target is run. - This puts the final set of built files into a temporary - directory (STAGEDIR, see - ). The hierarchy of this - directory mirrors that of the system on which the package - will be installed. - - - - The install target is run. - This copies the files listed in the port's pkg-plist to - the host system. - - - - The above are the default actions. In addition, you can - define targets - pre-something - or - post-something, - or put scripts with those names, in the - scripts subdirectory, and they will be - run before or after the default actions are done. - - For example, if you have a - post-extract target defined in your - Makefile, and a file - pre-build in the - scripts subdirectory, the - post-extract target will be called - after the regular extraction actions, and the - pre-build script will be executed before - the default build rules are done. It is recommended that you - use Makefile targets if the actions are - simple enough, because it will be easier for someone to figure - out what kind of non-default action the port requires. - - The default actions are done by the - bsd.port.mk targets - do-something. - For example, the commands to extract a port are in the target - do-extract. If you are not happy - with the default target, you can fix it by redefining the - do-something - target in your Makefile. - - - The main targets (e.g., - extract, - configure, etc.) do nothing more - than make sure all the stages up to that one are completed - and call the real targets or scripts, and they are not - intended to be changed. If you want to fix the extraction, - fix do-extract, but never ever - change the way extract - operates! Additionally, the target - post-deinstall is invalid and - is not run by the ports infrastructure. - - - Now that you understand what goes on when the user types - make install, let - us go through the recommended steps to create the perfect - port. - - - - Getting the Original Sources - - Get the original sources (normally) as a compressed - tarball - (foo.tar.gz or - foo.tar.bz2) - and copy it into DISTDIR. Always use - mainstream sources when and where you - can. - - You will need to set the variable - MASTER_SITES to reflect where the original - tarball resides. You will find convenient shorthand - definitions for most mainstream sites in - bsd.sites.mk. Please use these - sites—and the associated definitions—if at all - possible, to help avoid the problem of having the same - information repeated over again many times in the source base. - As these sites tend to change over time, this becomes a - maintenance nightmare for everyone involved. - - If you cannot find a FTP/HTTP site that is well-connected - to the net, or can only find sites that have irritatingly - non-standard formats, you might want to put a copy on a - reliable FTP or HTTP server that you control (e.g., your home - page). - - If you cannot find somewhere convenient and reliable to - put the distfile we can house it ourselves on - ftp.FreeBSD.org; however, this is the - least-preferred solution. The distfile must be placed into - ~/public_distfiles/ of someone's - freefall account. Ask the person who - commits your port to do this. This person will also set - MASTER_SITES to - MASTER_SITE_LOCAL and - MASTER_SITE_SUBDIR to their - freefall username. - - If your port's distfile changes all the time without any - kind of version update by the author, consider putting the - distfile on your home page and listing it as the first - MASTER_SITES. If you can, try to talk the - port author out of doing this; it really does help to - establish some kind of source code control. Hosting your own - version will prevent users from getting - checksum mismatch errors, and also - reduce the workload of maintainers of our FTP site. Also, if - there is only one master site for the port, it is recommended - that you house a backup at your site and list it as the second - MASTER_SITES. - - If your port requires some additional `patches' that are - available on the Internet, fetch them too and put them in - DISTDIR. Do not worry if they come from a - site other than where you got the main source tarball, we have - a way to handle these situations (see the description of - PATCHFILES - below). - - - - Modifying the Port - - Unpack a copy of the tarball in a private directory and - make whatever changes are necessary to get the port to compile - properly under the current version of &os;. Keep - careful track of everything you do, as - you will be automating the process shortly. Everything, - including the deletion, addition, or modification of files - should be doable using an automated script or patch file when - your port is finished. - - 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 and perhaps do - something similar yourself. The goal of the new ports - collection is to make each port as - plug-and-play as possible for the end-user - while using a minimum of disk space. - - - Unless explicitly stated, patch files, scripts, and - other files you have created and contributed to the &os; - ports collection are assumed to be covered by the standard - BSD copyright conditions. - - - - - Patching - - In the preparation of the port, files that have been added - or changed can be recorded with &man.diff.1; for later - feeding to &man.patch.1;. Doing this with a typical file - involves saving a copy of the original file before making any - changes. - - &prompt.user; cp file file.orig - - Patches are saved into files named - patch-* where - * indicates the pathname of the - file that is patched, such as - patch-Imakefile or - patch-src-config.h. - - After the file has been modified, &man.diff.1; is used to - record the differences between the original and the modified - version. causes &man.diff.1; to produce - unified diffs, the preferred form. - - &prompt.user; diff -u file.orig file > patch-pathname-file - - When generating patches for new, added files, - is added to tell &man.diff.1; to treat the - non-existent original file as if it existed but was - empty: - - &prompt.user; diff -u -N newfile.orig newfile > patch-pathname-newfile - - Patch files are stored in PATCHDIR - (usually files/, from - where they will be automatically applied. All patches must be - relative to WRKSRC (generally the directory - the port's tarball unpacks itself into, that being where the - build is done). To make fixes and upgrades easier, avoid - having more than one patch fix the same file (that is, - patch-file and - patch-file2 both changing - WRKSRC/foobar.c). Note that if the path - of a patched file contains an underscore - (_) character, the patch needs to have two - underscores instead in its name. For example, to patch a file - named src/freeglut_joystick.c, the - corresponding patch should be named - patch-src-freeglut__joystick.c. - - Please only use characters - [-+._a-zA-Z0-9] for naming patches. Do not - use any other characters besides them. Do not name patches - like patch-aa or - patch-ab, always mention the path and - file name in patch names. - - There is an alternate, easier method for creating patches - to existing files. The first steps are the same, make a copy - of the unmodified file with an .orig - extension, then make modifications. Then use - make makepatch to write updated patch files - to the files directory of the - port. - - Do not put RCS strings in patches. - Subversion 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. - - Using the recurse () option to - &man.diff.1; to generate patches is fine, but please - look at the resulting patches to make sure there is no - unnecessary junk in there. In particular, diffs between two - backup files, Makefiles when the port - uses Imake or GNU - configure, etc., are unnecessary and should - be deleted. If it was necessary to edit - configure.in and run - autoconf to regenerate - configure, do not take the diffs of - configure (it often grows to a few thousand - lines!). Instead, define - USE_AUTOTOOLS=autoconf:261 and take the - diffs of configure.in. - - Try to minimize the amount of non-functional whitespace - changes in patches. It is common in the Open Source world for - projects to share large amounts of a code base, but obey - different style and indenting rules. When taking a working - piece of functionality from one project to fix similar areas - in another, please be careful: the resulting line patch may be - full of non-functional changes. It not only increases the - size of the Subversion repository - but makes it hard to find out what exactly caused the problem - and what was changed at all. - - If a file must be deleted, do it in the - post-extract target rather than as - part of the patch. - - Simple replacements can be performed directly from the - port Makefile using the in-place mode of - &man.sed.1;. This is useful when changes use the value of a - variable: - - post-patch: - @${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README - - Quite often, software being ported uses the CR/LF - convention in source files. This may cause problems with - further patching, compiler warnings, or script execution (like - /bin/sh^M not found.) To quickly convert - all files from CR/LF to just LF, add this entry to the port - Makefile: - - USES= dos2unix - - A list of specific files to convert can - be given: - - USES= dos2unix -DOS2UNIX_FILES= util.c util.h - - Use DOS2UNIX_REGEX to convert a group - of files across subdirectories. Its argument is a - &man.find.1;-compatible regular expression. More on the - format is in &man.re.format.7;. This option is useful for - converting all files of a given extension. For example, - convert all source code files, leaving binary files - intact: - - USES= dos2unix -DOS2UNIX_REGEX= .*\.([ch]|cpp) - - A similar option is DOS2UNIX_GLOB, - which invokes find for each element listed - in it. - - USES= dos2unix -DOS2UNIX_GLOB= *.c *.cpp *.h - - *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***