diff --git a/swim-doc/QUICKSTART.text b/swim-doc/QUICKSTART.text new file mode 100644 index 0000000..68c55f9 --- /dev/null +++ b/swim-doc/QUICKSTART.text @@ -0,0 +1,140 @@ +READ THE REQUIREMENTS + +Now you can skip the next three steps if you have an installed Debian +distribution and you are in a hurry for a demonstration, but you will miss +out on swim's more awesome capabilities. With that said..... + +FIRST GET SWIMRC PREPARED + +Edit the swimrc configution file, you should read swimrc(5), but I'll ask +you some question right now. You can find swimrc in /etc/swim, and in +your home directory in the subdirectory .swim. Entries in the home +directory swimrc override ones in /etc/swim. + +Are you using an installed Debian system? If so, you almost definitely +have dpkg installed. So uncomment this line in /etc/swim/swimrc by +removing the pound sign. + +$package_tool = "/usr/bin/dpkg"; + +otherwise + +$package_tool = "/usr/bin/ar"; + +Do you have the apt package installed? Configure this, or -xyz will not +work. + +$apt = "yes"; + +Now you need to decide what architecture you would like to be swim's +default value when you download, build, and query the not-installed +databases. + +What flavor, do you want alpha, arm, hurd-i386, i386, m68k, powerpc, +or sparc? (more coming :*) I decided on ..... + +$architecture = "i386"; + +What kind of distribution do you want to be your default? stable, +unstable, frozen, or experimental (rare) I like the ever changing ... + +$distribution = "unstable"; + +Decide which sections you want? You can have this + +@user_defined_section = qw(main contrib non-free); + +or this. + +@user_defined_section = qw(main); + +or ..... + + +SECOND GET SWIMZ.LIST PREPARED + +Now grab a copy of the README.mirrors from +http://www.debian.org/misc/README.mirrors, you will need this to set-up +the configuration file /etc/swim/swimz.list. + +If your using apt make sure to read swim(8) to get the nitty gritty on how +you can synchronize swim along with apt :*} using swimz.list. + +Humm, you found a site which has the distribution you want, and you know +which section you want, and you are happy knowing about packages which can +install on the architecture you computer happens to have. + +So what site is that? + +deb ftp://ftp.swimz.org + +What was the directory you happened to notice in the README.mirrors page? + +deb ftp://ftp.swimz.org/pub/debian + +What distribution did you want? Note: You won't want to use the Release +code name for the distribution, see swimz.list. + +deb ftp://ftp.swimz.org/pub/debian unstable + +What sections did you want? + +deb ftp://ftp.swimz.org/pub/debian unstable main contrib non-free + +Now put this line in the swimz.list, exactly like written, and ofcourse +use the values you want. + +THIRD GET THE DEBIAN DATABASE WITH FTP + +Just issue this command. + +swim --ftp --Contents DF --Packages DF + +and wait a little bit. + + +FOURTH BUILD THE DATABASES + +This is for a computer system with a Debian distribution installed. + +swim --initdb + +This next part applies to people who followed all the steps to get here, +and also read the important requirements at the top. This makes the +not-installed databases. Go take a walk, or a swim :*} + +swim --initndb --Contents DF DF + +When either of these commands are complete they will say "over and out". + +NOW WHAT? + +Now the real fun begins. If you happen to have some experience with rpm +you already know some of the options which swim uses, but be prepared for +surpises. swim(8) goes into more detail, the "Maximum RPM" book by +Edward C. Bailey which is freely available may provide help for swim's +--query option, but you will find that swim greatly diverges from rpm. + +Try something like this, and do not use the -n unless you made the +not-installed databases, on the other hand, REMEMBER to use -n if you +do not have an installed system.... + +swim -n --search swim + +now do this.. + +swim -qnSi or swim -hn + +go to the directory /usr/bin and do + +swim -qnf . + +you probably will have to do + +swim -qnft . + +...the fun is just beginning... + +Where are you swimming to today? + + diff --git a/swim-doc/REQUIREMENTS.text b/swim-doc/REQUIREMENTS.text new file mode 100644 index 0000000..4877bb2 --- /dev/null +++ b/swim-doc/REQUIREMENTS.text @@ -0,0 +1,90 @@ +REQUIRMENTS: + +Don't get intimidated, this is just to cover all bases, most computer +systems meet the requirements. + +PERL: Yes, preferably Perl 5.004.04 or greater. + +FTP CAPABILITIES: (optional) You may need to get Net::FTP (Debian +libnet-perl package) which depends on Data::Dumper (Debian data-dumper +package). Also check the CPAN mirrors or the PACKAGES below. You also +need gcc if you do not have a Debian system so that swim can figure out +what architecture your machine is. You can also find these modules at the +CPAN mirrors or the PACKAGES below. + +READLINE CAPABILITIES: (optional) For nice readline cpabilities get +Term::ReadLine::Gnu or alternatively Term::ReadLine::Perl which depends on +Term::ReadKey. Term::ReadLine::Gnu may be tricky to set-up on non Debian +systems because it depends on ncurses3.4 and the GNU Readline Library +version 2.1 or later, but Term::ReadLine::Perl is much easier to set-up +and allows a huge amount of package names to be present on the command +line without a segmentation fault. You could get swim's ftp capabilities +working first, and then just fetch the Debian ReadLine package(s) and then +use swim's --extract option to set the package(s) up, but, it is sure fun +doing a 'make test' when setting up the ReadLine modules! You can also +find these modules at the CPAN mirrors or the PACKAGES below. + +DATABASE CAPABILITIES: DB_File comes standard with Perl. But, this +doesn't mean it is compiled for the newer Berkeley Database Libraries. DB +1.85 has known bugs which effect SWIM. SWIM can work with 1.85, but +--rebuildflatdb and --rebuildflatndb will not work properly. You can run +a test to find out whether or not you need to make the change if you have +db_dump available on your system (which db_dump). Enter this: + +perl -e 'use DB_File; tie %testdb,'DB_File',"testdb";'; +db_dump testdb + +If 'db_dump testdb' produces an error you need to make the change by +installing the newest DB_File. If you have a version of libc6 less than +2.1, first, install a new version (2.3.4 or greater) of the Berkeley DB if +you don't already have it installed. If you get DB_File from CPAN you +will need to edit config.in to point to the location of where libdb2 +installed db.h, where libdb2 is installed on your system, and the name of +the library. For Debian this would be: + +INCLUDE = /usr/include/db2 +LIB = /usr/lib +DBNAME = -ldb2 + +PACKAGES - You can get the CPAN modules in some package formats. Debian +2.1 and Red Hat 5.0 have been tested with these packages: + +Debian - + +libnet-perl and +data-dumper and +libterm-readline-gnu-perl (plus a lot more) or +libterm-readline-perl-perl and +libterm-readkey-perl +libdb2 + +Red Hat - + +perl-libnet and +perl-Data-Dumper +db-? + +USER: root. Some of swim's most important functions will not work +properly unless you are running the program as root. + +HARD DRIVE SPACE: Make sure you have enough hard drive space. 1500 +installed packages produces a 10MB fileindex.deb, and the virtual +not-installed filesystem database for the unstable distribution is now +over 40MB. 100MB of free space on your hard drive is probably a good +safety margin, if you run out of hard drive space the program will just +hang or quit. + +MEMORY: Databases made for an installed Debian system require memory in +proportion to the amount of packages actually installed; the --lowmem +option is an excellent alternative for making the databases if the +computer system is either overloaded or low on memory. If you get "out of +memory" warnings try to free up some memory first then make the databases. +You can also avoid making the virtual filesystem by not using the +--Contents option or using the FDB argument for that option. Updating the +databases uses very little memory. + +OTHER SWIM FUNCTIONS: Most free operating systems have these packages +installed: On a non Debian system, ar from binutils is used to query +Debian binary packages. These next packages are essential in a free +operating system (Linux) - textutils, fileutils, grep, tar, gzip, and +mount. diff --git a/swim-doc/swim.text b/swim-doc/swim.text new file mode 100644 index 0000000..bfe5644 --- /dev/null +++ b/swim-doc/swim.text @@ -0,0 +1,1622 @@ + + swim + ---- + Jonathan D. Rosenbaum + 15 June 1999 + +0.1 Contents +------------ + + 1. DESCRIPTION + + 2. COMMAND LINE OPTION SYNTAX + + 3. VERSION + + 4. HISTORY + + 5. MAKING INSTALLED SYSTEM DATABASES + 5.1. Initial database making, and Rebuilding for an Installed + system. + 5.2. UPDATING + 5.3. REBUILDING THE SEARCH + 5.4. FILES + + 6. IMPORTANT DEBIAN DATABASES FOR NOT-INSTALLED DATABASES + 6.1. A. downloading the important databases with --ftp. + 6.2. OVERVIEW + 6.3. DISTRIBUTION DEFINED + 6.4. SECTIONS + 6.5. ARCHITECTURES + 6.6. SWIMZ.LIST + 6.7. SWIMZ.LIST EXAMPLES + 6.8. FTP OR APT? + 6.9. OPTIONS + 6.10. B. downloading the important databases with apt, and + maintenance options. + + 7. MAKING NOT-INSTALLED DATABASES + 7.1. OVERVIEW + 7.2. OPTIONS + 7.3. UPDATING + 7.4. REBUILDING THE SEARCH + 7.5. FILES + + 8. PREPARING YOUR INSTALLATION FOR APT + + 9. QUERYING THE INSTALLED AND NOT-INSTALLED DATABASES + 9.1. MINOR MODES + 9.2. SPECIFYING THE DATABASES TO USE + 9.3. OPTIONS + 9.4. PACKAGE RELATIONSHIPS + 9.5. FORMAT + 9.6. FTP - VIRTUAL OPTIONS + 9.7. APT - VIRTUAL OPTIONS + 9.8. REMOVING AN INSTALLED PACKAGE - VIRTUAL OPTIONS + 9.9. STDIN - VIRTUAL OPTIONS + 9.10. PACKAGE MANIPULATION - VIRTUAL OPTIONS + 9.11. DATABASE LOCATIONS + + 10. UPGRADING WITH APT + + 11. SEARCHING + 11.1. OVERVIEW + 11.2. NARROWING A PREVIOUS SEARCH + 11.3. MINOR MODES + 11.4. OTHER OPTIONS + 11.5. EXAMPLES + + 12. RAMDISK + 12.1. OVERVIEW + + 13. FILES + + 14. SEE ALSO + + 15. BUGS + +0.2 Copyright Notice +-------------------- + + Copyright © 1999 Jonathan D. Rosenbaum + + SWIM, including this manual, is free software; you may redistribute it + and/or modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2, or (at + your option) any later version. + + This is distributed in the hope that it will be useful, but *without + any warranty*; without even the implied warranty of merchantability or + fitness for a particular purpose. See the GNU General Public License + for more details. + + You should have received a copy of the GNU General Public License with + the swim source as the file `COPYING'. If not, write to the Free + Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + + +------------------------------------------------------------------------------- + + +1. DESCRIPTION +--------------- + + *swim* is a powerful *package administration* and *research tool* for + both an *installed Debian distribution*, and/or *not-installed virtual + Debian distribution(s)* allowing querying of software packages with a + variety of package information options, and powerful searches. Virtual + options which include ftp, installation, and package removal + capabilities can be seamlessly combined with querying or searches. + *swim* can be used on computer systems which either have, or do not + have a Debian distribution installed. + + +------------------------------------------------------------------------------- + + +2. COMMAND LINE OPTION SYNTAX +------------------------------ + + When you press ``*swim* <*enter*>`` you will see a listing of command + line options in a particular syntax. This is to help you understand + under what context to use the options. When you enter the options on + the command line, the brackets, parentheses, braces, diamonds, and + question marks are not actually used. + + *Major Mode Option* + + All command line options for *swim* always start with a *major mode + option*, except for ``swim `` which will show the whole listing + of options. A major mode option is surrounded in braces *{ major mode + option }*. In the case of {--search} there are the alternative major + mode options {--refinesearch} and {--research}, but because --search + needs to be used first before either of these two options, + --refinesearch and --research are surrounded in parentheses (). + + Note: Through the other chapters of this manual *{}* is assumed for + the *major modes* in the *usage:* section shown at the beginning of + every chapter. + + Let's take a closer look at this situation: + + `{--search ? (--research || --refinesearch)}' + + `*||*' or `*|*' are used to indicate `*or*', `*?*' indicates + `*optional*', indicates an *argument* (a required argument - + see Arguments below), (parenthesis) means `if used, must be used after + the previous required option was used'. Note: for readability + `--research' and -`-refinesearch' are not surrounded in `{}'. + + *Normal Options* + + Options to the major mode options are enclosed in brackets *[ option + to major mode ]*. `swim [-n]' <`enter'> (assume enter from here on + out), for instance, will show all the command line options without + using the pager. The pager which swim uses can be set in *swimrc* (see + *swimrc(8)*). ```swim {--help} [-n]''' will provide brief explanations + of all of swim's options without using the pager. In this case the + major mode option *{--help}*, and the option *[-n]* were used. + + *Dashes* + + Options which have a single dash can be combined with other single + dashed options *(-qaint)*. Double dashed options need to be entered by + themselves *(--help --nopager)*, many double dashed options have an + alternative single dash option *(-n for --nopager)*. The meaning of + options is related to the major mode they are being used with. *[-n]* + means no pager when called with *{--help}*, but it's a reference to + the not-installed databases when used with *{-q --query}*, fortunately + most options do not have double meanings. + + *Arguments* + + Many options require an argument. Arguments are enclose in diamonds < + *argument* >. An argument to an option may also be optional in which + case a question mark ``*?*'' will be placed between the option and the + argument. *[-l ? <[--df]>]* illustrates such a situation. *[-l]* shows + a file listings, and optionally the option *[--df]* can be use with + *[-l]* to show an expanded listing. + + *[--dbpath* <*dir>]* requires an argument, this time the argument + would not be another option, but rather it is a directory. + + Rule: When an option is an argument to another option it can be + written anywhere, but when a non-option is an argument <*dir*> + *(notice no brackets)* it has to be placed directly after the option. + Sometimes, there may be alternative arguments divided with ``*|*''. + <*argument1|argument2*> means use argument1 or argument2, but not + both. + + Based on what we now know, let's compare this situation to the + *{--search}* situation shown above: + + `[--ftp ? --source | --source_only ? <[--diff]>]' + + In this case *--source* or alternatively *--source_only* can be + optionally used along with *--ftp* because they aren't in parentheses + *()* (also notice: | was used instead of ||, but means the same thing + ``or''). *--diff* can optionally be provided as an argument to either + *--source* or *--source_only*. For readability --source and + --source_only weren't enclosed in brackets. + + *Global Arguments* + + A *global argument* can be typed anywhere on the command line, and can + be an option or text. If global arguments exist they are placed last + after the list of normal options that can be used with a major mode + option. + + [targets | -S] and [targets|APT|DF] are examples. {-q}, {--initndb}, + and {--rebuildndb} all use global arguments. + + *Minor Mode Options* + + {-q --query} will generally use zero or more minor mode options + [-afpgn --dir], with one exception (see chapter 9, `QUERYING THE + INSTALLED AND NOT-INSTALLED DATABASES '). + + +------------------------------------------------------------------------------- + + +3. VERSION +----------- + + usage: *swim --version* + + This shows the version for the swim program. + + +------------------------------------------------------------------------------- + + +4. HISTORY +----------- + + usage: swim --history + swim -h + + options: [--arch ] [--dists ] + [--n] [--dbpath ] [--root ] + + This shows a shell-like history of searches and the most recent + --stdin edit. History is numbered with the most recent action being 1, + and the earlier actions being of a higher number until the maximum + amount of lines set in the HISTORY variable in `swimrc(5)'. A separate + history is kept for each architecture-distribution. + + +------------------------------------------------------------------------------- + + +5. MAKING INSTALLED SYSTEM DATABASES +------------------------------------- + + + +5.1. Initial database making, and Rebuilding for an Installed system. +---------------------------------------------------------------------- + + usage: swim --initdb + swim --rebuilddb + + options: [--dbpath ] [--root ] [--lowmem] + [--split_data ] + + An *installed Debian distribution* is one in which packages are + installed using *dpkg* or some front-end to *dpkg* like *apt* or + *dselect*; *swim* supports installation through *apt*. These major + modes are for a computer with an *installed Debian distribution* and + make the databases which allow querying and searching capabilities for + the installed distribution. + + *--initdb* is run when the databases do not exist yet, *--rebuilddb* + is run if the databases have become corrupt, or you want to rebuild + the databases instead of updating them. + + *--dbpath* can be specified as an alternative location for where the + databases will be made. The default location is ``*/var/lib/dpkg*''. + An argument like ``*/otherstuff*'' could be provided, and then the + databases would be made here instead. + + *--root* allows a database to be made for a Debian distribution + installed on a different partition. If the distribution is mounted on + */New_Debian*, ``*/New_Debian*'' would be the argument to root. The + databases would be made for the Debian distribution installed on the + ``*/New_Debian*'' partition. + + *--dbpath* and *--root* can be used together. Given the previous two + examples, the databases would be made on ``*/New_Debian/otherstuff*'', + assuming ``*/New_Debian/otherstuff*'' actually existed. + + *--lowmem* uses a method which uses a small amount of memory to make + the databases. By default *--initdb* and *--rebuilddb* use a method + which fully takes advantage of memory, this is a good thing, because + it means the databases are made in a quicker manner. On a computer + with a K6-200 CPU, 64MB of memory, and 1500 installed packages, the + databases can be made in 4.5 minutes using the default method, and 11 + minutes using the low memory method. The high memory method is the + default because in general the size of a distribution is related to + how much resources a computer has, and probably a large installation + is unusual. If you get an ``out of memory'' when you use the default + method, or if your system is overloaded to begin with, the *--lowmem + method* is the prefered way. + + *--split_data* determines the size of the files in the temporary + directory used to contruct the database. The default is 25000 lines + per file. If you are using the *--lowmem method* you may want to + provide a different argument to *--split_data*, like ``*--split_data + 10000*''. This is a subject of experimentation. + + + +5.2. UPDATING +-------------- + + usage: *swim --db* + + options: *[--dbpath* <*dir*>*] [--root* <*dir*>*] [--check]* + + *--db* allows you to update the databases by hand when packages have + been removed, added, or changed. swim will automatically run *--db* + under certain conditions. + + *--check* prints out the changes to STDERR, and the total to STDOUT + without proceeding with the update. + + See section 5.1, `Initial database making, and Rebuilding for an + Installed system. ' for options *--dbpath* and *--root*. + + + +5.3. REBUILDING THE SEARCH +--------------------------- + + usage: *swim --rebuildflatdb* + + options: *[--dbpath* <*dir*>*] [--root* <*dir*>*]* + + swim makes the flat databases *searchindex.deb* and *dirindex.deb* for + doing *powersearches*. Instead of rebuilding these databases everytime + *--db* is run, new information is just appended to these databases, + and old information is kept. Generally, this is not a problem because + only files and directories which the other databases actually know + something about will be refered to. But in a situation where a file + has changed into a directory, the *powersearch* may not work properly, + because the old file name remains in *searchindex.deb*, and the new + directory name is now in *dirindex.deb* directory. In general, it + takes a lot of changes to the installed system before it is really + becomes necessary to rebuild the flat databases. This process takes + less than a minute on a K6-200 with 1500 packages. + + See section 5.1, `Initial database making, and Rebuilding for an + Installed system. ' for options *--dbpath* and *--root*. + + +5.4. FILES +----------- + + Databases which are made: + + packages.deb + fileindex.deb + statusindex.deb + groupindex.deb + searchindex.deb + dirindex.deb + + +------------------------------------------------------------------------------- + + +6. IMPORTANT DEBIAN DATABASES FOR NOT-INSTALLED DATABASES +---------------------------------------------------------- + + + +6.1. A. downloading the important databases with --ftp. +-------------------------------------------------------- + + usage: swim --ftp + + options: --Contents + --Packages + [--dists ] [--arch ] + [--onec] [--Release_only] + + +6.2. OVERVIEW +-------------- + + *swim* provides a method so that all information about an existing + Debian distribution is quickly accessible through databases. Debian + already provides flat file databases for all its distributions. One + database called ``*Contents-(architecture)*'' provides a complete + listing of all the files associated with each package, the other much + more important database called ``*Packages*'' provides everything from + the Package's description, to all the dependencies for that package. + The Packages database is a crucial database for other important Debian + administrative tools like *dpkg* and *apt*. + + +6.3. DISTRIBUTION DEFINED +-------------------------- + + Debian Distributions choose a name which reflect the development state + of that distribution. The distribution named ``*unstable*'' is where + the majority of the development processing occurs, after *unstable* + has reached a certain level of maturity, it's copied over to a new + distribution called ``*frozen*'' which is tested extensively before + becoming the new ``*stable*'' distribution. The *frozen distribution* + retains the *Release version number* of the *unstable distribution*, + and the *unstable distribution* receives a new *Release version + number*. Eventually, *frozen* becomes *stable*, and at this point both + *frozen*, and the older *stable distribution* are removed. Code names + are associated with the *Release Version number* given for each of the + distributions. This is much better for mirroring Debian sites. + + *swim* was designed to ignore these code names, and instead shows the + user the *Release version number* associated with the distribution. + Swim users must always use the real distribution name, or swim will + not work properly. This is a nice feature because it allows user to + make decisions related to the management of their databases, and makes + research much more easier. + + The other Debian distribution which swim recognizes is *experimental*. + This distribution *does not have any Release version number*, and + contains packages which are considered risky because of their + development level. + + + +6.4. SECTIONS +-------------- + + Each Debian distribution has sections related to the relationship of + each of the packages to the *Debian's Policy Manual*. In ``*main*'' + there are packages which have a correct relationship with these + Policies. Packages in ``*contrib*'' comply with the *DFSG* (*Debian + Free Software Guidelines* found in the *Debian Policy Manual*) but + have various limitations like requiring a package which is found in + non-free, or is not in the Debian archive. Packages in ``*non-free*'' + do not comply with the *DFSG* but are electronically distributable + across international borders. The ``*non-us*'' section is found + outside of the United States and exists for packages which have export + restrictions. + + + +6.5. ARCHITECTURES +------------------- + + Distributions also have architecture specific sections since not all + packages compiled for one architecture can run on all other + archictectures, however, there are a large percentage of packages + which do run on all architectures. The architectures are *alpha*, + *arm*, *i386*, *m68k*, *powerpc*, *sparc*, and more recently + *hurd-i386* which represents packages for the hurd GNU kernel for the + i386 architecture. + + + +6.6. SWIMZ.LIST +---------------- + + *--ftp* uses a file called *swimz.list* which has the same type of + format (see format below) as the *sources.list(5)* which *apt* uses. + There are some differences. The *first difference* mentioned above + (see section 6.3, `DISTRIBUTION DEFINED ') requires that the + distribution names never should be the code names for the *Release + version*. *Secondly*, *apt* only retrieves databases specific to one + archictecture, normally the one you are running *apt* on. With *swim* + though you can fetch databases for any, or every architecture by + adding the architecture to ``deb'' with a hyphen (deb-hurd-i386). If + deb has no architecture appended it is assumed that the architecture + you want is the same as the system you are running *swim* on. + *Thirdly*, at this time *swim* only supports the ftp method. + *Fourthly*, you can change *swimz.list* as often as you want without + worrying about databases being removed so that that the *swimz.list* + and the downloaded databases match. This would occur with *apt's* + *sources.list(5)* if you removed a site. *Fifthly*, databases are kept + in a compressed state. *Sixthly* because the list is used for both + Contents and Packages, more flexibility is provided by only allowing + the default distribution/archictecture or distribution/architecture + provided on the commandline to be downloaded. + + For *apt* users: If you are using *apt*, and *swim* together it is a + good strategy to use the real distribution name in the *sources + list(8)*, and to have an exact copy of the *sources.list(5)* ftp sites + in the *swimz.list*. Packages databases specific to the architecture + *apt* is using can be retrieved using *swim --apt --update* (this also + will keep track of the Release version), and then *swim* can be used + to fetch the architecture specific *Contents database* as shown below. + It should also be of interest to note that Packages downloaded by + either swim or apt can be used interchangeably by using 'cp -a' and + 'gzip -d' or 'gzip -9'. + + Here is a brief outline of the format required by *swimz.list*. + + *deb uri distribution [section ... ]* + + *deb* - represents a standard Debian distribution. And is simply + written as deb or with the architecture appended (*deb* or + *deb-alpha*). + + *uri* - Universal Resource Identifier is exactly how you would enter + an address into a web browser. This address is the base of a Debian + distribution, generally this is right before the directory called + ``*dists*''. So if *dists* is found in */stuff/pub/debian/dists*, and + the site is *somewhere.com* then the uri would be + *ftp://somewhere.com/stuff/pub/debian*. + + *distribution* - This can be *unstable*, *frozen*, *stable*, + *experimental*. Distribution can also be a path which must end with a + slash like *unstable/binary-i386/*. This is used when there is no + section as in the experimental distribution or in sites which do not + have symlinks to the non-us section. No section would be mentioned in + this situation. + + *section* - *main*, *contrib*, *non-free*, *non-US* (write it this + way). + + + +6.7. SWIMZ.LIST EXAMPLES +------------------------- + + Examples (each on one line): + + *deb-alpha ftp://somewhere.com/stuff/pub/debian unstable main contrib + non-US* + + This will fetch the alpha databases from somewhere.com for the + unstable distribution for the main, contrib and non-US sections. + + Note: In these next two examples you can not append any architecture + to deb with a hyphen. + + *deb ftp://somewhere.com/stuff/pub/debian project/experimental/* + + This will fetch the experimental database, but there is not a + Contents-(architecture) database for this distribution. Notice that it + ends with a slash. + + *deb ftp://somewhere.com/stuff/pub/debian-non-US stable/binary-i386/* + + This will fetch the i386 databases for the stable distribution for + non-us, + + +6.8. FTP OR APT? +----------------- + + How you use major mode *--ftp* depends on your goals. Even if you are + using *apt*, you may be interested in keeping tabs on different + architectures. In this case you would have to download the *Packages + databases* specific to these architectures. If you are only interested + in the architecture which *apt* is interested in, then you only need + to use *--ftp* to fetch the *Contents database(s)*. But, because it + isn't a requirement to set up a virtual filesystem, you are not + required to fetch the Contents database. The *advantages* of fetching + the Contents database is determined by the method you choose to make + the database (see chapter 7, `MAKING NOT-INSTALLED DATABASES '). These + advantages include the ability to *view a listing of the files and + directories* associated with a package, the ability to *query files + and directories* to find out which packages relate to them, and the + ability to perform a *powersearch* on all the files and directories to + find the associated packages. + + + +6.9. OPTIONS +------------- + + *Remember:* If you want to download a different + distribution/architecture other than the default specified in your + configuration file, you must specify this on the commandline. + + *--Packages* determines where you want the Packages database as well + as the Release data put when they are downloaded. The *DF argument* + implies that the databases will be put in your default directory (see + `swimrc(5)).' These databases can later be located by the major modes + *--initndb and --rebuildndb* just by using *DF* as an argument. + Alternatively, these databases can be put in any directory you choose + by providing a *directory as an argument*. + + *--Contents* determines where you want the *Content-(architecture)* + `database(s)' put. (see --Packages). + + *--onec* will download only one Contents-arch per + distribution/architecture specified on the commandline or by default. + + *--Release_only* will download only the Release data for the + *swimz.list* or particular *Package(s)* mentioned on the command line. + + *--dists* will only find the distribution which corresponds to the + argument provided this option. + + *--arch* will only find the architecture which corresponds to the + argument provided this option. The different architecture needs to be + specified in swimz.list with a hyphen and the architecture appended to + deb (deb-(arch)). + + +6.10. B. downloading the important databases with apt, and maintenance +options. +---------------------------------------------------------------------------- + + usage: *swim --apt* + + options: *[--update] [--clean] [--autoclean] [--check]* + + Please read section 6.1, `A. downloading the important databases with + --ftp. ' for more information. + + *--update* calls *apt* to download the Packages databases. + + *--clean* is a call to an *apt* option to remove any packages stored + in *apt's* storage area for downloaded packages. The default for this + storage area is */var/cache/apt/arhives* + + *--autoclean* will only clean out packages which are not found in + apt's cache. + + *--check* tests and updates apt's cache. + + +------------------------------------------------------------------------------- + + +7. MAKING NOT-INSTALLED DATABASES +---------------------------------- + + usage: swim --initndb + swim --ndb + swim --rebuildndb + + options: [--Contents ] + [--main] [--contrib] [--non-free] [--non-us] + [--arch ] [--dists ] + [--dbpath ] [--root ] [--alt] + [--split_data ] [-v] [--cron] + [targets|APT|DF] + + + +7.1. OVERVIEW +-------------- + + The *not-installed database* provides swim with many capabilities like + the searching, and querying of packages which do not actually exist on + the live filesystem, as well as the ability to seamlessly install + packages while searching or quering, or the ability to fetch the + packages source code. The *virtual filesystem* is optional, but it is + highly recommended. These two major mode options set up these + databases, after determining the level of interaction which you want. + + Whenever *swim* makes databases it thinks only in terms of one + distribution and one architecture. This keeps things logical. *swim* + does have the ability to take Packages files with multiple + architectures, and distributions, and to extract information for one + distribution and one archictecture to make its databases. This could + provide interesting information from dumps from *apt* (`apt-cache + dumpavail'). + + *--initndb* creates the initial not-installed databases for a + particular architecture and distribution, and *--rebuildndb* remakes + the not-installed databases for that same architecure and + distribution. If not otherwise specified *swim* *will use the values* + it finds in *swimrc* to determine what architecture and distribution + you want to use to make *swim's* databases. Otherwise... + + +7.2. OPTIONS +------------- + + *--arch* allows an argument to override the *architecture* found in + *swimrc*. + + *--dists* allows an argument to override the *distribution* found in + *swimrc*. + + *--alt* is used for a distribution with a Debian archival structure, + but which has a different name. This allows for alternative + distributions. + + When *APT* or *DF* are provided as arguments (see below), by default + the *Packages* which pertain to the sections found in *swimrc* will be + shown. If you only want certain sections you may specify them on the + command line. If you are not using *APT* or *DF*, it is a good idea to + make sure that either the sections found in *swimrc* or the sections + you put on the command line match the *Packages* you a targetting + because this is much more effecient. + + *--main* will override the sections found in *swimrc*, and will use + this section. + + *--contrib* will override the sections found in *swimrc*, and will use + this section + + *--non-free* will override the sections found in *swimrc*, and will + use this section + + *--non-us* will override the sections found in *swimrc*, and will use + this section + + Global arguments *targets|APT|DF* must be used with either of these + two major modes to find the *Packages* databases. targets can be a + full path to one or a set of *Packages*. *APT* will use the *Packages* + found in */var/state/apt/lists*, and *DF* will use the Packages found + in the default directory for *swim* (see `--ftp'). If you use either + *APT* or *DF* you will be given an *interface* which allows you to + choose one *Packages* database for each section you would like to use + from the various sites. This *interface* shows the *site*, *date*, + *size* and *Release version* for each *Packages*. + + *--cron* allows you to override the *interface* produced when *APT* or + *DF* is provided as an argument. This is useful if you want to + automate the database making process. *--cron* will choose the newest + `database(s),' if cron notices that the Release version has changed, + cron will not proceed, but will provide a warning instead. This allows + you to make the appropriate changes and choices. + + *--Contents* can be give one of four arguments: + + *1).* If you have a *Contents-(architecture)* database in a target + location you know about you may provide a path to the location. The + *Contents* database can be compressed. + + *2).* If you prepend the path with the letters *FDB* (meaning flat + database) when the databases for swim are made, instead of using the + Contents database to make: + nfileindex-arch-dists.deb + nsearchindex-arch-dists.deb + ndirindex-arch-dists.deb + + Only the *ncontentsindex-arch-dists.deb.gz* database will be made + which allows the ability to view file/dir listing for not-installed + packages, but does not provide the virtual file system or powersearch + capabilities which the other databases would have provided. + + *3).* The argument *DF* may be used if you have used *--ftp* with the + *DF* argument to the option *--Contents* (see `--ftp'). In this case + it is assumed you are also using global arguments *DF* or *APT* for + the Packages databases. This will give you an *interface* (if --cron + isn't used) allowing you to choose one *Contents* database for the + particular distribution you want to make the databases for. + + *4).* *FDB* does the same exact thing with *DF* as it does with the + before mentioned *FDBtarget*, and provides the *interface*. + + *-v* will only work if you have dpkg installed. It allows swim to + verify *swim's* own built-in version comparison function with *dpkg's + version comparison function*. This is good for debugging purposes, and + produces a report called *.version_compare* in the same location that + *swim's* databases are made. + + *--split_data* is only advantageous if *--Contents* is being used. See + *--initdb* for more information about the *--split_data* option. + + See section 5.1, `Initial database making, and Rebuilding for an + Installed system. ' for options `--dbpath' and `--root'. + + +7.3. UPDATING +-------------- + + `--ndb' has the same options as --initndb and --rebuildndb except for + --split_data. It also has a new option `--nue' which will never have + to be used unless the experimental distribution or non-us section are + found in Contents (which presently isn't the case). `--check' prints + out the changes to STDERR, and the total to STDOUT without proceeding + with the update. `--status_only' can be used after a new package has + been installed to update the status, after which -qni and -qi will + correlate properly. + + +7.4. REBUILDING THE SEARCH +--------------------------- + + `--rebuildflatndb' serves the same purpose as --rebuildflatdb. See + section 5.3, `REBUILDING THE SEARCH ' + + +7.5. FILES +----------- + + Databases and reports which are made (arch = architecture dists = + distribution): + + npackages-arch-dists.deb + nfileindex-arch-dists.deb requires <--Contents> + nstatusindex-arch-dists.deb + ngroupindex-arch-dists.deb + nsearchindex-arch-dists.deb + ndirindex-arch-dists.deb + .packagesdiff-arch-dists.deb requires <--Contents> + + + +------------------------------------------------------------------------------- + + +8. PREPARING YOUR INSTALLATION FOR APT +--------------------------------------- + + usage: swim --audit + swim --status + swim -C + + If you are using *apt* with *swim*, and this is the first time you are + using it with your installation, check your live installation with + this major mode. This is a call to *dpkg -C (--audit)*, and will show + any packages which are not properly configured or installed. If you + get any output, make corrections. The goal is to get absolutely no + output whatsoever because it is under these conditions that apt will + work properly. See the section 9.8, `REMOVING AN INSTALLED PACKAGE - + VIRTUAL OPTIONS ' with *-q* to remove the offending packages. You may + have to remove the package by hand under unusual situations like when + it is not just dependencies (see `-T') between packages keeping the + package from being removed perhaps due to a broken script (see + `--scripts'). In an extreme case you could manually remove the entry + for this package from the */var/lib/dpkg/status* database, and hunt + down and remove all the files associated with the package with *swim's + -l* option. When you are done if you still want some of the packages + you removed, use *apt* to reinstall them with *swim's -xyz* option. + Also, *apt* provides its own built-in method to clean up your system, + and will provide instructions, but you still may have to do some of + the cleaning yourself as discussed above. + + +------------------------------------------------------------------------------- + + +9. QUERYING THE INSTALLED AND NOT-INSTALLED DATABASES +------------------------------------------------------ + + usage: swim -q [-fpgn --dir] [targets | -S] + swim --query [-fpgn --dir] [targets | -S] + swim -qa || swim --query -a + + options: [--total -t] [-i] [-l ? <[--df]>] [-d] [-c] + [--scripts] [--preinst] [--postinst] [--prerm] + [--postrm] [-v] [--dbpath ] [--menu -m] + [--shlibs] [-T] [--pre_depends] [--depends] + [--recommends] [--suggests] [--conflicts] + [--replaces] [--provides] [--md5sum] [--root ] + [--copyright] [--changelog] [--allgroups] + [--arch ] [--dists ] + [--ftp ? --source | --source_only ? <[--diff]>] + [--stdin] [--extract] ] + [-xyrz --remove ? <[--nz]>] [--purge] [--apt2df] + [--df2apt] + + global arguments: *[targets | -S ? <\d{1,}>]* + + Quering almost always involves using *-q or --query* with zero or one + or a combination of the *minor mode options* (package specification + options), and one or more (only one for `-g') targets specific to the + minor mode, or the results of a search (`-S'). [`-S' can be provided a + numerical argument pertaining to the past history.] This can be + combined with one or more options. The one exception is ``*swim -q + --allgroups*''. + + *--query or -q* can be used by itself or with *-n* to query known + package names or package names with versions. ``*swim -q test1 + test2_0.3-1*'' would produce the output: + + test1_1.0-2 + test2_0.3-1 + + +9.1. MINOR MODES +----------------- + + *-n* is the minor mode option to access the *not-installed system*, it + can be combined with the minor mode options *-a*, *-g*, *-f*, or it + can be used by itself. + + *-a* allows *every package* on an installed or not-installed (*-n*) + system to be queried. ``*swim -qan*'' will show all the package names + with versions for the not-installed system + + *-f* allows *files or directories* to be queried, when used without + any options the package name with version is shown. *--dir* will only + query directories, this is useful if you are not sure whether what you + are quering is a directory or a file. When a directory is queried, + swim shows all packages which exist below the queried directory. + ``*swim -qf /*'' is exactly the same as ``*swim -qa*''. Hint: ``*swim + -qf .*'' and ``*swim -qf **'' are quite different, the first shows all + packages which exist below the current directory, and the second will + show the package which each file in the current directory comes from. + + *-g* will query a *group* (also called a section, see subsection + 9.5.3, `SECTION AND PRIORITY ')) of packages. Groups represent + subjects which packages with similiar characteristics are catagorized + by. To view all the groups found in an installed or not-installed + system use ``*swim -q --allgroups*'' or ``*swim -qn --allgroups*''. + ``*swim -qg hamradio*'' or ``*swim -qng hamradio*'' shows all the + package names for the hamradio group. + + *-p* is used to query a *Debian package*, these packages are + distinguished by their ``deb'' ending, but swim can tell whether a + file is a debian package even without the ending. Called without any + options the package name with version will be shown. + + +9.2. SPECIFYING THE DATABASES TO USE +------------------------------------- + + *--dists* will use the databases for the argument given, otherwise the + databases pertaining to the value found in swimrc will be used. + + *--arch* will use the databases for the argument given, otherwise the + databases pertaining to the value found in swimrc will be used. + + Example: *swim -qat --arch hurd-i386 --dists unstable* + + Assuming these databases exist this will show all packages and their + versions for the unstable distribution and architecture hurd-i386 even + if the values in *swimrc* are i386 and stable. + + see section 6.1, `A. downloading the important databases with --ftp. ' + and chapter 7, `MAKING NOT-INSTALLED DATABASES ' for more information + about the databases. + + +9.3. OPTIONS +------------- + + *--total or -t* are *used to override the output suppressor*. The + output suppressor will not show output if a certain number of packages + is exceeded, instead it will show the number of packages you are + querying. This is useful for two reasons, first, knowing the number of + packages you are quering can be very informative, second, it gives you + a chance to add to the command line a pipe to a pager, ex: ``*swim + -qat | less*''. You can set the number that the output suppressor + works at as high or low as you want in the *swimrc(8)* file. By design + the *-t* option will have to be used if the *-i* option is used and + more than one package is being queried. This option can also be used + to alter the output of the various script options (--scripts, + --preinst, --postinst, --prerm, and --postrm). + + *-i* provides *information* about each package being queried. The + format differs slightly for the installed packages versus the + not-installed packages. see section 9.5, `FORMAT ': + + *-l* provides a listing of the files associated with a package. If the + option *--df* is provided as an argument, all the directories + associated with package will be shown. It is important to remember + that many packages provide directories which become important to them + after they are installed, so the option *--df* often provides + necessary information which *-l* called by itself would have not. + + *-d* shows the documentation which the package provides found in + */usr/doc/**, */usr/man/**, */usr/info/**. Other documentation which + the package may provide in a non-standard location will not be shown. + *-d* takes precedence over *-l*, so if *-l* is used on the command + line with *-d*, only the output for *-d* will be shown. + + *-v* is a special option which works only with the minor mode *-p*. It + can be used with *-l*, *--df*, *-d*, to show the packages files and/or + directories in long format (`ls - l'). + + *-c* will show the configuration files packages use. If the package + does not have a configuration file then nothing will be shown. The + output will show the file and its path indented one space with the + *MD5 checksum*. This will not work with *-n*. + + *--scripts* shows all scripts associated with a package with the name + of the script presented before each script in this way + *#####scriptname######*. If the scripts are called individually by + using the script options *--preinst*, *--postinst*, *--prerm*, or + *--postrm* no title is shown, this is nice for writing to a file. If + *-t* is used with the individual script options a title will be shown, + this makes sense because normally only individual packages would be + queried to write a script to a file, and *-t* wouldn't be used in this + situation. Scripts are the soul of Debianized packages allowing + packages to be installed, configured, and removed seamlessly and + cleanly under all kinds of conditions. These options do no work with + *-n*. + + *--menu or -m* is used to view menufiles which belong to various + packages. If the package does not have a menufile nothing will be + shown. This option can be useful in troubleshooting a menu entry which + does not seem to work, or in finding out where the menu entry is. + *Joost Witteveen's Debian menu system* is a centralized program which + interacts with all kinds of menus. *Please read the documentation* + ``*swim -qd menu*'' which comes with the menu package to find out + more. This will not work with *-n*. + + *--shlibs* shows a list of shared libraries certain packages supply. + The *Debian Packaging Manual* (packaging-manual) provides detailed + information about the format of a shlibs file. This will not work with + *-n*. + + *--md5sum* checks *MD5 checksums*. It can be used with *-l*, *-d*, + *-c*, or *-p*. If there are checksums available the md5sum result will + be either *OK*, *FAILED*, or *MISSING*. *MISSING* means that although + a checksum exists, the file can not be found. The result is put after + the file and its path and the *MD5 checksum* or the package name and + version and the *MD5 checksum*. + + *--copyright* does a case insensitive search for copy or license in + the */usr/doc/packagename* directory. This should show how the package + relates to *Debian's Policy Manual*. + + *--changelog* searches for any files in */usr/doc/packagename* which + look like changelogs. Debian packages always have a *Maintainer's* + changelog for the package. There may be a separate changelog kept by + the author of the program. + + +9.4. PACKAGE RELATIONSHIPS +--------------------------- + + *-T* shows all the package relationships of packages. Individual + package relationships can be viewed using *--pre_depends*, + *--depends*, *--recommends*, *--suggests*, *--replaces*, *--conflicts* + or *--provides*. Package relationships are the spirit of Debian + packages, here is a quick overview briefly reiterating what can be + found in the *Debian Packaging Manual*. *Package Maintainers* set + these relationships in control file fields of the same name. + + *Dependencies* *Pre-depends* - means that the pre-depended package or + packages must be installed before the queried package can be + installed. Most packages which have pre-dependencies are usually + essential and required packages. + + *Depends* - declares an absolute dependency to another package or + packages either *real or virtual*. The queried package cannot function + without this other package. + + *Recommends* - declares a strong, but not absolute dependency to + another package or packages either *real or virtual*. You would + usually find the recommended package together with the queried package + in a normal installation. + + *Suggests* - can be one or more packages either *real or virtual* + which would be useful to the queried package, but are not necessary. + *Alternative Packages* + + *Conflicts* - is a package or packages either *real or virtual* which + would cause problems with the queried package, and would not be + allowed to be installed while the queried package was installed. + + *Overwriting files and Replacing Packages* + + *Replaces* - allows the queried package to replace another package or + packages by overwriting their files, after which the previous package + would be considered to have disappeared. Essentially this allows the + queried package to take over the package or packages. In a situation + where there was a Conflict between the queried package and these + packages this field would help determine which packages should be + removed. + + *Virtual Packages* + + *Provides* - declares a virtual package which may be mentioned in + *Depends*, *Recommends*, *Suggests*, or *Conflicts*. *Virtual + packages* allow one or more packages to share the same name of another + package, which means if the queried package has a reference to a + virtual package in one of the before mentioned package relationship + fields, then whatever packages provide the virtual package are also + being listed. + + +9.5. FORMAT +------------ + + *1). Installed system* + + Package: name Status: hold ok installed + Version: 1.1-1 Essential: no + Section: namers Priority: extra + Installed-Size: 10 Source: generatename (2.0-1) + Maintainer: name + Description: hostname maker + A nice way to figure out a hostname nobody + else has. + + *2) Not-installed system* + + Package: name Status: r> hold ok installed (1.1-1) + Version: 1.1-2 Essential: no + Section: names Priority: extra + Installed-Size: 11 Source: generatename (2.0-1) + Size: 43000 Architecture: i386 + Distribution: experimental + Maintainer: name + Description: hostname maker + A nice way to figure out a hostname nobody + else has. + + There are several things to point out. The difference between the two + outputs relates to the addition of the Distribution, Size, and + Architecture fields for the not-installed query. Installed-Size is how + many kilobytes the package will occupy when it is unpacked, whereas + Size is the size in bytes of the package. + +9.5.1. STATUS FIELD +-------------------- + + The Status field provides the installation status of the package, this + holds true for the not-installed query as well. In a sense, the + not-installed database isn't always not-installed. If the + not-installed package is actually already installed, and the version + numbers are exactly the same, then the status will be the same for + either query. If the not-installed package is not installed then the + status will be ``not-installed''. In cases where the not-installed + package is already installed, swim uses it's comparison function to + figure out whether it is a newer of older package which is installed. + In the above example, swim realizes the same package is installed, and + only the debian-revision has changed, hence the only difference is + that the revision number is greater ``r>'' for the not-installed + package. When only the debian-revision has changed it can safely be + assumed that the author (creator, programmer) of the same program has + not made any changes to the same program, but the Debian maintainer + has made a change to an aspect of the package like a change in the + script the package uses to properly install. You may have also noticed + that the status field shows the version number of the installed + package enclosed in parenthesis. + +9.5.2. SOURCE FIELD +-------------------- + + The Source field is present in these examples, but the Source field + will not always be present for packages. In cases where the name of + the source package is the same as the the name found in the Package + field, and the version number of the source package is also the same + as found in the Version field, then there will be no Source field. In + the above examples there is a Source field. In this case name was + probably one of many packages generated from the source package called + generatename. In this particular example generatename also has its own + unique version number 2.0-1 enclosed in parentheses, if no version + number had been mentioned then the source package would have the same + version number as found in the Version field. + +9.5.3. SECTION AND PRIORITY +---------------------------- + + Section shows the subject which a package is categorized with (see + `-g'). Priority shows how important the package is to have installed. + In the case of the not-installed databases the information for these + fields is almost always available from the Packages databases, but + this is not always the case for Debian packages. For packages which do + no provide this information swim will do its best to fill in the + blanks from information found in the installed and not-installed + databases. If proper information can not be found it will be indicated + as ``unavailable'' or ``unknown.'' Unavailable would indicate that + information about the package exists, but it is from a different + version (includes debian-revision), and no information exists for this + version. Unknown means no similiar package exists, and there is + absolutely no information about this package in the databases. + + When a Debian package is queried using the *-p* option you will get + output like the first example shows, the status field is also + calculated. + + +9.6. FTP - VIRTUAL OPTIONS +--------------------------- + + For ftp capabilities swim uses the *swimz.list* to determine which + sites it will check for the requested packages. The first site which + fills the request will be used, otherwise *swim* will go through all + the sites avoiding repeats, and if no sites can fill the request, + *swim* will either quit or proceed on to check for another request. + + *--ftp* allows the queried package, its source package, or just the + source package diff to be downloaded while being queried. This is + refered to as virtual downloading because the quering and the + downloading are seamless as though the package already exists locally. + This has to be used with the option *-n* because packages which which + are not part of the not-installed database are considered to already + have been downloaded. Packages which are already installed can be + downloaded or their source retrieved by setting up a database which + corresponds to these packages; if the installed packages belong to the + stable distribution, set-up the not-installed stable databases. + + Packages or source code are placed in an area below the default + directory mirroring the remote directory they were downloaded from + after their size and modification times are checked for correct + values. This area is called the *DF* directory, and although this + directory mirrors remote directories, it is not an exact mirror, but + specific to the requirements of swim because code names for Release + versions are not taken into account. For real mirroring capabilities + there exist many excellent programs. If a package has a *MD5 + checksum*, *--md5sum* will automatically be run and the value shown. + Regardless of whether or not the md5sum check is *OK* or not, the + package will still be put in the *DF* directory to allow the package + to be looked at, so watch the output from *--ftp* to check for *FAILED + md5sums*. + + Packages or source code packages will not be downloaded again if they + are found in the *DF* directory unless their *upstream-version* has + changed in the not-installed database, if the packages are not in the + DF directory and the remote *upstream-version* is different than the + not-installed *upstream-version* then the packages will not be + downloaded until the not-installed database is updated or rebuilt to + reflect the version change. Changes in the package's + *upstream-version* indicates that the `author(s)' of the program have + made changes to the computer code for the program contained in the + package or the source code package. On the other hand, swim will check + for a *debian-revision* change at the remote site if the package can + not immediately be found. If the package's *debian-revision* has + changed and the package does not exist locally in the *DF* directory, + it will be downloaded. This is a nice feature, especially for the + unstable distribution, because it tends to extend the time needed + before the not-installed database has to be updated or rebuilt to + match the changes at remote sites. + + *--source* is used with *--ftp* to download the source code package. + *--source_only* will download the source code package without the deb + package. *Source packages consist of three files*. The *source control + file* which ends in ``dsc'', the *original source archive* which is a + compressed tar file, and the *unified context diff* showing the + changes necessary to make the original source into Debian source. The + diff can be downloaded by itself if *--diff* is provided as an + argument to *--source or --source_only*. + + For *apt* users: *apt* allows packages to be downloaded, but if more + than one package is required for the package relationships to be + proper, *apt* will download all these packages. *--ftp* allows + specific packages to be downloaded, packages from other architectures, + and source packages to be downloaded, here lies the advantage of this + option over using *-xyz --nz* (see below). If a particular package has + been dowloaded into the *DF* directory and it is needed by *apt* for + installation, simply copy or move the package from the *DF* directory + to */var/cache/apt/archives* before running *apt*, and the package + will not be downloaded by *apt* again; future versions of *swim* will + have an option to automatically accomplish this (see `--df2apt'). + + +9.7. APT - VIRTUAL OPTIONS +--------------------------- + + apt-get(8) is a nice package relationship checker from the *apt* + package which figures out what needs to be done to properly install a + package or packages when one or more package names are provided to it. + *apt-get* will get all packages which are needed using a variety of + methods, and then *apt-get* interacts with *dpkg* in a way which + allows for a successful installation. + + *-xyrz, --remove, and --nz* can be used if *apt-get* from the *apt* + package is installed. These options allow for what is refered to as + virtual installation/removal. It is prudent to always test what will + happen by using the *-x* option alone before actually proceeding with + the installation with the *-z* option. *-x* will actually simulate + what would happen in an installation, showing which and how many + packages will be changed, which and how many new packages will need to + be installed, which and how many packages will need to be removed, any + conflicts, and what needs to be configured. *-y* will automatically + answer yes to any prompts *apt-get* may produce allowing *apt-get* to + run non-interactively. *-z* as mentioned before actually proceeds with + the installation using *dpkg* after the *apt-get* gets the packages. + You can append a minus sign to a package name to cause it to be + removed. *--nz* when used as an optional argument with *-xz or -xyz* + will only download the packages into */var/cache/apt/archives* or into + whatever directory you configured for holding archives for *apt*. + + *IMPORTANT*: *apt* makes it so easy to make changes to your + installation that it is highly recommended to do your research with + swim first. This can be done by checking package relationships, + file/dir listings, comparing the not-installed package to an installed + package if such exists, checking *--md5sum* and *-c* for the installed + package, and checking the Source field by running a *--search* (see + chapter 11, `SEARCHING ') to check to see how the source package has + been split into binary packages for the not-installed package versus + an installed package if such exists. Ofcourse, there are many other + things you could look at, and you can always do your research after + the fact. Presently *--db* is run only by hand, so you can check the + old state after an installation if you have not already run *--db*, + yourself. + + +9.8. REMOVING AN INSTALLED PACKAGE - VIRTUAL OPTIONS +----------------------------------------------------- + + *--purge* uses *dpkg* to remove an installed package or packages and + the configuration files as shown with ``*swim -qc packagename*''. + + *-r or --remove* removes an installed package or packages with *apt*, + but not the configuration files as shown with ``*swim -qc + packagename*''. You may also append a plus sign to a package name to + cause it to be installed. This option is used with -x or -x(y)z. + + +9.9. STDIN - VIRTUAL OPTIONS +----------------------------- + + *--stdin* works with either *--ftp*, *-x*, *-xyz*, *-xz*, *--purge*, + *-r*, or *--remove*. + + *--stdin* provides the *readline capabilities* commonly found in + shells allowing you to edit what is on the command line. You can edit + the command line, press enter and then recall the history, and make + more changes, or *type in exit to process the changed or unchanged + command line*. To find out more about what readline commands your + shell supports please read the man pages which apply to your shell. + Information for the bash shell can be found in `bash(1)' under the + title ``*Readline Command Names*''. + + Example: ``*swim -qgnx --stdin hamradio*'' will list all the packages + from the not-installed hamradio group on the command line, this list + can be edited then submitted to *apt-get* for a simulated + installation. Another instance of *swim* can be run at the same time, + perhaps ``*swim -qinTg hamradio*'' to help in making editing decisions + for *--stdin*. + + +9.10. PACKAGE MANIPULATION - VIRTUAL OPTIONS +--------------------------------------------- + + *--extract* only works with the *minor mode -p* to extract parts or + all of a Debian package. If the *argument ALL* is provided then + *everything found in the package will be extracted* below the current + directory in the exact directories found in the package. A particular + *file may be extracted in its exact location* below the current + directory by *entering the exact path for the file* as shown by + ``*swim -qpl*'' or ``*swim -qpd*'' as the argument. Alternativily, a + *file may be extracted in the current directory* regardless of its + proper location by *prepending PWD\! before the path* shown by ``*swim + -qpl*'' or ``*swim -qpd*''. Notice the backslash before the + exclamation point, this is because shells consider ! a special + character, so it has to be backslashed so that the shell knows that it + is not such a special character. Example: ``*swim -qpi --extract + PWD\!usr/bin/name --scripts name_1.1-2.deb*'' will extract the binary + name in the current directory from the name package, show information + for the name package, and show any scripts for the name package. + + +9.11. DATABASE LOCATIONS +------------------------- + + *--dbpath* can be specified as an alternative location for where the + databases would be found. The default location is ``*/var/lib/dpkg*''. + An argument like ``*/otherstuff*'' can be provided, and then the + databases would be found here instead. + + *--root* allows a database to be found for a Debian distribution + installed on a different partition. If the distribution is mounted on + */New_Debian*, ``*/New_Debian*'' would be the argument to root. The + databases would be found for the Debian distribution installed on the + ``*/New_Debian*'' partition. + + *--dbpath and --root* can be used together. Given the previous two + examples, the databases would be found on + ``*/New_Debian/otherstuff*'', assuming ``*/New_Debian/otherstuff*'' + actually existed. + + +------------------------------------------------------------------------------- + + +10. UPGRADING WITH APT +----------------------- + + usage: *swim --apt* + + options: *[-xyz] [--upgrade] [--dist_upgrade]* + + *apt-get* provides powerful methods to change an installion. When + these methods are called using *--apt*, *swim* will not allow you to + proceed until you are absolutely sure this is what you want to do. + Before using these methods do a ``*swim --apt --update*'' so that + *apt-get* knows the newest versions of available packages. This major + mode requires a combination of *-x*, *-xz* or *-xyz* to be used along + with either *--upgrade* or *--dist_upgrade*. *-x* used alone will + simulate what would happen if *-xz or -xyz* were used (also see `-xyz' + above). + + *--upgrade* is somewhat similiar to doing ``*swim -qatxz*'' except + that it is a more intelligent method because *apt* does some behind + the scene calculations in regards to package relationships, in fact + the ``*swim -qatxz*'' approach will provide totally different results, + or maybe these were the results you really wanted. ``*swim --apt + --upgrade -xz*'' is the prefered, proper, and built-in way provided by + *apt-get* to install the newest versions for all packages installed on + your system. This method will not install any newer versions of + packages which would change the install status of other packages. + Note: It is not recommended to combine the query option *-a* with *-xz + or -xyz*, but combining the query option *-a* just with *-x* can be + educational. + + *--dist_upgrade* combines an *--upgrade* with the installation of + packages which are not installed. This method carefully examines + dependencies, and resolves conflicts, and given these factors it will + upgrade the most important packages before considering the + installation of less important packages. Less important packages will + be installed only if there are not any conflicts. + + +------------------------------------------------------------------------------- + + +11. SEARCHING +-------------- + +usage: swim --search ? (--research || --refinesearch) + swim --powersearch ? (--research || --refinesearch) + swim --ps ? (--research || --refinesearch) + +options: [-g] [-n] [--dbpath ] [--root ] [--no] + [--arch ] [--dists + [--ftp ? --source | --source_only <[--diff]>] + [-xyrz --remove ? <[--nz]>] [--stdin] [--apt2df] + [--no] [--df2apt] [--purge] [<\d{1,}>] + + [--dir] and no [-g]for --powersearch or --ps + + + +11.1. OVERVIEW +--------------- + + *swim* provides two major types of searches. A search with *--search* + *searches package information* (see section 9.5, `FORMAT '), and a + search with *--powersearch or --ps* *searches package information, and + all files and/or directories associated with each package*. + + The results of either of these searches can be *narrowed down* by + running a test search with *--research* (this step can be skipped) + and/or setting the results in stone with *--refinesearch*. *--search* + can be *narrowed down* initially by specifying a particular *group*, + and *--powersearch* can be *expanded* initially by specifying that + *directories* be searched as well as files. Both searches can *use the + same virtual options* which the major mode *-q or --query* use. + Generally, it is preferable to run a search, and then to provide the + results of a search (*using -S*) as an argument to *-q or --query*; + this allows the results of a search to be queried. Every time a search + is run the results are appended to the history, past searches can be + refined or researched by providing the numerical argument pertaining + to the history. \d{1,} is simply Perl notation meaning a number with + one of more digits. + + *Perl regexps* (see `perlre(1p))' can be used to define the pattern + (string) provided as an argument to a search. Do not surround a + pattern in slashes, a slash is only used after all patterns and before + the *modifiers i and/or m* (swim supports these two modifiers). To + search for more than one pattern, patterns are separated with *bars + (|)*. Patterns may include *quatifiers, and metacharacters*, also + found in `egrep(1).' + + If a search finds any packages which match the search, the package + information will be displayed as the package is found. The package + will only be shown once regardless of how many times it is found while + the search progresses. When the search is over the number of packages + found is shown. + + *--search* provides a search of package information. This is similiar + to grepping ``*swim -qait*'' or ``*swim -qaint*'', but it is + significantly faster. A search can be performed on a particular group + by using *-g* with a group as an argument + + *--powersearch* is somewhat similiar to ``*dpkg --search*'' which + searches all files and directories on an installed system, but it + combines *--search* with the file and/or directory search, and can + also be performed on a not-installed system. A *powersearch* is + significantly faster than the search which *dpkg* provides (even more + so when ```swim --ramdiskon --searchfile''' is used) and even more + importantly provides a logical output of the search (like ```swim -qi + packagename'''). By default a search of all directories is not + performed because usually this is redundant except in rare cases. To + enable a search of all directories use the *--dir* option. + + +11.2. NARROWING A PREVIOUS SEARCH +---------------------------------- + + *--research* allows the results of a previous search to be researched + without making the new results permanent. + + *--refinesearch* allows the results of a previous search to be + researched while making the new results permanent. + + *\d{1,}* is a numerical argument to refine or research a past search + from the history. + + +11.3. MINOR MODES +------------------ + + *-n* allows the not-installed databases to be searched. These + databases will not exist if the not-installed databases were made with + the FDB argument (see `--initndb'). + + *-g* (see -g above and section 9.1, `MINOR MODES '). + + +11.4. OTHER OPTIONS +-------------------- + + *--no* prevents normal output from a search, but does show how many + packages were found. + + See the section ``section 9.2, `SPECIFYING THE DATABASES TO USE ''' + for options *--arch*, *-dists*. + + See the section ``section 9.6, `FTP - VIRTUAL OPTIONS ''' for *--ftp*, + *--source*, *--source_only*, *--diff*, + + See the section ``section 9.7, `APT - VIRTUAL OPTIONS ''' for *-xyz*, + *--nz*, *--stdin*, + + See the section ``section 9.8, `REMOVING AN INSTALLED PACKAGE - + VIRTUAL OPTIONS ''' for *--purge*, *--remove*, *-r*. + + See the section ``section 9.11, `DATABASE LOCATIONS ''' for options + *--dbpath* and *--root*. + + +11.5. EXAMPLES +--------------- + + *swim -gn hamradio --search "radio network/i" --dbpath /test --arch + alpha* + + will search the alpha architecture not-installed system databases in + the /test directory for all package information from the hamradio + group using the case insensitive pattern ``radio network''. + + *swim --powersearch dpkg -xn* + + will search the not-installed system databases for all package + information and all files using the case sensitive pattern dpkg, after + which apt-get will run a simulation of what would happen if it got and + installed these packages. + + +------------------------------------------------------------------------------- + + +12. RAMDISK +------------ + + usage: swim --ramdiskon + swim --ramdiskoff + + options: [-n] [--searchfile] [--arch ] + [--dists ] [--dbpath] [--root] + + no options for --ramdiskoff + + + +12.1. OVERVIEW +--------------- + + A ramdisk can be mounted below the default path or the specified path + for the databases in the dramdisk directory. The ramdisk is used to + speed up powersearchs and/or file/dir listings for packages from the + not-installed system. Also, this is useful if a computer system is + heavily loaded with other processes using the memory, and the ramdisk + tends to persist even after being unmounted. Modern kernels usually + are built with support for ramdisks. If these options do not work the + kernel will need to be compiled to support ramdisks by answering yes + to RAM disk support. Perhaps the best *README* showing how to + configure and compile a kernel comes with the *kernel sources* in the + main directory. + + *--ramdiskon* allows a ramdisk to be created and mounted. If called + with *-n* (not-installed databases) *ncontents-arch-dists.deb.gz* will + automatically be written to the mounted ramdisk. This provides faster + file/dir listing capabilities when using *-l*, *--df*, or *-d* when + querying the not-installed system. Faster powersearch capabilities are + available through the option *--searchfile*. If the search databases + are not already compressed, they will now be compressed, this usually + only needs to be done once or until the databases are updated or + rebuilt again. The search databases will then be written to the + mounted ramdisk. An installed system only writes the search databases + to the mounted ramdisk, so always use --searchfile when specifying + installed system databases. + + *--ramdiskoff* is used to unmount the ramdisk. The not-installed + databases and the installed databases can not be simultaneously + provided by a mounted ramdisk, use *--ramdiskoff* first, then + *--ramdiskon* to install the other databases of choice. This also + pertains to different distributions and/or architectures. + + See the section ``section 9.2, `SPECIFYING THE DATABASES TO USE ''' + for options *--arch*, *-dists*. + + See the section ``section 9.11, `DATABASE LOCATIONS ''' for options + *--dbpath* and *--root*. + + +------------------------------------------------------------------------------- + + +13. FILES +---------- + + Configuration files: + + swimz.list + swimrc + + +------------------------------------------------------------------------------- + + +14. SEE ALSO +------------- + + `swimrc(5),' apt-get(8), sources.list(5), `dpkg(8)' + + +------------------------------------------------------------------------------- + + +15. BUGS +-------- + + Send directly to mttrader@access.mountain.net. + + +------------------------------------------------------------------------------- + + + swim + Jonathan D. Rosenbaum 15 June 1999 + diff --git a/swim-doc/swimrc.text b/swim-doc/swimrc.text new file mode 100644 index 0000000..850c670 --- /dev/null +++ b/swim-doc/swimrc.text @@ -0,0 +1,294 @@ + + swimrc - swim configuration file + -------------------------------- + Jonathan D. Rosenbaum + 27 May 1999 + +0.1 Contents +------------ + + 1. DESCRIPTION + + 2. USAGE + + 3. VARIABLES + 3.1. OUTPUT VARIABLE + 3.2. HISTORY + 3.3. AR or DPKG? + 3.4. APT + 3.5. PAGER + 3.6. NOT-INSTALLED VARIABLES + 3.7. DF LOCATION + 3.8. TEMPORARY DIRECTORY + 3.9. FTP + + 4. OTHER VARIABLES + + 5. FILES + + 6. BUGS + +0.2 Copyright Notice +-------------------- + + Copyright © 1999 Jonathan D. Rosenbaum + + SWIM, including this manual, is free software; you may redistribute it + and/or modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2, or (at + your option) any later version. + + This is distributed in the hope that it will be useful, but *without + any warranty*; without even the implied warranty of merchantability or + fitness for a particular purpose. See the GNU General Public License + for more details. + + You should have received a copy of the GNU General Public License with + the swim source as the file `COPYING'. If not, write to the Free + Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + + +------------------------------------------------------------------------------- + + +1. DESCRIPTION +--------------- + + swimrc is the configuartion file for swim allowing many default values + to be set so that they do not have to be mentioned on the command + line. Swimrc interacts directly with Perl allowing a wide variety of + variables found in SWIW::Conf to be altered. + + +------------------------------------------------------------------------------- + + +2. USAGE +--------- + + Values for variable can be altered for *swim* by assigning different + values enclosed in quotes or quoted whitespace (qw()), and ending with + a semi-colon. + + ` $variable = ``value'';' + + `$variable = ``(value1 value2 ..)'';' + + + +------------------------------------------------------------------------------- + + +3. VARIABLES +------------- + + This is a list of variables with explanations. The default values for + *swim* are shown. + + +3.1. OUTPUT VARIABLE +--------------------- + + `$my_number' can be changed to how many lines you would like ``swim + -qf <>'' to print out, before the program asks for `-t' or `--total'. + Exception: If `-i' is used in the query and there is more than one + package then the total will be presented. + + Hint: `-t' can be used with all the various `--scripts' family members + to view the title of the script file regardless of this variable + setting, and if `-t' has to be used, the titles will be displayed, + which makes sense. + + *$my_number = 23;* + + +3.2. HISTORY +------------- + + This is a shell-like history kept in relation to searches and the most + recent edit when `--stdin' is used. + + *$HISTORY = 10;* + + +3.3. AR or DPKG? +----------------- + + Debian packages are ar archives. If you are using a Debian + Distribution assign ``dpkg'' to $package_tool, otherwise assign ``ar'' + to $package_tool. + + *$package_tool = "/usr/bin/ar";* + + +3.4. APT +--------- + + *Swim* does not assign a value for apt. To use `--apt' and `-xyz' + assign `$apt' the value ``yes''. + + Example: *$apt = "yes";* + + +3.5. PAGER +----------- + + *less* is a nice pager, unless you like *more*! Pager is used for + `--help' and *swim* called without any options. There is an option + `--nopager' or `-n'. *more* comes from the required package + util-linux, whereas *less* comes from a standard package called less. + Values: ``less'', ``more'', or ``most'' or... + + *$ENV{PAGER} = "less";* + + +3.6. NOT-INSTALLED VARIABLES +----------------------------- + + Assign values for `$architecture' and/or `$distribution' to avoid + having to use `--arch' and `--dists' everytime the not-installed + databases are accessed with `-n' or made or altered. + + Architectures are always being added so check with Debian to find a + list. There is *alpha, arm, hurd-i386 (alternative kernel to linux), + i386, m68k, powerpc, sparc*. Just use the arch found after the hyphen + in the Contents-(arch) file. + + *$architecture = "i386";* + + The distribution can be either *stable, unstable, frozen, or + experimental (rare)*. These represent the state of development that + the packages are under. The unstable distribution can have lot's of + changes within a very short time period, and frozen may or may not be + available. + + *$distribution = "unstable";* + + Distributions are divided into sections. These sections were called + distributions in the version 2.4.1.0 packaging manual, because they + were at one time separate distributions, but this has since changed. + + You can determine which of the sections *main, non-free, contrib or + non-US* to pull out of the Contents file if you don't want to use + `--main', `--contrib', `--non-free', and `--non-us' to selectively + pick the sections. + + For efficiency, you should choose the sections which you will be + pulling out of the Packages `file(s)' being targetted. + + Rule: Use ``non-US'' not ``non-us''. + + *@user_defined_section = qw(main contrib non-free non-US);* + + +3.7. DF LOCATION +----------------- + + A little philosophy: *swim* was developed for maximum versatility, so + whether you are just interested in researching, and keeping tabs on + the newest packages, or maintaining a Debian virtual distribution on a + non-Debian distribution, or you are a using *swim* for distribution + development, *swim* provides a way. + + The next two variables determine the location of the DF (default + directory/file system) + + The default directory keeps track of Contents and/or Packages + databases retrieved with --ftp. The Contents and Packages databases + and Release file are give names specific to the distribution and + architectures they represent using the naming convention found in + apt's sources directory. You also have the freedom not to use the + default directory, in which case swim will still do the renaming and + keeping track of the mtime, but you will have to remember where you + put the files. + + *$default_directory = '/root/.swim';* + + The default root directory (DRD) is the key to easy management of + binary packages, source, dsc, and diff files received from --ftp, and + provides an easy way to put together a personalized distribution. This + directory can be a real ftp site on your computer, or put wherever + else you are allowed to have directories. The DRD is always placed + below the value assigned to $default_directory. According to the + previous assignment to $default_directory, if the DRD is + ``/pub/a/debian'' then the full path would be + ``/root/.swim/pub/a/debian''. + + Example: When a package is downloaded it will be placed in + dists/distribution/section/architecture/subject below the DRD. + + Rule: debian must be the final directory before dists, this is because + other distributions are placed alongside debian, like debian-non-US or + personal (specialized distribution). + + *$default_root_directory = '/pub/debian';* + + Because you may be using a real ftp site, this variable allows you to + determine what permissions *swim* will assign for directories it + creates below the DRD. + + *$permission = '0755';* + + +3.8. TEMPORARY DIRECTORY +------------------------- + + If you want to set an alternative directory for the temporary files + created when the databases are made, change here. You may want to make + `$tmp' a RAM disk. See package loadlin for initrd documentation and an + explanation for making such a disk. There is also documentation in + /usr/src/kernel-source.version/Documentation. Whether this will speed + things up is a subject of experimentation. + + *$tmp = "/tmp";* + + +3.9. FTP +--------- + + You can alter the Firewall, Port, Timeout, Debug and Passive + characteristics of the ftp client as defined in Net::FTP(3pm) by + providing arguments to these variables. All variables but $timeout are + set to untrue by default. + $firewall = 0; (FTP firewall machine name) + $port = 0; (defaults to 23) + $timeout = 120; (120 seconds) + $debug = 0; (1 will turn on STDERR) + $passive = 0; (1 will enable) + + +------------------------------------------------------------------------------- + + +4. OTHER VARIABLES +------------------- + + see SWIM::Conf + + +------------------------------------------------------------------------------- + + +5. FILES +--------- + + ` /etc/swim/swimrc' + + `~/.swim/swimrc' + + +------------------------------------------------------------------------------- + + +6. BUGS +------- + + Send directly to mttrader@access.mountain.net. + + +------------------------------------------------------------------------------- + + + swimrc - swim configuration file + Jonathan D. Rosenbaum 27 May 1999 +