From 626aecb4724fe5adc65f755d142804306fadb307 Mon Sep 17 00:00:00 2001 From: Levente Polyak Date: Mon, 20 Jun 2022 01:15:34 +0200 Subject: make: split out man page files into doc/man folder --- doc/man/arch-nspawn.1.asciidoc | 40 +++++++++++++++++ doc/man/archbuild.1.asciidoc | 47 ++++++++++++++++++++ doc/man/checkpkg.1.asciidoc | 43 +++++++++++++++++++ doc/man/devtools.7.asciidoc | 55 ++++++++++++++++++++++++ doc/man/diffpkg.1.asciidoc | 57 +++++++++++++++++++++++++ doc/man/export-pkgbuild-keys.1.asciidoc | 25 +++++++++++ doc/man/find-libdeps.1.asciidoc | 24 +++++++++++ doc/man/find-libprovides.1.asciidoc | 24 +++++++++++ doc/man/include/footer.asciidoc | 27 ++++++++++++ doc/man/lddd.1.asciidoc | 25 +++++++++++ doc/man/makechrootpkg.1.asciidoc | 76 +++++++++++++++++++++++++++++++++ doc/man/makerepropkg.1.asciidoc | 59 +++++++++++++++++++++++++ doc/man/mkarchroot.1.asciidoc | 49 +++++++++++++++++++++ doc/man/offload-build.1.asciidoc | 52 ++++++++++++++++++++++ doc/man/sogrep.1.asciidoc | 48 +++++++++++++++++++++ 15 files changed, 651 insertions(+) create mode 100644 doc/man/arch-nspawn.1.asciidoc create mode 100644 doc/man/archbuild.1.asciidoc create mode 100644 doc/man/checkpkg.1.asciidoc create mode 100644 doc/man/devtools.7.asciidoc create mode 100644 doc/man/diffpkg.1.asciidoc create mode 100644 doc/man/export-pkgbuild-keys.1.asciidoc create mode 100644 doc/man/find-libdeps.1.asciidoc create mode 100644 doc/man/find-libprovides.1.asciidoc create mode 100644 doc/man/include/footer.asciidoc create mode 100644 doc/man/lddd.1.asciidoc create mode 100644 doc/man/makechrootpkg.1.asciidoc create mode 100644 doc/man/makerepropkg.1.asciidoc create mode 100644 doc/man/mkarchroot.1.asciidoc create mode 100644 doc/man/offload-build.1.asciidoc create mode 100644 doc/man/sogrep.1.asciidoc (limited to 'doc/man') diff --git a/doc/man/arch-nspawn.1.asciidoc b/doc/man/arch-nspawn.1.asciidoc new file mode 100644 index 0000000..a3e8ec1 --- /dev/null +++ b/doc/man/arch-nspawn.1.asciidoc @@ -0,0 +1,40 @@ +arch-nspawn(1) +============== + +Name +---- +arch-nspawn - Run a command or OS in a light-weight namespace container + +Synopsis +-------- +arch-nspawn [options] working-dir [systemd-nspawn arguments] + +Description +----------- + +'arch-nspawn' is a wrapper around systemd-nspawn to run command or OS in a +namespace container such as a directory including base utilities of a OS. +It is used to build package(s) in given clean and defined environment. + +Options +------- + +*-C* :: + Location of a pacman config file + +*-M* :: + Location of a makepkg config file + +*-c* :: + Set pacman cache, if no directory is specified the passed pacman.conf's cachedir is used with a fallback to '/etc/pacman.conf' + +*-f* :: + Copy file from the host to the chroot + +*-s*:: + Do not run setarch + +*-h*:: + Show this usage message + +include::include/footer.asciidoc[] diff --git a/doc/man/archbuild.1.asciidoc b/doc/man/archbuild.1.asciidoc new file mode 100644 index 0000000..6b00572 --- /dev/null +++ b/doc/man/archbuild.1.asciidoc @@ -0,0 +1,47 @@ +archbuild(1) +============ + +Name +---- +archbuild - a script to build an Arch Linux package inside a clean chroot. + +Synopsis +-------- +archbuild [options] -- [makechrootpkg args] + +Description +----------- + +'archbuild' is a script to build an Arch Linux package. archbuild is part of devtools but should only be used via one of the included symlinks: + +* extra-x86_64-build +* gnome-unstable-x86_64-build +* kde-unstable-x86_64-build +* multilib-build +* multilib-staging-build +* multilib-testing-build +* staging-x86_64-build +* testing-x86_64-build + +The symlink used to run it will be inspected by archbuild, to determine which target you want it to use. It will load the available pacman configuration from 'pacman-reponame-arch.conf' with a fallback to 'pacman-reponame.conf' from {pkgdatadir}. The makepkg configuration is loaded from 'makepkg-repo-arch.conf' with a fallback to 'makepkg-reponame.conf' from {pkgdatadir}. + + +Options +------- + +*-h*:: + Output command line options. + +*-c*:: + Recreate the chroot before building. + +*-r* :: + Create chroots in this directory. + + +See Also +-------- + +linkman:devtools[7] + +include::include/footer.asciidoc[] diff --git a/doc/man/checkpkg.1.asciidoc b/doc/man/checkpkg.1.asciidoc new file mode 100644 index 0000000..bd41416 --- /dev/null +++ b/doc/man/checkpkg.1.asciidoc @@ -0,0 +1,43 @@ +checkpkg(1) +=========== + +Name +---- +checkpkg - Compare the current build package with the repository version + +Synopsis +-------- +checkpkg + +Description +----------- + +Searches for a locally built package corresponding to the PKGBUILD, and +downloads the last version of that package from the Pacman repositories. It +then compares the list of .so files provided by each version of the package and +outputs if there are soname differences for the new package. A directory is +also created using mktemp with files containing a file list for both packages +and a library list for both packages. + +Options +------- + +*-r, --rmdir*:: + Remove the temporary directory created to contain the file and library list + of both packages. + +*-w, --warn*:: + Print a warning instead of a regular message in case of soname differences. + +*-M, --makepkg-config*:: + Set an alternate makepkg configuration file. + +*-h, --help*:: + Show a help text + +See Also +-------- + +linkman:find-libprovides[1] + +include::include/footer.asciidoc[] diff --git a/doc/man/devtools.7.asciidoc b/doc/man/devtools.7.asciidoc new file mode 100644 index 0000000..82d0a77 --- /dev/null +++ b/doc/man/devtools.7.asciidoc @@ -0,0 +1,55 @@ +devtools(7) +=========== + +Name +---- +devtools - Developer tools for the Arch Linux distribution + +Description +----------- + +Devtools contains tools for package maintenance in Arch Linux. The toolset +varies from tools for building packages in a clean chroot ('mkarchroot',...), +packaging related tools for sonames ('sogrep', 'lddd') and tools for +repository management such as ('archco', 'extra2community') + +Programs +-------- +The list below gives a short overview; see the respective documentation +for details. + +linkman:archbuild[1] + Build an Arch Linux package inside a clean chroot + +linkman:arch-nspawn[1] + Run a command or OS in a light-weight namespace container + +linkman:checkpkg[1] + Compare the current build pakcage with the repository version + +linkman:find-libdeps[1] + Find soname dependencies for a package + +linkman:find-libprovides[1] + Find soname's which are provided by a package + +linkman:lddd[1] + Find broken library links on your system + +linkman:mkarchroot[1] + Creates an arch chroot in a specified location with a specified set of + packages + +linkman:makechrootpkg[1] + Build a PKGBUILD in a given chroot environment + +linkman:makerepropkg[1] + Rebuild a package to see if it is reproducible + +linkman:offload-build[1] + Build a PKGBUILD on a remote server using makechrootpkg + +linkman:sogrep[1] + Find packages using a linked to a given shared library + +include::include/footer.asciidoc[] diff --git a/doc/man/diffpkg.1.asciidoc b/doc/man/diffpkg.1.asciidoc new file mode 100644 index 0000000..48722a9 --- /dev/null +++ b/doc/man/diffpkg.1.asciidoc @@ -0,0 +1,57 @@ +diffpkg(1) +=========== + +Name +---- +diffpkg - Compare package files using different modes. + +Synopsis +-------- +diffpkg [OPTIONS] [MODES] [FILE|PKGNAME...] + +Description +----------- + +Searches for a locally built package corresponding to the PKGBUILD, and +downloads the last version of that package from the Pacman repositories. +It then compares the package archives using different modes while using +simple tar content list by default. + +When given one package, use it to diff against the locally built one. +When given two packages, diff both packages against each other. + +In either case, a package name will be converted to a filename from the +cache, and diffpkg will proceed as though this filename was initially +specified. + +Options +------- + +*-M, --makepkg-config*:: + Set an alternate makepkg configuration file + +*-v, --verbose*:: + Provide more detailed/unfiltered output + +*-h, --help*:: + Show a help text + +Modes +----- + +*-l, --list*:: + Activate tar content list diff mode (default) + +*-d, --diffoscope*:: + Activate diffoscope diff mode + +*-p, --pkginfo*:: + Activate .PKGINFO diff mode + +*-b, --buildinfo*:: + Activate .BUILDINFO diff mode + +See Also +-------- + +include::include/footer.asciidoc[] diff --git a/doc/man/export-pkgbuild-keys.1.asciidoc b/doc/man/export-pkgbuild-keys.1.asciidoc new file mode 100644 index 0000000..d0141e4 --- /dev/null +++ b/doc/man/export-pkgbuild-keys.1.asciidoc @@ -0,0 +1,25 @@ +export-pkgbuild-keys(1) +======================= + +Name +---- +export-pkgbuild-keys - Export valid source signing keys from a PKGBUILD + +Synopsis +-------- +export-pkgbuild-keys + +Description +----------- + +Export the PGP keys from a PKGBUILDs validpgpkeys array into the keys/pgp/ +subdirectory. Useful for distributing packager validated source signing +keys alongside PKGBUILDs. + +Options +------- + +*-h, --help*:: + Show a help text. + +include::include/footer.asciidoc[] diff --git a/doc/man/find-libdeps.1.asciidoc b/doc/man/find-libdeps.1.asciidoc new file mode 100644 index 0000000..79706b3 --- /dev/null +++ b/doc/man/find-libdeps.1.asciidoc @@ -0,0 +1,24 @@ +find-libdeps(1) +=============== + +Name +---- +find-libdeps - Find soname dependencies for a package + +Synopsis +-------- +find-libdeps [options] + +Description +----------- +Finds soname dependencies of a package and prints out a list in the following +format '=-'. + +Options +------- + +*--ignore-internal*:: + Ignore internal libraries. + + +include::include/footer.asciidoc[] diff --git a/doc/man/find-libprovides.1.asciidoc b/doc/man/find-libprovides.1.asciidoc new file mode 100644 index 0000000..e8e27d3 --- /dev/null +++ b/doc/man/find-libprovides.1.asciidoc @@ -0,0 +1,24 @@ +find-libprovides(1) +=================== + +Name +---- +find-libprovides - Find soname's which are provided by a package + +Synopsis +-------- +find-libprovides [options] + +Description +----------- + +Finds soname's provided by a package and prints out a list in the following +format '=-'. + +Options +------- + +*--ignore-internal*:: + Ignore internal libraries. + +include::include/footer.asciidoc[] diff --git a/doc/man/include/footer.asciidoc b/doc/man/include/footer.asciidoc new file mode 100644 index 0000000..14c5d36 --- /dev/null +++ b/doc/man/include/footer.asciidoc @@ -0,0 +1,27 @@ + +Bugs +---- +Bugs can be reported on the project's GitLab bug tracker 'https://gitlab.archlinux.org/archlinux/devtools' + + +Authors +------- + +Maintainers: + +* Aaron Griffin +* Allan McRae +* Bartłomiej Piotrowski +* Dan McGee +* Dave Reisner +* Evangelos Foutras +* Jan Alexander Steffens (heftig) +* Jelle van der Waa +* Levente Polyak +* Pierre Schmitz +* Sébastien Luttringer +* Sven-Hendrik Haase +* Thomas Bächler + +For additional contributors, use `git shortlog -s` on the devtools.git +repository. diff --git a/doc/man/lddd.1.asciidoc b/doc/man/lddd.1.asciidoc new file mode 100644 index 0000000..c6bff26 --- /dev/null +++ b/doc/man/lddd.1.asciidoc @@ -0,0 +1,25 @@ +lddd(1) +======= + +Name +---- +lddd - Find broken library links on your system + +Synopsis +-------- +lddd + +Description +----------- + +Scans '$PATH', '/lib', '/usr/lib', '/usr/local/lib' and +'/etc/ld.so.conf.d/*.conf' directories for ELF files with references to missing +shared libraries, and suggests which packages might need to be rebuilt. The +collected data is written to a temporary directory created by mktemp. + +See Also +-------- + +linkman:ldd[1] + +include::include/footer.asciidoc[] diff --git a/doc/man/makechrootpkg.1.asciidoc b/doc/man/makechrootpkg.1.asciidoc new file mode 100644 index 0000000..12d32f1 --- /dev/null +++ b/doc/man/makechrootpkg.1.asciidoc @@ -0,0 +1,76 @@ +makechrootpkg(1) +================ + +Name +---- +makechrootpkg - Build a PKGBUILD in a given chroot environment + +Synopsis +-------- +makechrootpkg [OPTIONS] -r [--] [makepkg args] + +Description +----------- + +Run this script in a directory containing a PKGBUILD to build a package +inside a clean chroot. Arguments passed to this script after the +end-of-options marker (--) will be passed to makepkg. + +The chroot dir consists of the following directories: +/{root, copy} but only "root" is required +by default. The working copy will be created as needed + +The chroot "root" directory must be created via the following +command: + mkarchroot /root base-devel + +This script reads {SRC,SRCPKG,PKG,LOG}DEST, MAKEFLAGS and PACKAGER +from makepkg.conf(5), if those variables are not part of the +environment. + +Default makepkg args: --syncdeps --noconfirm --log --holdver --skipinteg + +Options +------- + +*-h*:: + Show this usage message + +*-c*:: + Clean the chroot before building + +*-d* :: + Bind directory into build chroot as read-write + +*-D* :: + Bind directory into build chroot as read-only + +*-u*:: + Update the working copy of the chroot before building + This is useful for rebuilds without dirtying the pristine + chroot + +*-r* :: + The chroot dir to use + +*-I* :: + Install a package into the working copy of the chroot + +*-l* :: + The directory to use as the working copy of the chroot + Useful for maintaining multiple copies + Default: $USER + +*-n*:: + Run namcap on the build package + +*-C*:: + Run checkpkg on the build package + +*-T*:: + Build in a temporary directory + +*-U*:: + Run makepkg as a specified user + +include::include/footer.asciidoc[] diff --git a/doc/man/makerepropkg.1.asciidoc b/doc/man/makerepropkg.1.asciidoc new file mode 100644 index 0000000..4e694b3 --- /dev/null +++ b/doc/man/makerepropkg.1.asciidoc @@ -0,0 +1,59 @@ +makerepropkg(1) +================ + +Name +---- +makerepropkg - Rebuild a package to see if it is reproducible + +Synopsis +-------- +makerepropkg [OPTIONS] [...] + +Description +----------- + +Given the path to a built pacman package(s), attempt to rebuild it using the +PKGBUILD in the current directory. The package will be built in an environment +as closely matching the environment of the initial package as possible, by +building up a chroot to match the information exposed in the package's +linkman:BUILDINFO[5] manifest. On success, the resulting package will be +compared to the input package, and makerepropkg will report whether the +artifacts are identical. + +When given multiple packages, additional package files are assumed to be split +packages and will be treated as additional artifacts to compare during the +verification step. + +A valid target(s) for pacman -S can be specified instead, and makerepropkg will +download it to the cache if needed. This is mostly useful to specify which +repository to retrieve from. If no positional arguments are specified, the +targets will be sourced from the PKGBUILD. + +In either case, the package name will be converted to a filename from the +cache, and makerepropkg will proceed as though this filename was initially +specified. + +This implements a verifier for pacman/libalpm packages in accordance with the +link:https://reproducible-builds.org/[Reproducible Builds] project. + +Options +------- + +*-d*:: + If packages are not reproducible, compare them using diffoscope. + +*-c*:: + Set the pacman cache directory. + +*-M* :: + Location of a makepkg config file. + +*-l* :: + The directory name to use as the chroot namespace + Useful for maintaining multiple copies + Default: $USER + +*-h*:: + Show this usage message + +include::include/footer.asciidoc[] diff --git a/doc/man/mkarchroot.1.asciidoc b/doc/man/mkarchroot.1.asciidoc new file mode 100644 index 0000000..7930c4c --- /dev/null +++ b/doc/man/mkarchroot.1.asciidoc @@ -0,0 +1,49 @@ +mkarchroot(1) +============== + +Name +---- +mkarchroot - Creates an arch chroot in a specified location with a specified set of packages + +Synopsis +-------- +mkarchroot [options] [location] [packages] + +Description +----------- + +'mkarchroot' is a script to create an Arch Linux chroot at a specified location +with specified packages. Typically used by 'makechrootpkg' to create build +chroots. Apart from installing specified packages the chroot is created with an +en_US.UTF-8 and de_DE.UTF-8 locale and a generated machine-id. + +Options +------- + +*-U*:: + Use 'pacman -U' to install packages. + +*-C* :: + Location of a pacman config file. + +*-M* :: + Location of a makepkg config file. + +*-c* :: + Set pacman cache. + +*-f* :: + Copy file from the host to the chroot. + +*-s*:: + Do not run setarch. + +*-h*:: + Output command line options. + +See Also +-------- + +linkman:pacman[1] + +include::include/footer.asciidoc[] diff --git a/doc/man/offload-build.1.asciidoc b/doc/man/offload-build.1.asciidoc new file mode 100644 index 0000000..6b39711 --- /dev/null +++ b/doc/man/offload-build.1.asciidoc @@ -0,0 +1,52 @@ +offload-build(1) +================ + +Name +---- +offload-build - Build a PKGBUILD on a remote server using makechrootpkg + +Synopsis +-------- +offload-build [OPTIONS] -- [ARCHBUILD_OPTIONS] + +Description +----------- + +Build a PKGBUILD on a remote server using makechrootpkg. Requires a remote user +that can run archbuild in a non-interactive manner, e.g. must be able to +elevate permissions using passwordless sudo. + +Options +------- + +*-r, --repo* :: + Build against a specific repository. The default is `extra`, to build packages using + the stable repositories via extra-x86_64-build. + +*-a, --arch* :: + Build against a specific architecture. The default is `x86_64`, the only + architecture officially supported by Arch Linux. + +*-s, --server* :: + Offload to a specific build server. The default is build.archlinux.org + which is used as part of the build toolchain for the official Arch Linux + repos. + +*-h, --help*:: + Show a help text. + +Passing options to archbuild +---------------------------- + +Options after a delimiting -- are passed on to archbuild on the remote. +archbuild in turn supports passing arguments on to makechrootpkg, which in turn +supports passing options to makepkg. Since each uses -- to delimit options that +are forwarded, make sure to escape them properly: + + `offload-build offload-args -- archbuild-args -- makechrootpkg-args -- makepkg-args` + +Example: To use a second `testing-x86_64-build` instance with another copydir: + + `offload-build -r testing -- -- -l ` + +include::include/footer.asciidoc[] diff --git a/doc/man/sogrep.1.asciidoc b/doc/man/sogrep.1.asciidoc new file mode 100644 index 0000000..bae6da1 --- /dev/null +++ b/doc/man/sogrep.1.asciidoc @@ -0,0 +1,48 @@ +sogrep(1) +========= + +Name +---- +sogrep - Find shared library links in an Arch Linux repository + +Synopsis +-------- +sogrep [options] repo libname + +Description +----------- + +Check the soname links database for Arch Linux repositories containing packages +linked to a given shared library. If the repository specified is "all", then +all repositories will be searched, otherwise only the named repository will be +searched. + +If the links database does not exist, it will be downloaded first. + +Options +------- + +*-v, --verbose*:: + Provide detailed output containing the matched links for each package, the + repository it came from (in the event that all repositories are being + searched), and, in combination with `-r`, a progress bar for the links + database download. + +*-r, --refresh*:: + Refresh the links databases + +*-h, --help*:: + Show a help text + + +Environment Variables +--------------------- +**SOLINKS_MIRROR**="https://mirror.foo.com" + Alternative mirror to use for downloading soname links database. + +**SOCACHE_DIR**="/path/to/directory":: + Directory where soname links database is stored, overrides the default + directory set by the **XDG_CACHE_HOME** environment variable or the + **HOME** environment variable if **XDG_CACHE_HOME** is not set. + +include::include/footer.asciidoc[] -- cgit v1.2.3-54-g00ecf