[pacman-dev] [PATCH] makepkg: Document package splitting
Signed-off-by: Allan McRae <allan@archlinux.org> --- This is a RFC patch. I would like comments on the documentation I have written. I find it hard to write documentation for features I implemented as I know what I am talking about, even if no-one else does... (I haven't actually checked that the docs still build after these changes.) doc/PKGBUILD.5.txt | 19 +++++++++++++++++++ doc/makepkg.8.txt | 6 +++--- scripts/makepkg.sh.in | 2 +- 3 files changed, 23 insertions(+), 4 deletions(-) diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index e1ea632..e2f19ac 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -264,6 +264,25 @@ combination with the fakeroot BUILDENV option in linkman:makepkg.conf[5], fakero usage will be limited to running the packaging stage. The build() function will be run as the user calling makepkg. +Package Splitting +----------------- +makepkg supports building multiple packages from a single PKGBUILD. This is achieved +by assigning an array of package names to the `pkgname` directive. Each sub-package +uses a corresponding package function with name `package_foo()`, where `foo` is the +name of the 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 sub-package's +package function. The following variables can be overridden: `pkgdesc`, `license`, +`groups`, `depends`, `optdepends`, `provides`, `conflicts`, `replaces`, `backup`, +`options` and `install`. + +An additional directive is available when building a split package: + +*pkgbase*:: + The name used to refer to the group of packages in the output of makepkg. + Also, used when creating source-only tarballs. + Install/Upgrade/Remove Scripting -------------------------------- Pacman has the ability to store and execute a package-specific script when it diff --git a/doc/makepkg.8.txt b/doc/makepkg.8.txt index fb2e805..e480d8e 100644 --- a/doc/makepkg.8.txt +++ b/doc/makepkg.8.txt @@ -122,9 +122,9 @@ Options during dependency auto-resolution and installation when using `-s`. *-R, \--repackage*:: - Repackage contents of pkg/ without rebuilding the package. This is - useful if you forgot a depend or install file in your PKGBUILD and the - build itself will not change. + Repackage contents of the package without rebuilding the package. This + is useful if you forgot a depend or install file in your PKGBUILD and + the build itself will not change. *-s, \--syncdeps*:: Install missing dependencies using pacman. When build-time or run-time diff --git a/scripts/makepkg.sh.in b/scripts/makepkg.sh.in index ebc19bc..fefcc73 100644 --- a/scripts/makepkg.sh.in +++ b/scripts/makepkg.sh.in @@ -1308,7 +1308,7 @@ usage() { printf "$(gettext " -p <buildscript> Use an alternate build script (instead of '%s')")\n" "$BUILDSCRIPT" echo "$(gettext " -r, --rmdeps Remove installed dependencies after a successful build")" # fix flyspray feature request #2978 - echo "$(gettext " -R, --repackage Repackage contents of pkg/ without building")" + echo "$(gettext " -R, --repackage Repackage contents of the package without rebuilding")" echo "$(gettext " -s, --syncdeps Install missing dependencies with pacman")" echo "$(gettext " --allsource Generate a source-only tarball including downloaded sources")" echo "$(gettext " --asroot Allow makepkg to run as root user")" -- 1.6.3
Am Sonntag, 10. Mai 2009 17:24:33 schrieb Allan McRae: Sounds fine to me. Except the following:
+An additional directive is available when building a split package: + +*pkgbase*:: + The name used to refer to the group of packages in the output of makepkg. + Also, used when creating source-only tarballs.
Is this pkgbase variable optional? Does it effect anything else than makepkg output or the filename of the source package? -- Pierre Schmitz Clemens-August-Straße 76 53115 Bonn Telefon 0228 9716608 Mobil 0160 95269831 Jabber pierre@jabber.archlinux.de WWW http://www.archlinux.de
Pierre Schmitz wrote:
Am Sonntag, 10. Mai 2009 17:24:33 schrieb Allan McRae:
Sounds fine to me. Except the following:
+An additional directive is available when building a split package: + +*pkgbase*:: + The name used to refer to the group of packages in the output of makepkg. + Also, used when creating source-only tarballs.
Is this pkgbase variable optional? Does it effect anything else than makepkg output or the filename of the source package?
It is entirely optional and is only for cosmetic purposes as makepkg defaults to ${pkgname[0]} when it is not specified. I will clarify this. Allan
Allan McRae wrote:
Signed-off-by: Allan McRae <allan@archlinux.org> ---
This is a RFC patch. I would like comments on the documentation I have written. I find it hard to write documentation for features I implemented as I know what I am talking about, even if no-one else does...
(I haven't actually checked that the docs still build after these changes.)
doc/PKGBUILD.5.txt | 19 +++++++++++++++++++ doc/makepkg.8.txt | 6 +++--- scripts/makepkg.sh.in | 2 +- 3 files changed, 23 insertions(+), 4 deletions(-)
diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index e1ea632..e2f19ac 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -264,6 +264,25 @@ combination with the fakeroot BUILDENV option in linkman:makepkg.conf[5], fakero usage will be limited to running the packaging stage. The build() function will be run as the user calling makepkg.
+Package Splitting +----------------- +makepkg supports building multiple packages from a single PKGBUILD. This is achieved +by assigning an array of package names to the `pkgname` directive. Each sub-package +uses a corresponding package function with name `package_foo()`, where `foo` is the +name of the 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 sub-package's +package function. The following variables can be overridden: `pkgdesc`, `license`, +`groups`, `depends`, `optdepends`, `provides`, `conflicts`, `replaces`, `backup`, +`options` and `install`. + +An additional directive is available when building a split package: + +*pkgbase*:: + The name used to refer to the group of packages in the output of makepkg. + Also, used when creating source-only tarballs.
Changed to: +*pkgbase*:: + The name used to refer to the group of packages in the output of makepkg + and in the naming of source-only tarballs. If not specified, the first + element in the `pkgname` array is used.
+ Install/Upgrade/Remove Scripting -------------------------------- Pacman has the ability to store and execute a package-specific script when it diff --git a/doc/makepkg.8.txt b/doc/makepkg.8.txt index fb2e805..e480d8e 100644 --- a/doc/makepkg.8.txt +++ b/doc/makepkg.8.txt @@ -122,9 +122,9 @@ Options during dependency auto-resolution and installation when using `-s`.
*-R, \--repackage*:: - Repackage contents of pkg/ without rebuilding the package. This is - useful if you forgot a depend or install file in your PKGBUILD and the - build itself will not change. + Repackage contents of the package without rebuilding the package. This + is useful if you forgot a depend or install file in your PKGBUILD and + the build itself will not change.
*-s, \--syncdeps*:: Install missing dependencies using pacman. When build-time or run-time diff --git a/scripts/makepkg.sh.in b/scripts/makepkg.sh.in index ebc19bc..fefcc73 100644 --- a/scripts/makepkg.sh.in +++ b/scripts/makepkg.sh.in @@ -1308,7 +1308,7 @@ usage() { printf "$(gettext " -p <buildscript> Use an alternate build script (instead of '%s')")\n" "$BUILDSCRIPT" echo "$(gettext " -r, --rmdeps Remove installed dependencies after a successful build")" # fix flyspray feature request #2978 - echo "$(gettext " -R, --repackage Repackage contents of pkg/ without building")" + echo "$(gettext " -R, --repackage Repackage contents of the package without rebuilding")" echo "$(gettext " -s, --syncdeps Install missing dependencies with pacman")" echo "$(gettext " --allsource Generate a source-only tarball including downloaded sources")" echo "$(gettext " --asroot Allow makepkg to run as root user")"
Any further comments? Allan
On Sun, May 10, 2009 at 10:24 AM, Allan McRae <allan@archlinux.org> wrote:
Signed-off-by: Allan McRae <allan@archlinux.org> ---
This is a RFC patch. I would like comments on the documentation I have written. I find it hard to write documentation for features I implemented as I know what I am talking about, even if no-one else does...
(I haven't actually checked that the docs still build after these changes.)
doc/PKGBUILD.5.txt | 19 +++++++++++++++++++ doc/makepkg.8.txt | 6 +++--- scripts/makepkg.sh.in | 2 +- 3 files changed, 23 insertions(+), 4 deletions(-)
diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index e1ea632..e2f19ac 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -264,6 +264,25 @@ combination with the fakeroot BUILDENV option in linkman:makepkg.conf[5], fakero usage will be limited to running the packaging stage. The build() function will be run as the user calling makepkg.
+Package Splitting +----------------- +makepkg supports building multiple packages from a single PKGBUILD. This is achieved +by assigning an array of package names to the `pkgname` directive. Each sub-package +uses a corresponding package function with name `package_foo()`, where `foo` is the +name of the package. "name of the sub-package."
You realize the importance of choosing the "sub-package" terminology correctly, right? We're stuck with it once we start calling it that, but I think it is fine. :)
+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 sub-package's +package function. The following variables can be overridden: `pkgdesc`, `license`, Maybe "packaging function", so we don't abuse the poor package word? This would be done above as well.
+`groups`, `depends`, `optdepends`, `provides`, `conflicts`, `replaces`, `backup`, +`options` and `install`. + +An additional directive is available when building a split package: We've now strayed from "sub-package" to "split package". Minor nagging I know, but I think picking one name is probably in our best interest.
+ +*pkgbase*:: + The name used to refer to the group of packages in the output of makepkg. + Also, used when creating source-only tarballs. "This is also used when..."
And does this go in the sub-package packaging function, or out above? It isn't clear looking here.
+ Install/Upgrade/Remove Scripting -------------------------------- Pacman has the ability to store and execute a package-specific script when it diff --git a/doc/makepkg.8.txt b/doc/makepkg.8.txt index fb2e805..e480d8e 100644 --- a/doc/makepkg.8.txt +++ b/doc/makepkg.8.txt @@ -122,9 +122,9 @@ Options during dependency auto-resolution and installation when using `-s`.
*-R, \--repackage*:: - Repackage contents of pkg/ without rebuilding the package. This is - useful if you forgot a depend or install file in your PKGBUILD and the - build itself will not change. + Repackage contents of the package without rebuilding the package. This + is useful if you forgot a depend or install file in your PKGBUILD and + the build itself will not change.
This is good. Mind updating the description of *pkgdir*:: further on in the manpage, possibly dropping the alias business since I'm pretty sure with splitpkg we blow that concept away? $startdir doc may even want a small touchup too; up to you.
*-s, \--syncdeps*:: Install missing dependencies using pacman. When build-time or run-time diff --git a/scripts/makepkg.sh.in b/scripts/makepkg.sh.in index ebc19bc..fefcc73 100644 --- a/scripts/makepkg.sh.in +++ b/scripts/makepkg.sh.in @@ -1308,7 +1308,7 @@ usage() { printf "$(gettext " -p <buildscript> Use an alternate build script (instead of '%s')")\n" "$BUILDSCRIPT" echo "$(gettext " -r, --rmdeps Remove installed dependencies after a successful build")" # fix flyspray feature request #2978 - echo "$(gettext " -R, --repackage Repackage contents of pkg/ without building")" + echo "$(gettext " -R, --repackage Repackage contents of the package without rebuilding")" echo "$(gettext " -s, --syncdeps Install missing dependencies with pacman")" echo "$(gettext " --allsource Generate a source-only tarball including downloaded sources")" echo "$(gettext " --asroot Allow makepkg to run as root user")" -- 1.6.3
Thanks for doing the most fun part of coding, the docs! Now if I can just convince someone to fluff out that damn NEWS file for the next release... -Dan
participants (3)
-
Allan McRae
-
Dan McGee
-
Pierre Schmitz