From owner-svn-doc-all@FreeBSD.ORG Sun Feb 16 04:57:46 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 8F6FC946; Sun, 16 Feb 2014 04:57:46 +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 68B521CC6; Sun, 16 Feb 2014 04:57:46 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s1G4vkFs014217; Sun, 16 Feb 2014 04:57:46 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s1G4vk1C014216; Sun, 16 Feb 2014 04:57:46 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201402160457.s1G4vk1C014216@svn.freebsd.org> From: Warren Block Date: Sun, 16 Feb 2014 04:57:46 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43958 - head/en_US.ISO8859-1/books/porters-handbook/makefiles 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 04:57:46 -0000 Author: wblock Date: Sun Feb 16 04:57:45 2014 New Revision: 43958 URL: http://svnweb.freebsd.org/changeset/doc/43958 Log: Whitespace-only fixes, translators please ignore. Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Sun Feb 16 03:32:26 2014 (r43957) +++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Sun Feb 16 04:57:45 2014 (r43958) @@ -4,2114 +4,2087 @@ $FreeBSD$ --> + + + Configuring the Makefile + + Configuring the Makefile is pretty + simple, and again we suggest that you look at existing examples + before starting. Also, there is a + sample Makefile in this + handbook, so take a look and please follow the ordering of + variables and sections in that template to make your port easier + for others to read. + + Now, consider the following problems in sequence as you + design your new Makefile: + + + The Original Source + + Does it live in DISTDIR as a standard + gzipped tarball named something like + foozolix-1.2.tar.gz? If so, you can go on + to the next step. If not, you should look at overriding any of + the DISTVERSION, DISTNAME, + EXTRACT_CMD, + EXTRACT_BEFORE_ARGS, + EXTRACT_AFTER_ARGS, + EXTRACT_SUFX, or DISTFILES + variables, depending on how alien a format your port's + distribution file is. + + In the worst case, you can simply create your own + do-extract target to override the + default, though this should be rarely, if ever, + necessary. + + + + Naming + + The first part of the port's Makefile + names the port, describes its version number, and lists it in + the correct category. + + + <varname>PORTNAME</varname> and + <varname>PORTVERSION</varname> + + You should set PORTNAME to the base + name of your port, and PORTVERSION to the + version number of the port. + + + + <varname>PORTREVISION</varname> and + <varname>PORTEPOCH</varname> + + + <varname>PORTREVISION</varname> + + The PORTREVISION variable is a + monotonically increasing value which is reset to 0 with + every increase of PORTVERSION (i.e., + every time a new official vendor release is made), and + appended to the package name if non-zero. Changes to + PORTREVISION are used by automated tools + (e.g., pkg version, see + &man.pkg-version.8;) to highlight the fact that a new + package is available. + + PORTREVISION should be increased each + time a change is made to the port that changes the generated + package in any way. That includes changes that only affect + a package built with non-default + options. - - Configuring the Makefile + Examples of when PORTREVISION + should be bumped: - Configuring the Makefile is pretty - simple, and again we suggest that you look at existing examples - before starting. Also, there is a - sample Makefile in this - handbook, so take a look and please follow the ordering of - variables and sections in that template to make your port easier - for others to read. - - Now, consider the following problems in sequence as you - design your new Makefile: - - - The Original Source - - Does it live in DISTDIR as a standard - gzipped tarball named something like - foozolix-1.2.tar.gz? If so, you can go on - to the next step. If not, you should look at overriding any - of the DISTVERSION, - DISTNAME, EXTRACT_CMD, - EXTRACT_BEFORE_ARGS, - EXTRACT_AFTER_ARGS, - EXTRACT_SUFX, or - DISTFILES variables, depending on how alien - a format your port's distribution file is. - - In the worst case, you can simply create your own - do-extract target to override the - default, though this should be rarely, if ever, - necessary. - - - - Naming - - The first part of the port's Makefile - names the port, describes its version number, and lists it - in the correct category. - - - <varname>PORTNAME</varname> and - <varname>PORTVERSION</varname> - - You should set PORTNAME to the - base name of your port, and PORTVERSION - to the version number of the port. - - - - <varname>PORTREVISION</varname> and - <varname>PORTEPOCH</varname> - - - <varname>PORTREVISION</varname> - - The PORTREVISION variable is a - monotonically increasing value which is reset to 0 with - every increase of PORTVERSION (i.e., - every time a new official vendor release is made), and - appended to the package name if non-zero. Changes to - PORTREVISION are used by automated - tools (e.g., pkg version, see - &man.pkg-version.8;) to highlight the fact that a new - package is available. - - PORTREVISION should be increased - each time a change is made to the port that changes the - generated package in any way. That includes changes that - only affect a package built with non-default options. - - Examples of when PORTREVISION - should be bumped: - - - - Addition of patches to correct security - vulnerabilities, bugs, or to add new functionality to - the port. - - - - Changes to the port Makefile - to enable or disable compile-time options in the - package. - - - - Changes in the packing list or the install-time - behavior of the package (e.g., change to a script - which generates initial data for the package, like ssh - host keys). - - - - Version bump of a port's shared library dependency - (in this case, someone trying to install the old - package after installing a newer version of the - dependency will fail since it will look for the old - libfoo.x instead of libfoo.(x+1)). - - - - Silent changes to the port distfile which have - significant functional differences, i.e., changes to - the distfile requiring a correction to - distinfo with no corresponding - change to PORTVERSION, where a - diff -ru of the old and new - versions shows non-trivial changes to the code. - - - - Examples of changes which do not require a - PORTREVISION bump: - - - - Style changes to the port skeleton with no - functional change to what appears in the resulting - package. - - - - Changes to MASTER_SITES or - other functional changes to the port which do not - affect the resulting package. - - - - Trivial patches to the distfile such as correction - of typos, which are not important enough that users of - the package should go to the trouble of - upgrading. - - - - Build fixes which cause a package to become - compilable where it was previously failing (as long as - the changes do not introduce any functional change on - any other platforms on which the port did previously - build). Since PORTREVISION - reflects the content of the package, if the package - was not previously buildable then there is no need to - increase PORTREVISION to mark a - change. - - - - A rule of thumb is to ask yourself whether a change - committed to a port is something which everyone would - benefit from having (either because of an enhancement, - fix, or by virtue that the new package will actually work - at all), and weigh that against that fact that it will - cause everyone who regularly updates their ports tree to - be compelled to update. If yes, the - PORTREVISION should be bumped. - - - - <varname>PORTEPOCH</varname> - - From time to time a software vendor or &os; porter - will do something silly and release a version of their - software which is actually numerically less than the - previous version. An example of this is a port which goes - from foo-20000801 to foo-1.0 (the former will be - incorrectly treated as a newer version since 20000801 is a - numerically greater value than 1). - - - The results of version number comparisons are not - always obvious. pkg version (see - &man.pkg-version.8;) can be used to test the comparison - of two version number strings. For example: - - &prompt.user; pkg version -t 0.031 0.29 -> - - The > output indicates that - version 0.031 is considered greater than version 0.29, - which may not have been obvious to the porter. - - - In situations such as this, the - PORTEPOCH version should be increased. - If PORTEPOCH is nonzero it is appended - to the package name as described in section 0 above. - PORTEPOCH must never be decreased or - reset to zero, because that would cause comparison to a - package from an earlier epoch to fail (i.e., the package - would not be detected as out of date): the new version - number (e.g., 1.0,1 in the above - example) is still numerically less than the previous - version (20000801), but the ,1 suffix - is treated specially by automated tools and found to be - greater than the implied suffix ,0 on - the earlier package. - - Dropping or resetting PORTEPOCH - incorrectly leads to no end of grief; if you do not - understand the above discussion, please keep after it - until you do, or ask questions on the mailing - lists. - - It is expected that PORTEPOCH will - not be used for the majority of ports, and that sensible - use of PORTVERSION can often preempt it - becoming necessary if a future release of the software - should change the version structure. However, care is - needed by &os; porters when a vendor release is made - without an official version number — such as a code - snapshot release. The temptation is to - label the release with the release date, which will cause - problems as in the example above when a new - official release is made. - - For example, if a snapshot release is made on the date - 20000917, and the previous version of the software was - version 1.2, the snapshot release should be given a - PORTVERSION of 1.2.20000917 or similar, - not 20000917, so that the succeeding release, say 1.3, is - still a numerically greater value. - - - - Example of <varname>PORTREVISION</varname> and - <varname>PORTEPOCH</varname> Usage - - The gtkmumble port, version - 0.10, is committed to the ports - collection: - - PORTNAME= gtkmumble -PORTVERSION= 0.10 - - PKGNAME becomes - gtkmumble-0.10. - - A security hole is discovered which requires a local - &os; patch. PORTREVISION is bumped - accordingly. - - PORTNAME= gtkmumble -PORTVERSION= 0.10 -PORTREVISION= 1 - - PKGNAME becomes - gtkmumble-0.10_1 - - A new version is released by the vendor, numbered - 0.2 (it turns out the author actually - intended 0.10 to actually mean - 0.1.0, not - what comes after 0.9 - oops, too late now). - Since the new minor version 2 is - numerically less than the previous version - 10, the PORTEPOCH - must be bumped to manually force the new package to be - detected as newer. Since it is a new - vendor release of the code, - PORTREVISION is reset to 0 (or removed - from the Makefile). - - PORTNAME= gtkmumble -PORTVERSION= 0.2 -PORTEPOCH= 1 - - PKGNAME becomes - gtkmumble-0.2,1 - - The next release is 0.3. Since - PORTEPOCH never decreases, the version - variables are now: - - PORTNAME= gtkmumble -PORTVERSION= 0.3 -PORTEPOCH= 1 - - PKGNAME becomes - gtkmumble-0.3,1 - - - If PORTEPOCH were reset to - 0 with this upgrade, someone who had - installed the gtkmumble-0.10_1 - package would not detect the - gtkmumble-0.3 package as newer, since - 3 is still numerically less than - 10. Remember, this is the whole - point of PORTEPOCH in the first - place. - - - - - - <varname>PKGNAMEPREFIX</varname> and - <varname>PKGNAMESUFFIX</varname> - - Two optional variables, PKGNAMEPREFIX - and PKGNAMESUFFIX, are combined with - PORTNAME and - PORTVERSION to form - PKGNAME as - ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. - Make sure this conforms to our - guidelines for a good - package name. In particular, you are - not allowed to use a hyphen - (-) in PORTVERSION. - Also, if the package name has the - language- or the - -compiled.specifics part (see - below), use PKGNAMEPREFIX and - PKGNAMESUFFIX, respectively. Do not make - them part of PORTNAME. - - - - Package Naming Conventions - - The following are the conventions you should follow in - naming your packages. This is to have our package directory - easy to scan, as there are already thousands of packages and - users are going to turn away if they hurt their eyes! - - The package name should look like - language_region-name-compiled.specifics-version.numbers. - - The package name is defined as - ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. - Make sure to set the variables to conform to that - format. - - + - &os; strives to support the native language of - its users. The language- - part should be a two letter abbreviation of the natural - language defined by ISO-639 if the port is specific to a - certain language. Examples are ja - for Japanese, ru for Russian, - vi for Vietnamese, - zh for Chinese, ko - for Korean and de for German. - - If the port is specific to a certain region within - the language area, add the two letter country code as - well. Examples are en_US for US - English and fr_CH for Swiss - French. - - The language- part should - be set in the PKGNAMEPREFIX - variable. + Addition of patches to correct security + vulnerabilities, bugs, or to add new functionality to + the port. - The first letter of the name - part should be lowercase. (The rest of the name may - contain capital letters, so use your own discretion when - you are converting a software name that has some capital - letters in it.) There is a tradition of naming - Perl 5 modules by prepending - p5- and converting the double-colon - separator to a hyphen; for example, the - Data::Dumper module becomes - p5-Data-Dumper. + Changes to the port Makefile to + enable or disable compile-time options in the + package. - Make sure that the port's name and version are - clearly separated and placed into the - PORTNAME and - PORTVERSION variables. The only - reason for PORTNAME to contain a - version part is if the upstream distribution is really - named that way, as in the - textproc/libxml2 or - japanese/kinput2-freewnn ports. - Otherwise, the PORTNAME should not - contain any version-specific information. It is quite - normal for several ports to have the same - PORTNAME, as the - www/apache* ports do; in that case, - different versions (and different index entries) are - distinguished by the PKGNAMEPREFIX - and PKGNAMESUFFIX values. + Changes in the packing list or the install-time + behavior of the package (e.g., change to a script which + generates initial data for the package, like ssh host + keys). - If the port can be built with different - hardcoded - defaults (usually part of the directory name in - a family of ports), the - -compiled.specifics part - should state the compiled-in defaults (the hyphen is - optional). Examples are paper size and font - units. - - The -compiled.specifics - part should be set in the - PKGNAMESUFFIX variable. + Version bump of a port's shared library dependency + (in this case, someone trying to install the old package + after installing a newer version of the dependency will + fail since it will look for the old libfoo.x instead of + libfoo.(x+1)). - The version string should follow a dash - (-) and be a period-separated list of - integers and single lowercase alphabetics. In - particular, it is not permissible to have another dash - inside the version string. The only exception is the - string pl (meaning - patchlevel), which can be used - only when there are no major and - minor version numbers in the software. If the software - version has strings like alpha, - beta, rc, or - pre, take the first letter and put it - immediately after a period. If the version string - continues after those names, the numbers should follow - the single alphabet without an extra period between - them. - - The idea is to make it easier to sort ports by - looking at the version string. In particular, make sure - version number components are always delimited by a - period, and if the date is part of the string, use the - 0.0.yyyy.mm.dd - format, not - dd.mm.yyyy - or the non-Y2K compliant - yy.mm.dd - format. It is important to prefix the version with - 0.0. in case a release with an actual - version number is made, which would of course be - numerically less than - yyyy. + Silent changes to the port distfile which have + significant functional differences, i.e., changes to the + distfile requiring a correction to + distinfo with no corresponding + change to PORTVERSION, where a + diff -ru of the old and new versions + shows non-trivial changes to the code. - - - Here are some (real) examples on how to convert the name - as called by the software authors to a suitable package - name: - - - - - - Distribution Name - PKGNAMEPREFIX - PORTNAME - PKGNAMESUFFIX - PORTVERSION - Reason - - - - - - mule-2.2.2 - (empty) - mule - (empty) - 2.2.2 - No changes required - - - - EmiClock-1.0.2 - (empty) - emiclock - (empty) - 1.0.2 - No uppercase names for single programs - - - - rdist-1.3alpha - (empty) - rdist - (empty) - 1.3.a - No strings like alpha - allowed - - - - es-0.9-beta1 - (empty) - es - (empty) - 0.9.b1 - No strings like beta - allowed - - - - mailman-2.0rc3 - (empty) - mailman - (empty) - 2.0.r3 - No strings like rc - allowed - - - - v3.3beta021.src - (empty) - tiff - (empty) - 3.3 - What the heck was that anyway? - - - - tvtwm - (empty) - tvtwm - (empty) - pl11 - Version string always required - - - - piewm - (empty) - piewm - (empty) - 1.0 - Version string always required - - - - xvgr-2.10pl1 - (empty) - xvgr - (empty) - 2.10.1 - pl allowed only when no - major/minor version numbers - - - - gawk-2.15.6 - ja- - gawk - (empty) - 2.15.6 - Japanese language version - - - - psutils-1.13 - (empty) - psutils - -letter - 1.13 - Paper size hardcoded at package build - time - - - - pkfonts - (empty) - pkfonts - 300 - 1.0 - Package for 300dpi fonts - - - - - - If there is absolutely no trace of version information - in the original source and it is unlikely that the original - author will ever release another version, just set the - version string to 1.0 (like the - piewm example above). Otherwise, ask the - original author or use the date string - (0.0.yyyy.mm.dd) - as the version. - - - - - Categorization - - - <varname>CATEGORIES</varname> - - When a package is created, it is put under - /usr/ports/packages/All and links are - made from one or more subdirectories of - /usr/ports/packages. The names of - these subdirectories are specified by the variable - CATEGORIES. It is intended to make life - easier for the user when he is wading through the pile of - packages on the FTP site or the CDROM. Please take a look - at the current list of - categories and pick the ones that are suitable for - your port. - - This list also determines where in the ports tree the - port is imported. If you put more than one category here, - it is assumed that the port files will be put in the - subdirectory with the name in the first category. See - below for more - discussion about how to pick the right categories. - - - - Current List of Categories - - Here is the current list of port categories. Those - marked with an asterisk (*) are - virtual categories—those that do - not have a corresponding subdirectory in the ports tree. - They are only used as secondary categories, and only for - search purposes. - - - For non-virtual categories, you will find a one-line - description in the COMMENT in that - subdirectory's Makefile. - - - - - - - Category - Description - Notes - - - - - - accessibility - Ports to help disabled users. - - - - - afterstep* - - Ports to support the AfterStep - window manager. - - - - - arabic - Arabic language support. - - - - - archivers - Archiving tools. - - - - - astro - Astronomical ports. - - - - - audio - Sound support. - - - - - benchmarks - Benchmarking utilities. - - - - - biology - Biology-related software. - - - - - cad - Computer aided design tools. - - - - - chinese - Chinese language support. - - - - - comms - Communication software. - Mostly software to talk to your serial - port. - - - - converters - Character code converters. - - - - - databases - Databases. - - - - - deskutils - Things that used to be on the desktop before - computers were invented. - - - - - devel - Development utilities. - Do not put libraries here just because they are - libraries—unless they truly do not belong - anywhere else, they should not be in this - category. - - - - dns - DNS-related software. - - - - - docs* - Meta-ports for &os; documentation. - - - - - editors - General editors. - Specialized editors go in the section for those - tools (e.g., a mathematical-formula editor will go - in math). - - - - elisp* - Emacs-lisp ports. - - - - - emulators - Emulators for other operating systems. - Terminal emulators do not - belong here—X-based ones should go to - x11 and text-based ones to - either comms or - misc, depending on the exact - functionality. - - - - finance - Monetary, financial and related - applications. - - - - - french - French language support. - - - - - ftp - FTP client and server utilities. - If your port speaks both FTP and HTTP, put it - in ftp with a secondary - category of www. - - - - games - Games. - - - - - geography* - Geography-related software. - - - - - german - German language support. - - - - - gnome* - Ports from the - GNOME - Project. - - - - - gnustep* - Software related to the GNUstep desktop - environment. - - - - - graphics - Graphics utilities. - - - - - hamradio* - Software for amateur radio. - - - - - haskell* - Software related to the Haskell - language. - - - - - hebrew - Hebrew language support. - - - - - hungarian - Hungarian language support. - - - - - ipv6* - IPv6 related software. - - - - - irc - Internet Relay Chat utilities. - - - - - japanese - Japanese language support. - - - - - java - Software related to the Java™ - language. - The java category must - not be the only one for a port. Save for ports - directly related to the Java language, porters are - also encouraged not to use java - as the main category of a port. - - - *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***