Index: head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml +++ head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml @@ -19,13 +19,13 @@ 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. + user first types make in the port's + directory. Having + bsd.port.mk in another window while + reading 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... + But do not worry not many people understand exactly how + bsd.port.mk is working... :-) @@ -48,7 +48,7 @@ The extract target is run. - It looks for your port's distribution file (typically a + It looks for the port's distribution file (typically a gzipped tarball) in DISTDIR and unpacks it into a temporary subdirectory specified by WRKDIR @@ -115,7 +115,7 @@ - The above are the default actions. In addition, you can + The above are the default actions. In addition, define targets pre-something or @@ -124,35 +124,35 @@ 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 + For example, if there is a + post-extract target defined in the 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 + after the regular extraction actions, and + pre-build will be executed before + the default build rules are done. It is recommended to 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. + do-something + targets from bsd.port.mk. 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-extract. If + the default target does not do the job right, redefine the do-something - target in your Makefile. + target in the Makefile. - The main targets (e.g., + The main targets (for example, 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 + be changed. to fix the extraction, fix do-extract, but never ever change the way extract operates! Additionally, the target @@ -160,8 +160,8 @@ not run by the ports infrastructure. - Now that you understand what goes on when the user types - make install, let us go through the + Now that what goes on when the user types make + install is better understood, let us go through the recommended steps to create the perfect port. @@ -172,54 +172,55 @@ (foo.tar.gz or foo.tar.bz2) and copy it into DISTDIR. Always use - mainstream sources when and where you - can. + mainstream sources when and where + possible. - You will need to set the variable + Set the variable MASTER_SITES to reflect where the original - tarball resides. You will find convenient shorthand definitions + tarball resides. Shorthand definitions exist 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. + becomes a maintenance nightmare for everyone involved. See + for details. - If you cannot find a FTP/HTTP site that is well-connected to + If there is no 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 + non-standard formats, put a copy on a reliable + FTP or HTTP server (for example, a home page). - If you cannot find somewhere convenient and reliable to put - the distfile we can house it ourselves on + If a convenient and reliable place to put + the distfile cannot be found, 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 + commits the 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 + If the 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 + distfile on a home page and listing it as the first + MASTER_SITES. 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 + some kind of source code control. Hosting a specific 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 + only one master site for the port, it is recommended to + house a backup on a home page and list it as the second MASTER_SITES. - If your port requires some additional `patches' that are + If the 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 + site other than where the main source tarball comes, we have a way to handle these situations (see the description of PATCHFILES below). @@ -230,24 +231,24 @@ 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 + careful track of steps, as they will be + needed to automate the process shortly. Everything, including + the deletion, addition, or modification of files has to be + doable using an automated script or patch file when the port is finished. - If your port requires significant user - interaction/customization to compile or install, you should take + If the port requires significant user + interaction/customization to compile or install, take a look at one of Larry Wall's classic Configure scripts and perhaps do - something similar yourself. The goal of the new ports + something similar. 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 + files created and contributed to the &os; ports collection are assumed to be covered by the standard BSD copyright conditions. @@ -385,7 +386,7 @@ 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 + etc., are unnecessary and have to be deleted. If it was necessary to edit configure.in and run autoconf to regenerate configure, do not take the diffs of @@ -444,10 +445,10 @@ Configuring - Include any additional customization commands in your + Include any additional customization commands in the configure script and save it in the scripts subdirectory. As mentioned above, - you can also do this with Makefile targets + it is also possible do this with Makefile targets and/or scripts with the name pre-configure or post-configure. @@ -455,10 +456,10 @@ Handling User Input - If your port requires user input to build, configure, or - install, you must set IS_INTERACTIVE in your + If the port requires user input to build, configure, or + install, set IS_INTERACTIVE in the Makefile. This will allow - overnight builds to skip your port if the user + overnight builds to skip it. If the user sets the variable BATCH in his environment (and if the user sets the variable INTERACTIVE, then only those ports requiring interaction are @@ -466,8 +467,8 @@ machines that continually build ports (see below). It is also recommended that if there are reasonable default - answers to the questions, you check the - PACKAGE_BUILDING variable and turn off the + answers to the questions, + PACKAGE_BUILDING be used to turn off the interactive script when it is set. This will allow us to build the packages for CDROMs and FTP.