Send patches - preferably formatted by git format-patch - to patches at archlinux32 dot org.
summaryrefslogtreecommitdiff
path: root/doc/makepkg.8.asciidoc
diff options
context:
space:
mode:
authorEli Schwartz <eschwartz@archlinux.org>2018-05-03 00:10:21 -0400
committerAllan McRae <allan@archlinux.org>2018-05-14 09:59:17 +1000
commit076b6184de2b20e9b26225d93f6f3a7030504109 (patch)
treeca0e375b9fd89d6b6ce40026b732985c4b335841 /doc/makepkg.8.asciidoc
parent860e4c4943ad062bd0eff99f28e7d64804b3c08e (diff)
Ensure better text editor automatic filetype detection
Since we no longer use vim-specific modelines, use the .asciidoc file extension which is, well, reserved for asciidoc formatted files. This should presumably work everywhere without needing editor-specific workarounds and configuration. Also add a shebang to makepkg.conf to indicate it contains bash content. Signed-off-by: Eli Schwartz <eschwartz@archlinux.org> Signed-off-by: Allan McRae <allan@archlinux.org>
Diffstat (limited to 'doc/makepkg.8.asciidoc')
-rw-r--r--doc/makepkg.8.asciidoc349
1 files changed, 349 insertions, 0 deletions
diff --git a/doc/makepkg.8.asciidoc b/doc/makepkg.8.asciidoc
new file mode 100644
index 00000000..b15e3a67
--- /dev/null
+++ b/doc/makepkg.8.asciidoc
@@ -0,0 +1,349 @@
+makepkg(8)
+==========
+
+Name
+----
+makepkg - package build utility
+
+
+Synopsis
+--------
+'makepkg' [options] [ENVVAR=value] [ENVVAR+=value] ...
+
+
+Description
+-----------
+'makepkg' is a script to automate the building of packages. The requirements for
+using the script are a build-capable *nix platform and a custom build script
+for each package you wish to build (known as a PKGBUILD). See
+linkman:PKGBUILD[5] for details on creating your own build scripts.
+
+The advantage to a script-based build is that the work is only done once. Once
+you have the build script for a package, 'makepkg' will do the rest: download and
+validate source files, check dependencies, configure the build-time settings,
+build the package, install the package into a temporary root, make
+customizations, generate meta-info, and package the whole thing up for pacman
+to use.
+
+NOTE: 'makepkg' uses your current locale by default and does not unset it when
+building packages. If you wish to share your build output with others when
+seeking help or for other purposes, you may wish to run "`LC_ALL=C makepkg`" so
+your logs and output are not localized.
+
+
+Options
+-------
+*-A, \--ignorearch*::
+ Ignore a missing or incomplete arch field in the build script. This is
+ for rebuilding packages from source when the PKGBUILD may be slightly
+ outdated and not updated with an `arch=('yourarch')` field.
+
+*-c, \--clean*::
+ Clean up leftover work files and directories after a successful build.
+
+*\--config* <file>::
+ Use an alternate configuration file instead of the +{sysconfdir}/makepkg.conf+
+ default.
+
+*-d, \--nodeps*::
+ Do not perform any dependency checks. This will let you override and
+ ignore any dependencies required. There is a good chance this option
+ will break the build process if all of the dependencies are not
+ installed.
+
+*-e, \--noextract*::
+ Do not extract source files or run the prepare() function (if present);
+ use whatever source already exists in the $srcdir/ directory. This is
+ handy if you want to go into $srcdir/ and manually patch or tweak code,
+ then make a package out of the result. Keep in mind that creating a
+ patch may be a better solution to allow others to use your PKGBUILD.
+
+*\--verifysource*::
+ For each source file in the source array of PKGBUILD, download the file
+ if required and perform the integrity checks. No extraction or build is
+ performed. Dependencies specified in the PKGBUILD will not be handled
+ unless `--syncdeps` is used. Useful for performing subsequent offline
+ builds.
+
+*-f, \--force*::
+ makepkg will not build a package if a built package already exists in
+ the `PKGDEST` (set in linkman:makepkg.conf[5]) directory, which may
+ default to the current directory. This allows the built package to be
+ overwritten.
+
+*-g, \--geninteg*::
+ For each source file in the source array of PKGBUILD, download the file
+ if required and generate integrity checks. The integrity checks generated
+ are determined by the checks present in the PKGBUILD, falling back to the
+ value of the INTEGRITY_CHECK array in makepkg.conf(5) if these are absent
+ This output can be redirected into your PKGBUILD for source validation
+ using "`makepkg -g >> PKGBUILD`".
+
+*--skipinteg*::
+ Do not perform any integrity checks (checksum and PGP) on source files.
+
+*\--skipchecksums*::
+ Do not verify checksums of source files.
+
+*\--skippgpcheck*::
+ Do not verify PGP signatures of source files.
+
+*-h, \--help*::
+ Output syntax and command line options.
+
+*--holdver*::
+ When using VCS sources (linkman:PKGBUILD[5]) any currently checked out source
+ will not be updated to the latest revision.
+
+*-i, \--install*::
+ Install or upgrade the package after a successful build using
+ linkman:pacman[8].
+
+*-L, \--log*::
+ Enable logging. This will use the *tee* program to send the output of each
+ of the PKGBUILD functions to both the console and to a text file in the
+ build directory named `pkgbase-pkgver-pkgrel-arch-<function>.log`.
+ As mentioned above, the logs will be localized so you may want to set your
+ locale accordingly if sharing the log output with others.
+
+*-m, \--nocolor*::
+ Disable color in output messages.
+
+*-o, \--nobuild*::
+ Download and extract files, run the prepare() function, but do not build
+ them. Useful with the '\--noextract' option if you wish to tweak the files
+ in $srcdir/ before building.
+
+*-p* <buildscript>::
+ Read the package script `buildscript` instead of the `PKGBUILD` default;
+ see linkman:PKGBUILD[5]. The `buildscript` must be located in the directory
+ makepkg is called from.
+
+*-r, \--rmdeps*::
+ Upon successful build, remove any dependencies installed by makepkg
+ during dependency auto-resolution and installation when using `-s`.
+
+*-R, \--repackage*::
+ Repackage contents of the package without rebuilding the package. This
+ is useful if you forgot, for example, a dependency 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
+ dependencies are not found, pacman will try to resolve them. If
+ successful, the missing packages will be downloaded and installed.
+
+*-S, \--source*::
+ Do not actually build the package, but build a source-only tarball that
+ does not include sources that can be fetched via a download URL. This is
+ useful for passing a single tarball to another program such as a chroot,
+ remote builder, or a tarball upload. Because integrity checks are verified,
+ all source files of the package need to be present or downloadable.
+
+*-V, \--version*::
+ Display version information.
+
+*-C, \--cleanbuild*::
+ Remove the $srcdir before building the package.
+
+*\--allsource*::
+ Do not actually build the package, but build a source-only tarball that
+ includes all sources, including those that are normally downloaded via
+ makepkg. This is useful for passing a single tarball to another program
+ such as a chroot or remote builder. It will also satisfy requirements of
+ the GPL when distributing binary packages.
+
+*\--check*::
+ Run the check() function in the PKGBUILD, overriding the setting in
+ linkman:makepkg.conf[5].
+
+*\--noarchive*::
+ Do not create the archive at the end of the build process. This can be
+ useful to test the package() function or if your target distribution does
+ not use pacman.
+
+*\--nocheck*::
+ Do not run the check() function in the PKGBUILD or handle the checkdepends.
+
+*\--noprepare*::
+ Do not run the prepare() function in the PKGBUILD.
+
+*\--sign*::
+ Sign the resulting package with gpg, overriding the setting in
+ linkman:makepkg.conf[5].
+
+*\--nosign*::
+ Do not create a signature for the built package.
+
+*\--key* <key>::
+ Specify a key to use when signing packages, overriding the GPGKEY setting
+ in linkman:makepkg.conf[5]. If not specified in either location, the
+ default key from the keyring will be used.
+
+*\--noconfirm*::
+ (Passed to pacman) Prevent pacman from waiting for user input before
+ proceeding with operations.
+
+*\--needed*::
+ (Passed to pacman) Tell pacman not to reinstall a target if it is already
+ up-to-date. (used with '-i' / '\--install').
+
+*\--asdeps*::
+ (Passed to pacman) Install packages as non-explicitly installed (used
+ with '-i' / '\--install').
+
+*\--noprogressbar*::
+ (Passed to pacman) Prevent pacman from displaying a progress bar;
+ useful if you are redirecting makepkg output to file.
+
+*\--packagelist*::
+ List the package filenames that would be produced without building. Listed
+ package filenames include PKGDEST and PKGEXT.
+
+*\--printsrcinfo*::
+ Generate and print the SRCINFO file to stdout.
+
+
+Additional Features
+-------------------
+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'. See linkman:PKGBUILD[5] for details on how to
+set up a development PKGBUILD.
+
+
+Reproducibility
+---------------
+makepkg is designed to be compatible with
+link:https://reproducible-builds.org/docs/[Reproducible Builds]. If the
+**SOURCE_DATE_EPOCH** environment variable is set, it will be exported to
+subprocesses, and source and package file modification times and package
+metadata will be unified based on the timestamp specified.
+
+If the **SOURCE_DATE_EPOCH** environment variable is not set, makepkg will use
+its own start date for internal use, but will not unify source file timestamps
+before building.
+
+
+Environment Variables
+---------------------
+**PACMAN**::
+ The command that will be used to check for missing dependencies and to
+ install and remove packages. Pacman's '-Qq', '-Rns', '-S', '-T', and '-U'
+ operations must be supported by this command. If the variable is not
+ set or empty, makepkg will fall back to `pacman'.
+
+**MAKEPKG_CONF=**"/path/to/file"::
+ Use an alternate config file instead of the +{sysconfdir}/makepkg.conf+
+ default.
+
+**PKGDEST=**"/path/to/directory"::
+ Directory where the resulting packages will be stored. Overrides the
+ corresponding value defined in linkman:makepkg.conf[5].
+
+**SRCDEST=**"/path/to/directory"::
+ Directory where the downloaded sources will be stored. Overrides the
+ corresponding value defined in linkman:makepkg.conf[5].
+
+**SRCPKGDEST=**"/path/to/directory"::
+ Directory where source package files will be stored. Overrides the
+ corresponding value defined in linkman:makepkg.conf[5].
+
+**LOGDEST=**"/path/to/directory"::
+ Directory where generated log files will be stored. Overrides the
+ corresponding value defined in linkman:makepkg.conf[5].
+
+**PACKAGER=**"John Doe <john@doe.com>"::
+ String to identify the creator of the resulting package. Overrides
+ the corresponding value defined in linkman:makepkg.conf[5].
+
+**BUILDDIR=**"/path/to/directory"::
+ Directory where the package will be built. Overrides the corresponding
+ value defined in linkman:makepkg.conf[5].
+
+**CARCH=**"(i686|x86_64)"::
+ Force build for a specific architecture. Useful for cross-compiling.
+ Overrides the corresponding value defined in linkman:makepkg.conf[5].
+
+**PKGEXT=**".pkg.tar.gz", **SRCEXT=**".src.tar.gz"::
+ Sets the compression used when making compiled or source packages.
+ Overrides the corresponding value defined in linkman:makepkg.conf[5].
+
+**GNUPGHOME=**"/path/to/directory"::
+ Directory where the gpg keyring for signing the built package is stored.
+
+**GPGKEY=**"keyid"::
+ Specify a key to use when signing packages, overriding the GPGKEY setting
+ in linkman:makepkg.conf[5]
+
+**SOURCE_DATE_EPOCH=**"<date>"::
+ Used for link:https://reproducible-builds.org/docs/[Reproducible Builds].
+
+Configuration
+-------------
+See linkman:makepkg.conf[5] for more details on configuring makepkg using the
+'makepkg.conf' file.
+
+
+Errors
+------
+On exit, makepkg will return one of the following error codes.
+
+0::
+ Normal exit condition.
+
+1::
+ Unknown cause of failure.
+
+2::
+ Error in configuration file.
+
+3::
+ User specified an invalid option
+
+4::
+ Error in user-supplied function in PKGBUILD.
+
+5::
+ Failed to create a viable package.
+
+6::
+ A source or auxiliary file specified in the PKGBUILD is
+ missing.
+
+7::
+ The PKGDIR is missing.
+
+8::
+ Failed to install dependencies.
+
+9::
+ Failed to remove dependencies.
+
+10::
+ User attempted to run makepkg as root.
+
+11::
+ User lacks permissions to build or install to a given
+ location.
+
+12::
+ Error parsing PKGBUILD.
+
+13::
+ A package has already been built.
+
+14::
+ The package failed to install.
+
+15::
+ Programs necessary to run makepkg are missing.
+
+16::
+ Specified GPG key does not exist.
+
+See Also
+--------
+linkman:makepkg.conf[5], linkman:PKGBUILD[5], linkman:pacman[8]
+
+include::footer.asciidoc[]