[pacman-dev] [PATCH] doc/PKGBUILD: misc changes
matt mooney
mfm at muteddisk.com
Thu Jun 9 19:58:06 EDT 2011
On 23:20 Thu 09 Jun , Florian Pritz wrote:
> Signed-off-by: Florian Pritz <bluewind at 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
>
More information about the pacman-dev
mailing list