From owner-svn-doc-all@FreeBSD.ORG Sun Feb 16 02:39:13 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 B447FF33; Sun, 16 Feb 2014 02:39:13 +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 9AC621062; Sun, 16 Feb 2014 02:39:13 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s1G2dDYv052952; Sun, 16 Feb 2014 02:39:13 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s1G2dDF0052951; Sun, 16 Feb 2014 02:39:13 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201402160239.s1G2dDF0052951@svn.freebsd.org> From: Warren Block Date: Sun, 16 Feb 2014 02:39:13 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43954 - head/en_US.ISO8859-1/books/porters-handbook/slow-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:39:13 -0000 Author: wblock Date: Sun Feb 16 02:39:13 2014 New Revision: 43954 URL: http://svnweb.freebsd.org/changeset/doc/43954 Log: Whitespace-only fixes, translators please ignore. Modified: head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml Sun Feb 16 02:24:38 2014 (r43953) +++ head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml Sun Feb 16 02:39:13 2014 (r43954) @@ -4,427 +4,414 @@ $FreeBSD$ --> - + + + 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: - Slow Porting + USES= dos2unix - 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: + A list of specific files to convert can be given: - USES= dos2unix - - A list of specific files to convert can - be given: - - USES= dos2unix + 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: + 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 + USES= dos2unix DOS2UNIX_REGEX= .*\.([ch]|cpp) - A similar option is DOS2UNIX_GLOB, - which invokes find for each element listed - in it. + A similar option is DOS2UNIX_GLOB, which + invokes find for each element listed in + it. - USES= dos2unix + USES= dos2unix DOS2UNIX_GLOB= *.c *.cpp *.h - - - - Configuring + - Include any additional customization commands in your - configure script and save it in the - scripts subdirectory. As mentioned - above, you can also do this with Makefile - targets and/or scripts with the name - pre-configure or - post-configure. - - - - Handling User Input - - If your port requires user input to build, configure, or - install, you must 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 those ports requiring interaction - are built). This will save a lot of wasted time on the set of - 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 - interactive script when it is set. This will allow us to - build the packages for CDROMs and FTP. - - + + Configuring + Include any additional customization commands in your + configure script and save it in the + scripts subdirectory. As mentioned above, + you can also do this with Makefile targets + and/or scripts with the name pre-configure + or post-configure. + + + + Handling User Input + + If your port requires user input to build, configure, or + install, you must 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 those ports requiring interaction are + built). This will save a lot of wasted time on the set of + 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 + interactive script when it is set. This will allow us to build + the packages for CDROMs and FTP. + +