Add initial manpage drafts

3 files changed, 719 insertions, 1 deletions

diff --git a/APKBUILD.5 b/APKBUILD.5
new file mode 100644
index 0000000..4392cd1
--- /dev/null
+++ b/APKBUILD.5
@@ -0,0 +1,488 @@
+.Dd February 13, 2018
+.Dt APKBUILD 5 PRM
+.Os "Alpine Linux"
+
+
+.Sh NAME
+.Nm APKBUILD
+.Nd metadata and instructions to build a package
+
+
+.Sh SYNOPSIS
+.Nm /usr/src/packages/<repo>/<package>/APKBUILD
+
+
+.Sh DESCRIPTION
+An
+.Nm
+file is used by tools such as
+.Xr abuild 1
+to build a package for eventual installation by the
+.Xr apk 8
+package manager.  It defines metadata such as the name of the package, the
+version information, the source license, and contact information for the
+developer.  It additionally contains the commands needed to build, test, and
+install the package.
+.Pp
+The
+.Nm
+format is similar to a typical shell script; you set pre-defined variables and
+implement pre-defined functions, and the
+.Xr abuild 1
+(or similar) utility will use them to create the package.
+
+
+.Ss Required Variables
+The following variables must be set in all
+.Nm
+files:
+
+.Bl -tag -width Ds
+.It Cm pkgname
+Specifies name of the package.  This is typically the name of the package
+upstream; however, note that all letters must be lowercased.
+.Pp
+Libraries for scripting languages should have a prefix before the library name
+describing the language.  Such prefixes include
+.Em lua- ,
+.Em perl- ,
+.Em py- ,
+and
+.Em rb- .
+Not all languages use prefixes.  For a definitive list, consult the PREFIXES
+file in the root directory of the repository you are using for packaging.
+
+.It Cm pkgver
+Specifies the version of the software being packaged.  The version specified
+must match the pattern
+.Li digit[.digit]*[_suffix[digit]]*
+where
+.Ar digit
+must be a number greater than or equal to zero,
+and
+.Ar suffix
+must be one of
+.Em alpha ,
+.Em beta ,
+.Em pre ,
+.Em rc ,
+.Em cvs ,
+.Em svn ,
+.Em git ,
+.Em hg ,
+or
+.Em p .
+
+.It Cm pkgrel
+Specifies the package release number of this particular package version.  This
+indicates when a package has changed without a corresponding change in version.
+Always increment
+.Cm pkgrel
+when you change the contents or dependencies of a package.  The first release
+of a package is always
+.Li 0 .
+
+.It Cm pkgdesc
+Specifies what the package contains.
+.Cm pkgdesc
+must be 128 characters or less, and should concisely describe what actions the
+software or items being packaged will allow the user to perform.  For example,
+.Li Dq Fully-featured word processor with spell check and many plugins
+would be a sufficient
+.Cm pkgdesc
+for AbiWord.
+
+.It Cm url
+Specifies the Web address of the package's upstream.  This allows users and
+future maintainers to find documentation, release information, and contact
+information for the package.  If no Web address is available for the package,
+you must set
+.Cm url
+to an empty string ("").
+
+.It Cm license
+Specifies the license under which the package is distributed.  The value
+provided must match a SPDX license identifier.
+
+.It Cm source
+Specifies the location of both local and remote source files used to build the
+package.  Typically, the remote source file(s) or archive(s) is specified,
+followed by any local patches, install scripts, configuration files, or other
+necessary files.
+.El
+
+
+.Ss Optional Variables
+The following variables are not required, but may be set in any
+.Nm
+file:
+
+.Bl -tag -width Ds
+.It Cm arch
+Specifies the architectures for which the package may be built.  It is highly
+recommended that you set this variable to "all" if the package is portable.
+
+You may use "noarch" if the package does not contain any architecture-specific
+binary files - that is, any files that are compiled for the target only.  Such
+packages may include pure Python packages, shell script packages, and JARs.  If
+you are not sure what this means, using "all" is safe.
+
+.It Cm depends
+Specifies the run-time dependencies of the package.  The
+.Xr abuild 1
+utility will automatically scan the resultant package for shared library (.so)
+dependencies; do not specify them here.
+
+.It Cm install
+Specifies install scripts for the package, if any.  See
+.Sx Install Scripts
+for more information about install scripts.
+
+.It Cm install_if
+Specifies a condition when
+.Xr apk 8
+should automatically install the package (or subpackage).  For instance, the
+OpenRC subpackages set
+.Cm install_if
+to
+.Li Dq $pkgname=$pkgver openrc
+which means that the OpenRC subpackage will be automatically installed if the
+origin package and OpenRC are both installed on the same computer.
+
+.It Cm makedepends
+Specifies build dependencies for the package.
+
+.It Cm pkggroups
+Specifies a space-separated list of login groups to create during build-time.
+Note that you will need to create the login groups in a pre-install install
+script as well; see
+.Sx Install Scripts
+for more information about install scripts.
+
+.It Cm pkgusers
+Specifies a space-separated list of user logins to create during build-time.
+Note that you will ned to create the user logins in a pre-install install
+script as well; see
+.Sx Install Scripts
+for more information about install scripts.
+
+.It Cm provides
+Specifies that the package "provides" the same contents as another package.
+This is typically used for virtual dependencies.
+
+.It Cm provider_priority
+Specifies the numeric value for
+.Xr apk 8
+to use for the package when considering which provider should be installed for
+the same
+.Cm provides
+virtual provider.
+
+.It Cm replaces
+Specifies packages that the package replaces.  This is typically used for
+packages renamed by upstream.
+
+.It Cm triggers
+Specifies a trigger script used by the package.  A trigger script is a shell
+script that is called whenever monitored files or directories are modified.
+You may specify the paths to monitor using the triggers variable as follows:
+
+.Li Dq $pkgname.trigger=/usr/share/man:/usr/local/share/man
+
+This will run the package trigger script whenever files in
+.Pa /usr/share/man
+or
+.Pa /usr/local/share/man
+are created, modified, or removed.
+
+.El
+
+
+.Ss options
+The
+.Cm options
+variable allows you to set parameters for the package at build time.  There are
+a number of valid options you may set, and you may set multiple options by
+inserting a space between each one.
+
+.Bl -tag -width Ds
+.It Cm !archcheck
+Specifies that the package contains binaries that cannot run on the target
+architecture.  This is primarily used for packages containing firmware, and
+should typically never need to be used.
+
+.It Cm charset.alias
+Specifies that the package ships a /usr/lib/charset.alias file and that it
+should be installed on the user's system.  This is almost never the case.  Do
+not use this option.
+
+.It Cm !check
+Specifies that the package will not run a test suite.  The reason for disabling
+the check phase should be noted in a comment.
+
+.It Cm !checkroot
+Specifies that the package's test suite will be run as a non-privileged user
+instead of using
+.Xr fakeroot 8 .
+This is necessary for some test suites which fail when run as root.
+
+.It Cm !dbg
+(Adélie-specific) Specifies that the package should not be built with a debug
+information package.  This is typically used on packages that do not generate
+debug information (such as pure Python packages) or packages that do not
+support debug information packages (such as LLVM).
+
+.It Cm !fhs
+Specifies that the package violates FHS and installs to a location such as
+.Pa /usr/local ,
+.Pa /opt ,
+or
+.Pa /srv .
+
+.It Cm ldpath-recursive
+Specifies that
+.Xr abuild 1
+should use the
+.Fl --recursive
+argument to
+.Xr scanelf 1
+when attempting to find shared library (.so) dependencies for the package.
+
+.It Cm !libc_eglibc
+Specifies that the package cannot be built on the eglibc libc.
+
+.It Cm !libc_musl
+Specifies that the package cannot be built on the musl libc.
+
+.It Cm !libc_uclibc
+Specifies that the package cannot be built on the uclibc libc.
+
+.It Cm libtool
+Specifies that the package requires its libtool (.la) files.  They will not be
+automatically removed by
+.Xr abuild 1 .
+
+.It Cm net
+Specifies that the package build system requires access to a network.  This is
+discouraged and an issue should be filed with the package's authors.
+
+.It Cm !strip
+Specifies that
+.Xr strip 1
+should not be run on any of the package's binaries.  This is automatically
+implied if the -dbg subpackage is enabled, or if you are using
+.Ev DEFAULT_DBG .
+
+.It Cm suid
+Specifies that binaries in the package may be installed set-uid.  This is a
+security risk and it is highly recommended to use capabilities or process
+separation instead of set-uid where available.
+
+.It Cm textrels
+Specifies that the package's binaries 
+
+.It Cm toolchain
+Specifies that the package is part of the base toolchain set and may depend
+on packages like
+.Li g++ .
+
+.It Cm !tracedeps
+Specifies that
+.Xr abuild 1
+should not automatically populate
+.Cm depends
+with shared library (.so) or symlink target dependencies.
+
+.El
+
+
+.Ss Special Variables
+The following variables are used only in special circumstances, and may be
+required or optional depending on their usage and the contents of other
+variables.
+
+.Bl -tag -width Ds
+.It Cm depends_dev
+Specifies the run-time dependencies of the -dev subpackage.
+
+.It Cm giturl
+Specifies the URL of the Git repository to use with
+.Cm abuild checkout .
+If the default branch of the repository is not desired, a different one may be
+specified by appending
+.Fl b Ar branch
+where
+.Cm branch
+is the branch to checkout.
+.El
+
+
+.Ss Functions
+Functions specified here may be present in any
+.Nm
+file, but with the exception of
+.Li build and
+.Li package ,
+are not strictly required.
+
+.Bl -tag -width Ds
+.It Cm fetch
+This function is called to download the remote files in
+.Cm source .
+
+.It Cm unpack
+This function unpacks any archives in
+.Cm source
+to
+.Ev srcdir .
+
+.It Cm prepare
+Prepares the source in
+.Ev srcdir
+to be built.  The default
+.Cm prepare
+function ensures the build directories are set up correctly and applies any
+*.patch files specified in
+.Cm source .
+You must call
+.Cm default_prepare
+if you write a custom
+.Cm prepare
+function.
+
+.It Cm build
+Compiles the source in
+.Ev builddir .
+You must implement this function yourself.  If no compilation is required, you
+may simply write
+.Li return 0
+to skip the build phase.
+
+.It Cm check
+Runs the package's test suite.  This function must be implemented unless
+.Li Dq !check
+was specified in
+.Cm options .
+
+.It Cm package
+Installs the package into
+.Ev pkgdir .
+Note that
+.Ev pkgdir
+is not created for you; if this package installs no files (for example, a
+metapackage), you must use
+.Li mkdir -p "$pkgdir"
+to skip the package phase.
+
+.El
+
+
+.Ss Install Scripts
+An install script is run when an action is taken on a package by
+.Xr apk 8 .
+An install script must be written in shell and must have a
+.Li Dq #!/bin/sh
+interpreter declaration as the first line.  The
+.Cm install
+variable must contain the install scripts needed by the package.  The different
+actions available are as follows:
+
+.Bl -tag -width Ds
+.It Ic $pkgname.pre-install
+Executed before the package is installed.  If this script exits with an error
+(non-zero exit code),
+.Xr apk 8
+will halt the installation and the package will not be installed.  This install
+script is typically used to create any users or groups needed as described in
+.Cm pkggroups
+and
+.Cm pkgusers .
+
+.It Ic $pkgname.post-install
+Executed after the package is installed.  If this script exits with an error
+(non-zero exit code),
+.Xr apk 8
+will mark the package as broken.  The
+.Li apk fix
+command will attempt to re-run the post-install script if this occurs.
+
+.It Ic $pkgname.pre-upgrade
+Executed before the package is upgraded.  If this script exits with an error
+(non-zero exit code),
+.Xr apk 8
+will mark the package as broken.
+
+.It Ic $pkgname.post-upgrade
+Executed after the package is upgraded.  If this script exits with an error
+(non-zero exit code),
+.Xr apk 8
+will mark the package as broken.  The
+.Li apk fix
+command will attempt to re-run the post-upgrade script if this occurs.
+
+.It Ic $pkgname.pre-deinstall
+Executed before the package is removed from the system.  If this script exits
+with an error (non-zero exit code),
+.Xr apk 8
+will not remove the package from the system.
+
+.It Ic $pkgname.post-deinstall
+Executed after the package is removed from the system.  Exiting with an error
+will have no effect.
+
+.El
+
+
+.Sh IMPLEMENTATION NOTES
+Currently,
+.Nm
+files are sourced as normal shell scripts.  This may change at a later date.
+The
+.Xr abuild 1
+utility as distributed by Alpine uses the ash shell, a part of
+.Xr busybox 1
+that is currently undocumented.  It is mostly compliant with
+.St -p1003.2 ,
+but this cannot be fully relied upon.  The
+.Xr abuild 1
+utility as distributed by Adélie uses whatever the user has set as /bin/sh,
+which is typically
+.Xr bash 1
+or
+.Xr dash 1
+on Adélie systems.
+This is something to keep in mind as you write more complex packages.
+
+
+.Sh COMPATIBILITY
+It is highly recommended that package functions comply with
+.St -p1003.2
+for maximum compatibility.
+
+
+.Sh SEE ALSO
+
+The SPDX License List (Web copy at <https://spdx.org/licenses/>),
+.Xr abuild 1 ,
+.Xr newapkbuild 1 ,
+.Xr apk 8 .
+
+
+.Sh HISTORY
+The
+.Nm
+format and
+.Xr abuild 1
+utility first appeared in Alpine Linux 1.9.
+
+
+.Sh AUTHORS
+.An Timo Teräs Aq Mt timo.teras@iki.fi
+.An Natanael Copa Aq Mt ncopa@alpinelinux.org
+
+Documentation:
+.An A. Wilcox Aq Mt awilfox@adelielinux.org
+
+
+.\" .Sh BUGS
+.\" if we end up finding bugs that should be documented, put them here.
diff --git a/Makefile b/Makefile
index 788ad9f..cf023c6 100644
--- a/Makefile
+++ b/Makefile
@@ -6,11 +6,14 @@ prefix		?= /usr
 bindir		?= $(prefix)/bin
 sysconfdir	?= /etc
 datadir		?= $(prefix)/share/$(PACKAGE)
+mandir		?= $(prefix)/share/man
 
 SCRIPTS		:= abuild abuild-keygen abuild-sign newapkbuild \
 		   abump apkgrel buildlab apkbuild-cpan checkapk \
 		   apkbuild-gem-resolver
 USR_BIN_FILES	:= $(SCRIPTS) abuild-tar abuild-gzsplit abuild-sudo abuild-fetch abuild-rmtemp
+MAN_1_PAGES	:= newapkbuild.1
+MAN_5_PAGES	:= APKBUILD.5
 SAMPLES		:= sample.APKBUILD sample.initd sample.confd \
 		sample.pre-install sample.post-install
 AUTOTOOLS_TOOLCHAIN_FILES := config.sub config.guess
@@ -91,7 +94,8 @@ help:
 
 install: $(USR_BIN_FILES) $(SAMPLES) abuild.conf functions.sh
 	install -d $(DESTDIR)/$(bindir) $(DESTDIR)/$(sysconfdir) \
-		$(DESTDIR)/$(datadir)
+		$(DESTDIR)/$(datadir) $(DESTDIR)/$(mandir)/man1 \
+		$(DESTDIR)/$(mandir)/man5
 	for i in $(USR_BIN_FILES); do\
 		install -m 755 $$i $(DESTDIR)/$(bindir)/$$i;\
 	done
@@ -99,6 +103,12 @@ install: $(USR_BIN_FILES) $(SAMPLES) abuild.conf functions.sh
 	for i in adduser addgroup apk; do \
 		ln -fs abuild-sudo $(DESTDIR)/$(bindir)/abuild-$$i; \
 	done
+	for i in $(MAN_1_PAGES); do\
+		install -m 644 $$i $(DESTDIR)/$(mandir)/man1/$$i;\
+	done
+	for i in $(MAN_5_PAGES); do\
+		install -m 644 $$i $(DESTDIR)/$(mandir)/man5/$$i;\
+	done
 	if [ -n "$(DESTDIR)" ] || [ ! -f "/$(sysconfdir)"/abuild.conf ]; then\
 		cp abuild.conf $(DESTDIR)/$(sysconfdir)/; \
 	fi
diff --git a/newapkbuild.1 b/newapkbuild.1
new file mode 100644
index 0000000..93471b9
--- /dev/null
+++ b/newapkbuild.1
@@ -0,0 +1,220 @@
+.Dd November 4, 2017
+.Dt NEWAPKBUILD 1 PRM
+.Os "Alpine Linux"
+
+
+.Sh NAME
+.Nm newapkbuild
+.Nd generate a new APKBUILD
+
+
+.Sh SYNOPSIS
+.Nm
+.Op Fl n Ar NAME
+.Op Fl d Ar DESC
+.Op Fl l Ar LICENSE
+.Op Fl u Ar URL
+.Op Fl aCmpy
+.Op Fl cfhs
+.Op Ar pkgname Op Ar -pkgver
+
+.Nm
+.Op Fl n Ar NAME
+.Op Fl d Ar DESC
+.Op Fl l Ar LICENSE
+.Op Fl u Ar URL
+.Op Fl aCmpy
+.Op Fl cfhs
+.Op Ar source_url
+
+
+.Sh DESCRIPTION
+.Nm
+generates a new APKBUILD for use with
+.Xr abuild 1 .
+
+.Bl -tag -width "pkgname-pkgver" -offset indent -compact
+
+.It Fl n Ar NAME
+Specifies the name of the new package.  A new directory called
+.Ar NAME
+will be created in the current directory, with the APKBUILD file.
+
+.It Fl d Ar DESC
+Specifies the description (pkgdesc=) for the new package.
+
+.It Fl l Ar LICENSE
+Specifies the license under which the new package is distributed.  This should
+match an SPDX Identifier.
+
+.It Fl u Ar URL
+Specifies the Web page (url=) for the new package.  This should
+.Em not
+be the source package URL; it should be the project's main Web page.
+
+.It Fl c
+Causes
+.Nm
+to additionally copy an init.d script, conf.d file, and sample pre- and post-
+install scripts to the APKBUILD directory.  This allows you to have a quick
+start for daemon packages.
+
+.It Fl f
+Forces
+.Nm
+to overwrite an existing APKBUILD, if one already exists in the package
+directory.
+
+.It Fl h
+Displays usage information.
+
+.It Fl s
+Create an automatic SourceForge URL for the package based on its name and
+version.  This is only valid if
+.Ar pkgname-pkgver
+is specified on the command line.
+
+.It Ar pkgname-pkgver
+Specify the package name, if not already specified by
+.Fl n .
+If followed by a dash (-) and a valid version string, additionally specify the
+package's version.
+
+.El
+
+
+.Ss Build system type
+
+.Nm
+will try to automatically detect the build system by inspecting the source
+directory if
+.Ar source_url
+is specified, and write out typical build instructions for that build system.
+If you do not specify the source URL, or you want to override auto-detection,
+you may specify one of the following four flags:
+
+.Bl -tag -width "-a" -offset indent -compact
+
+.It Fl a
+Specifies that the package uses autotools.  The APKBUILD will contain a typical
+invocation of ./configure, make, and make install.
+
+.It Fl C
+Specifies that the package uses CMake.  CMake will be added to the makedepends
+and a typical CMake invocation will be added to the APKBUILD.
+
+.It Fl m
+Specifies that the package uses Meson.  A typical Meson and Ninja invocation
+will be added to the APKBUILD.
+
+.It Fl p
+Specifies that the package uses a Perl Makefile.PL file.  The CPAN template
+will be used.
+
+.It Fl y
+Specifies that the package uses a Python setup.py build system.  Python will be
+added to the makedepends.
+
+.El
+
+If you do not specify any option, and you do not specify the source URL, the
+generated APKBUILD file will not contain any build instructions.
+
+
+.Sh FILES
+
+All files generated will be placed in a
+.Pa pkgname
+directory inside the current working directory, with
+.Pa pkgname
+being created if it does not exist.
+
+.Bl -tag -width "pkgname.post-install" -compact
+
+.It Pa APKBUILD
+.Nm
+will create
+.Pa APKBUILD
+with the details gathered from the invocation of
+.Nm ,
+and introspection of the downloaded package source if
+.Ar source_url
+is provided.
+
+For more information about APKBUILD and its format, see
+.Xr APKBUILD 5 .
+
+.It Pa pkgname.initd
+If
+.Fl c
+is given,
+.Nm
+will create
+.Pa pkgname.initd
+with example data to assist in the creation of an init.d script for a daemon.
+
+.It Pa pkgname.confd
+If
+.Fl c
+is given,
+.Nm
+will create
+.Pa pkgname.confd
+to assist in the creation of a conf.d file for a daemon, used by init.d
+scripts.  conf.d files are used to configure init.d scripts; for more
+information, see
+.Xr openrc 8
+and
+.Xr rc_config 3 .
+
+.It Pa pkgname.pre-install
+If
+.Fl c
+is given,
+.Nm
+will create
+.Pa pkgname.pre-install ,
+the contents of which will be run by
+.Xr apk 8
+before the package is installed.
+
+.It Pa pkgname.post-install
+If
+.Fl c
+is given,
+.Nm
+will create
+.Pa pkgname.post-install ,
+the contents of which will be run by
+.Xr apk 8
+after the package is successfully installed.
+
+For more information about apk install hooks, consult the
+.Xr apk 8
+manual.
+
+.El
+
+
+.Sh EXAMPLES
+
+newapkbuild -n sharutils -d "Utilities for manipulating shell archives" \\
+            -l "GPL-3.0+" -u "https://www.gnu.org/software/sharutils/" -a \\
+            https://ftp.gnu.org/gnu/sharutils/sharutils-4.15.2.tar.xz
+
+
+.Sh SEE ALSO
+
+SPDX license reference (on the Web at <https://spdx.org/licenses/>),
+.Xr abuild 1 ,
+.Xr apk 8 ,
+.Xr APKBUILD 5 .
+
+
+.Sh AUTHORS
+
+.Nm :
+.An Natanael Copa Aq ncopa@alpinelinux.org
+
+Documentation:
+.An A. Wilcox Aq awilfox@adelielinux.org