From owner-svn-doc-all@FreeBSD.ORG Sun Feb 16 02:10:30 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 391BFA90; Sun, 16 Feb 2014 02:10:30 +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 22E611DDE; Sun, 16 Feb 2014 02:10:30 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s1G2AUSP041952; Sun, 16 Feb 2014 02:10:30 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s1G2AUQT041951; Sun, 16 Feb 2014 02:10:30 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201402160210.s1G2AUQT041951@svn.freebsd.org> From: Warren Block Date: Sun, 16 Feb 2014 02:10:30 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43952 - head/en_US.ISO8859-1/books/porters-handbook/quick-porting 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, 16 Feb 2014 02:10:30 -0000 Author: wblock Date: Sun Feb 16 02:10:29 2014 New Revision: 43952 URL: http://svnweb.freebsd.org/changeset/doc/43952 Log: Whitespace-only cleanup, translators please ignore. Modified: head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml Sun Feb 16 00:44:25 2014 (r43951) +++ head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml Sun Feb 16 02:10:29 2014 (r43952) @@ -4,45 +4,47 @@ $FreeBSD$ --> - + + + 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. + - Quick Porting + + Writing the <filename>Makefile</filename> - 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. + The minimal Makefile would look + something like this: - 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$ + # $FreeBSD$ PORTNAME= oneko PORTVERSION= 1.1b @@ -54,101 +56,100 @@ COMMENT= Cat chasing a mouse all over th .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. + - 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. + 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). - 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. - + 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. - The following example shows how your - pkg-descr should look: + + 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 + 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> + + <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. + 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: + Here is a small example: - bin/oneko + bin/oneko man/man1/oneko.1.gz lib/X11/app-defaults/Oneko lib/X11/oneko/cat1.xpm @@ -156,34 +157,34 @@ 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. + 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: + + 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. + - PLIST_FILES= bin/oneko \ + 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 \ @@ -191,215 +192,211 @@ lib/X11/oneko/mouse.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. + Of course, PLIST_DIRS should be left + unset if a port installs no directories of its own. - 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. + 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 + . - 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. - - + 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. + +