[pacman-dev] [PATCH] makepkg: Document package splitting

[Dan McGee]

On Sun, May 10, 2009 at 10:24 AM, Allan McRae <allan at archlinux.org> wrote:
> Signed-off-by: Allan McRae <allan at 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