qire/qire.1

.TH QIRE "1" "April 2020" "qire 0.0.3" "User Commands"
.SH NAME
qire \- Qi Remote Extension
.SH SYNOPSIS
.B qire
\fI\,COMMAND\/\fR
[\fI\,OPTIONS...\/\fR]
[\fI\,ARGUMENTS...\/\fR]
.br
.B qire
\f install,downgrade,info\fR
[\f -r,--repo repo\fR]
[\f -l,--local\fR]
[\f -f,--force\fR]
\f pkg1\fR
[\f pkgs... \fR]
.br
.B qire
\f upgrade,search\fR
[\f -r,--repo repo\fR]
[\f -l,--local\fR]
[\f -f,--force\fR]
[\f pkgs... \fR]
.br
.B qire
\f install,upgrade,downgrade\fR
[\f -r,--repo repo\fR]
[\f -f,--force\fR]
\f -c,--category category\fR
.br
.B qire
\f search\fR
[\f -l,--local\fR]
\f -c, --category category\fR
.br
.B qire
\f fetch\fR
[\f -r,--repo repo\fR]
[\f -o,--output-directory dir\fR]
\f pkg1\fR
[\f pkgs... \fR]
.br
.B qire
\f fetch\fR
[\f -r,--repo repo\fR]
\f -c,--category category\fR
.br
.B qire
\f sync,build-index\fR
\f repo1\fR
[\f repos...\fR]
.br
.B qire
\f remove\fR
\f pkg\fR
.br
.B qire
\f remove\fR
\f -c,--category category\fR
.br
.B qire
\f clean,version,help\fR


.SH DESCRIPTION
Qire is the remote package manager for Dragora. It uses the local package
manager, see qi(1), to install, update, and remove packages. Qire is able to work with
many package repositories that are set in the qire config file, see \fBQIRERC\fR
for more information on how to configure qire. Qire is also able to manipulate
many versions of the same program intelligibly and easily, see \fBMANIPULATING
MULTIPLE VERSIONS\fR for more information. If you are a repository maintainer,
qire offers a build command to easily create a new index file for your repo, see
\fBBUILDING INDEX FILES\fR and \fBMAINTAINING A REPOSITORY\fR for more
information.
.br
.SS "Remote/Local Commands:"
.TP
\fBinstall\fR
Install packages from the repo(s) or local filesystem
.TP
\fBupgrade\fR
Upgrade installed packages from the repo(s) or local filesystem
.TP
\fBdowngrade\fR
Downgrade installed packages from the repo(s) or local filesystem
.TP
\fBsearch\fR
Search the repo(s) or local filesystem for a particular package
.TP
\fBinfo\fR
Display information on a package in the repo(s) or local filesystem
.SS "Remote-Only Commands:"
.TP
\fBsync\fR
Sync the local repo(s) tree
.TP
\fBfetch\fR
Fetch package from repo
.TP
\fBbuild\-index\fR
Build index files for repos in config. See \fBBUILDING INDEX FILES\fR for
more information
.SS "Local-Only Commands:"
.TP
\fBremove\fR
Remove installed packages
.TP
\fBclean\fR
Clean out the Qire cache directory
.SS "Options:"
.TP
\fB\-c\fR, \fB\-\-category\fR
Supply a category name rather than a package name to an applicable command
.TP
\fB\-f\fR, \fB\-\-force\fR
Force an applicable command to be reran
.TP
\fB\-l\fR, \fB\-\-local\fR
Run an applicable command locally
.TP
\fB\-o\fR, \fB\-\-output\-directory\fR
Choose a different output directory for fetched packages
.TP
\fB\-r\fR, \fB\-\-repo\fR
Select which repo(s) you'd like to use
.SS "Other Commands:"
.TP
\fBversion\fR
Display the version
.TP
\fBhelp\fR
Display this help information

.SH FILES AND DIRECTORIES
/etc/qire/qirerc \(em Qire config file
.PP
/etc/qire/${id}.index \(em various index files of the repos found in Qire config
.PP
/var/cache/qire/ \(em default location for package binaries and SHA256 files are located.
.PP
.br
.SH QIRERC
The qirerc file is the only configuration file required for qire. The qirerc is
very easy to understand and edit. Currently, these are the configuration options:
.TP
\fBdefault\fR
Usage: \fBdefault\fR [repo1,repo2,...] [all]
.br
Set the default repositories for qire to do business in. The default setting for
this is "all" which means all the repositories placed in qirerc are used. If you
wish to only select a subset of your repository list, you can place the id of
the repositories in a list separated by a space character, i.e. "default
my-repo1 my-repo2". You can always override this setting by using the
\fT-r,--repo\fR option.
.TP
\fBrepo\fR
Usage: \fBrepo\fR id url
.br
Set the id and URL of a repository. The id of the repository can be whatever
you'd like, so long that there are no spaces in the id, i.e. "repo
dragora-noarch http://rsync.dragora.org/current/packages/noarch/". It is
recommended that you select a reasonable name as you will see this name
throughout qire's UI.

.PP
If you get \fBError 3\fR, this means you are lacking a qirerc. This will
generally not happen unless there was an issue with installation. To fix this,
all you must do is create a qirerc file with the information you'd like.

.br
.SH MANIPULATING MULTIPLE VERSIONS
As mentioned, qire is able to work with many versions of the same program thanks
to graft(1). It's quite easy to do these tasks.
.TP
\fBInstalling\fR
To install another version of a package, simple run the qire install command as
normal, i.e. "qire install moe." If qire finds many versions of the queried
package, it will display them in a list and you can select whichever one you'd
like by inputting the corresponding number. If you already have the selected
version installed, qire will inform you. If you select a another, non-installed
version, qire will fetch and install it as any package. If you perform a local
search (qire search -l ${program-name}), you will notice that 2 versions will
show up. This means you've successfully installed 2 versions of the same
package!
.TP
\fBUp/Downgrading\fR
Upgrading/downgrading many versions of the same package with qire is also very
easy. To do so, run the upgrade or downgrade command as you would with any other
package, i.e. "qire upgrade moe." If qire finds many versions of the
queried package, it will display them in a list and you can select whichever
one you'd like by inputting the corresponding number. If you already have the
selected version installed, qire will inform you. If you select a version that
is newer or older, qire will then search your system for potential
candidates. If there are many candidates qire will list them and allow you to
select which version to apply the upgrade or downgrade to. Once you select which
version to upgrade or downgrade, qire will perform its action.
\fBRemoving\fR
If you have more than one version of a package installed, running the qire
remove command will simple display a list of packages to remove.
.br
.SH BUILDING INDEX FILES
There are 2 ways to create an index file for your repository: with qire and
manually. If you wish to use qire, make sure that all the packages you wish to
include are currently uploaded to the repository. Then make sure that you have
the repo found in your qirerc file. If it isn't, see the \fBQIRERC\fR section
for more information. To generate the index file, simply run the qire
build-index command with the id of the repository as the argument, i.e. "qire
build-index dragora-noarch," where "dragora-noarch" is the id of the repository
that I wish to generate an index file for.
.br
To manually create an index file, all you must do is place the \fIfull name\fR
of the package, a space, and the location of that package on the repo per
line. An example line would look like this: "moe_1.11-rc1_amd64-1@tools.tlz /\\n"
- notice that I included the newline character "\\n" as it is required for
parsing. \fBEven the last line in the index file must have a newline character
at the end!\fR Another example, with a non-root path would be:
"moe_1.11-rc1_amd64-1@tools.tlz /editors/\\n", if the package for "moe" was found
in "editors/".
.SH MAINTAINING A REPOSITORY
Maintaining a repository is fairly easy as there are only a handful of
requirements. First, the server you host your repository on must be accessible
via HTTP[S]. At this time, qire does not support FTP or any other
protocol. Second, the HTML of the package list must allow qire to parse
it. What this means is that you cannot use a fancy JavaScript list or something
non-standard. It is recommended that your either use the standard when you
browse to a directory via HTTP, Apache, or Hiawatha. Third, the URL that you supply must
contain a file entitled "packages.index" which is the index file of your
repository. See \fBBUILDING INDEX FILES\fR for more information on creating
index files. You, of course, can have many repositories on one server but each
URL must contain a valid packages.index file. Fourth, all packages must follow
the qi(1) package naming convention. That convention is:
"${program-name}_${version}_${arch}-${release-number}[@${category}].tlz". You
will notice that category is optional but it is recommended that you provide a
category to allow for easy upgrading or installation of dependencies. If you
fail to follow this convention, qire may fail to work on your repository. Fifth,
along with the binary file (.tlz), you must also include the sha256 checksum
(.tlz.sha256) and the metadata (.tlz.txt) files. The sha256 is to make sure that
there is no corruption with the fetched package before installation. The
metadata file is so that users can use qire's info command, i.e. "qire info
moe". After meeting these requirements, you will have a working qire repository!
.SH SIDE NOTE
Qire is still fairly knew and things are always subject to change. If you have
recommendations, concerns, wishes, or what to help, contact the author as listed
under the \fBREPORTING BUGS\fR section.
.SH AUTHOR
Qire was written by Kevin "The Nuclear" Bloom.
.SH "REPORTING BUGS"
Report bugs to https://notabug.org/dragora/qire/issues or <nuclearkev@dragora.org>
.SH COPYRIGHT
Copyright \(co 2020-2021 Kevin "The Nuclear" Bloom.
Qire comes with ABSOLUTELY NO WARRANTY.
You may redistribute copies of Qire
under the terms of the GNU General Public License version 3 or later.
For more information about these matters, see the file named LICENSE.
.SH "SEE ALSO"
.BR qi (1),
.BR sha256sum (1),
.BR wget (1)