1 files changed, 258 insertions, 0 deletions
diff --git a/trunk/doc/README b/trunk/doc/README
new file mode 100644
index 0000000..50b0e9d
--- /dev/null
+++ b/trunk/doc/README
@@ -0,0 +1,258 @@
+Simplepkg: installation manager and metapackage system
+------------------------------------------------------
+
+Author: Silvio Rhatto <rhatto at riseup.net>
+Licence: GPL
+
+Simplepkg is a non-intrusive package management system running on top of pkgtool.
+It uses templates -- lists of installed packages, scripts and configuration files
+-- allowing the creation of installation profiles that can be used do install a
+complete and configured slackware system in another partition or to create chroot
+environments. The same templating scheme extends slackware packaging system, adding
+metapackages: a list of packages installed or removed with a single command.
+
+Documentation
+-------------
+
+  English documentation: README | http://slack.sarava.org/node/15
+  Portuguese documentation: REAMDE.pt_BR | http://slack.sarava.org/node/12
+
+Description
+-----------
+
+All GNU/Linux distributions comes with a well developed packaging system. The question now
+is how pratical is the way to install, configure and control any changes in a system.
+
+As an example, suppose you should keep a list of about 200 slackware machines, some
+of them used as desktops, others as mail or webservers. If you lost some hardrives
+or usually need to re-install or update some of those boxes.
+
+Using the slackware installation cd and configuring by hand all the time you got a crash
+is a time loss activity and you'll never know if something remained missconfigured. An
+alternative is to keep a complete backup of a machine or some parts of the tree, but for
+a large number of different boxes this procedure costs a lots of resources.
+
+Simplepkg offers an alternative sollution for this and other problems related to installation
+management, allowing you to keep templates of each machine and install a custom slackware
+system with just one or a few commands. Creating and upgrading chroot and vservers is easy
+with simplepkg.
+
+Architecture
+------------
+
+Simplepkg is a set of scripts wrote in the KISS philosophy. Its a pretty simple system, composed
+by the following commands:
+
+   - mkjail: build a slackware jail/installation in a folder
+   - metapkg: install or remove a metapackage
+   - templatepkg: create or update a package list of an installation template
+   - lspkg: show installed packages and its contents
+   - jail-upgrade: upgrade all or some of the jails/installations 
+   - jail-update: update all configuration files of a template
+   - rebuildpkg: rebuild a package based on its /var/log/packages entry
+   - simplaret: package retrieval tool
+   - createpkg: donwload, compile and package creationg script based on http://slack.sarava.org/slackbuilds
+
+Simplepkg configs are placed at /etc/simplepkg. Templates are .template files containing an one-by-line
+package list. A template can be something like this:
+
+  aaa_base
+  aaa_elflibs
+  apache
+  bash
+  bin
+  coreutils
+  findutils
+
+Slackware's tagfile format can be used too as a template.
+
+Installation
+------------
+
+The latest version of simplepkg is locate at http://slack.sarava.org/packages/noarch/.
+Install it with the usual way:
+
+  installpkg simplepkg-VERSION-noarch-BUILD.tgz
+
+If you have a working swaret on your system, add this line on you swaret.conf:
+
+  REPOS_ROOT=SlackMidiataticaNoarch%http://slack.sarava.org/packages/noarch
+
+and then issue those commands:
+
+  swaret --update
+  swaret --install simplepkg
+
+Configuration
+-------------
+
+As an example, we'll create a jail based on the packages installed in your slackware
+system. Edit the config file /etc/simplepkg/simplepkg.conf:
+
+  # /etc/simplepkg/simplepkg.conf
+  JAIL_ROOT="/vservers" # where jails are placed
+  SIMPLARET="simplaret" # package grabber program (can be swaret if you have it installed)
+  SIMPLARET_CLEAN="1" # clean package cache before installation
+  SIMPLARET_DELETE_DOWN="1" # clean package cache after the installation
+  SIMPLARET_UPDATE="0" # issue an simplaret --update before install the jail
+  SIMPLARET_PURGE_WEEKS="N" # delete packages older than N weeks from the cache
+  PATCHES_DIR="/storage/package/patches" # where patches are placed
+  DEFAULT_ARCH="i386"
+  DEFAULT=VERSION="10.2"
+  STORAGE="/storage/packages" # where simplepkg store packages
+  PASSIVE_FTP="1"
+
+You should also put in /etc/simplepkg/repos.conf all package repositories you use, like this:
+
+  ROOT-i386="http://slack.sarava.org/packages/slackware"
+  REPOS-i386="slack-sarava%http://slack.sarava.org/packages/slackware/slackware-10.2/"
+  ROOT-x86_64-10.2="http://darkstar.ist.utl.pt/pub/slamd64/"
+  REPOS-x86_64-10.2="slamd-sarava%http://slack.sarava.org/packages/slamd64/slamd64-10.2/"
+
+Instead of simplaret you can use swaret to fetch packages and them your swaret.conf must
+be configured to use the same place as STORAGE to the package cache. In this case you cant
+keep installations and jails with multiple arquitetures and for that reason the use of
+simplaret is recommended.
+
+Creating jails and replicating installations
+--------------------------------------------
+
+  templatepkg my-slackare
+  mkjail jail my-slackware
+
+The previous commands creates a template called my-slackware from based on your installed
+softwares listed in /var/log/packages and then creates a completely new slackware
+tree with all those packages in the folder /vservers/jail (depending on the value of JAIL_ROOT from
+your simplepkg.conf).
+
+If you want that some config files get copied or some scripts executed after install this jail,
+place in the folder /etc/simplepkg/my-slackware.d all your config files (preserving the file
+system hierarchy, i.e, /etc/simplepkg/my-slackware/etc/apache/httpd.conf) and the scripts at
+/etc/simplepkg/my-slackware.s/. The template vserver, which comes in the simplepkg package, has
+an example script to use with mkjail.
+
+You can specify an alternative destination for your jail with a command like
+
+  ROOT=/mnt mkjail hda2 my-slackware
+
+This does exactly what you think: installs slackware in /mnt/hda2 with exactly the same packages
+you have on your system, replacing the need of the slackware installer!
+
+In case no template specified, mkjail uses the one called /etc/simplepkg/default.template.
+
+If you keep your jails in JAIL_ROOT with the same name as the template you used to create it, its
+possible to use the command jail-update to copy all modifications made in the files which their
+counterparts are placed at /etc/simplepkg/jail-name.d. Then you can copy all configuration files
+you edited to the template folder and leave a crontab entry to everyday seek for changes and update
+the template. When you issue the command
+
+  jail-update
+
+all jails listed in /etc/simplepkg/jaillist are updated. This command also updates the package list
+of the template.
+
+To add or remove packages from a template, you can just edit by hand the template file or use the
+command templatepkg with the -a (append) flag, which adds just the new installed packages in the
+template file. 
+
+If you want to create a template from a jail, use
+
+  templatepkg jail /vservers/jail
+
+Metapackages
+------------
+
+Another use for the templates is the creation of metapackegs: new users have lots of difficulties
+to track dependencies when installing a software. Using a template containing the name of all
+packages needed by some program allow users to easily install it through the command
+
+  metapkg --install program-name
+
+This seems like swaret or slapt-get, with the only difference in the way metapkg deals with
+dependence resolution. Slapt-get support the slack-required file, wich comes or not with the
+package. Swaret has its own tool for dependence matching.
+
+Simplepkg doesn't wish to substitute those two dependence checking modes, but offer an alternate
+way to distribute packages where dependences are resolved without an specific tool or a change
+in the package itself.
+
+A metapackage, i.e, all installed packages from a template, can be removed with 
+
+  metapkg --remove program-name
+
+Upgrading jails
+---------------
+
+Both the main installation (your root system) and your jails are upgraded with the command
+jail-upgrade: just adjust simplepkg.conf's PATCHES_DIR to where you store slackware patches
+(that can be rsync'ed everyday) and do a
+
+  jail-upgrade
+
+This will upgrade your main system and all jails living in JAIL_ROOT. To specify another
+folder, use
+
+  ROOT=/otherroot jail-upgrade
+
+If you want to upgrade just one specific jail,
+
+  jail-upgrade jail-name
+
+To use a patches folder other than PATCHES_DIR, e.g when you have jails with different
+slackware versions, use
+ 
+  PATCHES=/alternative/patches/folder jail-upgrade jail-name
+
+Different archs and versions
+----------------------------
+
+Simplepkg was idealized to permit a template to create jails from any architecture and version
+of a slackware-like system. Upgrading tasks also are unified. This feature just works if you
+use simplaret and not swaret as the package retrieval tool.
+
+As another example, to create an slack 10.1 installation (assuming your /etc/simplepkg/repos.conf with
+the right configuration), just type
+
+  VERSION=10.1 mkjail my-jail server-template 
+
+Different archs can be used too. If you have a x86_64 system and wants to install a slack 10.2
+in a partition, try something like
+
+  ARCH=i386 VERSION=10.2 ROOT=/mnt mkjail hda2 my-slackware
+
+Note that the templates are arch and version independent, as they just contain package names,
+configuration files and scripts. For this reason, the commands templatepkg, metapkg, lspkg and
+jail-update can be used normaly.
+
+To upgrade jails with othes archs and versions, jail-upgrade checks this information through
+/etc/slackware-version for each jail and applies the correspondent patches grabed from
+simplaret (see the proper documentation).
+
+By this way, doesn't matter which versions and archs each of your jails has, jail-upgrade remains
+the same since your patches are sorted by arch an version, as explained in simplaret documentation
+found at http://slack.sarava.org/node/17.
+
+Auxiliar applications: rebuildpkg and createpkg
+-----------------------------------------------
+
+Simplepkg comes with an additional helper tool that recover installed packages which the original
+.tgz file was lost. The command rebuildpkg rebuilds a package from their entry in /var/log/packages.
+As an example,
+
+  rebuildpkg coreutils
+
+rebuilds the coreutils package using the files, scripts and metainformations stored in
+/var/log/packages/ and /var/log/scripts/.
+
+If you want to build you own packages using the scripts available from http://slack.sarava.org/slackbuilds,
+use the createpkg script:
+
+  createpkg package-name
+
+Source
+------
+
+Source code for simplepkg and its package builder can be fetched via subversion:
+
+  svn checkout svn://slack.sarava.org/simplepkg
+