Index: head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml (revision 48472) +++ head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml (revision 48473) @@ -1,409 +1,409 @@ Quick Porting This section describes how to quickly create a new port. For applications where this quick method is not adequate, the full Slow Porting process is described in . First, get the original tarball and put it into DISTDIR, which defaults to /usr/ports/distfiles. These steps assume that the software compiled out-of-the-box. In other words, absolutely no changes were required for the application to work on a &os; system. If anything had to be changed, refer to . 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. Try to 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. A more detailed example is shown 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 when copying from the README or manpage. Too often they are not a concise description of the port or are in an awkward format. For example, 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 must 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. This example shows how pkg-descr looks: 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). 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 Refer to the &man.pkg-create.8; manual page for details on the packing list. It is recommended to keep all the filenames in this file sorted alphabetically. It will make verifying changes when upgrading 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, list them in PLIST_FILES, within the port's Makefile. For instance, we could get along without pkg-plist in the above oneko port by adding these 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 Usage of PLIST_FILES should not be abused. When looking for the origin of a file, people usually try to grep through the pkg-plist files in the ports tree. Listing files in PLIST_FILES in the Makefile makes that search more difficult. If a port needs to create an empty directory, or creates directories outside of ${PREFIX} during installation, refer to for more information. The price for this way of listing a port's files and directories is that the keywords described in &man.pkg-create.8; and cannot be used. 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 resorting 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. Testing the Port Make sure that the port rules do exactly what is desired, including packaging up the port. These are the important points 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. The port only has access to network resources during the fetch target phase. This is important for package builders, such as ports-mgmt/poudriere. 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 the Port with <command>portlint</command> Please use portlint to see if the port conforms to our guidelines. The ports-mgmt/portlint program is part of the ports collection. In particular, check that 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 the 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 To submit oneko.shar, use the bug submit form (category Ports Tree). Add a short description of the program to the Description field of the PR (perhaps a short version of COMMENT), and do not forget to add oneko.shar as an attachment. Giving a good description in the summary 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 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. A simple search form of the Problem Report database can be searched here. To get a listing of open port PRs, select Open and Ports & Packages in the search form, then click [ Search ] to list the reports. After looking at the new port, we will reply if necessary, - and commit it to the tree. The submitter's name will also be added to the - list of Additional &os; Contributors and other files.