tagged trunk/ rev. 400 as simplepkg 0.5

git-svn-id: svn+slack://slack.fluxo.info/var/svn/simplepkg@401 04377dda-e619-0410-9926-eae83683ac58

1 files changed, 319 insertions, 0 deletions

diff --git a/tags/0.5/doc/README.simplaret b/tags/0.5/doc/README.simplaret
new file mode 100644
index 0000000..397d913
--- /dev/null
+++ b/tags/0.5/doc/README.simplaret
@@ -0,0 +1,319 @@
+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.
+