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. 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 <enter>`` 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)<pattern(s)>}

`||' or `|' are used to indicate `or', `?' indicates `optional', <diamond> 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 ). VERSION

usage: swim --version

This shows the version for the swim program. HISTORY

usage: swim --history swim -h options: [--arch <architecture>] [--dists <distribution>] [--n] [--dbpath <dir>] [--root <dir>]

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. MAKING INSTALLED SYSTEM DATABASES

Initial database making, and Rebuilding for an Installed system.

usage: swim --initdb swim --rebuilddb options: [--dbpath <dir>] [--root <dir>] [--lowmem] [--split_data <lines>]

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.

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 for options --dbpath and --root.

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 for options --dbpath and --root. FILES

Databases which are made:

packages.deb fileindex.deb statusindex.deb groupindex.deb searchindex.deb dirindex.deb IMPORTANT DEBIAN DATABASES FOR NOT-INSTALLED DATABASES

A. downloading the important databases with --ftp.

usage: swim --ftp options: --Contents <DF|directory> --Packages <DF|directory> [--dists <distribution>] [--arch <architecture>] [--onec] [--Release_only] 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. 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.

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.

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.

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 ) 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).

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, 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 ). 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.

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)). B. downloading the important databases with apt, and maintenance options.

usage: swim --apt

options: [--update] [--clean] [--autoclean] [--check]

Please read 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. MAKING NOT-INSTALLED DATABASES

usage: swim --initndb swim --ndb swim --rebuildndb options: [--Contents <target|FDBtarget|DF|FDBDF>] [--main] [--contrib] [--non-free] [--non-us] [--arch <architecture>] [--dists <distribution>] [--dbpath <dir>] [--root <dir>] [--alt] [--split_data <lines>] [-v] [--cron] [targets|APT|DF]

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... 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 for options --dbpath and --root. 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. REBUILDING THE SEARCH

--rebuildflatndb serves the same purpose as --rebuildflatdb. See 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>

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 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. 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 <dir>] [--menu -m] [--shlibs] [-T] [--pre_depends] [--depends] [--recommends] [--suggests] [--conflicts] [--replaces] [--provides] [--md5sum] [--root <dir>] [--copyright] [--changelog] [--allgroups] [--arch <architecture>] [--dists <distribution>] [--ftp ? --source | --source_only ? <[--diff]>] [--stdin] [--extract] <ALL|archive|PWD!archive>] [-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 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 )) 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. 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 and for more information about the databases. 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 :

-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. 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. 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 <name@name.org> 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 <name@name.org> 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. 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. 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. 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. 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). 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 ) 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. 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. 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. 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. 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. 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. SEARCHING

usage: swim --search ? (--research || --refinesearch) <pattern(s)> swim --powersearch ? (--research || --refinesearch) <pattern(s)> swim --ps ? (--research || --refinesearch) <pattern(s)> options: [-g] [-n] [--dbpath <dir>] [--root <dir>] [--no] [--arch <architecture>] [--dists <distribution> [--ftp ? --source | --source_only <[--diff]>] [-xyrz --remove ? <[--nz]>] [--stdin] [--apt2df] [--no] [--df2apt] [--purge] [<\d{1,}>] [--dir] and no [-g]for --powersearch or --ps

OVERVIEW

swim provides two major types of searches. A search with --search searches package information (see ), 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. 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. 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 ). OTHER OPTIONS

--no prevents normal output from a search, but does show how many packages were found.

See the section ``'' for options --arch, -dists.

See the section ``'' for --ftp, --source, --source_only, --diff,

See the section ``'' for -xyz, --nz, --stdin,

See the section ``'' for --purge, --remove, -r.

See the section ``'' for options --dbpath and --root. 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. RAMDISK

usage: swim --ramdiskon swim --ramdiskoff options: [-n] [--searchfile] [--arch <architecture>] [--dists <distribution>] [--dbpath] [--root] no options for --ramdiskoff

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 ``'' for options --arch, -dists.

See the section ``'' for options --dbpath and --root. FILES

Configuration files:

swimz.list swimrc SEE ALSO

swimrc(5), apt-get(8), sources.list(5), dpkg(8) BUGS

Send directly to mttrader@access.mountain.net.