[pacman-dev] [PATCH] doc/PKGBUILD: misc changes
Signed-off-by: Florian Pritz <bluewind@xinu.at> --- doc/PKGBUILD.5.txt | 81 +++++++++++++++++++++++++-------------------------- 1 files changed, 40 insertions(+), 41 deletions(-) diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index c0fa594..dab81e8 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -16,12 +16,12 @@ PKGBUILD Description ----------- -This manual page is meant to describe general rules about PKGBUILDs. Once a +This manual page describes general rules about PKGBUILDs. Once a PKGBUILD is written, the actual package is built using makepkg and installed with pacman. -NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}'. -Also located there are other example files such as a ChangeLog and an install +NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}' +along with other example files such as a ChangeLog and an install script. You can copy the provided PKGBUILD.proto file to a new package build directory and make customizations to suit your needs. @@ -30,18 +30,18 @@ Options and Directives ---------------------- The following is a list of standard options and directives available for use in a PKGBUILD. These are all understood and interpreted by makepkg, and most -will be directly transferred to the built package. +of them will be directly transferred to the built package. If you need to create any custom variables for use in your build process, it is -recommended to name your custom variables with an '_' (underscore) prefix. +recommended to prefix their name with an '_' (underscore). This will prevent any possible name clashes with internal makepkg variables. For example, to store the base kernel version in a variable, use something similar to `$_basekernver`. *pkgname (array)*:: - The name of the package. This has be a unix-friendly name as it will be - used in the package filename. Members of the array are not allowed to start - with hyphens. + The name of the package or an array of names for split packages. + Because it will be used in the package filename, this has to be unix-friendly. + Members of the array are not allowed to start with hyphens. *pkgver*:: The version of the software as released from the author (e.g. '2.7.1'). @@ -50,13 +50,13 @@ similar to `$_basekernver`. *pkgrel*:: This is the release number specific to the Arch Linux release. This allows package maintainers to make updates to the package's configure - flags, for example. A pkgrel of '1' is typically used for each upstream - software release and is incremented for intermediate PKGBUILD updates. The + flags, for example. This is typically (re)set to '1' for each new upstream + software release and incremented for intermediate PKGBUILD updates. The variable is not allowed to contain hyphens. *pkgdesc*:: This should be a brief description of the package and its functionality. - Try to keep the description to one line of text. + Try to keep the description to one line of text and not use the package's name. *epoch*:: Used to force the package to be seen as newer than any previous versions @@ -69,18 +69,18 @@ similar to `$_basekernver`. *url*:: This field contains a URL that is associated with the software being - packaged. This is typically the project's website. + packaged. Typically the project's website. *license (array)*:: This field specifies the license(s) that apply to the package. - Commonly-used licenses are found in '/usr/share/licenses/common'. If you + Commonly used licenses can be found in '/usr/share/licenses/common'. If you see the package's license there, simply reference it in the license field (e.g. `license=('GPL')`). If the package provides a license not - found in '/usr/share/licenses/common', then you should include the license + available in '/usr/share/licenses/common', then you should include it in the package itself and set `license=('custom')` or `license=('custom:LicenseName')`. The license should be placed in - '$pkgdir/usr/share/licenses/$pkgname' when building the package. If - multiple licenses are applicable for a package, list all of them: + '$pkgdir/usr/share/licenses/$pkgname/' when building the package. If + multiple licenses are applicable, list all of them: `license=('GPL' 'FDL')`. *install*:: @@ -97,22 +97,21 @@ similar to `$_basekernver`. *source (array)*:: An array of source files required to build the package. Source files - must either reside in the same directory as the PKGBUILD file, or be a - fully-qualified URL that makepkg will use to download the file. In order - to make the PKGBUILD as useful as possible, use the $pkgname and $pkgver - variables if possible when specifying the download location. Any files - that are compressed will automatically be extracted, unless found in - the noextract array listed below. + must either reside in the same directory as the PKGBUILD, or be a + fully-qualified URL that makepkg can use to download the file. + To make the PKGBUILD as useful as possible, use the $pkgname and $pkgver + variables if possible when specifying the download location. Compressed files + will be extracted automatically, unless found in + the noextract array described below. + -It is also possible to specify an optional filename, which is helpful +It is also possible to overwrite the filename, which is helpful with weird URLs and for handling multiple source files with the same name. The syntax is: `source=('filename::url')`. *noextract (array)*:: An array of filenames corresponding to those from the source array. Files listed here will not be extracted with the rest of the source files. This - is useful for packages which use compressed data which is downloaded but - not necessary to uncompress. + is useful for packages that use compressed data directly. *md5sums (array)*:: This array contains an MD5 hash for every source file specified in the @@ -135,16 +134,16 @@ name. The syntax is: `source=('filename::url')`. *arch (array)*:: Defines on which architectures the given package is available (e.g. `arch=('i686' 'x86_64')`). Packages that contain no architecture specific - files may use arch=('any'). + files should use arch=('any'). *backup (array)*:: - A space-delimited array of filenames, without preceding slashes, that + An array of filenames, without preceding slashes, that should be backed up if the package is removed or upgraded. This is commonly used for packages placing configuration files in /etc. See Handling Config Files in linkman:pacman[8] for more information. *depends (array)*:: - An array of packages that this package depends on to run. Packages in + An array of packages this package depends on to run. Entries in this list should be surrounded with single quotes and contain at least the package name. Entries can also include a version requirement of the form 'name<>version', where <> is one of five comparisons: >= (greater @@ -152,12 +151,12 @@ name. The syntax is: `source=('filename::url')`. than), or < (less than). *makedepends (array)*:: - An array of packages that this package depends on to build, but are not + An array of packages this package depends on to build, but are not needed at runtime. Packages in this list follow the same format as depends. *checkdepends (array)*:: - An array of packages that this package depends on to run its test suite, + An array of packages this package depends on to run its test suite, but are not needed at runtime. Packages in this list follow the same format as depends. These dependencies are only considered when the check() function is present and is to be run by makepkg. @@ -177,7 +176,7 @@ name. The syntax is: `source=('filename::url')`. same format as depends. Versioned conflicts are also supported. *provides (array)*:: - An array of ``virtual provisions'' that this package provides. This allows + An array of ``virtual provisions'' this package provides. This allows a package to provide dependencies other than its own package name. For example, the dcron package can provide 'cron', which allows packages to depend on 'cron' rather than 'dcron OR fcron'. @@ -188,7 +187,7 @@ name. The syntax is: `source=('filename::url')`. provided. *replaces (array)*:: - An array of packages that this package should replace, and can be used + An array of packages this package should replace. This can be used to handle renamed/combined packages. For example, if the 'j2re' package is renamed to 'jre', this directive allows future upgrades to continue as expected even though the package has moved. Sysupgrade is currently @@ -248,7 +247,7 @@ name. The syntax is: `source=('filename::url')`. build() Function ---------------- -In addition to the above directives, the optional build() bash function usually +In addition to the above directives, the optional build() function usually comprises the remainder of the PKGBUILD. This is directly sourced and executed by makepkg, so anything that bash or the system has available is available for use here. The function is run in `bash -e` mode, meaning any command that exits @@ -256,22 +255,22 @@ with a non-zero status will cause the function to exit. Be sure any exotic commands used are covered by `makedepends`. All of the above variables such as `pkgname` and `pkgver` are available for use -in the build function. In addition, makepkg defines three variables for your -use during the build and install process. These three variables are as follows: +in the build function. In addition, makepkg defines ithe following three +variables for use during the build and install process: *startdir*:: - This contains the absolute path to the directory where the PKGBUILD was + This contains the absolute path to the directory where the PKGBUILD is located, which is usually the output of `$(pwd)` when makepkg is started. *srcdir*:: - This points to the directory where makepkg extracts or copies all source + This points to the directory where makepkg extracts to or copies to all source files. *pkgdir*:: This points to the directory where makepkg bundles the installed package (this directory will become the root directory of your built package). -If you create any variables of your own in the build function, it is +If you create any variables on your own in the build function, it is recommended to use the bash `local` keyword to scope the variable to inside the build function. @@ -301,8 +300,8 @@ Each split package uses a corresponding packaging function with name `package_foo()`, where `foo` is the name of the split package. All options and directives for the split packages default to the global values -given within the PKGBUILD. However, some of these can be overridden within each -split package's packaging function. The following variables can be overridden: +given in the PKGBUILD. However, the following ones can be overwridden within +each split package's packaging function: `pkgver`, `pkgrel`, `pkgdesc`, `arch`, `license`, `groups`, `depends`, `optdepends`, `provides`, `conflicts`, `replaces`, `backup`, `options`, `install` and `changelog`. @@ -363,7 +362,7 @@ makepkg supports building development versions of packages without having to manually update the pkgver in the PKGBUILD. This was formerly done using the separate utility 'versionpkg'. In order to utilize this functionality, your PKGBUILD must use correct variable names depending on the SCM being fetched -from. +from (e.g.: "makepkg-git", "mplayer-svn"). *CVS*:: The generated pkgver will be the date the package is built. -- 1.7.5.4
On 23:20 Thu 09 Jun , Florian Pritz wrote:
Signed-off-by: Florian Pritz <bluewind@xinu.at> --- doc/PKGBUILD.5.txt | 81 +++++++++++++++++++++++++-------------------------- 1 files changed, 40 insertions(+), 41 deletions(-)
diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index c0fa594..dab81e8 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -16,12 +16,12 @@ PKGBUILD
Description ----------- -This manual page is meant to describe general rules about PKGBUILDs. Once a +This manual page describes general rules about PKGBUILDs. Once a PKGBUILD is written, the actual package is built using makepkg and installed with pacman.
-NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}'. -Also located there are other example files such as a ChangeLog and an install +NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}' +along with other example files such as a ChangeLog and an install script. You can copy the provided PKGBUILD.proto file to a new package build directory and make customizations to suit your needs.
@@ -30,18 +30,18 @@ Options and Directives ---------------------- The following is a list of standard options and directives available for use in a PKGBUILD. These are all understood and interpreted by makepkg, and most -will be directly transferred to the built package. +of them will be directly transferred to the built package.
If you need to create any custom variables for use in your build process, it is -recommended to name your custom variables with an '_' (underscore) prefix. +recommended to prefix their name with an '_' (underscore). This will prevent any possible name clashes with internal makepkg variables. For example, to store the base kernel version in a variable, use something similar to `$_basekernver`.
*pkgname (array)*:: - The name of the package. This has be a unix-friendly name as it will be - used in the package filename. Members of the array are not allowed to start - with hyphens. + The name of the package or an array of names for split packages. + Because it will be used in the package filename, this has to be unix-friendly. + Members of the array are not allowed to start with hyphens.
*pkgver*:: The version of the software as released from the author (e.g. '2.7.1'). @@ -50,13 +50,13 @@ similar to `$_basekernver`. *pkgrel*:: This is the release number specific to the Arch Linux release. This allows package maintainers to make updates to the package's configure - flags, for example. A pkgrel of '1' is typically used for each upstream - software release and is incremented for intermediate PKGBUILD updates. The + flags, for example. This is typically (re)set to '1' for each new upstream + software release and incremented for intermediate PKGBUILD updates. The variable is not allowed to contain hyphens.
*pkgdesc*:: This should be a brief description of the package and its functionality. - Try to keep the description to one line of text. + Try to keep the description to one line of text and not use the package's name.
*epoch*:: Used to force the package to be seen as newer than any previous versions @@ -69,18 +69,18 @@ similar to `$_basekernver`.
*url*:: This field contains a URL that is associated with the software being - packaged. This is typically the project's website. + packaged. Typically the project's website.
*license (array)*:: This field specifies the license(s) that apply to the package. - Commonly-used licenses are found in '/usr/share/licenses/common'. If you + Commonly used licenses can be found in '/usr/share/licenses/common'. If you see the package's license there, simply reference it in the license field (e.g. `license=('GPL')`). If the package provides a license not - found in '/usr/share/licenses/common', then you should include the license + available in '/usr/share/licenses/common', then you should include it in the package itself and set `license=('custom')` or `license=('custom:LicenseName')`. The license should be placed in - '$pkgdir/usr/share/licenses/$pkgname' when building the package. If - multiple licenses are applicable for a package, list all of them: + '$pkgdir/usr/share/licenses/$pkgname/' when building the package. If + multiple licenses are applicable, list all of them: `license=('GPL' 'FDL')`.
*install*:: @@ -97,22 +97,21 @@ similar to `$_basekernver`.
*source (array)*:: An array of source files required to build the package. Source files - must either reside in the same directory as the PKGBUILD file, or be a - fully-qualified URL that makepkg will use to download the file. In order - to make the PKGBUILD as useful as possible, use the $pkgname and $pkgver - variables if possible when specifying the download location. Any files - that are compressed will automatically be extracted, unless found in - the noextract array listed below. + must either reside in the same directory as the PKGBUILD, or be a + fully-qualified URL that makepkg can use to download the file. + To make the PKGBUILD as useful as possible, use the $pkgname and $pkgver + variables if possible when specifying the download location. Compressed files + will be extracted automatically, unless found in + the noextract array described below.
"unless" is being used as a subordinate conjunction here and should not be preceded by a comma.
+ -It is also possible to specify an optional filename, which is helpful +It is also possible to overwrite the filename, which is helpful with weird URLs and for handling multiple source files with the same name. The syntax is: `source=('filename::url')`.
*noextract (array)*:: An array of filenames corresponding to those from the source array. Files listed here will not be extracted with the rest of the source files. This - is useful for packages which use compressed data which is downloaded but - not necessary to uncompress. + is useful for packages that use compressed data directly.
*md5sums (array)*:: This array contains an MD5 hash for every source file specified in the @@ -135,16 +134,16 @@ name. The syntax is: `source=('filename::url')`. *arch (array)*:: Defines on which architectures the given package is available (e.g. `arch=('i686' 'x86_64')`). Packages that contain no architecture specific - files may use arch=('any'). + files should use arch=('any').
*backup (array)*:: - A space-delimited array of filenames, without preceding slashes, that + An array of filenames, without preceding slashes, that should be backed up if the package is removed or upgraded. This is commonly used for packages placing configuration files in /etc. See Handling Config Files in linkman:pacman[8] for more information.
*depends (array)*:: - An array of packages that this package depends on to run. Packages in + An array of packages this package depends on to run. Entries in this list should be surrounded with single quotes and contain at least the package name. Entries can also include a version requirement of the form 'name<>version', where <> is one of five comparisons: >= (greater @@ -152,12 +151,12 @@ name. The syntax is: `source=('filename::url')`. than), or < (less than).
*makedepends (array)*:: - An array of packages that this package depends on to build, but are not + An array of packages this package depends on to build, but are not
The comma before "but" is not needed because it does not separate independent clauses.
needed at runtime. Packages in this list follow the same format as depends.
*checkdepends (array)*:: - An array of packages that this package depends on to run its test suite, + An array of packages this package depends on to run its test suite, but are not needed at runtime. Packages in this list follow the same format as depends. These dependencies are only considered when the check() function is present and is to be run by makepkg. @@ -177,7 +176,7 @@ name. The syntax is: `source=('filename::url')`. same format as depends. Versioned conflicts are also supported.
*provides (array)*:: - An array of ``virtual provisions'' that this package provides. This allows + An array of ``virtual provisions'' this package provides. This allows a package to provide dependencies other than its own package name. For example, the dcron package can provide 'cron', which allows packages to depend on 'cron' rather than 'dcron OR fcron'. @@ -188,7 +187,7 @@ name. The syntax is: `source=('filename::url')`. provided.
*replaces (array)*:: - An array of packages that this package should replace, and can be used + An array of packages this package should replace. This can be used to handle renamed/combined packages. For example, if the 'j2re' package is renamed to 'jre', this directive allows future upgrades to continue as expected even though the package has moved. Sysupgrade is currently @@ -248,7 +247,7 @@ name. The syntax is: `source=('filename::url')`.
build() Function ---------------- -In addition to the above directives, the optional build() bash function usually +In addition to the above directives, the optional build() function usually comprises the remainder of the PKGBUILD. This is directly sourced and executed by makepkg, so anything that bash or the system has available is available for use here. The function is run in `bash -e` mode, meaning any command that exits @@ -256,22 +255,22 @@ with a non-zero status will cause the function to exit. Be sure any exotic commands used are covered by `makedepends`.
All of the above variables such as `pkgname` and `pkgver` are available for use -in the build function. In addition, makepkg defines three variables for your -use during the build and install process. These three variables are as follows: +in the build function. In addition, makepkg defines ithe following three
Oops, extraneous "i" before the.
+variables for use during the build and install process:
*startdir*:: - This contains the absolute path to the directory where the PKGBUILD was + This contains the absolute path to the directory where the PKGBUILD is located, which is usually the output of `$(pwd)` when makepkg is started.
*srcdir*:: - This points to the directory where makepkg extracts or copies all source + This points to the directory where makepkg extracts to or copies to all source files.
*pkgdir*:: This points to the directory where makepkg bundles the installed package (this directory will become the root directory of your built package).
-If you create any variables of your own in the build function, it is +If you create any variables on your own in the build function, it is recommended to use the bash `local` keyword to scope the variable to inside the build function.
@@ -301,8 +300,8 @@ Each split package uses a corresponding packaging function with name `package_foo()`, where `foo` is the name of the split package.
All options and directives for the split packages default to the global values -given within the PKGBUILD. However, some of these can be overridden within each -split package's packaging function. The following variables can be overridden: +given in the PKGBUILD. However, the following ones can be overwridden within
Another typo "overwridden" and a debateable use of "however" when "nevertheless" is meant. (I still haven't parted with Strunk and White on this on.)
+each split package's packaging function: `pkgver`, `pkgrel`, `pkgdesc`, `arch`, `license`, `groups`, `depends`, `optdepends`, `provides`, `conflicts`, `replaces`, `backup`, `options`, `install` and `changelog`. @@ -363,7 +362,7 @@ makepkg supports building development versions of packages without having to manually update the pkgver in the PKGBUILD. This was formerly done using the separate utility 'versionpkg'. In order to utilize this functionality, your PKGBUILD must use correct variable names depending on the SCM being fetched -from. +from (e.g.: "makepkg-git", "mplayer-svn").
I am sure you know the standard use of "e.g." is to follow with a comma. Apart from those minor issues, great work! I am a big fan of grammar cleanups ;) Thanks, matt
*CVS*:: The generated pkgver will be the date the package is built. -- 1.7.5.4
On 10.06.2011 01:58, matt mooney wrote:
Apart from those minor issues, great work! I am a big fan of grammar cleanups ;)
Thanks for taking a look at it. I don't want to clutter this ML too much so the fixed patch is available at [1]. Once it's been read by a few more people I'll send the final one for merging. [1] http://git.server-speed.net/users/flo/pacman/log/?h=doc_cleanup -- Florian Pritz -- {flo,bluewind}@server-speed.net
On 09:00 Fri 10 Jun , Florian Pritz wrote:
On 10.06.2011 01:58, matt mooney wrote:
Apart from those minor issues, great work! I am a big fan of grammar cleanups ;)
Thanks for taking a look at it. I don't want to clutter this ML too much so the fixed patch is available at [1]. Once it's been read by a few more people I'll send the final one for merging.
Next time you should just resend it inline as [PATCH v2] to allow people to comment on the corrected version. Acked-by: matt mooney <mfm@muteddisk.com>
On Fri, Jun 10, 2011 at 4:31 AM, matt mooney <mfm@muteddisk.com> wrote:
On 09:00 Fri 10 Jun , Florian Pritz wrote:
On 10.06.2011 01:58, matt mooney wrote:
Apart from those minor issues, great work! I am a big fan of grammar cleanups ;)
Thanks for taking a look at it. I don't want to clutter this ML too much so the fixed patch is available at [1]. Once it's been read by a few more people I'll send the final one for merging.
Next time you should just resend it inline as [PATCH v2] to allow people to comment on the corrected version.
Acked-by: matt mooney <mfm@muteddisk.com>
Definitely just send it again next time; don't ever worry about cluttering the ML. Whether a message includes a patch or not, it is still a message. Comments (made harder by not inline): * "The name of the package or an array of names for split packages." - seems to be looking for an "Either" at the start to pair with the "or" already there, and then a comma can be put before the or, e.g. "Either the name of the package, or an array of names for split packages." Matt, correct me if I'm wrong. :) * "(re)set" -> "set", I don't think the former adds any clarity. * source: we seem to have a precedent elsewhere in the docs to put variables in `` (backticks). Since this got a total rewrite anyway, feel free to rewrap the whole thing for consistency at the normal textwidth of 80. * "It is also possible to overwrite the filename". This seems a bit misleading- "It is possible to change the name of the downloaded file..." or something? * "where makepkg extracts to or copies to all source"- not sure why this change is being made? Adding the two "to"s doesn't seem like proper English to me. Also, for these three, we should be consistent with either "This contains" or "This points to" (I think the former). * s/of/on/ not sure this is needed? * (e.g., "makepkg-git", "mplayer-svn"). Elsewhere we already used have multiple formats, we shouldn't add a third for consistency's sake: (e.g. '2.7.1'), (e.g. `install=pkgname.install`) . -Dan
Signed-off-by: Florian Pritz <bluewind@xinu.at> --- On 10.06.2011 19:12, Dan McGee wrote:
On Fri, Jun 10, 2011 at 4:31 AM, matt mooney <mfm@muteddisk.com> wrote:
On 09:00 Fri 10 Jun , Florian Pritz wrote:
On 10.06.2011 01:58, matt mooney wrote:
Apart from those minor issues, great work! I am a big fan of grammar cleanups ;)
Thanks for taking a look at it. I don't want to clutter this ML too much so the fixed patch is available at [1]. Once it's been read by a few more people I'll send the final one for merging.
Next time you should just resend it inline as [PATCH v2] to allow people to comment on the corrected version.
Acked-by: matt mooney <mfm@muteddisk.com>
Definitely just send it again next time; don't ever worry about cluttering the ML. Whether a message includes a patch or not, it is still a message.
Comments (made harder by not inline):
Ok I didn't think about that sorry.
* "The name of the package or an array of names for split packages." - seems to be looking for an "Either" at the start to pair with the "or" already there,
added
and then a comma can be put before the or, e.g. "Either the name of the package, or an array of names for split packages." Matt, correct me if I'm wrong. :)
added for now
* "(re)set" -> "set", I don't think the former adds any clarity.
removed
* source: we seem to have a precedent elsewhere in the docs to put variables in `` (backticks).
fixed
Since this got a total rewrite anyway, feel free to rewrap the whole thing for consistency at the normal textwidth of 80.
2 lines are exactly 80 chars, the rest is below. That script might come in handy: http://git.server-speed.net/bin/plain/long-lines.pl
* "It is also possible to overwrite the filename". This seems a bit misleading- "It is possible to change the name of the downloaded file..." or something?
done
* "where makepkg extracts to or copies to all source"- not sure why this change is being made? Adding the two "to"s doesn't seem like proper English to me.
I felt this was missing something, but you're right is sounds weird. Maybe "where makepkg extracts or copies all the source files to"? Since I'm not a native speaker I'd appreciate it if someone who is could comment on that.
Also, for these three, we should be consistent with either "This contains" or "This points to" (I think the former).
fixed
* s/of/on/ not sure this is needed?
I haven't yet seen/heard "of your own" and assumed it was a mistake. Again, I'd appreciate a comment here.
* (e.g., "makepkg-git", "mplayer-svn"). Elsewhere we already used have multiple formats, we shouldn't add a third for consistency's sake: (e.g. '2.7.1'), (e.g. `install=pkgname.install`) .
fixed doc/PKGBUILD.5.txt | 83 +++++++++++++++++++++++++-------------------------- 1 files changed, 41 insertions(+), 42 deletions(-) diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index c0fa594..63c8640 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -16,12 +16,12 @@ PKGBUILD Description ----------- -This manual page is meant to describe general rules about PKGBUILDs. Once a +This manual page describes general rules about PKGBUILDs. Once a PKGBUILD is written, the actual package is built using makepkg and installed with pacman. -NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}'. -Also located there are other example files such as a ChangeLog and an install +NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}' +along with other example files such as a ChangeLog and an install script. You can copy the provided PKGBUILD.proto file to a new package build directory and make customizations to suit your needs. @@ -30,18 +30,18 @@ Options and Directives ---------------------- The following is a list of standard options and directives available for use in a PKGBUILD. These are all understood and interpreted by makepkg, and most -will be directly transferred to the built package. +of them will be directly transferred to the built package. If you need to create any custom variables for use in your build process, it is -recommended to name your custom variables with an '_' (underscore) prefix. +recommended to prefix their name with an '_' (underscore). This will prevent any possible name clashes with internal makepkg variables. For example, to store the base kernel version in a variable, use something similar to `$_basekernver`. *pkgname (array)*:: - The name of the package. This has be a unix-friendly name as it will be - used in the package filename. Members of the array are not allowed to start - with hyphens. + Either the name of the package, or an array of names for split packages. + Because it will be used in the package filename, this has to be unix-friendly. + Members of the array are not allowed to start with hyphens. *pkgver*:: The version of the software as released from the author (e.g. '2.7.1'). @@ -50,13 +50,13 @@ similar to `$_basekernver`. *pkgrel*:: This is the release number specific to the Arch Linux release. This allows package maintainers to make updates to the package's configure - flags, for example. A pkgrel of '1' is typically used for each upstream - software release and is incremented for intermediate PKGBUILD updates. The + flags, for example. This is typically set to '1' for each new upstream + software release and incremented for intermediate PKGBUILD updates. The variable is not allowed to contain hyphens. *pkgdesc*:: This should be a brief description of the package and its functionality. - Try to keep the description to one line of text. + Try to keep the description to one line of text and not use the package's name. *epoch*:: Used to force the package to be seen as newer than any previous versions @@ -69,18 +69,18 @@ similar to `$_basekernver`. *url*:: This field contains a URL that is associated with the software being - packaged. This is typically the project's website. + packaged. Typically the project's website. *license (array)*:: This field specifies the license(s) that apply to the package. - Commonly-used licenses are found in '/usr/share/licenses/common'. If you + Commonly used licenses can be found in '/usr/share/licenses/common'. If you see the package's license there, simply reference it in the license field (e.g. `license=('GPL')`). If the package provides a license not - found in '/usr/share/licenses/common', then you should include the license + available in '/usr/share/licenses/common', then you should include it in the package itself and set `license=('custom')` or `license=('custom:LicenseName')`. The license should be placed in - '$pkgdir/usr/share/licenses/$pkgname' when building the package. If - multiple licenses are applicable for a package, list all of them: + '$pkgdir/usr/share/licenses/$pkgname/' when building the package. If + multiple licenses are applicable, list all of them: `license=('GPL' 'FDL')`. *install*:: @@ -97,22 +97,21 @@ similar to `$_basekernver`. *source (array)*:: An array of source files required to build the package. Source files - must either reside in the same directory as the PKGBUILD file, or be a - fully-qualified URL that makepkg will use to download the file. In order - to make the PKGBUILD as useful as possible, use the $pkgname and $pkgver - variables if possible when specifying the download location. Any files - that are compressed will automatically be extracted, unless found in - the noextract array listed below. + must either reside in the same directory as the PKGBUILD, or be a + fully-qualified URL that makepkg can use to download the file. + To make the PKGBUILD as useful as possible, use the `$pkgname` and `$pkgver` + variables if possible when specifying the download location. Compressed files + will be extracted automatically unless found in + the noextract array described below. + -It is also possible to specify an optional filename, which is helpful +It is also possible to change the name of the downloaded file, which is helpful with weird URLs and for handling multiple source files with the same name. The syntax is: `source=('filename::url')`. *noextract (array)*:: An array of filenames corresponding to those from the source array. Files listed here will not be extracted with the rest of the source files. This - is useful for packages which use compressed data which is downloaded but - not necessary to uncompress. + is useful for packages that use compressed data directly. *md5sums (array)*:: This array contains an MD5 hash for every source file specified in the @@ -135,16 +134,16 @@ name. The syntax is: `source=('filename::url')`. *arch (array)*:: Defines on which architectures the given package is available (e.g. `arch=('i686' 'x86_64')`). Packages that contain no architecture specific - files may use arch=('any'). + files should use arch=('any'). *backup (array)*:: - A space-delimited array of filenames, without preceding slashes, that + An array of filenames, without preceding slashes, that should be backed up if the package is removed or upgraded. This is commonly used for packages placing configuration files in /etc. See Handling Config Files in linkman:pacman[8] for more information. *depends (array)*:: - An array of packages that this package depends on to run. Packages in + An array of packages this package depends on to run. Entries in this list should be surrounded with single quotes and contain at least the package name. Entries can also include a version requirement of the form 'name<>version', where <> is one of five comparisons: >= (greater @@ -152,12 +151,12 @@ name. The syntax is: `source=('filename::url')`. than), or < (less than). *makedepends (array)*:: - An array of packages that this package depends on to build, but are not + An array of packages this package depends on to build but are not needed at runtime. Packages in this list follow the same format as depends. *checkdepends (array)*:: - An array of packages that this package depends on to run its test suite, + An array of packages this package depends on to run its test suite but are not needed at runtime. Packages in this list follow the same format as depends. These dependencies are only considered when the check() function is present and is to be run by makepkg. @@ -177,7 +176,7 @@ name. The syntax is: `source=('filename::url')`. same format as depends. Versioned conflicts are also supported. *provides (array)*:: - An array of ``virtual provisions'' that this package provides. This allows + An array of ``virtual provisions'' this package provides. This allows a package to provide dependencies other than its own package name. For example, the dcron package can provide 'cron', which allows packages to depend on 'cron' rather than 'dcron OR fcron'. @@ -188,7 +187,7 @@ name. The syntax is: `source=('filename::url')`. provided. *replaces (array)*:: - An array of packages that this package should replace, and can be used + An array of packages this package should replace. This can be used to handle renamed/combined packages. For example, if the 'j2re' package is renamed to 'jre', this directive allows future upgrades to continue as expected even though the package has moved. Sysupgrade is currently @@ -248,7 +247,7 @@ name. The syntax is: `source=('filename::url')`. build() Function ---------------- -In addition to the above directives, the optional build() bash function usually +In addition to the above directives, the optional build() function usually comprises the remainder of the PKGBUILD. This is directly sourced and executed by makepkg, so anything that bash or the system has available is available for use here. The function is run in `bash -e` mode, meaning any command that exits @@ -256,22 +255,22 @@ with a non-zero status will cause the function to exit. Be sure any exotic commands used are covered by `makedepends`. All of the above variables such as `pkgname` and `pkgver` are available for use -in the build function. In addition, makepkg defines three variables for your -use during the build and install process. These three variables are as follows: +in the build function. In addition, makepkg defines the following three +variables for use during the build and install process: *startdir*:: - This contains the absolute path to the directory where the PKGBUILD was + This contains the absolute path to the directory where the PKGBUILD is located, which is usually the output of `$(pwd)` when makepkg is started. *srcdir*:: - This points to the directory where makepkg extracts or copies all source + This contains the directory where makepkg extracts to or copies to all source files. *pkgdir*:: - This points to the directory where makepkg bundles the installed package + This contains the directory where makepkg bundles the installed package (this directory will become the root directory of your built package). -If you create any variables of your own in the build function, it is +If you create any variables on your own in the build function, it is recommended to use the bash `local` keyword to scope the variable to inside the build function. @@ -301,8 +300,8 @@ Each split package uses a corresponding packaging function with name `package_foo()`, where `foo` is the name of the split package. All options and directives for the split packages default to the global values -given within the PKGBUILD. However, some of these can be overridden within each -split package's packaging function. The following variables can be overridden: +given in the PKGBUILD. Nevertheless, the following ones can be overridden within +each split package's packaging function: `pkgver`, `pkgrel`, `pkgdesc`, `arch`, `license`, `groups`, `depends`, `optdepends`, `provides`, `conflicts`, `replaces`, `backup`, `options`, `install` and `changelog`. @@ -363,7 +362,7 @@ makepkg supports building development versions of packages without having to manually update the pkgver in the PKGBUILD. This was formerly done using the separate utility 'versionpkg'. In order to utilize this functionality, your PKGBUILD must use correct variable names depending on the SCM being fetched -from. +from (e.g. "makepkg-git", "mplayer-svn"). *CVS*:: The generated pkgver will be the date the package is built. -- 1.7.5.4
On 10.06.2011 19:12, Dan McGee wrote:
* "where makepkg extracts to or copies to all source"- not sure why this change is being made? Adding the two "to"s doesn't seem like proper English to me.
I felt this was missing something, but you're right is sounds weird. Maybe "where makepkg extracts or copies all the source files to"? Since I'm not a native speaker I'd appreciate it if someone who is could comment on that. "This contains the directory where makepkg copies and extracts all
On Fri, Jun 10, 2011 at 12:39 PM, Florian Pritz <bluewind@xinu.at> wrote: source files." really seems fine to me (note the or->and switch, since we do both). No need to have a dangling preposition at the end.
* s/of/on/ not sure this is needed?
I haven't yet seen/heard "of your own" and assumed it was a mistake. Again, I'd appreciate a comment here.
"A bed of your own", "A house of your own", "variables of your own". If that helps. :)
@@ -363,7 +362,7 @@ makepkg supports building development versions of packages without having to manually update the pkgver in the PKGBUILD. This was formerly done using the separate utility 'versionpkg'. In order to utilize this functionality, your PKGBUILD must use correct variable names depending on the SCM being fetched -from. +from (e.g. "makepkg-git", "mplayer-svn"). I actually meant the "" vs '' vs `` as much as the comma business, which is really a matter of choice/location, it seems (http://dictionary.reference.com/help/faq/language/g58.html).
-Dan
On 19:39 Fri 10 Jun , Florian Pritz wrote:
Signed-off-by: Florian Pritz <bluewind@xinu.at> --- On 10.06.2011 19:12, Dan McGee wrote:
On Fri, Jun 10, 2011 at 4:31 AM, matt mooney <mfm@muteddisk.com> wrote:
On 09:00 Fri 10 Jun , Florian Pritz wrote:
On 10.06.2011 01:58, matt mooney wrote:
Apart from those minor issues, great work! I am a big fan of grammar cleanups ;)
Thanks for taking a look at it. I don't want to clutter this ML too much so the fixed patch is available at [1]. Once it's been read by a few more people I'll send the final one for merging.
Next time you should just resend it inline as [PATCH v2] to allow people to comment on the corrected version.
Acked-by: matt mooney <mfm@muteddisk.com>
Definitely just send it again next time; don't ever worry about cluttering the ML. Whether a message includes a patch or not, it is still a message.
Comments (made harder by not inline):
Ok I didn't think about that sorry.
* "The name of the package or an array of names for split packages." - seems to be looking for an "Either" at the start to pair with the "or" already there,
added
and then a comma can be put before the or, e.g. "Either the name of the package, or an array of names for split packages." Matt, correct me if I'm wrong. :)
added for now
There should not be a comma here; "Either..or" is a correlative conjunction. If the "or" was being used as an appositive or coordinating conjuntion, then the comma would be correct. I do like the change though.
* "(re)set" -> "set", I don't think the former adds any clarity.
removed
* source: we seem to have a precedent elsewhere in the docs to put variables in `` (backticks).
fixed
Since this got a total rewrite anyway, feel free to rewrap the whole thing for consistency at the normal textwidth of 80.
I definitely agree here!
2 lines are exactly 80 chars, the rest is below. That script might come in handy: http://git.server-speed.net/bin/plain/long-lines.pl
* "It is also possible to overwrite the filename". This seems a bit misleading- "It is possible to change the name of the downloaded file..." or something?
done
* "where makepkg extracts to or copies to all source"- not sure why this change is being made? Adding the two "to"s doesn't seem like proper English to me.
I felt this was missing something, but you're right is sounds weird. Maybe "where makepkg extracts or copies all the source files to"? Since I'm not a native speaker I'd appreciate it if someone who is could comment on that.
I overlooked that one. If the words in question were nouns, "copies" would be a non-restrictive appositive for "extract"; however, I don't know the name for this when applied to verbs... renaming or something. Either way it is non-restrictive element and should be offset with commas. My suggestion for the sentence: "This contains the directory where makepkg extracts, or copies, the source files."
Also, for these three, we should be consistent with either "This contains" or "This points to" (I think the former).
fixed
* s/of/on/ not sure this is needed?
Both are prepositions and used correctly, so it seems to be a question of style.
I haven't yet seen/heard "of your own" and assumed it was a mistake. Again, I'd appreciate a comment here.
* (e.g., "makepkg-git", "mplayer-svn"). Elsewhere we already used have multiple formats, we shouldn't add a third for consistency's sake: (e.g. '2.7.1'), (e.g. `install=pkgname.install`) .
fixed
Yeah, I didn't look at the file as a whole for consistency, but that is obviously important. In this case, maybe he should modify the other uses of "e.g." while adhering to the quoting style within the file. -matt
doc/PKGBUILD.5.txt | 83 +++++++++++++++++++++++++-------------------------- 1 files changed, 41 insertions(+), 42 deletions(-)
diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index c0fa594..63c8640 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -16,12 +16,12 @@ PKGBUILD
Description ----------- -This manual page is meant to describe general rules about PKGBUILDs. Once a +This manual page describes general rules about PKGBUILDs. Once a PKGBUILD is written, the actual package is built using makepkg and installed with pacman.
-NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}'. -Also located there are other example files such as a ChangeLog and an install +NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}' +along with other example files such as a ChangeLog and an install script. You can copy the provided PKGBUILD.proto file to a new package build directory and make customizations to suit your needs.
@@ -30,18 +30,18 @@ Options and Directives ---------------------- The following is a list of standard options and directives available for use in a PKGBUILD. These are all understood and interpreted by makepkg, and most -will be directly transferred to the built package. +of them will be directly transferred to the built package.
If you need to create any custom variables for use in your build process, it is -recommended to name your custom variables with an '_' (underscore) prefix. +recommended to prefix their name with an '_' (underscore). This will prevent any possible name clashes with internal makepkg variables. For example, to store the base kernel version in a variable, use something similar to `$_basekernver`.
*pkgname (array)*:: - The name of the package. This has be a unix-friendly name as it will be - used in the package filename. Members of the array are not allowed to start - with hyphens. + Either the name of the package, or an array of names for split packages. + Because it will be used in the package filename, this has to be unix-friendly. + Members of the array are not allowed to start with hyphens.
*pkgver*:: The version of the software as released from the author (e.g. '2.7.1'). @@ -50,13 +50,13 @@ similar to `$_basekernver`. *pkgrel*:: This is the release number specific to the Arch Linux release. This allows package maintainers to make updates to the package's configure - flags, for example. A pkgrel of '1' is typically used for each upstream - software release and is incremented for intermediate PKGBUILD updates. The + flags, for example. This is typically set to '1' for each new upstream + software release and incremented for intermediate PKGBUILD updates. The variable is not allowed to contain hyphens.
*pkgdesc*:: This should be a brief description of the package and its functionality. - Try to keep the description to one line of text. + Try to keep the description to one line of text and not use the package's name.
*epoch*:: Used to force the package to be seen as newer than any previous versions @@ -69,18 +69,18 @@ similar to `$_basekernver`.
*url*:: This field contains a URL that is associated with the software being - packaged. This is typically the project's website. + packaged. Typically the project's website.
*license (array)*:: This field specifies the license(s) that apply to the package. - Commonly-used licenses are found in '/usr/share/licenses/common'. If you + Commonly used licenses can be found in '/usr/share/licenses/common'. If you see the package's license there, simply reference it in the license field (e.g. `license=('GPL')`). If the package provides a license not - found in '/usr/share/licenses/common', then you should include the license + available in '/usr/share/licenses/common', then you should include it in the package itself and set `license=('custom')` or `license=('custom:LicenseName')`. The license should be placed in - '$pkgdir/usr/share/licenses/$pkgname' when building the package. If - multiple licenses are applicable for a package, list all of them: + '$pkgdir/usr/share/licenses/$pkgname/' when building the package. If + multiple licenses are applicable, list all of them: `license=('GPL' 'FDL')`.
*install*:: @@ -97,22 +97,21 @@ similar to `$_basekernver`.
*source (array)*:: An array of source files required to build the package. Source files - must either reside in the same directory as the PKGBUILD file, or be a - fully-qualified URL that makepkg will use to download the file. In order - to make the PKGBUILD as useful as possible, use the $pkgname and $pkgver - variables if possible when specifying the download location. Any files - that are compressed will automatically be extracted, unless found in - the noextract array listed below. + must either reside in the same directory as the PKGBUILD, or be a + fully-qualified URL that makepkg can use to download the file. + To make the PKGBUILD as useful as possible, use the `$pkgname` and `$pkgver` + variables if possible when specifying the download location. Compressed files + will be extracted automatically unless found in + the noextract array described below. + -It is also possible to specify an optional filename, which is helpful +It is also possible to change the name of the downloaded file, which is helpful with weird URLs and for handling multiple source files with the same name. The syntax is: `source=('filename::url')`.
*noextract (array)*:: An array of filenames corresponding to those from the source array. Files listed here will not be extracted with the rest of the source files. This - is useful for packages which use compressed data which is downloaded but - not necessary to uncompress. + is useful for packages that use compressed data directly.
*md5sums (array)*:: This array contains an MD5 hash for every source file specified in the @@ -135,16 +134,16 @@ name. The syntax is: `source=('filename::url')`. *arch (array)*:: Defines on which architectures the given package is available (e.g. `arch=('i686' 'x86_64')`). Packages that contain no architecture specific - files may use arch=('any'). + files should use arch=('any').
*backup (array)*:: - A space-delimited array of filenames, without preceding slashes, that + An array of filenames, without preceding slashes, that should be backed up if the package is removed or upgraded. This is commonly used for packages placing configuration files in /etc. See Handling Config Files in linkman:pacman[8] for more information.
*depends (array)*:: - An array of packages that this package depends on to run. Packages in + An array of packages this package depends on to run. Entries in this list should be surrounded with single quotes and contain at least the package name. Entries can also include a version requirement of the form 'name<>version', where <> is one of five comparisons: >= (greater @@ -152,12 +151,12 @@ name. The syntax is: `source=('filename::url')`. than), or < (less than).
*makedepends (array)*:: - An array of packages that this package depends on to build, but are not + An array of packages this package depends on to build but are not needed at runtime. Packages in this list follow the same format as depends.
*checkdepends (array)*:: - An array of packages that this package depends on to run its test suite, + An array of packages this package depends on to run its test suite but are not needed at runtime. Packages in this list follow the same format as depends. These dependencies are only considered when the check() function is present and is to be run by makepkg. @@ -177,7 +176,7 @@ name. The syntax is: `source=('filename::url')`. same format as depends. Versioned conflicts are also supported.
*provides (array)*:: - An array of ``virtual provisions'' that this package provides. This allows + An array of ``virtual provisions'' this package provides. This allows a package to provide dependencies other than its own package name. For example, the dcron package can provide 'cron', which allows packages to depend on 'cron' rather than 'dcron OR fcron'. @@ -188,7 +187,7 @@ name. The syntax is: `source=('filename::url')`. provided.
*replaces (array)*:: - An array of packages that this package should replace, and can be used + An array of packages this package should replace. This can be used to handle renamed/combined packages. For example, if the 'j2re' package is renamed to 'jre', this directive allows future upgrades to continue as expected even though the package has moved. Sysupgrade is currently @@ -248,7 +247,7 @@ name. The syntax is: `source=('filename::url')`.
build() Function ---------------- -In addition to the above directives, the optional build() bash function usually +In addition to the above directives, the optional build() function usually comprises the remainder of the PKGBUILD. This is directly sourced and executed by makepkg, so anything that bash or the system has available is available for use here. The function is run in `bash -e` mode, meaning any command that exits @@ -256,22 +255,22 @@ with a non-zero status will cause the function to exit. Be sure any exotic commands used are covered by `makedepends`.
All of the above variables such as `pkgname` and `pkgver` are available for use -in the build function. In addition, makepkg defines three variables for your -use during the build and install process. These three variables are as follows: +in the build function. In addition, makepkg defines the following three +variables for use during the build and install process:
*startdir*:: - This contains the absolute path to the directory where the PKGBUILD was + This contains the absolute path to the directory where the PKGBUILD is located, which is usually the output of `$(pwd)` when makepkg is started.
*srcdir*:: - This points to the directory where makepkg extracts or copies all source + This contains the directory where makepkg extracts to or copies to all source files.
*pkgdir*:: - This points to the directory where makepkg bundles the installed package + This contains the directory where makepkg bundles the installed package (this directory will become the root directory of your built package).
-If you create any variables of your own in the build function, it is +If you create any variables on your own in the build function, it is recommended to use the bash `local` keyword to scope the variable to inside the build function.
@@ -301,8 +300,8 @@ Each split package uses a corresponding packaging function with name `package_foo()`, where `foo` is the name of the split package.
All options and directives for the split packages default to the global values -given within the PKGBUILD. However, some of these can be overridden within each -split package's packaging function. The following variables can be overridden: +given in the PKGBUILD. Nevertheless, the following ones can be overridden within +each split package's packaging function: `pkgver`, `pkgrel`, `pkgdesc`, `arch`, `license`, `groups`, `depends`, `optdepends`, `provides`, `conflicts`, `replaces`, `backup`, `options`, `install` and `changelog`. @@ -363,7 +362,7 @@ makepkg supports building development versions of packages without having to manually update the pkgver in the PKGBUILD. This was formerly done using the separate utility 'versionpkg'. In order to utilize this functionality, your PKGBUILD must use correct variable names depending on the SCM being fetched -from. +from (e.g. "makepkg-git", "mplayer-svn").
*CVS*:: The generated pkgver will be the date the package is built. -- 1.7.5.4
Signed-off-by: Florian Pritz <bluewind@xinu.at> Acked-by: matt mooney <mfm@muteddisk.com> --- On 10.06.2011 23:07, matt mooney wrote:
* "The name of the package or an array of names for split packages." - seems to be looking for an "Either" at the start to pair with the "or" already there,
added
and then a comma can be put before the or, e.g. "Either the name of the package, or an array of names for split packages." Matt, correct me if I'm wrong. :)
added for now
There should not be a comma here; "Either..or" is a correlative conjunction. If the "or" was being used as an appositive or coordinating conjuntion, then the comma would be correct.
fixed
* "where makepkg extracts to or copies to all source"- not sure why this change is being made? Adding the two "to"s doesn't seem like proper English to me.
I felt this was missing something, but you're right is sounds weird. Maybe "where makepkg extracts or copies all the source files to"? Since I'm not a native speaker I'd appreciate it if someone who is could comment on that.
I overlooked that one. If the words in question were nouns, "copies" would be a non-restrictive appositive for "extract"; however, I don't know the name for this when applied to verbs... renaming or something. Either way it is non-restrictive element and should be offset with commas.
My suggestion for the sentence: "This contains the directory where makepkg extracts, or copies, the source files."
fixed
* s/of/on/ not sure this is needed?
Both are prepositions and used correctly, so it seems to be a question of style.
I haven't yet seen/heard "of your own" and assumed it was a mistake. Again, I'd appreciate a comment here.
* (e.g., "makepkg-git", "mplayer-svn"). Elsewhere we already used have multiple formats, we shouldn't add a third for consistency's sake: (e.g. '2.7.1'), (e.g. `install=pkgname.install`) .
fixed
Yeah, I didn't look at the file as a whole for consistency, but that is obviously important. In this case, maybe he should modify the other uses of "e.g." while adhering to the quoting style within the file.
It's "e.g.," (or should I loose the comma?) everywhere now. `` is used for variable assignments and '' for everything else. -- Florian Pritz doc/PKGBUILD.5.txt | 91 +++++++++++++++++++++++++-------------------------- 1 files changed, 45 insertions(+), 46 deletions(-) diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index c0fa594..753c4ea 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -16,12 +16,12 @@ PKGBUILD Description ----------- -This manual page is meant to describe general rules about PKGBUILDs. Once a +This manual page describes general rules about PKGBUILDs. Once a PKGBUILD is written, the actual package is built using makepkg and installed with pacman. -NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}'. -Also located there are other example files such as a ChangeLog and an install +NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}' +along with other example files such as a ChangeLog and an install script. You can copy the provided PKGBUILD.proto file to a new package build directory and make customizations to suit your needs. @@ -30,33 +30,33 @@ Options and Directives ---------------------- The following is a list of standard options and directives available for use in a PKGBUILD. These are all understood and interpreted by makepkg, and most -will be directly transferred to the built package. +of them will be directly transferred to the built package. If you need to create any custom variables for use in your build process, it is -recommended to name your custom variables with an '_' (underscore) prefix. +recommended to prefix their name with an '_' (underscore). This will prevent any possible name clashes with internal makepkg variables. For example, to store the base kernel version in a variable, use something similar to `$_basekernver`. *pkgname (array)*:: - The name of the package. This has be a unix-friendly name as it will be - used in the package filename. Members of the array are not allowed to start - with hyphens. + Either the name of the package or an array of names for split packages. + Because it will be used in the package filename, this has to be unix-friendly. + Members of the array are not allowed to start with hyphens. *pkgver*:: - The version of the software as released from the author (e.g. '2.7.1'). + The version of the software as released from the author (e.g., '2.7.1'). The variable is not allowed to contain colons or hyphens. *pkgrel*:: This is the release number specific to the Arch Linux release. This allows package maintainers to make updates to the package's configure - flags, for example. A pkgrel of '1' is typically used for each upstream - software release and is incremented for intermediate PKGBUILD updates. The + flags, for example. This is typically set to '1' for each new upstream + software release and incremented for intermediate PKGBUILD updates. The variable is not allowed to contain hyphens. *pkgdesc*:: This should be a brief description of the package and its functionality. - Try to keep the description to one line of text. + Try to keep the description to one line of text and not use the package's name. *epoch*:: Used to force the package to be seen as newer than any previous versions @@ -69,50 +69,49 @@ similar to `$_basekernver`. *url*:: This field contains a URL that is associated with the software being - packaged. This is typically the project's website. + packaged. Typically the project's website. *license (array)*:: This field specifies the license(s) that apply to the package. - Commonly-used licenses are found in '/usr/share/licenses/common'. If you + Commonly used licenses can be found in '/usr/share/licenses/common'. If you see the package's license there, simply reference it in the license - field (e.g. `license=('GPL')`). If the package provides a license not - found in '/usr/share/licenses/common', then you should include the license + field (e.g., `license=('GPL')`). If the package provides a license not + available in '/usr/share/licenses/common', then you should include it in the package itself and set `license=('custom')` or `license=('custom:LicenseName')`. The license should be placed in - '$pkgdir/usr/share/licenses/$pkgname' when building the package. If - multiple licenses are applicable for a package, list all of them: + '$pkgdir/usr/share/licenses/$pkgname/' when building the package. If + multiple licenses are applicable, list all of them: `license=('GPL' 'FDL')`. *install*:: Specifies a special install script that is to be included in the package. This file should reside in the same directory as the PKGBUILD, and will be copied into the package by makepkg. It does not need to be included - in the source array (e.g. `install=pkgname.install`). + in the source array (e.g., `install=pkgname.install`). *changelog*:: Specifies a changelog file that is to be included in the package. This file should reside in the same directory as the PKGBUILD, and will be copied into the package by makepkg. It does not need to be included - in the source array (e.g. `changelog=$pkgname.changelog`). + in the source array (e.g., `changelog=$pkgname.changelog`). *source (array)*:: An array of source files required to build the package. Source files - must either reside in the same directory as the PKGBUILD file, or be a - fully-qualified URL that makepkg will use to download the file. In order - to make the PKGBUILD as useful as possible, use the $pkgname and $pkgver - variables if possible when specifying the download location. Any files - that are compressed will automatically be extracted, unless found in - the noextract array listed below. + must either reside in the same directory as the PKGBUILD, or be a + fully-qualified URL that makepkg can use to download the file. + To make the PKGBUILD as useful as possible, use the `$pkgname` and `$pkgver` + variables if possible when specifying the download location. Compressed files + will be extracted automatically unless found in + the noextract array described below. + -It is also possible to specify an optional filename, which is helpful +It is also possible to change the name of the downloaded file, which is helpful with weird URLs and for handling multiple source files with the same name. The syntax is: `source=('filename::url')`. *noextract (array)*:: An array of filenames corresponding to those from the source array. Files listed here will not be extracted with the rest of the source files. This - is useful for packages which use compressed data which is downloaded but - not necessary to uncompress. + is useful for packages that use compressed data directly. *md5sums (array)*:: This array contains an MD5 hash for every source file specified in the @@ -133,18 +132,18 @@ name. The syntax is: `source=('filename::url')`. example, one could install all KDE packages by installing the 'kde' group. *arch (array)*:: - Defines on which architectures the given package is available (e.g. + Defines on which architectures the given package is available (e.g., `arch=('i686' 'x86_64')`). Packages that contain no architecture specific - files may use arch=('any'). + files should use arch=('any'). *backup (array)*:: - A space-delimited array of filenames, without preceding slashes, that + An array of filenames, without preceding slashes, that should be backed up if the package is removed or upgraded. This is commonly used for packages placing configuration files in /etc. See Handling Config Files in linkman:pacman[8] for more information. *depends (array)*:: - An array of packages that this package depends on to run. Packages in + An array of packages this package depends on to run. Entries in this list should be surrounded with single quotes and contain at least the package name. Entries can also include a version requirement of the form 'name<>version', where <> is one of five comparisons: >= (greater @@ -152,12 +151,12 @@ name. The syntax is: `source=('filename::url')`. than), or < (less than). *makedepends (array)*:: - An array of packages that this package depends on to build, but are not + An array of packages this package depends on to build but are not needed at runtime. Packages in this list follow the same format as depends. *checkdepends (array)*:: - An array of packages that this package depends on to run its test suite, + An array of packages this package depends on to run its test suite but are not needed at runtime. Packages in this list follow the same format as depends. These dependencies are only considered when the check() function is present and is to be run by makepkg. @@ -177,7 +176,7 @@ name. The syntax is: `source=('filename::url')`. same format as depends. Versioned conflicts are also supported. *provides (array)*:: - An array of ``virtual provisions'' that this package provides. This allows + An array of ``virtual provisions'' this package provides. This allows a package to provide dependencies other than its own package name. For example, the dcron package can provide 'cron', which allows packages to depend on 'cron' rather than 'dcron OR fcron'. @@ -188,7 +187,7 @@ name. The syntax is: `source=('filename::url')`. provided. *replaces (array)*:: - An array of packages that this package should replace, and can be used + An array of packages this package should replace. This can be used to handle renamed/combined packages. For example, if the 'j2re' package is renamed to 'jre', this directive allows future upgrades to continue as expected even though the package has moved. Sysupgrade is currently @@ -248,7 +247,7 @@ name. The syntax is: `source=('filename::url')`. build() Function ---------------- -In addition to the above directives, the optional build() bash function usually +In addition to the above directives, the optional build() function usually comprises the remainder of the PKGBUILD. This is directly sourced and executed by makepkg, so anything that bash or the system has available is available for use here. The function is run in `bash -e` mode, meaning any command that exits @@ -256,19 +255,19 @@ with a non-zero status will cause the function to exit. Be sure any exotic commands used are covered by `makedepends`. All of the above variables such as `pkgname` and `pkgver` are available for use -in the build function. In addition, makepkg defines three variables for your -use during the build and install process. These three variables are as follows: +in the build function. In addition, makepkg defines the following three +variables for use during the build and install process: *startdir*:: - This contains the absolute path to the directory where the PKGBUILD was + This contains the absolute path to the directory where the PKGBUILD is located, which is usually the output of `$(pwd)` when makepkg is started. *srcdir*:: - This points to the directory where makepkg extracts or copies all source + This contains the directory where makepkg extracts, or copies, all source files. *pkgdir*:: - This points to the directory where makepkg bundles the installed package + This contains the directory where makepkg bundles the installed package (this directory will become the root directory of your built package). If you create any variables of your own in the build function, it is @@ -301,8 +300,8 @@ Each split package uses a corresponding packaging function with name `package_foo()`, where `foo` is the name of the split package. All options and directives for the split packages default to the global values -given within the PKGBUILD. However, some of these can be overridden within each -split package's packaging function. The following variables can be overridden: +given in the PKGBUILD. Nevertheless, the following ones can be overridden within +each split package's packaging function: `pkgver`, `pkgrel`, `pkgdesc`, `arch`, `license`, `groups`, `depends`, `optdepends`, `provides`, `conflicts`, `replaces`, `backup`, `options`, `install` and `changelog`. @@ -363,7 +362,7 @@ makepkg supports building development versions of packages without having to manually update the pkgver in the PKGBUILD. This was formerly done using the separate utility 'versionpkg'. In order to utilize this functionality, your PKGBUILD must use correct variable names depending on the SCM being fetched -from. +from (e.g., 'makepkg-git', 'mplayer-svn'). *CVS*:: The generated pkgver will be the date the package is built. -- 1.7.5.4
On 15:04 Sat 11 Jun , Florian Pritz wrote:
Signed-off-by: Florian Pritz <bluewind@xinu.at> Acked-by: matt mooney <mfm@muteddisk.com> --- On 10.06.2011 23:07, matt mooney wrote:
* "The name of the package or an array of names for split packages." - seems to be looking for an "Either" at the start to pair with the "or" already there,
added
and then a comma can be put before the or, e.g. "Either the name of the package, or an array of names for split packages." Matt, correct me if I'm wrong. :)
added for now
There should not be a comma here; "Either..or" is a correlative conjunction. If the "or" was being used as an appositive or coordinating conjuntion, then the comma would be correct.
fixed
* "where makepkg extracts to or copies to all source"- not sure why this change is being made? Adding the two "to"s doesn't seem like proper English to me.
I felt this was missing something, but you're right is sounds weird. Maybe "where makepkg extracts or copies all the source files to"? Since I'm not a native speaker I'd appreciate it if someone who is could comment on that.
I overlooked that one. If the words in question were nouns, "copies" would be a non-restrictive appositive for "extract"; however, I don't know the name for this when applied to verbs... renaming or something. Either way it is non-restrictive element and should be offset with commas.
My suggestion for the sentence: "This contains the directory where makepkg extracts, or copies, the source files."
fixed
* s/of/on/ not sure this is needed?
Both are prepositions and used correctly, so it seems to be a question of style.
I haven't yet seen/heard "of your own" and assumed it was a mistake. Again, I'd appreciate a comment here.
* (e.g., "makepkg-git", "mplayer-svn"). Elsewhere we already used have multiple formats, we shouldn't add a third for consistency's sake: (e.g. '2.7.1'), (e.g. `install=pkgname.install`) .
fixed
Yeah, I didn't look at the file as a whole for consistency, but that is obviously important. In this case, maybe he should modify the other uses of "e.g." while adhering to the quoting style within the file.
It's "e.g.," (or should I loose the comma?) everywhere now. `` is used for variable assignments and '' for everything else.
The majority of grammarians say that the comma is required, and I agree. If you look at the meaning, I think you will too. e.g. = for example and you would _not_ write (for example ...) because it is an introductory phrase that reads with a distinct pause; therefore, the comma is required although it is not visually pleasing. The changes look good to me! -mfm
-- Florian Pritz
doc/PKGBUILD.5.txt | 91 +++++++++++++++++++++++++-------------------------- 1 files changed, 45 insertions(+), 46 deletions(-)
diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index c0fa594..753c4ea 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -16,12 +16,12 @@ PKGBUILD
Description ----------- -This manual page is meant to describe general rules about PKGBUILDs. Once a +This manual page describes general rules about PKGBUILDs. Once a PKGBUILD is written, the actual package is built using makepkg and installed with pacman.
-NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}'. -Also located there are other example files such as a ChangeLog and an install +NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}' +along with other example files such as a ChangeLog and an install script. You can copy the provided PKGBUILD.proto file to a new package build directory and make customizations to suit your needs.
@@ -30,33 +30,33 @@ Options and Directives ---------------------- The following is a list of standard options and directives available for use in a PKGBUILD. These are all understood and interpreted by makepkg, and most -will be directly transferred to the built package. +of them will be directly transferred to the built package.
If you need to create any custom variables for use in your build process, it is -recommended to name your custom variables with an '_' (underscore) prefix. +recommended to prefix their name with an '_' (underscore). This will prevent any possible name clashes with internal makepkg variables. For example, to store the base kernel version in a variable, use something similar to `$_basekernver`.
*pkgname (array)*:: - The name of the package. This has be a unix-friendly name as it will be - used in the package filename. Members of the array are not allowed to start - with hyphens. + Either the name of the package or an array of names for split packages. + Because it will be used in the package filename, this has to be unix-friendly. + Members of the array are not allowed to start with hyphens.
*pkgver*:: - The version of the software as released from the author (e.g. '2.7.1'). + The version of the software as released from the author (e.g., '2.7.1'). The variable is not allowed to contain colons or hyphens.
*pkgrel*:: This is the release number specific to the Arch Linux release. This allows package maintainers to make updates to the package's configure - flags, for example. A pkgrel of '1' is typically used for each upstream - software release and is incremented for intermediate PKGBUILD updates. The + flags, for example. This is typically set to '1' for each new upstream + software release and incremented for intermediate PKGBUILD updates. The variable is not allowed to contain hyphens.
*pkgdesc*:: This should be a brief description of the package and its functionality. - Try to keep the description to one line of text. + Try to keep the description to one line of text and not use the package's name.
*epoch*:: Used to force the package to be seen as newer than any previous versions @@ -69,50 +69,49 @@ similar to `$_basekernver`.
*url*:: This field contains a URL that is associated with the software being - packaged. This is typically the project's website. + packaged. Typically the project's website.
*license (array)*:: This field specifies the license(s) that apply to the package. - Commonly-used licenses are found in '/usr/share/licenses/common'. If you + Commonly used licenses can be found in '/usr/share/licenses/common'. If you see the package's license there, simply reference it in the license - field (e.g. `license=('GPL')`). If the package provides a license not - found in '/usr/share/licenses/common', then you should include the license + field (e.g., `license=('GPL')`). If the package provides a license not + available in '/usr/share/licenses/common', then you should include it in the package itself and set `license=('custom')` or `license=('custom:LicenseName')`. The license should be placed in - '$pkgdir/usr/share/licenses/$pkgname' when building the package. If - multiple licenses are applicable for a package, list all of them: + '$pkgdir/usr/share/licenses/$pkgname/' when building the package. If + multiple licenses are applicable, list all of them: `license=('GPL' 'FDL')`.
*install*:: Specifies a special install script that is to be included in the package. This file should reside in the same directory as the PKGBUILD, and will be copied into the package by makepkg. It does not need to be included - in the source array (e.g. `install=pkgname.install`). + in the source array (e.g., `install=pkgname.install`).
*changelog*:: Specifies a changelog file that is to be included in the package. This file should reside in the same directory as the PKGBUILD, and will be copied into the package by makepkg. It does not need to be included - in the source array (e.g. `changelog=$pkgname.changelog`). + in the source array (e.g., `changelog=$pkgname.changelog`).
*source (array)*:: An array of source files required to build the package. Source files - must either reside in the same directory as the PKGBUILD file, or be a - fully-qualified URL that makepkg will use to download the file. In order - to make the PKGBUILD as useful as possible, use the $pkgname and $pkgver - variables if possible when specifying the download location. Any files - that are compressed will automatically be extracted, unless found in - the noextract array listed below. + must either reside in the same directory as the PKGBUILD, or be a + fully-qualified URL that makepkg can use to download the file. + To make the PKGBUILD as useful as possible, use the `$pkgname` and `$pkgver` + variables if possible when specifying the download location. Compressed files + will be extracted automatically unless found in + the noextract array described below. + -It is also possible to specify an optional filename, which is helpful +It is also possible to change the name of the downloaded file, which is helpful with weird URLs and for handling multiple source files with the same name. The syntax is: `source=('filename::url')`.
*noextract (array)*:: An array of filenames corresponding to those from the source array. Files listed here will not be extracted with the rest of the source files. This - is useful for packages which use compressed data which is downloaded but - not necessary to uncompress. + is useful for packages that use compressed data directly.
*md5sums (array)*:: This array contains an MD5 hash for every source file specified in the @@ -133,18 +132,18 @@ name. The syntax is: `source=('filename::url')`. example, one could install all KDE packages by installing the 'kde' group.
*arch (array)*:: - Defines on which architectures the given package is available (e.g. + Defines on which architectures the given package is available (e.g., `arch=('i686' 'x86_64')`). Packages that contain no architecture specific - files may use arch=('any'). + files should use arch=('any').
*backup (array)*:: - A space-delimited array of filenames, without preceding slashes, that + An array of filenames, without preceding slashes, that should be backed up if the package is removed or upgraded. This is commonly used for packages placing configuration files in /etc. See Handling Config Files in linkman:pacman[8] for more information.
*depends (array)*:: - An array of packages that this package depends on to run. Packages in + An array of packages this package depends on to run. Entries in this list should be surrounded with single quotes and contain at least the package name. Entries can also include a version requirement of the form 'name<>version', where <> is one of five comparisons: >= (greater @@ -152,12 +151,12 @@ name. The syntax is: `source=('filename::url')`. than), or < (less than).
*makedepends (array)*:: - An array of packages that this package depends on to build, but are not + An array of packages this package depends on to build but are not needed at runtime. Packages in this list follow the same format as depends.
*checkdepends (array)*:: - An array of packages that this package depends on to run its test suite, + An array of packages this package depends on to run its test suite but are not needed at runtime. Packages in this list follow the same format as depends. These dependencies are only considered when the check() function is present and is to be run by makepkg. @@ -177,7 +176,7 @@ name. The syntax is: `source=('filename::url')`. same format as depends. Versioned conflicts are also supported.
*provides (array)*:: - An array of ``virtual provisions'' that this package provides. This allows + An array of ``virtual provisions'' this package provides. This allows a package to provide dependencies other than its own package name. For example, the dcron package can provide 'cron', which allows packages to depend on 'cron' rather than 'dcron OR fcron'. @@ -188,7 +187,7 @@ name. The syntax is: `source=('filename::url')`. provided.
*replaces (array)*:: - An array of packages that this package should replace, and can be used + An array of packages this package should replace. This can be used to handle renamed/combined packages. For example, if the 'j2re' package is renamed to 'jre', this directive allows future upgrades to continue as expected even though the package has moved. Sysupgrade is currently @@ -248,7 +247,7 @@ name. The syntax is: `source=('filename::url')`.
build() Function ---------------- -In addition to the above directives, the optional build() bash function usually +In addition to the above directives, the optional build() function usually comprises the remainder of the PKGBUILD. This is directly sourced and executed by makepkg, so anything that bash or the system has available is available for use here. The function is run in `bash -e` mode, meaning any command that exits @@ -256,19 +255,19 @@ with a non-zero status will cause the function to exit. Be sure any exotic commands used are covered by `makedepends`.
All of the above variables such as `pkgname` and `pkgver` are available for use -in the build function. In addition, makepkg defines three variables for your -use during the build and install process. These three variables are as follows: +in the build function. In addition, makepkg defines the following three +variables for use during the build and install process:
*startdir*:: - This contains the absolute path to the directory where the PKGBUILD was + This contains the absolute path to the directory where the PKGBUILD is located, which is usually the output of `$(pwd)` when makepkg is started.
*srcdir*:: - This points to the directory where makepkg extracts or copies all source + This contains the directory where makepkg extracts, or copies, all source files.
*pkgdir*:: - This points to the directory where makepkg bundles the installed package + This contains the directory where makepkg bundles the installed package (this directory will become the root directory of your built package).
If you create any variables of your own in the build function, it is @@ -301,8 +300,8 @@ Each split package uses a corresponding packaging function with name `package_foo()`, where `foo` is the name of the split package.
All options and directives for the split packages default to the global values -given within the PKGBUILD. However, some of these can be overridden within each -split package's packaging function. The following variables can be overridden: +given in the PKGBUILD. Nevertheless, the following ones can be overridden within +each split package's packaging function: `pkgver`, `pkgrel`, `pkgdesc`, `arch`, `license`, `groups`, `depends`, `optdepends`, `provides`, `conflicts`, `replaces`, `backup`, `options`, `install` and `changelog`. @@ -363,7 +362,7 @@ makepkg supports building development versions of packages without having to manually update the pkgver in the PKGBUILD. This was formerly done using the separate utility 'versionpkg'. In order to utilize this functionality, your PKGBUILD must use correct variable names depending on the SCM being fetched -from. +from (e.g., 'makepkg-git', 'mplayer-svn').
*CVS*:: The generated pkgver will be the date the package is built. -- 1.7.5.4
participants (3)
-
Dan McGee
-
Florian Pritz
-
matt mooney