From 0d2ab81f23438cd71a79366c7359bc1598b73bf0 Mon Sep 17 00:00:00 2001 From: pghvlaans Date: Thu, 19 Dec 2024 15:25:59 +0900 Subject: [PATCH] Finish editing man3 and install (#13) See e.g. SBO::Lib::Util.3. --- README.md | 1 + SBO-Lib/Changes | 1 + SBO-Lib/lib/SBO/Lib/Build.pm | 10 +-- SBO-Lib/lib/SBO/Lib/Download.pm | 8 +- SBO-Lib/lib/SBO/Lib/Repo.pm | 113 ++++++++++++++++-------- SBO-Lib/lib/SBO/Lib/Tree.pm | 11 +-- SBO-Lib/lib/SBO/Lib/Util.pm | 7 +- man3/SBO::Lib::Build.3 | 10 +-- man3/SBO::Lib::Download.3 | 10 +-- man3/SBO::Lib::Repo.3 | 113 ++++++++++++++++-------- man3/SBO::Lib::Tree.3 | 11 +-- man3/SBO::Lib::Util.3 | 7 +- slackbuild/sbotools/README | 3 +- slackbuild/sbotools/sbotools.SlackBuild | 2 +- 14 files changed, 202 insertions(+), 105 deletions(-) diff --git a/README.md b/README.md index 3157f73c..e9fbeff1 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ To make **sbotools** packages from the master branch, see [sbotools-git-slackbui * Util.pm: Read the hints file only once; allow multiple optional dependency specs for the same script * Lint the value of SBO_HOME before running anything other than sboconfig * Repo.pm: Remove antiquated subroutine migrate_repo() + * Install development man pages on SBO::Lib to man 3 * 3.1 - 2024-12-05 * sbofind: Allow multiple search terms diff --git a/SBO-Lib/Changes b/SBO-Lib/Changes index 50fdcc7c..cef17b6b 100644 --- a/SBO-Lib/Changes +++ b/SBO-Lib/Changes @@ -9,6 +9,7 @@ sbotools * Util.pm: Read the hints file only once; allow multiple optional dependency specs for the same script * Lint the value of SBO_HOME before running anything other than sboconfig * Repo.pm: Remove antiquated subroutine migrate_repo() + * Install development man pages on SBO::Lib to man 3 3.1 - 2024-12-05 * sbofind: Allow multiple search terms diff --git a/SBO-Lib/lib/SBO/Lib/Build.pm b/SBO-Lib/lib/SBO/Lib/Build.pm index d3b7951a..0b7cf2c8 100644 --- a/SBO-Lib/lib/SBO/Lib/Build.pm +++ b/SBO-Lib/lib/SBO/Lib/Build.pm @@ -189,7 +189,7 @@ sub do_slackbuild { do_upgradepkg($pkg); -C runs C on C<$pkg>. +C runs C on C<$pkg>. There is no useful return value. @@ -394,7 +394,7 @@ sub make_distclean { my @merged = @{ merge_queues([@queue1], [@queue2]) }; -C takes two array references and merges them such that C<@queue1> +C takes two array references and merges them such that C<@queue1> is in front, followed by any non-redundant items in C<@queue2>. This is returned as an array reference. @@ -410,7 +410,7 @@ sub merge_queues { =head2 get_full_queue - my ($revdep_queue) = ($installed, @sbos); + my @revdep_queue = ($installed, @sbos); C takes a list of installed SlackBuilds and an array of SlackBuilds to check. It returns a list of reverse dependencies. @@ -528,9 +528,9 @@ sub perform_sbo { =head2 process_sbos - my ($failures, $exit) = process_sbos(TODO => [@queue]); + my (@failures, $exit) = process_sbos(TODO => [@queue]); -C processes a C<@queue> of SlackBuilds and returns an array +C processes a C<@queue> of SlackBuilds and returns an array reference with failed builds and the exit status. In case of a mass rebuild, C updates the resume file C diff --git a/SBO-Lib/lib/SBO/Lib/Download.pm b/SBO-Lib/lib/SBO/Lib/Download.pm index 7f35701d..2307b4eb 100644 --- a/SBO-Lib/lib/SBO/Lib/Download.pm +++ b/SBO-Lib/lib/SBO/Lib/Download.pm @@ -35,7 +35,7 @@ our %EXPORT_TAGS = ( =head1 NAME -SBO::Lib::Download - Routines for downloading slackbuild sources. +SBO::Lib::Download - Routines for downloading SlackBuild sources. =head1 SYNOPSIS @@ -43,7 +43,7 @@ SBO::Lib::Download - Routines for downloading slackbuild sources. my ($ret, $exit) = check_distfiles(LOCATION => $loc); -=head2 SUBROUTINES +=head1 SUBROUTINES =cut @@ -53,9 +53,9 @@ SBO::Lib::Download - Routines for downloading slackbuild sources. C gets the list of downloads from C<$loc>. Any previously-downloaded files have their checksums verified. Missing and unverifiable files are downloaded and -verified. Finally, C is run on each download. +verified. Finally, C is run on each download. -In case of success, an array of symlinks from Cis returned. In case of +In case of success, an array of symlinks from C is returned. In case of failure, an error message and an exit code are returned. =cut diff --git a/SBO-Lib/lib/SBO/Lib/Repo.pm b/SBO-Lib/lib/SBO/Lib/Repo.pm index b58e5552..f46424b6 100644 --- a/SBO-Lib/lib/SBO/Lib/Repo.pm +++ b/SBO-Lib/lib/SBO/Lib/Repo.pm @@ -45,7 +45,7 @@ our %EXPORT_TAGS = ( =head1 NAME -SBO::Lib::Repo - Routines for downloading and updating the SBo repo. +SBO::Lib::Repo - Routines for downloading and updating the SBo repository. =head1 SYNOPSIS @@ -57,18 +57,34 @@ SBO::Lib::Repo - Routines for downloading and updating the SBo repo. =head2 $distfiles -By default $distfiles is set to C, and it is where all the +C<$distfiles> defaults to C, and it is where all downloaded sources are kept. The location depends on the C config setting. +=head2 $gpg_log + +C<$gpg_log> defaults to C, and it is where the output +of the most recent C verification is kept. + +The location depends on the C config setting. + =head2 $repo_path -By default $repo_path is set to C, and it is where the +C<$repo_path> defaults to C, and it is where the SlackBuilds.org tree is kept. The location depends on the C config setting. +=head2 $slackbuilds_txt + +C<$slackbuilds_txt> defaults to C. It is +included in the official rsync repos, but not the git mirrors. Currently, +this file is used to indicate that C<$repo_path> is a local mirror of the +upstream repo. This is likely to change in an upcoming version. + +The location depends on the C config setting. + =cut # some stuff we'll need later @@ -85,10 +101,9 @@ our $slackbuilds_txt = "$repo_path/SLACKBUILDS.TXT"; my $bool = check_git_remote($path, $url); -C will check if the repository at C<$path> is a git -repository and if so, it will check if it defined an C remote that -matches the C<$url>. If so, it will return a true value. Otherwise it will -return a false value. +C checks if the repository at C<$path> is a git repository. +If so, it checks for a defined C remote matching C<$url>. If so, it returns +a true value, and a false value otherwise. =cut @@ -129,6 +144,10 @@ regardless of fetch method. If C<$repo_path> does not exist, creation will be attempted, returning a true value on success. Creation failure results in a usage error. +B: This is a prime candidate for changes in an upcoming version. +In principle, it would be better to check that the contents of C<$repo_path> +are sufficiently similar to an SBo mirror to continue safely. (KEC) + =cut sub check_repo { @@ -166,6 +185,9 @@ C checks if the file C exists in the correct location, and returns a true value if it does, and a false value otherwise. +B: It is possible that some code related to repository detection +independent of C will be placed here. (KEC) + =cut # does the SLACKBUILDS.TXT file exist in the sbo tree? @@ -177,10 +199,11 @@ sub chk_slackbuilds_txt { fetch_tree(); -C will make sure the C<$repo_path> exists and is empty, and then -fetch the SlackBuilds.org repository tree there. +C checks that C<$repo_path> exists and is empty, and then fetches +the SlackBuilds.org repository. -If the C<$repo_path> is not empty, it will exit with a usage error. +If the C<$repo_path> exists and is non-empty, the user will see a series of prompts +from C before the fetch proceeds. =cut @@ -194,9 +217,9 @@ sub fetch_tree { my $bool = generate_slackbuilds_txt(); -C will generate a minimal C for a -repository that doesn't come with one. If it fails, it will return a false -value. Otherwise it will return a true value. +C generates a minimal C for +repositories that do not include this file. If the file cannot be opened for +write, it returns a false value. Otherwise, it returns a true value. =cut @@ -229,12 +252,15 @@ sub generate_slackbuilds_txt { my $bool = git_sbo_tree($url); -C will C the repository specified by C<$url> to the -C<$repo_path> if the C<$url> repository is not already there. If it is, it will -run C. +C will C the repository specified by C<$url> to the +C<$repo_path> if the C<$url> repository is not present. If it is, it runs +C. -If any command fails, it will return a false value. Otherwise it will return a -true value. +If C is set, or the if running or configured Slackware version has a +recommended git branch, C is attempted. If successful, C follows. + +If C is C, C verification proceeds with C +at the end of the subroutine. =cut @@ -291,12 +317,13 @@ sub git_sbo_tree { pull_sbo_tree(); -C will pull the SlackBuilds.org repository tree from -C or whatever the C -configuration variable has been set to. +C pulls the SlackBuilds.org repository tree from +the default in C<%supported> for the running Slackware version (accounting +for C, C and C). -C<$ver> is the version of Slackware you are running, provided it is supported, -or whatever you've set in the C configuration variable. +C<$ver> is the running or configured version of Slackware, provided that it +is supported. Version support verification occurs in C +via C; see C. =cut @@ -336,6 +363,9 @@ sub pull_sbo_tree { C syncs the SlackBuilds.org repository to C<$repo_path> from the C<$url> provided. +If C is C, C verification proceeds with C +at the end of the subroutine. + =cut # rsync the sbo tree from slackbuilds.org to $repo_path @@ -358,8 +388,11 @@ sub rsync_sbo_tree { slackbuilds_or_fetch(); -C will check if there is a C in the -C<$repo_path>, and if not, offer to fetch the tree. +C checks for the file C in +C<$repo_path>. If not, it offers to fetch the tree. + +B: Changes are likely once C is no longer needed +for checking that a local copy of the repository exists. (KEC) =cut @@ -385,9 +418,8 @@ sub slackbuilds_or_fetch { update_tree(); -C will check if there is a C in the -C<$repo_path>, and if not, will run C. Otherwise it will update -the SlackBuilds.org tree. +C checks for C in C<$repo_path>. If not, it runs +C. Otherwise, it updates the SlackBuilds.org tree. =cut @@ -402,8 +434,10 @@ sub update_tree { verify_git_commit($branch); C attempts to verify the GPG signature of the most -recent git commit, if any. Git commit verification is unavailable for -Slackware 14.0 and Slackware 14.1. +recent git commit, if any. + +Git commit verification is unavailable for Slackware 14.0 and Slackware 14.1. +A user prompt for continuation appears if C is C. =cut @@ -475,9 +509,11 @@ sub verify_git_commit { C checks the signature of CHECKSUMS.md5.asc, prompting the user to download the public key if not present. If "fullcheck" is passed (i.e., when syncing the local -repository), md5 verification is performed as well. Failure at any juncture leaves a lockfile -.rsync.lock in SBO_HOME, which prevents script installation and upgrade until the issue has -been resolved, GPG_TRUE is set to FALSE or the lockfile is removed. +repository), md5sum verification is performed as well. + +Failure at any juncture leaves a lockfile C<.rsync.lock> in C, which prevents +script installation and upgrade until the issue has been resolved, C is set to +C or the lockfile is removed. =cut @@ -602,7 +638,8 @@ sub verify_rsync { verify_gpg(); C determines whether a git repo is in use, and then -runs GnuPG verification. It can be called from outside Repo.pm. +runs C verification. It is exportable, and is currently used in +C, C and C. =cut @@ -632,8 +669,12 @@ sub verify_gpg { retrieve_key($fingerprint); -C attempts to retrieve a missing public key and add it to -the keyring. +C attempts to retrieve a missing public key from +C and add it to the keyring. + +C output is saved to C<$key_log>, and the output of +C is displayed with a prompt to ensure +that the user can trust the key. =cut diff --git a/SBO-Lib/lib/SBO/Lib/Tree.pm b/SBO-Lib/lib/SBO/Lib/Tree.pm index 20db53f0..5c157ea9 100644 --- a/SBO-Lib/lib/SBO/Lib/Tree.pm +++ b/SBO-Lib/lib/SBO/Lib/Tree.pm @@ -67,11 +67,12 @@ sub get_orig_location { my $loc = get_sbo_location($sbo, ...); my $loc = get_sbo_location([$sbo, ...]); -C returns the location in the C or the +C returns the location in C or the SlackBuilds.org tree for the first C<$sbo> given. -Specifying more than one C<$sbo> is useful for only needing to access the -filesystem once when searching, and populating the internal cache. +Specifying more than one C<$sbo> is useful only for accessing the +filesystem once when searching or populating the internal cache. No +code does this currently. =cut @@ -89,7 +90,7 @@ sub get_sbo_location { my %locations = get_sbo_locations(@sbos); -C tries to find all C<@sbos> and returns a hash matching the +C finds all SlackBuilds in C<@sbos>, returns a hash matching each package name to its location. =cut @@ -146,7 +147,7 @@ sub get_sbo_locations { my $bool = is_local($sbo); C checks whether the given C<$sbo> is in the C or -not, and returns a true value if it is, and a false value if it is not. +not. The return value is true if it is, and false if it is not. =cut diff --git a/SBO-Lib/lib/SBO/Lib/Util.pm b/SBO-Lib/lib/SBO/Lib/Util.pm index d475fb5f..130bac21 100644 --- a/SBO-Lib/lib/SBO/Lib/Util.pm +++ b/SBO-Lib/lib/SBO/Lib/Util.pm @@ -107,6 +107,11 @@ The supported keys are: C, C, C, C, C, C, C, C, C, C and C. +=head2 @listings + +An array with blacklisted packages and optional dependency requests read in +from C. Non-exportable. + =cut # global config variables @@ -702,7 +707,7 @@ sub uniq { usage_error($msg); -C warns and exits, printing C<$msg> to STDERR. +C warns and exits, printing C<$msg> to STDERR. There is no useful return value. diff --git a/man3/SBO::Lib::Build.3 b/man3/SBO::Lib::Build.3 index 2f30df7a..b66beaec 100644 --- a/man3/SBO::Lib::Build.3 +++ b/man3/SBO::Lib::Build.3 @@ -115,7 +115,7 @@ value is an error message; the second and third values are empty. \& do_upgradepkg($pkg); .Ve .PP -\&\f(CWdo_upgradepkg()\fR runs \f(CW\*(C`upgradepkg\*(C'\fR on \f(CW$pkg\fR. +\&\f(CWdo_upgradepkg()\fR runs \f(CW\*(C`upgradepkg \-\-reinstall \-\-install\-new\*(C'\fR on \f(CW$pkg\fR. .PP There is no useful return value. .SS get_build_queue @@ -188,13 +188,13 @@ It has no useful return value. \& my @merged = @{ merge_queues([@queue1], [@queue2]) }; .Ve .PP -\&\f(CW\*(C`merge_queues\*(C'\fR takes two array references and merges them such that \f(CW@queue1\fR +\&\f(CWmerge_queues()\fR takes two array references and merges them such that \f(CW@queue1\fR is in front, followed by any non-redundant items in \f(CW@queue2\fR. This is returned as an array reference. .SS get_full_queue .IX Subsection "get_full_queue" .Vb 1 -\& my ($revdep_queue) = ($installed, @sbos); +\& my @revdep_queue = ($installed, @sbos); .Ve .PP \&\f(CWget_full_queue()\fR takes a list of installed SlackBuilds and an array @@ -211,10 +211,10 @@ the first value is instead an error message. .SS process_sbos .IX Subsection "process_sbos" .Vb 1 -\& my ($failures, $exit) = process_sbos(TODO => [@queue]); +\& my (@failures, $exit) = process_sbos(TODO => [@queue]); .Ve .PP -\&\f(CWprocess_sbos()\fR processes a \f(CW@queue\fR of SlackBuilds and returns an array +\&\f(CWprocess_sbos()\fR processes a \f(CW@queue\fR of SlackBuilds and returns an array reference with failed builds and the exit status. .PP In case of a mass rebuild, \f(CW\*(C`process_sbos\*(C'\fR updates the resume file \f(CW\*(C`resume.temp\*(C'\fR diff --git a/man3/SBO::Lib::Download.3 b/man3/SBO::Lib::Download.3 index 7bebdf7d..c62616cd 100644 --- a/man3/SBO::Lib::Download.3 +++ b/man3/SBO::Lib::Download.3 @@ -61,7 +61,7 @@ .if n .ad l .nh .SH NAME -SBO::Lib::Download \- Routines for downloading slackbuild sources. +SBO::Lib::Download \- Routines for downloading SlackBuild sources. .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 @@ -69,8 +69,8 @@ SBO::Lib::Download \- Routines for downloading slackbuild sources. \& \& my ($ret, $exit) = check_distfiles(LOCATION => $loc); .Ve -.SS SUBROUTINES -.IX Subsection "SUBROUTINES" +.SH SUBROUTINES +.IX Header "SUBROUTINES" .SS check_distfiles .IX Subsection "check_distfiles" .Vb 1 @@ -79,9 +79,9 @@ SBO::Lib::Download \- Routines for downloading slackbuild sources. .PP \&\f(CWcheck_distfiles()\fR gets the list of downloads from \f(CW$loc\fR. Any previously-downloaded files have their checksums verified. Missing and unverifiable files are downloaded and -verified. Finally, \f(CW\*(C`create_symlinks\*(C'\fR is run on each download. +verified. Finally, \f(CWcreate_symlinks()\fR is run on each download. .PP -In case of success, an array of symlinks from \f(CW\*(C`create_symlinks\*(C'\fRis returned. In case of +In case of success, an array of symlinks from \f(CWcreate_symlinks()\fR is returned. In case of failure, an error message and an exit code are returned. .SS compute_md5sum .IX Subsection "compute_md5sum" diff --git a/man3/SBO::Lib::Repo.3 b/man3/SBO::Lib::Repo.3 index aba88f29..0ccf8f55 100644 --- a/man3/SBO::Lib::Repo.3 +++ b/man3/SBO::Lib::Repo.3 @@ -61,7 +61,7 @@ .if n .ad l .nh .SH NAME -SBO::Lib::Repo \- Routines for downloading and updating the SBo repo. +SBO::Lib::Repo \- Routines for downloading and updating the SBo repository. .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 @@ -74,17 +74,33 @@ SBO::Lib::Repo \- Routines for downloading and updating the SBo repo. .ie n .SS $distfiles .el .SS \f(CW$distfiles\fP .IX Subsection "$distfiles" -By default \f(CW$distfiles\fR is set to \f(CW\*(C`/usr/sbo/distfiles\*(C'\fR, and it is where all the +\&\f(CW$distfiles\fR defaults to \f(CW\*(C`/usr/sbo/distfiles\*(C'\fR, and it is where all downloaded sources are kept. .PP The location depends on the \f(CW\*(C`SBO_HOME\*(C'\fR config setting. +.ie n .SS $gpg_log +.el .SS \f(CW$gpg_log\fP +.IX Subsection "$gpg_log" +\&\f(CW$gpg_log\fR defaults to \f(CW\*(C`/usr/sbo/gpg.log\*(C'\fR, and it is where the output +of the most recent \f(CW\*(C`gnupg\*(C'\fR verification is kept. +.PP +The location depends on the \f(CW\*(C`SBO_HOME\*(C'\fR config setting. .ie n .SS $repo_path .el .SS \f(CW$repo_path\fP .IX Subsection "$repo_path" -By default \f(CW$repo_path\fR is set to \f(CW\*(C`/usr/sbo/repo\*(C'\fR, and it is where the +\&\f(CW$repo_path\fR defaults to \f(CW\*(C`/usr/sbo/repo\*(C'\fR, and it is where the SlackBuilds.org tree is kept. .PP The location depends on the \f(CW\*(C`SBO_HOME\*(C'\fR config setting. +.ie n .SS $slackbuilds_txt +.el .SS \f(CW$slackbuilds_txt\fP +.IX Subsection "$slackbuilds_txt" +\&\f(CW$slackbuilds_txt\fR defaults to \f(CW\*(C`/usr/sbo/repo/SLACKBUILDS.TXT\*(C'\fR. It is +included in the official rsync repos, but not the git mirrors. Currently, +this file is used to indicate that \f(CW$repo_path\fR is a local mirror of the +upstream repo. This is likely to change in an upcoming version. +.PP +The location depends on the \f(CW\*(C`SBO_HOME\*(C'\fR config setting. .SH SUBROUTINES .IX Header "SUBROUTINES" .SS check_git_remote @@ -93,10 +109,9 @@ The location depends on the \f(CW\*(C`SBO_HOME\*(C'\fR config setting. \& my $bool = check_git_remote($path, $url); .Ve .PP -\&\f(CWcheck_git_remote()\fR will check if the repository at \f(CW$path\fR is a git -repository and if so, it will check if it defined an \f(CW\*(C`origin\*(C'\fR remote that -matches the \f(CW$url\fR. If so, it will return a true value. Otherwise it will -return a false value. +\&\f(CWcheck_git_remote()\fR checks if the repository at \f(CW$path\fR is a git repository. +If so, it checks for a defined \f(CW\*(C`origin\*(C'\fR remote matching \f(CW$url\fR. If so, it returns +a true value, and a false value otherwise. .SS check_repo .IX Subsection "check_repo" .Vb 1 @@ -115,6 +130,10 @@ regardless of fetch method. .PP If \f(CW$repo_path\fR does not exist, creation will be attempted, returning a true value on success. Creation failure results in a usage error. +.PP +\&\fBNote\fR: This is a prime candidate for changes in an upcoming version. +In principle, it would be better to check that the contents of \f(CW$repo_path\fR +are sufficiently similar to an SBo mirror to continue safely. (KEC) .SS chk_slackbuilds_txt .IX Subsection "chk_slackbuilds_txt" .Vb 1 @@ -124,49 +143,57 @@ value on success. Creation failure results in a usage error. \&\f(CWchk_slackbuilds_txt()\fR checks if the file \f(CW\*(C`SLACKBUILDS.TXT\*(C'\fR exists in the correct location, and returns a true value if it does, and a false value otherwise. +.PP +\&\fBNote\fR: It is possible that some code related to repository detection +independent of \f(CW\*(C`SLACKBUILDS.TXT\*(C'\fR will be placed here. (KEC) .SS fetch_tree .IX Subsection "fetch_tree" .Vb 1 \& fetch_tree(); .Ve .PP -\&\f(CWfetch_tree()\fR will make sure the \f(CW$repo_path\fR exists and is empty, and then -fetch the SlackBuilds.org repository tree there. +\&\f(CWfetch_tree()\fR checks that \f(CW$repo_path\fR exists and is empty, and then fetches +the SlackBuilds.org repository. .PP -If the \f(CW$repo_path\fR is not empty, it will exit with a usage error. +If the \f(CW$repo_path\fR exists and is non-empty, the user will see a series of prompts +from \f(CWcheck_repo()\fR before the fetch proceeds. .SS generate_slackbuilds_txt .IX Subsection "generate_slackbuilds_txt" .Vb 1 \& my $bool = generate_slackbuilds_txt(); .Ve .PP -\&\f(CWgenerate_slackbuilds_txt()\fR will generate a minimal \f(CW\*(C`SLACKBUILDS.TXT\*(C'\fR for a -repository that doesn't come with one. If it fails, it will return a false -value. Otherwise it will return a true value. +\&\f(CWgenerate_slackbuilds_txt()\fR generates a minimal \f(CW\*(C`SLACKBUILDS.TXT\*(C'\fR for +repositories that do not include this file. If the file cannot be opened for +write, it returns a false value. Otherwise, it returns a true value. .SS git_sbo_tree .IX Subsection "git_sbo_tree" .Vb 1 \& my $bool = git_sbo_tree($url); .Ve .PP -\&\f(CWgit_sbo_tree()\fR will \f(CW\*(C`git clone\*(C'\fR the repository specified by \f(CW$url\fR to the -\&\f(CW$repo_path\fR if the \f(CW$url\fR repository is not already there. If it is, it will -run \f(CW\*(C`git fetch && git reset \-\-hard origin\*(C'\fR. +\&\f(CWgit_sbo_tree()\fR will \f(CW\*(C`git clone \-\-no\-local\*(C'\fR the repository specified by \f(CW$url\fR to the +\&\f(CW$repo_path\fR if the \f(CW$url\fR repository is not present. If it is, it runs +\&\f(CW\*(C`git fetch && git reset \-\-hard origin\*(C'\fR. .PP -If any command fails, it will return a false value. Otherwise it will return a -true value. +If \f(CW\*(C`GIT_BRANCH\*(C'\fR is set, or the if running or configured Slackware version has a +recommended git branch, \f(CW\*(C`git checkout\*(C'\fR is attempted. If successful, \f(CW\*(C`git pull\*(C'\fR follows. +.PP +If \f(CW\*(C`GPG_VERIFY\*(C'\fR is \f(CW\*(C`TRUE\*(C'\fR, \f(CW\*(C`gnupg\*(C'\fR verification proceeds with \f(CWverify_git_commit($branch)\fR +at the end of the subroutine. .SS pull_sbo_tree .IX Subsection "pull_sbo_tree" .Vb 1 \& pull_sbo_tree(); .Ve .PP -\&\f(CWpull_sbo_tree()\fR will pull the SlackBuilds.org repository tree from -\&\f(CW\*(C`rsync://slackbuilds.org/slackbuilds/$ver/\*(C'\fR or whatever the \f(CW\*(C`REPO\*(C'\fR -configuration variable has been set to. +\&\f(CWpull_sbo_tree()\fR pulls the SlackBuilds.org repository tree from +the default in \f(CW%supported\fR for the running Slackware version (accounting +for \f(CW\*(C`SLACKWARE_VERSION\*(C'\fR, \f(CW\*(C`RSYNC_DEFAULT\*(C'\fR and \f(CW\*(C`REPO\*(C'\fR). .PP -\&\f(CW$ver\fR is the version of Slackware you are running, provided it is supported, -or whatever you've set in the \f(CW\*(C`SLACKWARE_VERSION\*(C'\fR configuration variable. +\&\f(CW$ver\fR is the running or configured version of Slackware, provided that it +is supported. Version support verification occurs in \f(CWget_slack_version_url()\fR +via \f(CWget_slack_version()\fR; see \f(CWSBO::Lib::Util(3)\fR. .SS rsync_sbo_tree .IX Subsection "rsync_sbo_tree" .Vb 1 @@ -175,23 +202,28 @@ or whatever you've set in the \f(CW\*(C`SLACKWARE_VERSION\*(C'\fR configuration .PP \&\f(CWrsync_sbo_tree()\fR syncs the SlackBuilds.org repository to \f(CW$repo_path\fR from the \f(CW$url\fR provided. +.PP +If \f(CW\*(C`GPG_VERIFY\*(C'\fR is \f(CW\*(C`TRUE\*(C'\fR, \f(CW\*(C`gnupg\*(C'\fR verification proceeds with \f(CWverify_rsync("fullcheck")\fR +at the end of the subroutine. .SS slackbuilds_or_fetch .IX Subsection "slackbuilds_or_fetch" .Vb 1 \& slackbuilds_or_fetch(); .Ve .PP -\&\f(CWslackbuilds_or_fetch()\fR will check if there is a \f(CW\*(C`SLACKBUILDS.TXT\*(C'\fR in the -\&\f(CW$repo_path\fR, and if not, offer to fetch the tree. +\&\f(CWslackbuilds_or_fetch()\fR checks for the file \f(CW\*(C`SLACKBUILDS.TXT\*(C'\fR in +\&\f(CW$repo_path\fR. If not, it offers to fetch the tree. +.PP +\&\fBNote\fR: Changes are likely once \f(CW\*(C`SLACKBUILDS.TXT\*(C'\fR is no longer needed +for checking that a local copy of the repository exists. (KEC) .SS update_tree .IX Subsection "update_tree" .Vb 1 \& update_tree(); .Ve .PP -\&\f(CWupdate_tree()\fR will check if there is a \f(CW\*(C`SLACKBUILDS.TXT\*(C'\fR in the -\&\f(CW$repo_path\fR, and if not, will run \f(CWfetch_tree()\fR. Otherwise it will update -the SlackBuilds.org tree. +\&\f(CWupdate_tree()\fR checks for \f(CW\*(C`SLACKBUILDS.TXT\*(C'\fR in \f(CW$repo_path\fR. If not, it runs +\&\f(CWfetch_tree()\fR. Otherwise, it updates the SlackBuilds.org tree. .SS verify_git_commit .IX Subsection "verify_git_commit" .Vb 1 @@ -199,8 +231,10 @@ the SlackBuilds.org tree. .Ve .PP \&\f(CWverify_git_commit()\fR attempts to verify the GPG signature of the most -recent git commit, if any. Git commit verification is unavailable for -Slackware 14.0 and Slackware 14.1. +recent git commit, if any. +.PP +Git commit verification is unavailable for Slackware 14.0 and Slackware 14.1. +A user prompt for continuation appears if \f(CW\*(C`GPG_VERIFY\*(C'\fR is \f(CW\*(C`TRUE\*(C'\fR. .SS verify_rsync .IX Subsection "verify_rsync" .Vb 1 @@ -209,9 +243,11 @@ Slackware 14.0 and Slackware 14.1. .PP \&\f(CWverify_rsync()\fR checks the signature of CHECKSUMS.md5.asc, prompting the user to download the public key if not present. If "fullcheck" is passed (i.e., when syncing the local -repository), md5 verification is performed as well. Failure at any juncture leaves a lockfile -\&.rsync.lock in SBO_HOME, which prevents script installation and upgrade until the issue has -been resolved, GPG_TRUE is set to FALSE or the lockfile is removed. +repository), md5sum verification is performed as well. +.PP +Failure at any juncture leaves a lockfile \f(CW\*(C`.rsync.lock\*(C'\fR in \f(CW\*(C`SBO_HOME\*(C'\fR, which prevents +script installation and upgrade until the issue has been resolved, \f(CW\*(C`GPG_TRUE\*(C'\fR is set to +\&\f(CW\*(C`FALSE\*(C'\fR or the lockfile is removed. .SS verify_gpg .IX Subsection "verify_gpg" .Vb 1 @@ -219,15 +255,20 @@ been resolved, GPG_TRUE is set to FALSE or the lockfile is removed. .Ve .PP \&\f(CW\*(C`verify_gpg\*(C'\fR determines whether a git repo is in use, and then -runs GnuPG verification. It can be called from outside Repo.pm. +runs \f(CW\*(C`gnupg\*(C'\fR verification. It is exportable, and is currently used in +\&\f(CWsboinstall(1)\fR, \f(CWsboupgrade(1)\fR and \f(CWsbocheck(1)\fR. .SS retrieve_key .IX Subsection "retrieve_key" .Vb 1 \& retrieve_key($fingerprint); .Ve .PP -\&\f(CW\*(C`retrieve_key\*(C'\fR attempts to retrieve a missing public key and add it to -the keyring. +\&\f(CW\*(C`retrieve_key\*(C'\fR attempts to retrieve a missing public key from +\&\f(CW\*(C`hkp://keyserver.ubuntu.com:80\*(C'\fR and add it to the keyring. +.PP +\&\f(CW\*(C`gnupg\*(C'\fR output is saved to \f(CW$key_log\fR, and the output of +\&\f(CW\*(C`gpg \-\-no\-batch \-\-search\-keys\*(C'\fR is displayed with a prompt to ensure +that the user can trust the key. .SH AUTHORS .IX Header "AUTHORS" SBO::Lib was originally written by Jacob Pipkin with diff --git a/man3/SBO::Lib::Tree.3 b/man3/SBO::Lib::Tree.3 index a46219c2..8fb73115 100644 --- a/man3/SBO::Lib::Tree.3 +++ b/man3/SBO::Lib::Tree.3 @@ -86,18 +86,19 @@ given \f(CW$sbo\fR. \& my $loc = get_sbo_location([$sbo, ...]); .Ve .PP -\&\f(CWget_sbo_location()\fR returns the location in the \f(CW\*(C`LOCAL_OVERRIDES\*(C'\fR or the +\&\f(CWget_sbo_location()\fR returns the location in \f(CW\*(C`LOCAL_OVERRIDES\*(C'\fR or the SlackBuilds.org tree for the first \f(CW$sbo\fR given. .PP -Specifying more than one \f(CW$sbo\fR is useful for only needing to access the -filesystem once when searching, and populating the internal cache. +Specifying more than one \f(CW$sbo\fR is useful only for accessing the +filesystem once when searching or populating the internal cache. No +code does this currently. .SS get_sbo_locations .IX Subsection "get_sbo_locations" .Vb 1 \& my %locations = get_sbo_locations(@sbos); .Ve .PP -\&\f(CW\*(C`get_sbo_locations\*(C'\fR tries to find all \f(CW@sbos\fR and returns a hash matching the +\&\f(CW\*(C`get_sbo_locations\*(C'\fR finds all SlackBuilds in \f(CW@sbos\fR, returns a hash matching each package name to its location. .SS is_local .IX Subsection "is_local" @@ -106,7 +107,7 @@ package name to its location. .Ve .PP \&\f(CWis_local()\fR checks whether the given \f(CW$sbo\fR is in the \f(CW\*(C`LOCAL_OVERRIDES\*(C'\fR or -not, and returns a true value if it is, and a false value if it is not. +not. The return value is true if it is, and false if it is not. .SH AUTHORS .IX Header "AUTHORS" SBO::Lib was originally written by Jacob Pipkin with diff --git a/man3/SBO::Lib::Util.3 b/man3/SBO::Lib::Util.3 index 15967513..20647cec 100644 --- a/man3/SBO::Lib::Util.3 +++ b/man3/SBO::Lib::Util.3 @@ -90,6 +90,11 @@ they change according to the configuration. \f(CW\*(C`SBO_HOME\*(C'\fR is change The supported keys are: \f(CW\*(C`NOCLEAN\*(C'\fR, \f(CW\*(C`DISTCLEAN\*(C'\fR, \f(CW\*(C`JOBS\*(C'\fR, \f(CW\*(C`PKG_DIR\*(C'\fR, \&\f(CW\*(C`SBO_HOME\*(C'\fR, \f(CW\*(C`LOCAL_OVERRIDES\*(C'\fR, \f(CW\*(C`SLACKWARE_VERSION\*(C'\fR, \f(CW\*(C`REPO\*(C'\fR, \f(CW\*(C`BUILD_IGNORE\*(C'\fR, \&\f(CW\*(C`GPG_VERIFY\*(C'\fR and \f(CW\*(C`RSYNC_DEFAULT\*(C'\fR. +.ie n .SS @listings +.el .SS \f(CW@listings\fP +.IX Subsection "@listings" +An array with blacklisted packages and optional dependency requests read in +from \f(CW\*(C`/etc/sbotools/sbotools.hints\*(C'\fR. Non-exportable. .SH SUBROUTINES .IX Header "SUBROUTINES" .SS build_cmp @@ -338,7 +343,7 @@ list in the same order. \& usage_error($msg); .Ve .PP -\&\f(CW\*(C`usage_error\*(C'\fR warns and exits, printing \f(CW$msg\fR to STDERR. +\&\f(CWusage_error()\fR warns and exits, printing \f(CW$msg\fR to STDERR. .PP There is no useful return value. .SS version_cmp diff --git a/slackbuild/sbotools/README b/slackbuild/sbotools/README index 124a607f..5b21c97b 100644 --- a/slackbuild/sbotools/README +++ b/slackbuild/sbotools/README @@ -6,7 +6,8 @@ using a custom git branch, generating 32-bit and compat32 builds on multilib systems, reverse dependency search, gpg verification and more. There is a man page for each included command. For 'executive -summaries' and online man pages, see the project's home page. +summaries' and online man pages, see the project's home page. The +SBO::LIB::* modules are documented in man 3. sbotools bundles the required Perl module Sort::Versions. This does not interfere with a copy installed from the CPAN or from diff --git a/slackbuild/sbotools/sbotools.SlackBuild b/slackbuild/sbotools/sbotools.SlackBuild index a85f6641..6e4fbcd0 100644 --- a/slackbuild/sbotools/sbotools.SlackBuild +++ b/slackbuild/sbotools/sbotools.SlackBuild @@ -73,7 +73,7 @@ find -L . \ ) SCRIPTS="check clean config find install remove snap upgrade" -MANS="man1 man5" +MANS="man1 man3 man5" mkdir -p $PKG/usr/sbin \ $PKG/usr/share/zsh/site-functions \