Mostly font changes to both man pages

Also added several more points to HACKING which cover most of the other
changes - there are a few semantic/textual changes in here, too. The
largest changes are probably a making the 'type' of the conf values a
part of the 'template', moving and adding complete authors to both
This commit is contained in:
slakmagik 2010-06-02 23:05:31 +00:00
parent b555c36c94
commit 355a3176fb
3 changed files with 641 additions and 238 deletions

View File

@ -257,3 +257,24 @@ Manual Page Style Guidelines
* Try to be as specific as conveniently possible, where 'convenient' means to
generalize wherever constant updates might be necessary and such
generalization wouldn't compromise clarity and accuracy.
* Italicize filenames, URLs, replaceable terms (including references to
unspecified variable values ($VARs).
* Embolden variables (when used literally rather than replaceably), option
values, programs, program flags, and all references to sbopkg itself.
* Use `` and '' for double-quotes so groff does the fancy stuff for ps output.
* Make all option dashes in the form \- (or \-\-) unless in a code example.
* .EX doesn't seem to be very well supported or necessarily what is wanted -
code examples can be done with the following cookie-cutter code:
.RS
.IP \" or .PP or whatever's appropriate
.nf
\fCline_of_code\fP
.fi
.RE
If inline, at least embolden them so they're set off in ascii overstrike
output.
* Start configuration file option sections with a statement of type, a
description, and the following cookie-cutter code:
The default assignment is:
.IP
\fCdefault_assignment\fP

View File

@ -5,29 +5,39 @@
sbopkg.conf \- configuration file for sbopkg
.\"=====================================================================
.SH DESCRIPTION
The sbopkg.conf file contains configuration settings for
The
.I sbopkg.conf
file contains configuration settings for
.BR sbopkg (8),
a tool for interacting with the SlackBuilds.org ("SBo") repository, a
a tool for interacting with the SlackBuilds.org (``SBo'') repository, a
collection of third-party SlackBuild scripts to build Slackware
packages.
A sample file is provided at /etc/sbopkg/sbopkg.conf.new.
Also, please see a note below about ARCH.
The default configuration file is installed at
.IR /etc/sbopkg/sbopkg.conf .
Also, please see the subsection below about
.BR ARCH .
.PP
Boolean options are case-insensitive.
All boolean options require a
.B YES
or a
.B NO
without regard to case. All path values must be full.
.PP
The different configuration options are:
The default configuration options are:
.\"---------------------------------------------------------------------
.TP 3
.B ALLOW_MULTI
This option should be set to YES or NO.
When set to YES, this option allows the user to run multiple instances
of sbopkg.
Boolean.
.IP
When set to
.BR YES ,
this option allows the user to run multiple instances of
.BR sbopkg .
.IP
Please understand that this option is provided for convenience, but
given the number of potential issues you can face when enabling this
(and we aren't going to try to work around users doing silly things),
you should consider working with ALLOW_MULTI=YES as an EXPERIMENTAL
UNSUPPORTED feature.
you should consider this an EXPERIMENTAL UNSUPPORTED feature.
If you encounter problems, please try to make sure these aren't caused
by yourself doing improper things.
.IP
@ -36,15 +46,18 @@ option enabled:
.RS 5
.TP 3
\(bu
run an ALLOW_MULTI=NO instance together with one or more having
ALLOW_MULTI=YES
run instances with a mixture of
.B YES
and
.B NO
settings
.TP
\(bu
sync a repository when another instance is using it
.TP
\(bu
change the branch of a git repository when another instance is using it
(you can do this with rsync -- i.e., SlackBuild.org -- repos)
(this caveat does not apply to rsync repositories)
.TP
\(bu
simultaneously build or install the same package from different
@ -63,13 +76,27 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B CLEANUP
This option should be set to YES or NO.
When set to YES, the unpacked source files and package tree in $TMP are
deleted right after the build, though the downloaded source archive and
completed package are left in $SRCDIR and $OUTPUT.
Boolean.
.IP
A side effect of setting CLEANUP to YES is that TMP is set to an
internal value and any other TMP setting is ignored.
When set to
.BR YES ,
the unpacked source files and package tree in
.I $TMP
are deleted right after the build, though the downloaded source archive
and completed package are left in
.I $SRCDIR
and
.IR $OUTPUT .
.IP
A side effect of setting
.B CLEANUP
to
.B YES
is that
.B TMP
is set to an internal value and any other
.B TMP
setting is ignored.
.IP
The default assignment is:
.IP
@ -77,16 +104,33 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B DEBUG
This option should be set to 0, 1, or 2.
DEBUG sets the default debugging level for the update list feature of
sbopkg.
When DEBUG is set to 0, then only potential updated (or downgraded)
packages are listed.
When DEBUG is set to 1, then potential updates plus packages not in the
repo and packages that are newer than the repo are listed.
When DEBUG is set to 2, all non-updated packages are also listed.
Changing DEBUG to 1 or 2 may be helpful if it appears the updatelist
might be missing an update.
Enumeration.
.IP
This option should be set to
.BR 0 ,
.BR 1 ,
or
.BR 2 .
.B DEBUG
sets the default debugging level for the update list feature of
.BR sbopkg .
When set to
.BR 0 ,
only potential updated (or downgraded) packages are listed.
When set to
.BR 1 ,
potential updates plus packages not in the repo and packages that are
newer than the repo are listed.
When set to
.BR 2 ,
all non-updated packages are also listed.
Changing
.B DEBUG
to
.B 1
or
.B 2
may be helpful if it appears the updatelist might be missing an update.
.IP
The default assignment is:
.IP
@ -94,7 +138,10 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B DIFF
This option allows the user to set which diff program to use when sbopkg
Command.
.IP
This option allows the user to set which diff program to use when
.B sbopkg
displays differences between edited files.
.IP
The default assignment is:
@ -103,8 +150,13 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B DIFFOPTS
This option allows the user to set which options are used by the $DIFF
program when sbopkg displays differences between edited files.
Command options.
.IP
This option allows the user to set which options are used by the
.I $DIFF
program when
.B sbopkg
displays differences between edited files.
.IP
The default assignment is:
.IP
@ -112,11 +164,16 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B KEEPLOG
This option should be set to YES or NO.
Boolean.
.IP
This option allows the user to choose whether to keep a permanent log of
packages that are built with sbopkg in order to go back and review the
build, and any errors, after exiting sbopkg.
If set to YES, this permanent log is saved at $LOGDIR/sbopkg-build-log.
packages that are built with
.B sbopkg
in order to go back and review the build, and any errors, after exiting
.BR sbopkg .
See
.B LOGFILE
for where this log is.
.IP
The default assignment is:
.IP
@ -124,8 +181,12 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B LOGFILE
This option (which must be set to a full path) sets the name for the
build log if KEEPLOG is set to YES.
Path.
.IP
This option sets the name for the build log if
.B KEEPLOG
is set to
.BR YES .
.IP
The default assignment is:
.IP
@ -133,13 +194,18 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B MKDIR_PROMPT
This option may be set to YES or NO.
When set to YES, sbopkg will prompt for confirmation before changing the
filesystem by creating its directories.
Boolean.
.IP
When set to
.BR YES ,
.B sbopkg
will prompt for confirmation before changing the filesystem by creating
its directories.
If you do not wish to be prompted (for instance, if you have some of the
directories on a temporary filesystem and don't wish to be prompted for
confirmation each time the filesystem is reinitialized) you can set this
to NO.
to
.BR NO .
.IP
The default assignment is:
.IP
@ -147,11 +213,15 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B OUTPUT
Path.
.IP
This option sets the default directory where compiled packages are
saved.
OUTPUT must be exported as it is also used by the SBo SlackBuilds.
Also note that the default value of OUTPUT is therefore the same as in
the SBo SlackBuilds.
.B OUTPUT
must be exported as it is also used by the SBo SlackBuilds.
Note that the default value of
.B OUTPUT
is therefore the same as in the SBo SlackBuilds.
.IP
The default assignment is:
.IP
@ -159,6 +229,8 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B QUEUEDIR
Path.
.IP
This option defines the directory under which saved queue files will be
kept.
.IP
@ -168,9 +240,18 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B REPO_BRANCH
Enumeration.
.IP
This option allows the user to set the default active repository branch.
The current options are listed in the default repos.d/* files and can
also be listed by issuing 'sbopkg -V ?'.
The current standard values are listed in the default
.I repos.d/*
files and can also be listed by issuing
.RS
.IP
.nf
\fCsbopkg -V ?\fP
.fi
.RE
.IP
The default assignment is:
.IP
@ -178,14 +259,24 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B REPO_NAME
Enumeration.
.IP
This option allows the user to choose the repository to use.
The default options are SBo, SB64 and local.
The 'local' choice corresponds to a user-maintained repository whose
See
.B REPO_BRANCH
for how to get an enumeration of standard values.
The ``local'' choice corresponds to a user-maintained repository whose
structure must be the same as the one used by SlackBuilds.org, in the
sense of a category/package/files hierarchy.
NOTE: all of the REPO_* variables are affected by the repository files
maintained in /etc/sbopkg/repos.d.
Please see the README-repos.d document in the sbopkg /doc directory.
sense of a
.I category/package/files
hierarchy.
Note: all of the
.B REPO_*
variables are affected by the repository files maintained in
.I /etc/sbopkg/repos.d.
Please see the
.I README-repos.d
document in the sbopkg documentation directory.
.IP
The default assignment is:
.IP
@ -193,6 +284,8 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B REPO_ROOT
Path.
.IP
This option allows the user to set the location of the local mirrors of
the remote repositories.
Currently, the size of a local copy of the SBo repository is about 70MB.
@ -203,15 +296,35 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B RSYNCFLAGS
Rsync is used by sbopkg to mirror the SlackBuilds.org repository.
This option allows the user to manually tweak the rsync flags (options)
that are used by sbopkg.
Command options.
.IP
.B Rsync
is used by
.B sbopkg
to mirror the SlackBuilds.org repository.
This option allows the user to manually tweak the
.B rsync
flags (options) that are used by
.BR sbopkg .
Users are cautioned against making any changes to the default values
since new flags may or may not work.
Note: the rsync command in sbopkg already uses the --archive, --delete,
--no-owner, and --exclude flags, so there is no need to add them to the
RSYNCFLAGS option.
Changing these default options is not recommended.
Note: the
.B rsync
command in
.B sbopkg
already uses the
.BR \-\-archive ,
.BR \-\-delete ,
.BR \-\-no-owner ,
and
.B \-\-exclude
flags, so there is no need to add them to the
.B RSYNCFLAGS
option.
Changing those internal default options is not recommended.
However,
.B \-\-timeout
is a useful option to play with if getting syncing errors.
.IP
The default assignment is:
.IP
@ -219,8 +332,12 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B SBOPKGTMP
This option sets the default directory where certain working files are
saved on a temporary basis.
Path.
.IP
This option sets the default directory where certain working files
specific to
.B sbopkg
are saved on a temporary basis.
.IP
The default assignment is:
.IP
@ -228,6 +345,8 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B SRCDIR
Path.
.IP
This option contains the location of the cache directory where source
downloads will be saved.
.IP
@ -237,13 +356,21 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B TMP
This option sets the default directory where built packages should be
stored.
TMP must be exported as it is used by the SlackBuilds.
Note that the default value of TMP is the same as in the SBo SlackBuild
scripts.
Path.
.IP
Also note that if the CLEANUP variable is set to YES, any custom TMP
This option sets the default directory where built packages are saved.
.B TMP
must be exported as it is also used by the SBo SlackBuilds.
Note that the default value of
.B TMP
is therefore the same as in the SBo SlackBuilds.
.IP
Also note that if the
.B CLEANUP
variable is set to
.BR YES ,
any custom
.B TMP
setting is ignored.
.IP
The default assignment is:
@ -252,15 +379,31 @@ The default assignment is:
.\"---------------------------------------------------------------------
.TP
.B WGETFLAGS
Wget is used by sbopkg to download the source files for package
building.
This option allows the user to manually tweak the wget flags (options)
that are used by sbopkg.
Command options.
.IP
.B Wget
is used by
.B sbopkg
to download the source files for package building.
This option allows the user to manually tweak the
.B wget
flags (options) that are used by
.BR sbopkg .
Users are cautioned against making any changes to the default values
since new flags may or may not work.
Note: the wget command in sbopkg already uses the -O flag, so there is
no need to add that to the WGETFLAGS option.
Changing these default options is not recommended.
Note: the
.B wget
command in
.B sbopkg
already uses the
.B \-O
flag, so there is no need to add that to the
.B WGETFLAGS
option.
Changing most of these default options is not recommended.
However,
.B \-\-timeout
is a useful option to play with if getting download errors.
.IP
The default assignment is:
.IP
@ -270,46 +413,115 @@ The default assignment is:
.\"---------------------------------------------------------------------
.SS Overriding Environmental Variables
It is possible to set or override environmental variables and pass them
to the SlackBuild scripts when they are built from within sbopkg.
This is already demonstrated in the following line in the sbopkg.conf
to the SlackBuild scripts when they are built from within
.BR sbopkg .
This is already demonstrated in the following example line (and others
like it) in the
.I sbopkg.conf
file:
.PP
export TMP=${TMP:-/tmp/SBo}
.RS
.nf
\fCexport TMP=${TMP:-/tmp/SBo}\fP
.fi
.RE
.PP
This sets TMP to /tmp/SBo for building SBo packages within sbopkg (which
is currently the default for SBo SlackBuilds already).
Since this variable is exported, it could be changed for both sbopkg and
for building SBo packages within sbopkg.
This sets
.B TMP
to
.I /tmp/SBo
for building SBo packages within
.B sbopkg
(which is currently the default for SBo SlackBuilds already).
Since this variable is exported, it could be changed for both
.B sbopkg
and for building SBo packages within
.BR sbopkg .
For example, changing this line so it reads:
.PP
export TMP=${TMP:-/home/sbo/tmp}
.RS
.nf
\fCexport TMP=${TMP:-/home/sbo/tmp}\fP
.fi
.RE
.PP
would then set TMP to /home/sbo/tmp for building SBo packages.
OUTPUT can also be changed to save compiled packages in a location other
than the default of /tmp.
would then set
.B TMP
to
.I /home/sbo/tmp
for building SBo packages and still allow it to be overridden at runtime
by invoking
.B sbopkg
as
.RS
.PP
You can also export variables in sbopkg.conf that are not used by sbopkg
.nf
\fCexport TMP=foo; sbopkg\fP
.fi
.RE
.PP
.B OUTPUT
can also be changed to save compiled packages in a location other than
the default of
.IR /tmp .
.PP
You can also export variables in
.I sbopkg.conf
that are not used by
.B sbopkg
at all.
.\"---------------------------------------------------------------------
.SS About the ARCH Variable
You may be wondering why ARCH is not a configuration setting in the
default sbopkg.conf file.
You may be wondering why
.B ARCH
is not a configuration setting in the default
.I sbopkg.conf
file.
The reason is that it does not have to be.
If ARCH is not set, sbopkg does some checking (using 'uname -m') to
determine what the system's architecture is.
If the architecture is x86, x86_64, or arm*, then sbopkg automatically
sets ARCH to i486, x86_64, or arm, respectively.
If ARCH is set, sbopkg will inherit that setting.
This means the user can add, for example, 'export ARCH=i686' in their
\&.bashrc or similar file, or the user can also execute something in the
root terminal like 'export ARCH=i686 && sbopkg'.
The user can also manually add it to their sbopkg.conf file if they
wish.
Finally, if ARCH is not set by the user and sbopkg does not detect one
of the previously mentioned architectures, then ARCH will be set by
whatever is in the SlackBuild scripts.
If
.B ARCH
is not set,
.B sbopkg
does some checking (using the output of
.BR "uname \-m" )
to determine what the system's architecture is.
If the architecture is x86, x86_64, or arm*, then
.B sbopkg
automatically sets
.B ARCH
to i486, x86_64, or arm, respectively.
If
.B ARCH
is set,
.B sbopkg
will inherit that setting.
This means the user can add, for example,
.B export ARCH=i686
in their
.I .bashrc
or similar file, or the user can also execute something in the
root terminal like
.RS
.PP
.nf
\fCexport ARCH=i686; sbopkg\fP
.fi
.RE
.PP
The user can also manually add it to their
.I sbopkg.conf
file if they wish.
Finally, if
.B ARCH
is not set by the user and
.B sbopkg
does not detect one of the previously mentioned architectures, then
.B ARCH
will be set by whatever is in the SlackBuild scripts.
Note that the SlackBuild may, in certain instances, discard or override
previous ARCH settings if this is required for the build.
previous
.B ARCH
settings if this is required for the build.
.\"=====================================================================
.SH FILES
.TP 3
@ -317,15 +529,31 @@ previous ARCH settings if this is required for the build.
File to specify configuration options.
.TP
.I /etc/sbopkg/renames.d/50-default
Default file that lists software in SBo repository that has been
Default file that lists software in the SBo repository that has been
renamed.
See the README-renames.d document in the sbopkg doc/ directory for more
information.
See the
.I README-renames.d
document in the sbopkg documentation directory for more information.
.TP
.I /etc/sbopkg/repos.d/{40-sbo.repo,50-sb64.repo,60-local.repo}
Three default files for various types of sbopkg repositories.
See the README-repos.d document in the sbopkg doc/ directory for more
information.
Three default files for various types of
.B sbopkg
repositories.
See the
.I README-repos.d
document in the
.B sbopkg
documentation directory for more information.
.\"=====================================================================
.SH AUTHORS
Chess Griffin
<chess@chessgriffin.com>
.PP
Mauro Giachero
<mauro.giachero@gmail.com>
.PP
slakmagik
<slakmagik@gmail.com>
.\"=====================================================================
.\" Make the release process handle a DOCDIR here? But the files from
.\" the official tarball go here.

View File

@ -9,42 +9,63 @@ sbopkg \- the SlackBuilds.org package browser
.RI [ options ]
.\"=====================================================================
.SH DESCRIPTION
Sbopkg is a command-line and dialog-based tool to interact with the
SlackBuilds.org ("SBo") repository, a collection of third-party
SlackBuild scripts to build Slackware packages.
.B Sbopkg
is a command-line and
.BR dialog -based
tool to interact with the SlackBuilds.org (``SBo'') repository, a
collection of third-party SlackBuild scripts to build Slackware
packages.
.\"=====================================================================
.SS Instructions
Sbopkg usage assumes an understanding of SlackBuild scripts, generally,
and the third-party repository SlackBuilds.org, specifically.
A thorough reading of http://www.slackbuilds.org/howto/ and the pages at
http://www.slackwiki.org about SlackBuild scripts is strongly advised.
.B Sbopkg
usage assumes an understanding of SlackBuild scripts, generally, and the
third-party repository SlackBuilds.org, specifically.
A thorough reading of
.I http://www.slackbuilds.org/howto/
and the pages at
.I http://www.slackwiki.org
about SlackBuild scripts is strongly advised.
.PP
In order for sbopkg to be used, a configuration file must exist at
/etc/sbopkg/sbopkg.conf.
An initial install will provide the user with an /etc/sbopkg/sbopkg.conf
while upgrades will add an /etc/sbopkg/sbopkg.conf.new which may be
merged with or replace the older version.
In order for
.B sbopkg
to be used, a configuration file must exist at
.IR /etc/sbopkg/sbopkg.conf .
An initial install will provide the user with that file while upgrades
will add an
.I /etc/sbopkg/sbopkg.conf.new
which may be merged with or replace the older version.
See
.BR sbopkg.conf (5)
for more information about the configuration file.
.PP
Sbopkg must be run as the root user (since the SlackBuild scripts at
.B Sbopkg
must be run as the root user (since the SlackBuild scripts at
SlackBuilds.org are written with the intention of being run as root).
Furthermore, using 'su -' instead of 'su' is strongly encouraged.
Furthermore, using the
.B \-
option with
.B su
is strongly encouraged.
The reason is that some SlackBuild scripts rely on certain tools that
are only available in root's PATH when the scripts in /etc/profile.d
have been run (i.e., texmf to build man pages), which is only done for
login shells, or otherwise require a 'truer' root environment than that
given by only 'su'.
are only available in root's
.B PATH
when the scripts in
.I /etc/profile.d
have been run (i.e.,
.B texmf
to build man pages), which is only done for login shells, or otherwise
require a ``truer'' root environment than that given by only
.BR su .
In any event, invoking
.B sbopkg
with no arguments (or with just
.BR -d ,
.B -f
.BR \-d ,
.B \-f
or
.BR -V )
will launch the dialog-based interface, and the menus provided should be
fairly self-explanatory.
.BR \-V )
will launch the
.BR dialog -based
interface, and the menus provided should be fairly self-explanatory.
The main menu allows the user to synchronize with the SlackBuilds.org
repository.
This is the first step to take (after configuration) with a new install
@ -52,75 +73,137 @@ of
.BR sbopkg .
Currently, the size of a local copy of the SBo repository is about 70MB.
The main menu also allows the user to view the SlackBuilds.org
ChangeLog, check for potential updates to SBo packages, display the
contents of the local cache directory where source tarballs are saved,
display the permanent build log, and browse or search the local copy of
the SBo repository.
.IR ChangeLog ,
check for potential updates to SBo packages, display the contents of the
local cache directory where source tarballs are saved, display the
permanent build log, and browse or search the local copy of the SBo
repository.
Once the browse function is chosen, the user can select the category of
software to view.
After choosing a category, the user can then view the various software
packages available in that category within the local SBo repository.
Selecting a package will display another menu allowing the user to view
the package's README, SlackBuild, .info, or slack-desc files.
The user can also edit the .info file and SlackBuild and the edited
files will remain after doing an rsync.
Additionally, the user can choose to build a package as well using
either the original SlackBuild or the locally-edited one, if present.
If using the dialog interface, and if sbopkg finds a built package for a
particular piece of software in the OUTPUT directory, then sbopkg will
automatically add a new menu entry allowing the user to install the
package if he so chooses.
Alternatively, the user can choose to automatically build or build and
install individual packages or several packages in a build queue.
Finally, if KEEPLOG is set to YES in the sbopkg.conf file then a
permanent log of the build process is saved to wherever LOGFILE is set
to in that same file.
the package's
.IR README ,
.IR SlackBuild ,
.IR .info ,
or
.I slack-desc
files.
The user can also edit the
.I .info
file and
.I SlackBuild
and the edited files will remain after doing a sync.
Additionally, the user can choose to build a package using either the
original
.I SlackBuild
or the locally-edited one, if present.
If using the
.B dialog
interface, and if
.B sbopkg
finds a built package for a particular piece of software in the
.B OUTPUT
directory, then
.B sbopkg
will automatically add a new menu entry allowing the user to install the
package if he chooses.
Alternatively, the user can choose to automatically build, or both build
and install, individual packages or several packages in a build queue.
Finally, if
.B KEEPLOG
is set to YES in the
.B sbopkg.conf
file then a permanent log of the build process is saved.
See
.BR sbopkg.conf (5)
under
.B KEEPLOG
and
.B LOGFILE
for details.
.PP
Alternatively, sbopkg can be run from the command line without using the
dialog interface.
See below for the available command line options.
Alternatively,
.B sbopkg
can be run from the command line without using the
.B dialog
interface.
See the OPTIONS section for the available command line options.
.PP
Sbopkg also has the capability of loading, saving, and using
user-created queuefiles.
.B Sbopkg
also has the capability of loading, saving, and using user-created
queuefiles.
These queuefiles are simple text files with one application name per
line.
By default, when a queuefile is loaded in the dialog interface, the
application is selected, or "ON."
This can be changed by inserting a "-" in front of the application name
in the queuefile.
application is selected, or ``ON.''
This can be changed by inserting a ``-'' in front of the application
name in the queuefile.
Also, queuefiles can reference other queuefiles when the first character
is an "@".
See the readme-queuefiles document in the doc/ directory for more
information.
is an ``@''.
See the
.I readme-queuefiles
document in the documentation directory for more information.
.PP
Certain features of sbopkg rely on outside binaries, such as a pager to
view the text files when sbopkg is run from the comamnd line, and an
editor to edit the .info or SlackBuild files.
The pager function will look to the environmental variable PAGER and if
that variable is not defined then it will default to 'more.'
Similarly, the edit function found when sbopkg is used with the dialog
interface will look to the EDITOR variable and will default to 'vi' if
EDITOR is undefined.
If the user wants sbopkg to use another editor, such as nano, then
adding the requisite information in ~/.bashrc, /etc/profile, or other
similar configuration file to export EDITOR will suffice.
Certain features of
.B sbopkg
rely on outside binaries, such as a pager to view the text files when
.B sbopkg
is run from the command line, and an editor to edit the
.I .info
or
.I SlackBuild
files.
The paging functions will look to the environmental variable
.B PAGER
and, if that variable is not defined, it will default to
.BR more .
Similarly, the editing functions will look to
.B EDITOR
and will default to
.BR vi .
If the user wants
.B sbopkg
to use another editor, such as
.BR nano ,
then adding the requisite information in
.IR ~/.bashrc ,
.IR /etc/profile ,
or other similar configuration file to export
.B EDITOR
will suffice.
.\"=====================================================================
.SH OPTIONS
.\"---------------------------------------------------------------------
.TP 5
.BI \-b " PACKAGE(s)/QUEUE(s)"
Search for and build PACKAGE(s) from the local SBo repository.
If more than one package is specified, they must be in quotes.
Build packages of the argument(s) from the active repository.
If more than one package is specified, they must be quoted.
.IP
For example:
.RS
.IP
# sbopkg -b "foo bar"
.nf
\fC# sbopkg -b "foo bar"\fP
.fi
.RE
.IP
will build foo and then bar.
will build
.I foo
and then
.IR bar .
Queuefile names can also be specified.
In that case, all the packages specified in the queuefile will be built.
In the unfortunate case a token matches both a queuefile name and a
package name (i.e., the user named a queuefile with the name of a
package), sbopkg will ask the user which one should be used.
package),
.B sbopkg
will ask the user which one should be used.
A way to avoid this is to specify the queuefile with its
.I .sqf
extension.
Also, a mix of both packages and queuefiles may be given.
The tokens (package names or queuefiles) are processed in the order they
are specified on the command line, and the build order specified in the
queuefiles is retained.
@ -133,13 +216,15 @@ Display list of installed SBo packages and potential updates.
.\"---------------------------------------------------------------------
.TP
.BI \-d " DIRECTORY"
Manually specify the full path to the DIRECTORY containing the local SBo
repository.
Manually specify the full path to the
.I DIRECTORY
containing the local SBo repository.
.\"---------------------------------------------------------------------
.TP
.B \-e \fBask\fR|\fBcontinue\fR|\fBstop
Specify what sbopkg should do when it encounters an error while building
a package.
Specify what
.B sbopkg
should do when it encounters an error while building a package.
Valid options are:
.IP
.BR ask :
@ -147,26 +232,37 @@ This is the default behavior, asking the user what to do.
.IP
.BR continue :
Ignore the error and continue processing (act as if the user answered
"Yes" to all questions).
``Yes'' to all questions).
.IP
.BR stop :
Stop the processing (act as if the user answered "No" to all questions).
Stop the processing (act as if the user answered ``No'' to all questions).
.\"---------------------------------------------------------------------
.TP
.BI \-f " FILE"
Override the default configuration file, /etc/sbopkg/sbopkg.conf, with
another configuration file.
Override the default configuration file,
.IR /etc/sbopkg/sbopkg.conf ,
with another configuration file.
.\"---------------------------------------------------------------------
.TP
.BI \-g " PACKAGE(s)"
General search for PACKAGE(s) by glob.
General search for
.I PACKAGE(s)
by glob.
If more than one glob is specified, they must be quoted.
.IP
For example:
.RS
.IP
# sbopkg -g nv
.nf
\fC# sbopkg -g "foo bar"\fP
.fi
.RE
.IP
will return a list of matches, such as the nvidia packages,
konversation, and other packages with 'nv' in their name.
If more than one glob is specified, they must be in quotes.
will return a list of packages with either
.I foo
or
.I bar
in their names.
.\"---------------------------------------------------------------------
.TP
.B \-h
@ -174,37 +270,43 @@ Display the help.
.\"---------------------------------------------------------------------
.TP
.BI \-i " PACKAGE(s)/QUEUE(s)"
Build and install PACKAGE(s) from the local SBo repository.
If more than one package is specified, they must be in quotes, and the
packages will be built and then installed in the listed order.
For example:
Build and install packages of the argument(s) from the active
repository.
.IP
# sbopkg -i "foo bar"
See the
.B \-b
option for details since, other than the installation, these two options
operate similarly.
.IP
will build and install foo and then build and install bar.
By carefully considering the order of the packages listed, the user may
be able to build and install dependencies in the right order before the
final application is built and installed.
Note that by carefully considering the order of the packages listed, the
user may be able to build and install dependencies in the right order
before the final application is built and installed.
Of course, given the nature of dependencies, this may not always be
possible and so building dependencies like this is not really a
supported feature.
Still, when when it works, it can be helpful.
.IP
Queuefile names are supported, too.
See the explanation for the '-b' command for details.
.\"---------------------------------------------------------------------
.TP
.B \-k
When used together with -b or -i, this option tells sbopkg to skip
(i.e., don't build) any package it finds to be already installed.
When used together with
.B \-b
or
.BR \-i ,
this option tells
.B sbopkg
to skip (i.e., don't build) any package it finds to be already
installed.
.IP
Please note that only a name comparison is performed, so when this
option is specified sbopkg will also omit the build of different
versions of installed packages.
option is specified
.B sbopkg
will also omit the build of different versions of installed packages.
.\"---------------------------------------------------------------------
.TP
.B \-l
Display the SBo ChangeLog and quit.
Display the SBo
.I ChangeLog
and quit.
.\"---------------------------------------------------------------------
.TP
.B \-o
@ -212,12 +314,12 @@ List the currently installed cached source files which are deemed
obsolete, and optionally delete them.
.IP
Source files are obsolete when no SBo script references it any more,
which is something that can happen after rsync-ing the local repository.
which is something that can happen after syncing the local repository.
.IP
Please note that only the currently active repository is used to
identify the obsolete sources, so if the user builds packages with
different repositories (e.g., for different Slackware versions) the
source files only used in the "other" repository will be listed.
source files only used in the ``other'' repository will be listed.
.\"---------------------------------------------------------------------
.TP
.B \-P
@ -230,7 +332,7 @@ List installed SlackBuilds.org packages.
.\"---------------------------------------------------------------------
.TP
.B \-q
Enable the "quiet mode."
Enable the ``quiet mode.''
When this flag is specified, the output of some of the command-line
options is minimized.
.\"---------------------------------------------------------------------
@ -240,45 +342,80 @@ Rsync the local repository with SlackBuilds.org and quit.
.\"---------------------------------------------------------------------
.TP
.B \-R
Show all the README files of the queued packages before starting the
build.
Show all the
.I README
files of the queued packages before starting the build.
This is useful when the user wants to make a final check.
.\"---------------------------------------------------------------------
.TP
.BI \-s " PACKAGE(s)"
Specific search for PACKAGE(s) by PACKAGE name and, if found, display
the README, SlackBuild, .info, and slack-desc files in that order using
$PAGER, which defaults to 'more' as described above.
If more than one package is specified, they must be in quotes.
Specific search for
.I PACKAGE(s)
by name and, if found, display the
.IR README ,
.IR SlackBuild ,
.IR .info ,
and
.I slack-desc
files in that order for each
.I PACKAGE
found, using
.IR $PAGER .
If more than one package is specified, they must be quoted.
.IP
For example:
.RS
.IP
# sbopkg -s "foo bar"
.nf
\fC# sbopkg -s "foo bar"\fP
.fi
.RE
.IP
will search for foo and then bar.
will display all the above-mentioned files for packages whose names are
exactly
.I foo
or
.IR bar .
.\"---------------------------------------------------------------------
.TP
.B \-u
Check for an update to sbopkg itself and then quit.
Check for an update to
.B sbopkg
itself and then quit.
.\"---------------------------------------------------------------------
.TP
.BI \-V " VERSION"
Set the repository and branch to use.
.IP
For a list of valid versions, invoke sbopkg as
.BR "sbopkg -V ?" .
For a list of valid versions, invoke
.B sbopkg
as
.RS
.IP
.nf
\fCsbopkg -V ?\fP
.fi
.RE
.IP
See the
.BR sbopkg.conf (5)
man page for more information about the 'local' repository.
man page for more information about the ``local'' repository.
.IP
The VERSION format is repository/branch (e.g., SBo/13.1).
If the repository is omitted, sbopkg will first look for the specified
branch in the default repository.
If that attempt fails, sbopkg will look for the first matching branch in
any repository.
The
.I VERSION
format is repository/branch (e.g., SBo/13.1).
If the repository is omitted,
.B sbopkg
will first look for the specified branch in the default repository.
If that attempt fails,
.B sbopkg
will look for the first matching branch in any repository.
.\"---------------------------------------------------------------------
.TP
.B \-v
Prints the current version of sbopkg on stdout.
Prints the current version of
.B sbopkg
on stdout.
.\"=====================================================================
.SH FILES
.TP 5
@ -288,25 +425,42 @@ Default system-wide file to specify configuration options.
.I /etc/sbopkg/renames.d/50-default
Default file that lists software in the SBo repositories that has been
renamed.
See the README-renames.d document in the sbopkg doc/ directory for more
information.
See the
.I README-renames.d
document in the
.B sbopkg
documentation directory for more information.
.TP
.I /etc/sbopkg/repos.d/{40-sbo.repo,50-sb64.repo,60-local.repo}
Three default files for various types of sbopkg repositories.
See the README-repos.d document in the sbopkg doc/ directory for more
information.
Three default files for various types of
.B sbopkg
repositories.
See the
.I README-repos.d
document in the
.B sbopkg
documentation directory for more information.
.\"=====================================================================
.SH AUTHORS
Chess Griffin
<chess@chessgriffin.com>
.PP
Mauro Giachero
<mauro.giachero@gmail.com>
.PP
slakmagik
<slakmagik@gmail.com>
.\"=====================================================================
.\" Make the release process handle a DOCDIR here? But the files from
.\" the official tarball go here.
.SH SEE ALSO
.BR dialog (1),
.BR more (1),
.BR removepkg (8),
.BR rsync (1),
.BR sbopkg.conf (5),
.BR su (1),
.BR upgradepkg (8),
.BR vi (1),
.IR /usr/doc/sbopkg-SVN/*
.\"=====================================================================
.SH AUTHOR
Chess Griffin
<chess@chessgriffin.com>
.\" vim:set tw=72: