path: root/trunk/doc/README.simplaret

simplaret: simplepkg retrieval tool
-----------------------------------

Simplaret is a simplepkg tool used to download packages from local and remote repositories.
With simplaret, one can grab packages for all archictectures and versions of slackware-like
distributions that follows the mirror guidelines, allowing an easy management all
jails and slackware installations in a machine, no matter wich arquiteture or version
each one has.

It was inspired in swaret behavior but don't tries to get its complexity level, but
execute package download in a different way, where the local repository is organized
by archictecture and version. It can also search for packages. It runs on top of pkgtool
and is totally non-instrusive and can search, add, remove and upgrade packages.

Documentation
-------------

The always updated english documentation is hosted at http://slack.sarava.org/simplaret-en

Downloading and installing
--------------------------

Simplaret comes with simplepkg, wich installation and configuration is detailed at
http://slack.sarava.org/simplepkg. Simplaret uses /etc/simplepkg/simplepkg.conf for its definitions
and /etc/simplepkg/repos.conf for repository information. The default configuration should work
for almost everyone.

Using simplaret
---------------

Simplaret stores its data in system wide folders. Then, some funcionality will just be available
if its run with root user capabilities. The first thing you need to do with simplaret is to fetch
repository metadata, using

  simplaret --update

or simply 

  simplaret update

as simplepkg supports both command line behaviour (--update or just update). After that, you can
search for packages using commands like

  simplaret search ekiga

The result should be something like

  REPOS repository sarava, arch: i386, version: 11.0: ekiga-2.0.5-i586-1rd.tgz

As we'll see afterwards, "REPOS" means the repository type, "sarava" is the repository name,
"arch" is the package architecture (i386 in this case) and "version" is the repository version
(11.0 in this case).

To install this package, just type

  simplaret install ekiga

By default, if simplaret finds in the repository a slack-required file for this package (i.e, the
file ekiga.slack-required in the same folder of the binary package) then it will try to install
all unmet dependencies. This default behaviour can be disabled through config file parameters.

If you just want to download the package, type

  simplaret get ekiga

In the case of simplaret finds more than one package with the same name, it will get in the order
that the "search" option shows them. The search precedence can also be defined by config file
parameters. For instance, the command

  simplaret search kernel-generic

can return something like

  ROOT repository sarava, arch: i386, version: 11.0: kernel-generic-2.6.17.13-i486-1.tgz
  ROOT repository sarava, arch: i386, version: 11.0: kernel-generic-2.6.18-i486-1.tgz

So the command

  simplaret install kernel-generic

will attempt to install the package "kernel-generic-2.6.17.13-i486-1.tgz" and not the file
"kernel-generic-2.6.18-i486-1.tgz". If you want to force simplaret to get and specific package,
use its complete file name:

  simplaret install kernel-generic-2.6.18-i486-1.tgz

If a package is already installed in the system, the --install option will try to upgrade it
if the version or build number between the installed package and the one in the repository
are different. So the command

  simplaret install simplepkg

updates simplepkg in the case there's a new version. To remove a package, type

  simplaret remove nome-do-pacote

That's just an alias for the standard removepkg command.

Simplaret stores downloaded packages in a system folder that defaults to /var/simplaret.
As you get more and more packages, simplaret will consume more space ir your disk. To
erase your local repository folder, use the command

  simplaret purge

This will erase just the packages from the current arch and version. Details about how to
erase the repository for different arch and version are in another session.

You can also force simplaret to erase just old packages. The following command erases just
packages older than six weeks or more:

  simplaret purge -w 3

Downloading patches and upgrading the system
--------------------------------------------

Simplaret hasn't just about package installing and removal, it has two more important
features: patches retrieval and application. Assuming that the patches repository of
your slackware flavour is correctly configured (what should work with almost everyone
with the default configuration), you can fetch the available patches using the command

  simplaret get-patches

If you don't just donwload but also apply those patches, use

  simplaret upgrade

Working with more than one architecture and version
---------------------------------------------------

Until now we just looked what is the requirement for all package management system: package
retrieval, installation, search, upgrade and dependency resolution. What makes simplaret
different from another tools is the ability to deal with different architectures and versions
and slackware installations.

The features descibed in this section will just make sense after you read the next section, when
we'll talk about multiple slackware installations and jails in the same computer.

Suppose you're running Slackware (arch i386) bit wants to update the package list from Slamd64
version 11.0 (arch x86_64). To do that, just type

  ARCH=x86_64 VERSION=11.0 simplaret update

This command grabs the Slamd64 package list without confliting in any way with the standard and
already downloaded i386 Slackware package list. This doesn't happens because simplaret stores
metadata from different archs and versions at different folders.

Its optional to pass ARCH and VERSION environment variables to simplaret. If one or none of them
was specified, simplaret uses the standar system value, obtained from the file /etc/slackware-version,
or uses config parameters to do that.

As an example, to search for a package in the arch powerpc (Slackintosh) version 11.0, just type

  ARCH=powerpc VERSION=11.0 simplaret search package-name

All command previously mentioned can work that way, except those that install or remove packages as
its dangerous to mix packages from different archs and versions in the same system.

Working with multiple installations
-----------------------------------

The previously section mentions a feature that just makes sense in systems where there's more than
one slackware-like installation using different archs and versions.

Say you have a x86_64 machine with three installed systems:

  - Slamd64 11.0 at the root folder
  - Slackware 11.0 at /mnt/slackware-1
  - Slackware 10.2 at /mnt/slackware-2

In the case of package install or patch retrieval and application, simplaret supports the environment
variable ROOT to specify which folder simplaret should look for a system.

Then, to install a package at /mnt/slackware-1, just type

  ARCH=i386 VERSION=11.0 simplaret update
  ROOT=/mnt/slackware-1 simplaret install package-name

The first command just updates the package list and the second makes simplepkg install the package with
using /mnt/slackware-1 arch and version. If you want to do the same at /mnt/slackware-2, use the analogous
command

  ARCH=i386 VERSION=10.2 simplaret update
  ROOT=/mnt/slackware-2 simplaret install package-name

There's also a feature to make patch retrieval and application with just one command, using the file
/etc/simplepkg/jailist. This file is used by simplepkg's mkjail script to store with jails you have
on your system but is also used by simplaret to upgrade all jails with just one command.

Considering that your box has the three previously mentioned slackware installation. Then, to add
/mnt/slackware-1 and /mnt/slackware-2 in the automatic upgrade list, add the following lines in your
/etc/simplepkg/jailist (without spaces):

  /mnt/slackware-1
  /mnt/slackware-2

The root system doesn't need to be added in this file. Then, you can get the patches for all your three
systems with the command

  simplaret get-patches

To get the patches and/or apply them in all jails (including the root system), use

  simplaret upgrade

This feature makes easier to keep all your installations always upgraded.

The repos.conf file
-------------------

Now that we just talked about all simplaret features, its time to take a tour at its configuration
files. The first one we'll say about is the repository definition file, /etc/simplepkg/repos.conf.

If you don't mind to make an advanced simplaret usage, then probably you can just leave this section
as the default config should work for almost all standard situations and you'll just need to edit
repos.conf to change repository priorities.

The repos.conf file contains one repository definition per line using the following syntax:

  TYPE[-ARCH][-VERSION]="name%URL"

The content in brackets are optional depending on the repository type as we'll see later in this
section. The repository types supported by simplaret are:

  - PATCHES: used for repositories containing patches and which file metadata is the file
    FILE_LIST instead the standard FILELIST.TXT; example:

      PATCHES-i386-11.0="sarava%http://slack.sarava.org/packages/slackware/slackware-11.0/patches/"

    This defines a patches repository for arch i386 (official Slackware), version 11.0 and named
    as "sarava".

    Its optional to have a PATCHES definition in order to get patches: the ROOT repository definition
    just take care of that and you'll just need to use a PATCHES definition if you want to give
    precedence to some patches repository over all other definition types.

  - ROOT: this type specifies the default slackware-like repository, where the content is sorted
    by version. An official slackware repository then is defined as

      ROOT-i386="tds%http://slackware.mirrors.tds.net/pub/slackware/"

    ROOT repositories needs just the arch definition, a name and an URL. In the previous case,
    we have a ROOT repository called "tds". It doesn't need any version information as its already
    considers tha the content is sorted in folders like

      http://slackware.mirrors.tds.net/pub/slackware/slackware-10.2/ and
      http://slackware.mirrors.tds.net/pub/slackware/slackware-11.0/

  - REPOS: this repository type ir arch and version oriented, like

      REPOS-i386-11.0="sarava%http://slack.sarava.org/packages/slackware/slackware-11.0/"

    In the above case, a repository called "sarava" is defined using arch i386 and version 11.0
    with URL http://slack.sarava.org/packages/slackware/slackware-11.0/. This repository type is
    recommended when using non-official repositories.

  - NOARCH: the last type is used to define repositories where packages are arch and version
    independent, like

      NOARCH="sarava%http://slack.sarava.org/packages/noarch"

In any repository type, the supperted URL schemes are http://, ftp:// or file:// (for local
repositories).

As simplaret supports more than one repository definition for each type, arch or version, each
definition has its own name. Definitions can have the same name just if they're dont use the
same repository type and/or arch and version.

There's also a priority rule between the repository types wich defines a precedence order.
Repositories are searched according the following order:

  - PATCHES has the highest priority: if a package from a given arch and version is not found
    in the first (if existent) PATCHES definition, then the next one is searched until all
    PATCHES definitions are searched.

  - Then, the package is searched in all ROOT defintions in the order they appear at repos.conf.

  - The next searched repository type is REPOS in the specified arch an version, in the order
    they appear at repos.conf.

  - At last, NOARCH type is searched in the order they're defined.

In the case you're issuing an upgrade or just geting patches, simplaret by default will just
search in PATCHES and ROOT definitions.

At REPOS and ROOT is also possible to specify its internal search order according its subfolders.

Configuration file simplepkg.conf
---------------------------------

Simplaret also stores its configurations inside simplepkg's configuration file
/etc/simplepkg/simplepkg.conf. This file is well commented and you should find there a description
of all supported options.

But why use that?
-----------------

You may ask why someone wishes to use such tool.

Simplaret was written with a *x86 environment in mind, where lots of jails with different archs
and versions are installed. Suppose a x86_64 with the following chroots installed:

  - slamd64 11.0
  - slackware 10.0
  - slackware 11.0 with additional i686 packages
  - uSlack (i386 uClibc) 

Keep all this stuff update manually is really a headache. Simplaret just tries to make it trivial.

Additional information
----------------------

Simplaret was written by Silvio Rhatto (rhatto at riseup.net) and is released under GPL license. The code
can be obtained from the subversion repository:

  svn checkout svn://slack.sarava.org/simplepkg

Simplepkg's wiki is http://slack.sarava.org/wiki/Main/SimplePKG and its mailing list address is
http://listas.sarava.org/wws/info/slack.