From owner-svn-doc-all@FreeBSD.ORG Fri Apr 4 01:25:04 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 230DD9B4; Fri, 4 Apr 2014 01:25:04 +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)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 0E9A5797; Fri, 4 Apr 2014 01:25:04 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s341P3l0002445; Fri, 4 Apr 2014 01:25:03 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s341P3SN002444; Fri, 4 Apr 2014 01:25:03 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201404040125.s341P3SN002444@svn.freebsd.org> From: Warren Block Date: Fri, 4 Apr 2014 01:25:03 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44434 - 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: Fri, 04 Apr 2014 01:25:04 -0000 Author: wblock Date: Fri Apr 4 01:25:03 2014 New Revision: 44434 URL: http://svnweb.freebsd.org/changeset/doc/44434 Log: Recover lost tags. Make descriptions of the components of package names easier to read. 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 Thu Apr 3 23:20:15 2014 (r44433) +++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Fri Apr 4 01:25:03 2014 (r44434) @@ -335,25 +335,27 @@ PORTEPOCH= 1 Package Naming Conventions - The following are the conventions you should follow in - naming your packages. This is to have our package directory + These are the conventions to follow when + naming packages. This is to make the 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. + Package names take the form of + 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. - + + + language_region- &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 + is a two letter abbreviation of the natural + language defined by ISO-639 when the port is specific to a certain language. Examples are ja for Japanese, ru for Russian, vi for Vietnamese, @@ -365,25 +367,25 @@ PORTEPOCH= 1 Examples are en_US for US English and fr_CH for Swiss French. - The language- part should - be set in the PKGNAMEPREFIX + The language- part is + set in the PKGNAMEPREFIX variable. + + + name 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 + capital letters, so use your own discretion when 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 + separator to a hyphen. For example, the Data::Dumper module becomes p5-Data-Dumper. - - - Make sure that the port's name and version are clearly separated and placed into the PORTNAME and PORTVERSION variables. The only @@ -401,7 +403,10 @@ PORTEPOCH= 1 distinguished by the PKGNAMEPREFIX and PKGNAMESUFFIX values. + + + -compiled.specifics If the port can be built with different hardcoded @@ -412,13 +417,16 @@ PORTEPOCH= 1 Examples are paper size and font units. The -compiled.specifics - part should be set in the PKGNAMESUFFIX + part is set in the PKGNAMESUFFIX variable. + + + -version.numbers - The version string should follow a dash - (-) and be a period-separated list of + The version string follows a dash + (-) and is 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 @@ -437,18 +445,19 @@ PORTEPOCH= 1 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 + 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. + yyyy. - + + - Package name should be unique among all of the ports + Package name must be unique among all of the ports tree, check that there is not already a port with the same PORTNAME and if there is add one of PKGNAMEPREFIX @@ -595,7 +604,7 @@ PORTEPOCH= 1 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. + (0.0.yyyy.mm.dd) as the version. @@ -1983,7 +1992,7 @@ DISTFILES= source1.tar.gz:source1 \ - Elements can be postfixed with :n + Elements can be postfixed with :n where n is [^:,]+, i.e., n could conceptually be any @@ -2090,7 +2099,7 @@ DISTFILES= source1.tar.gz:source1 \ be terminated with the forward slash / character. If any elements belong to any groups, the group postfix - :n must come right after the + :n must come right after the terminator /. The MASTER_SITES:n mechanism relies on the existence of the terminator @@ -2383,7 +2392,7 @@ PATCHFILES= patch1:test All current ports remain the same. The MASTER_SITES:n feature code is only activated if there are elements postfixed with - :n like elements according to the + :n like elements according to the aforementioned syntax rules, especially as shown in item . @@ -2750,7 +2759,7 @@ ALWAYS_KEEP_DISTFILES= yes This variable specifies executables or files this port depends on during run-time. It is a list of - path:dir:target + path:dir:target tuples where path is the name of the executable or file, dir is the directory in which to find it in case it is not available, and @@ -2832,7 +2841,7 @@ ALWAYS_KEEP_DISTFILES= yes This variable specifies executables or files this port requires to build. Like RUN_DEPENDS, it is a list of - path:dir:target + path:dir:target tuples. For example, BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip @@ -2856,7 +2865,7 @@ ALWAYS_KEEP_DISTFILES= yes This variable specifies executables or files this port requires to fetch. Like the previous two, it is a list of - path:dir:target + path:dir:target tuples. For example, FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 @@ -2877,7 +2886,7 @@ ALWAYS_KEEP_DISTFILES= yes This variable specifies executables or files this port requires for extraction. Like the previous, it is a list of - path:dir:target + path:dir:target tuples. For example, EXTRACT_DEPENDS= unzip:${PORTSDIR}/archivers/unzip @@ -2907,7 +2916,7 @@ ALWAYS_KEEP_DISTFILES= yes This variable specifies executables or files this port requires to patch. Like the previous, it is a list of - path:dir:target + path:dir:target tuples. For example, PATCH_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract @@ -4248,8 +4257,8 @@ PORTVERSION= 1.0 files in the port's *-install targets. Set ownership directly in pkg-plist with the corresponding entries, - such as @owner owner and - @group group. These operators work until + such as @owner owner and + @group group. These operators work until being overridden, or until the end of pkg-plist, so do not forget to reset them after they are no longer needed. The default ownership is