diff options
Diffstat (limited to 'tags/0.5.1/doc/README.simplaret')
-rw-r--r-- | tags/0.5.1/doc/README.simplaret | 319 |
1 files changed, 319 insertions, 0 deletions
diff --git a/tags/0.5.1/doc/README.simplaret b/tags/0.5.1/doc/README.simplaret new file mode 100644 index 0000000..397d913 --- /dev/null +++ b/tags/0.5.1/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. + |