" there are +packages which have a correct relationship with these Policies. Packages +in "I" comply with the I (I found in the I) but have various +limitations like requiring a package which is found in non-free, or is not +in the Debian archive. Packages in "I" do not comply with the +I but are electronically distributable across international borders. +The "I" section is found outside of the United States and exists +for packages which have export restrictions. + +=head2 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 I, I, +I, I, I, I, and more recently I +which represents packages for the hurd GNU kernel for the i386 +architecture. + +=head2 SWIMZ.LIST + +B<--ftp> uses a file called F which has the same type of +format (see format below) as the F which B uses. +There are some differences. The B mentioned above +requires that the distribution names never should be the code names for +the I. B, B only retrieves databases +specific to one archictecture, normally the one you are running B on. +With B 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 B on. B, at this +time B only supports the ftp method. B, you can change +F as often as you want without worrying about databases being +removed so that that the F and the downloaded databases match. +This would occur with B F if you removed a site. +B, databases are kept in a compressed state. B, 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 B users: If you are using B, and B together it is a +good strategy to use the real distribution name in the F, +and to have an exact copy of the F ftp sites in the +F. Packages databases specific to the architecture B is +using can be retrieved using B (this also will keep +track of the Release version), and then B can be used to fetch the +architecture specific F 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 F. + +B + +B - represents a standard Debian distribution. And is simply written +as deb or with the architecture appended (B or B). + +B - 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 +"F". So if F is found in F, and the +site is B then the uri would be +F. + +B - This can be I, I, I, +I. Distribution can also be a path which must end with a +slash like F. 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. + +B

- I

, I, I, I (write it this +way). + + +=head2 SWIMZ.LIST EXAMPLES + +Examples (each on one line): + +B + +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. + +B + +This will fetch the experimental database, but there is +not a Contents-(architecture) database for this distribution. Notice that +it ends with a slash. + +B + +This will fetch the i386 databases for the stable distribution for non-us, + +=head2 FTP OR APT? + +How you use major mode B<--ftp> depends on your goals. Even if you are +using B, you may be interested in keeping tabs on different +architectures. In this case you would have to download the I specific to these architectures. If you are only interested in +the architecture which B is interested in, then you only need to use +B<--ftp> to fetch the I. But, because it isn't a +requirement to set up a virtual filesystem, you are not required to fetch +the Contents database. The B of fetching the Contents +database is determined by the method you choose to make the database (see +C<--initndb>). These advantages include the ability to I associated with a package, the ability to +I to find out which packages relate to them, +and the ability to perform a I on all the files and +directories to find the associated packages. + +=head2 OPTIONS + +B 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. + +B<--Packages> determines where you want the Packages database as well as +the Release data put when they are downloaded. The B implies +that the databases will be put in your default directory (see swimrc(8)). +These databases can later be located by the major modes B<--initndb and +--rebuildndb> just by using B as an argument. Alternatively, these +databases can be put in any directory you choose by providing a +B. + +B<--Contents> determines where you want the F +database(s) put. (see --Packages). + +B<--onec> will download only one Contents-arch per +distribution/architecture specified on the commandline or by default. + +B<--Release_only> will download only the Release data for the +F or particular F mentioned on the command line. + +B<--dists> will only find the distribution which corresponds to the +argument provided this option. + +B<--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)). + +=head2 B. downloading the important databases with apt, and maintenance +options. + +usage: B + +options: B<[--update] [--clean] [--autoclean] [--check]> + +Please read "B" for +more information. + +B<--update> calls B to download the Packages databases. + +B<--clean> is a call to an B option to remove any packages stored in +B storage area for downloaded packages. The default for this +storage area is F + +B<--autoclean> will only clean out packages which are not +found in apt's cache. + + +B<--check> tests and updates apt's cache. + + +=head1 MAKING NOT-INSTALLED DATABASES + +usage: B + B + B + +options: B<[--Contents> >B<]> + B<[--main] [--contrib] [--non-free] [--non-us]> + B<[--arch> >B<]> B<[--dists> >B<]> + B<[--dbpath> >B<] [--root> >B<] [--alt]> + B<[--split_data> >B<] [-v] [--cron]> + B<[targets|APT|DF]> + +=head2 OVERVIEW + +The B 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 I 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 B makes databases it thinks only in terms of one +distribution and one architecture. This keeps things logical. B +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 B (C). + +B<--initndb> creates the initial not-installed databases for a particular +architecture and distribution, and B<--rebuildndb> remakes the +not-installed databases for that same architecure and distribution. If not +otherwise specified B I it finds in F +to determine what architecture and distribution you want to use to make +B databases. Otherwise... + +=head2 OPTIONS + +B<--arch> allows an argument to override the B found in +F. + +B<--dists> allows an argument to override the B found in +F. + +B<--alt> is used for a distribution with a Debian archival +structure, but which has a different name. This allows for alternative +distributions. + +When B or B are provided as arguments (see below), by default the +F which pertain to the sections found in F will be +shown. If you only want certain sections you may specify them on the +command line. If you are not using B or B, it is a good idea to +make sure that either the sections found in F or the sections you +put on the command line match the F you a targetting because +this is much more effecient. + +B<--main> will override the sections found in F, and will use this +section. + +B<--contrib> will override the sections found in F, and will use +this section + +B<--non-free> will override the sections found in F, and will use +this section + +B<--non-us> will override the sections found in F, and will use +this section + +Global arguments B must be used with either of these two +major modes to find the F databases. targets can be a full path +to one or a set of F. B will use the F found in +F, and B will use the Packages found in the +default directory for B (see C<--ftp>). If you use either B or +B you will be given an B which allows you to choose one +F database for each section you would like to use from the +various sites. This B shows the B, B, B and +B for each F. + +B<--cron> allows you to override the B produced when B or +B is provided as an argument. This is useful if you want to automate +the database making process. B<--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. + +B<--Contents> can be give one of four arguments: + +B<1).> If you have a F database in a target +location you know about you may provide a path to the location. The +F database can be compressed. + +B<2).> If you prepend the path with the letters B (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 F 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. + +B<3).> The argument B may be used if you have used B<--ftp> with the +B argument to the option B<--Contents> (see C<--ftp>). In this case +it is assumed you are also using global arguments B or B for the +Packages databases. This will give you an B (if --cron isn't +used) allowing you to choose one F database for the particular +distribution you want to make the databases for. + +B<4).> B does the same exact thing with B as it does with the +before mentioned B, and provides the B. + +B<-v> will only work if you have dpkg installed. It allows swim to verify +B own built-in version comparison function with B. This is good for debugging purposes, and produces a +report called F<.version_compare> in the same location that B +databases are made. + +B<--split_data> is only advantageous if B<--Contents> is being used. See +B<--initdb> for more information about the B<--split_data> option. + +See C<--initdb> for options C<--dbpath> and C<--root>. + +=head2 UPDATING + +B<--ndb> has the same options as --initndb and --rebuildndb except for +--split_data. It also has a new option B<--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). B<--check> prints out the +changes to STDERR, and the total to STDOUT without proceeding with the +update. B<--status_only> can be used after a new package has been +installed to update the status, after which -qni and -qi will correlate +properly. + +=head2 REBUILDING THE SEARCH + +B<--rebuildflatndb> serves the same purpose that --rebuildflatdb serves. + +=head2 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 + ncontenstsindex-arch-dists.deb.gz requires --Contents + .packagesdiff-arch-dists.deb requires --Contents + +=head1 PREPARING YOUR INSTALLATION FOR APT + +usage: B + B + B + +If you are using B with B, 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 B, 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 B<--purge>, B<-r>, B<--remove> options for B<-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 C<-T>) +between packages keeping the package from being removed perhaps due to a +broken script (see C<--scripts>). In an extreme case you could manually +remove the entry for this package from the F +database, and hunt down and remove all the files associated with the +package with B option. When you are done if you still want +some of the packages you removed, use B to reinstall them with +B option. Also, B 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. + + +=head1 QUERYING THE INSTALLED AND NOT-INSTALLED DATABASES + +usage: B + B + B + +options: B<[--total -t] [-i] [-l ?> >B<] [-d] [-c]> + B<[--scripts] [--preinst] [--postinst] [--prerm]> + B<[--postrm] [-v] [--dbpath> >B<] [--menu -m]> + B<[--shlibs] [-T] [--pre_depends] [--depends> + B<[--recommends] [--suggests] [--conflicts]> + B<[--replaces] [--provides] [--md5sum]]> + B<[--copyright] [--changelog] [--allgroups]> + B<[--arch> >B<] [--dists> >B<]> + B<[--ftp ? --source | --source_only ?> >B<]> + B<[--stdin] [--extract> >B<]> + B<[-xyrz --remove> >B<] [--purge] [--apt2df]> + B<[--df2apt] [--root> >B<]> + +global arguments: B<[targets | -S ?> >B<]> + +Quering almost always involves using B<-q or --query> with zero or one or +a combination of the B (package specification +options), and one or more (only one for C<-g>) targets specific to the +minor mode, or the results of a search (C<-S>). [C<-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 "B". + +B<--query or -q> can be used by itself or with B<-n> to query known +package names or package names with versions. "B" would produce the output: + + test1_1.0-2 + test2_0.3-1 + + +=head2 MINOR MODES + +B<-n> is the minor mode option to access the I, it +can be combined with the minor mode options B<-a>, B<-g>, B<-f>, or it can +be used by itself. + +B<-a> allows I on an installed or not-installed (B<-n>) +system to be queried. "B" will show all the package names with +versions for the not-installed system + +B<-f> allows I to be queried, when used without any +options the package name with version is shown. B<--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. "B" is +exactly the same as "B". Hint: "B" and "B" 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. + +B<-g> will query a I (also called a section, see C<-i>)) 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 "B" or "B". "B" or "B" +shows all the package names for the hamradio group. + +B<-p> is used to query a I, 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. + + +=head2 SPECIFYING THE DATABASES TO USE + +B<--dists> will use the databases for the argument given, otherwise the +databases pertaining to the value found in swimrc will be used. + +B<--arch> will use the databases for the argument given, otherwise the +databases pertaining to the value found in swimrc will be used. + +Example: B + +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 F are i386 and stable. + +see C<--ftp> and C<--initndb> for more information about the databases. + + +=head2 OPTIONS + +B<--total or -t> are I. 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: "B". You can +set the number that the output suppressor works at as high or low as you +want in the F file. By design the B<-t> option will have to be +used if the B<-i> option is used and more than one package is being +queried. This option can also be used to alter the output of the script +related options (see C<--script>). + +B<-i> provides I about each package being queried. The +format differs slightly for the installed packages versus the +not-installed packages. See FORMAT: + +B<-l> provides a listing of the files associated with a package. If the +option B<--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 B<--df> often provides necessary information +which B<-l> called by itself would have not. + +B<-d> shows the documentation which the package provides found in +F, F, F. Other documentation which +the package may provide in a non-standard location will not be shown. +B<-d> takes precedence over B<-l>, so if B<-l> is used on the command line +with B<-d>, only the output for B<-d> will be shown. + +B<-v> is a special option which works only with the minor mode B<-p>. It +can be used with B<-l>, B<--df>, B<-d>, to show the packages files and/or +directories in long format (C). + +B<-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 B. +This will not work with B<-n>. + +B<--scripts> shows all scripts associated with a package with the name of +the script presented before each script in this way +B<#####scriptname######>. If the scripts are called individually by using +the script options B<--preinst>, B<--postinst>, B<--prerm>, or B<--postrm> +no title is shown, this is nice for writing to a file. If B<-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 B<-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 B<-n>. + +B<--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. I is a centralized program which interacts +with all kinds of menus. I "B" which comes with the menu package to find out more. This will not +work with B<-n>. + +B<--shlibs> shows a list of shared libraries certain packages supply. The +I (packaging-manual) provides detailed +information about the format of a shlibs file. This will not work with +B<-n>. + +B<--copyright> does a case insensitive search for copy or license in the +F directory. This should show how the package +relates to I. + +B<--changelog> searches for any files in F which +look like changelogs. Debian packages always have a I +changelog for the package. There may be a separate changelog kept by the +author of the program. + +=head2 PACKAGE RELATIONSHIPS + +B<-T> shows all the package relationships of packages. Individual package +relationships can be viewed using B<--pre_depends>, B<--depends>, +B<--recommends>, B<--suggests>, B<--replaces>, B<--conflicts> or +B<--provides>. Package relationships are the spirit of Debian packages, +here is a quick overview briefly reiterating what can be found in the +I. I set these +relationships in control file fields of the same name. + +=head2 Dependencies + +I - 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. + +I - declares an absolute dependency to another package or +packages either I. The queried package cannot function +without this other package. + +I - declares a strong, but not absolute dependency to another +package or packages either I. You would usually find the +recommended package together with the queried package in a normal +installation. + +I - can be one or more packages either I which +would be useful to the queried package, but are not necessary. + +=head2 Alternative Packages + +I - is a package or packages either I +which would cause problems with the queried package, and would not be +allowed to be installed while the queried package was installed. + +=head2 Overwriting files and Replacing Packages + +I - 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. + +=head2 Virtual Packages + +I - declares a virtual package which may be mentioned in +I, I, I, or I. I 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. + +B<--md5sum> checks B. It can be used with B<-l>, B<-d>, +B<-c>, or B<-p>. If there are checksums available the md5sum result will +be either B, B, or B. B means that although +a checksum exists, the file can not be found. The result is put after the +file and its path and the B or the package name and version +and the B. + +=head2 FORMAT + +B<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. + +B<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. + + +=head2 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. + +=head2 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. + +=head2 SECTION AND PRIORITY + +Section shows the subject which a package is categorized with (see C<-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. + +=head2 DEBIAN PACKAGE OUTPUT + +When a Debian package is queried using the B<-p> option you will get +output like the first example shows, the status field is also calculated. + +=head2 VIRTUAL OPTIONS + +=head2 FTP + +For ftp capabilities swim uses the F to determine which sites +it will check for the requested packages. The first site which fills the +request will be used, otherwise B will go through all the sites +avoiding repeats, and if no sites can fill the request, B will +either quit or proceed on to check for another request. + +B<--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 B<-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 B 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 B, B<--md5sum> will +automatically be run and the value shown. Regardless of whether or not +the md5sum check is B or not, the package will still be put in the +B directory to allow the package to be looked at, so watch the output +from B<--ftp> to check for B. + +Packages or source code packages will not be downloaded again if they are +found in the B directory unless their I has changed +in the not-installed database, if the packages are not in the DF directory +and the remote I is different than the not-installed +I 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 I 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 I change at the remote site +if the package can not immediately be found. If the package's +I has changed and the package does not exist locally in +the B 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. + +B<--source> is used with B<--ftp> to download the source code package. +B<--source_only> will download the source code package without the deb +package. I. The I which ends in "dsc", the I which is a +compressed tar file, and the I showing the changes +necessary to make the original source into Debian source. The diff can be +downloaded by itself if B<--diff> is provided as an argument to B<--source +or --source_only>. + +For B users: B allows packages to be downloaded, but if more +than one package is required for the package relationships to be proper, +B will download all these packages. B<--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 B<-xyz --nz> (see below). If a particular package has been +dowloaded into the B directory and it is needed by B for +installation, simply copy or move the package from the B directory to +F before running B, and the package will not +be downloaded by B again; future versions of B will have an +option to automatically accomplish this (see C<--df2apt>). + +=head2 APT + +apt-get(8) is a nice package relationship checker from the B 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. B +will get all packages which are needed using a variety of methods, and +then B interacts with B in a way which allows for a +successful installation. + +B<-xyrz, --remove and --nz> can be used if B from the B +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 B<-x> option alone before actually proceeding with the +installation with the B<-z> option. B<-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. B<-y> will automatically answer yes to any +prompts B may produce allowing B to run +non-interactively. B<-z> as mentioned before actually proceeds with the +installation using B after the B gets the packages. You +can append a minus sign to a package name to cause it to be removed. +B<--nz> when used as an optional argument with B<-xz or -xyz> will only +download the packages into F or into whatever +directory you configured for holding archives for B. + +B: B 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 B<--md5sum> and B<-c> for the installed package, and +checking the Source field by running a B<--search> (see below) 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 B<--db> is run only by +hand, so you can check the old state after an installation if you have not +already run B<--db>, yourself. + +=head2 REMOVING AN INSTALLED PACKAGE + +B<--purge> uses B to remove an installed package or packages and the +configuration files as shown with "B". + +B<-r or --remove> removes an installed package or packages with B, +but not the configuration files as shown with "B". +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. + +=head2 STDIN + +B<--stdin> works with either B<--ftp>, B<-x>, B<-xyz>, B<-xz>, B<--purge>, +B<-r>, or B<--remove>. + +B<--stdin> provides the I 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 +I. 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 "B". + +Example: "B" will list all the packages from +the not-installed hamradio group on the command line, this list can be +edited then submitted to B for a simulated installation. Another +instance of B can be run at the same time, perhaps "B" to help in making editing decisions for B<--stdin>. + +=head2 PACKAGE MANIPULATION + +B<--extract> only works with the B to extract parts or all +of a Debian package. If the B is provided then I below the current directory in the +exact directories found in the package. A particular I below the current directory by I as shown by "B" or "B" +as the argument. Alternativily, a I regardless of its proper location by I shown by "B" or "B". 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: "B" 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. + +=head2 DATABASE LOCATIONS + +B<--dbpath> can be specified as an alternative location for where the +databases would be found. The default location is "F". An +argument like "F" can be provided, and then the databases +would be found here instead. + +B<--root> allows a database to be found for a Debian distribution +installed on a different partition. If the distribution is mounted on +F, "F" would be the argument to root. The +databases would be found for the Debian distribution installed on the +"F" partition. + +B<--dbpath and --root> can be used together. Given the previous two +examples, the databases would be found on "F", +assuming "F" actually existed. + + + +=head1 UPGRADING WITH APT + +usage: B + +options: B<[-xyz] [--upgrade] [--dist_upgrade]> + +B provides powerful methods to change an installion. When these +methods are called using B<--apt>, B will not allow you to proceed +until you are absolutely sure this is what you want to do. Before using +these methods do a "B" so that B knows the +newest versions of available packages. This major mode requires a +combination of B<-x>, B<-xz> or B<-xyz> to be used along with either +B<--upgrade> or B<--dist_upgrade>. B<-x> used alone will simulate what +would happen if B<-xz or -xyz> were used (also see C<-xyz> above). + +B<--upgrade> is somewhat similiar to doing "B" except that it +is a more intelligent method because B does some behind the scene +calculations in regards to package relationships, in fact the "B" approach will provide totally different results, or maybe these +were the results you really wanted. "B" is the +prefered, proper, and built-in way provided by B 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 B<-a> with B<-xz or -xyz>, but combining the query option +B<-a> just with B<-x> can be educational. + +B<--dist_upgrade> combines an B<--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. + +=head1 SEARCHING + +usage: B + B + B + > + +options: B<[-g] [-n] [--dbpath> >B<] [--root> >B<]> + B<[--arch> >B<] [--dists> >B<]> + B<[--ftp ? --source | --source_only --diff]> + B<[-xyrz --remove ?> >B<] [--stdin] [--apt2df]> + B<[--no] [--df2apt] [--purge] [>B<\d{1,}>B<]> + + B<[--dir]> and no B<[-g]> for B<--powersearch or --ps> + + +=head2 OVERVIEW + +B provides two major types of searches. A search with B<--search> +I, and a search with B<--powersearch or +--ps> I. + +The results of either of these searches can be I by running +a test search with B<--research> (this step can be skipped) and/or setting +the results in stone with B<--refinesearch>. B<--search> can be +I initially by specifying a particular I, and +B<--powersearch> can be I initially by specifying that +I be searched as well as files. Both searches can I which the major mode B<-q or --query> use. +Generally, it is preferable to run a search, and then to provide the +results of a search (B) as an argument to B<-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. + +I (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 +I (swim supports these two modifiers). To search +for more than one pattern, patterns are separated with I. +Patterns may include I, 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. + +B<--search> provides a search of package information. This is similiar to +grepping "B" or "B", but it is significantly +faster. A search can be performed on a particular group by using B<-g> +with a group as an argument + +B<--powersearch> is somewhat similiar to "B" which searches +all files and directories on an installed system, but it combines +B<--search> with the file and/or directory search, and can also be +performed on a not-installed system. A I is significantly +faster than the search which B provides (even more so when "C" is used) and even more importantly provides a +logical output of the search (like "C"). 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 B<--dir> option. + +=head2 NARROWING A PREVIOUS SEARCH + +B<--research> allows the results of a previous search to be researched +without making the new results permanent. + +B<--refinesearch> allows the results of a previous search to be researched +while making the new results permanent. + +B<\d{1,}> is a numerical argument to refine or research a +past search from the history. + +=head2 MINOR MODES + +B<-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 C<--initndb>). + +B<-g> (see C<--search>) + +=head2 OTHER OPTIONS + +B<--no> prevents normal output from a search, but does show how many +packages were found. + +See the section "B" for options +B<--arch>, B<-dists>. + +See the section "B" for options B<--ftp>, +B<--source>, B<--source_only>, B<--diff>, B<-xyz>, B<--nz>, B<--stdin>, +B<--purge>, B<--remove>, B<-r>. + +See the section "B" for options B<--dbpath> +and B<--root>. + +=head2 EXAMPLES + +B + +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". + +B + +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. + + +=head1 RAMDISK + +usage: B + B + +options: B<[-n] [--searchfile] [--arch> >B<]> + B<[--dists> >B<] [--dbpath] [--root]> + + no options for B<--ramdiskoff> + + +=head2 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 F showing how to configure and compile a kernel comes with +the F in the main directory. + +B<--ramdiskon> allows a ramdisk to be created and mounted. If called with +B<-n> (not-installed databases) F will +automatically be written to the mounted ramdisk. This provides faster +file/dir listing capabilities when using B<-l>, B<--df>, or B<-d> when +querying the not-installed system. Faster powersearch capabilities are +available through the option B<--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. + +B<--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 B<--ramdiskoff> first, then B<--ramdiskon> to +install the other databases of choice. This also pertains to different +distributions and/or architectures. + +See the section "B" for options +B<--arch>, B<-dists>. + +See the section "B" for options B<--dbpath> +and B<--root>. + +=head1 FILES + + Configuration files: + + swimz.list + swimrc + +=head1 SEE ALSO + +swimrc(5), apt-get(8), sources.list(5), dpkg(8) + +=head1 BUGS + +Send directly to mttrader@access.mountain.net + +=head1 AUTHOR + +Jonathan D. Rosenbaum + +=head1 COPYRIGHT + +Copyright (c) 1999 Jonathan Rosenbaum. All rights reserved. This program +is free software; you can redistribute it and/or modify it under the GPL. + +=cut diff --git a/swim.sgml b/swim.sgml new file mode 100644 index 0000000..eb19610 --- /dev/null +++ b/swim.sgml @@ -0,0 +1,2036 @@ + + + + + + + + + swim + + + Jonathan D. Rosenbaum + mttrader@access.mountain.net + + + + + + + + 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. +

+ + + + + + + +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. + +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. + + + + diff --git a/swim.text b/swim.text new file mode 100644 index 0000000..bfe5644 --- /dev/null +++ b/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_by_example.html b/swim_by_example.html new file mode 100644 index 0000000..01f2330 --- /dev/null +++ b/swim_by_example.html @@ -0,0 +1,755 @@ + +swim by example + +

+ +
+

The Swift, Wise, and Intuitive package Manager.

+
+

+We run a search for case-insensitive matches for the word "quake." +Because we don't know how many matches the search will find, the +descriptions of all packages found are supressed with "--no." Note: "-n" +pertains to the not-installed (uninstalled) distribution. + +

+linuxalive:/home/swim/SWIMANIA$ swim -n --search quake/i --no
+swim: found 17 package(s)
+

+ +

swim keeps a history for all searches. + +

+linuxalive:/home/swim/SWIMANIA$ swim -hn
+    5  dpsclient-demos dgs dgs-dev freefont gs-aladdin gs-aladdin-manual
+gs-aladdin-manual-de gsfonts-other xpacman abc2ps efax ghostview gnome-gv
+gs gsfonts gsfonts-x11 gv hatman libroxen-tex pacman ppd-gs pstotext
+python-imaging svgalib1-altdev svgalibg1-dev tex4ht type1inst yorick
+    4  lsof-2.2
+    3  libwine-dev
+    2  libwine libwine-dev libwings-dev
+    1  gtkpak pak qstat quake-lib quake2 quake2-bin quake2-ctf quake2-dm
+xqf quake-3dfx quake-ggi quake-gl quake-lib-stub quake-sdl quake-server
+quake-svga quake-x11
+

+ +

+We can access any part of the history which we want. The first command looks at the +information pertaining to the package. The second command shows a listing of the packages +found for "quake." Note: When no numbers are specified for "-S", the number 1 is assumed. + +

+linuxalive:/home/swim/SWIMANIA$ swim -qnSi 3
+Package: libwine-dev                 Status: install ok installed
+Version: 0.0.20000109-1              Essential: no
+Section: otherosfs                   Priority: optional
+Installed-Size: 3680                 Source: wine
+Size: 729818                         Architecture: i386
+Distribution: unstable
+Maintainer: Andrew D. Lenharth <andrewl@debian.org>
+Description: Windows Emulator (Development files)
+ This is an ALPHA release of Wine, the MS-Windows emulator.  This is
+ still a developers release and many applications may still not work.
+ .
+ This package consists of the C header files.
+ .
+ Wine is often updated.
+
+linuxalive:/home/swim/SWIMANIA$ swim -qnS  
+gtkpak_0.2-1
+pak_0.2-1
+qstat_2.3e-1
+quake-lib_1.06-9
+quake2_3.20-5
+quake2-bin_3.20-1
+quake2-ctf_1.50-1
+quake2-dm_3.13-1
+xqf_0.8.99-1
+quake-3dfx_0.0.9-1
+quake-ggi_0.0.9-1
+quake-gl_0.0.9-1
+quake-lib-stub_1.9-1
+quake-sdl_0.0.9-1
+quake-server_0.0.9-1
+quake-svga_0.0.9-1
+quake-x11_0.0.9-1
+

+ +

+After looking at the descriptions for the packages found through the "quake" search we decide +to narrow down the search to "tools." Notes: We could have done this for any part of the +history by specifying a number. "--research" will not write the changes to the history, +"--refinesearch" will write the changes to the history. The qstat package is installed, but +there is a newer version. + +

+linuxalive:/home/swim/SWIMANIA$ swim -n --research tool
+Package: gtkpak                      Status: not-installed
+Version: 0.2-1                       Essential: no
+Section: games                       Priority: optional
+Installed-Size: 105                  Source: pak
+Size: 32182                          Architecture: i386
+Distribution: unstable
+Maintainer: Joseph Carter <knghtbrd@debian.org>
+Description: GTK program for manipulating pak archives
+ gtkpak is a nifty GTK tool for manipulating the pak archives used by Quake,
+ Quake 2, and QuakeWorld.  It can view, extract, create, and append pak
+ archives.  pak contains basic command-line utilities that can do much of
+ what gtkpak does without X or GTK, but gtkpak is easier to work with by
+ far.  Installing both won't hurt anything.
+
+Package: pak                         Status: not-installed
+Version: 0.2-1                       Essential: no
+Section: games                       Priority: optional
+Installed-Size: 110
+Size: 37412                          Architecture: i386
+Distribution: unstable
+Maintainer: Joseph Carter <knghtbrd@debian.org>
+Description: command-line tools for pak archives
+ This package contains pakx and pakc, a couple of tools for working with the
+ pak archives used by Quake, Quake 2, and QuakeWorld.  pakc can create and
+ add files to archives, pakx can list and extract files from them.  gtkpak
+ is a bit fancier but then again it requires X and GTK.
+
+Package: qstat                       Status: > hold ok installed (2.0b-1)
+Version: 2.3e-1                      Essential: no
+Section: games                       Priority: optional
+Installed-Size: 236
+Size: 68652                          Architecture: i386
+Distribution: unstable
+Maintainer: Michael Alan Dorman <mdorman@debian.org>
+Description: Command-line tool for querying quake (and other) servers
+ Qstat provides a simple interface for querying servers for a number
+ of games, including but not limited to quake, quakeworld, quake2,
+ quake3arena, unreal tournament, kingpin and others.
+
+swim: found 3 package(s)
+linuxalive:/home/swim/SWIMANIA$ swim -n --refinesearch tool --no
+swim: found 3 package(s)
+

+ +

This is what 1 now looks like in the history: +

+    1  gtkpak pak qstat
+

+ +

If apt is installed it is possible to find out how other packages will +be installed. + +

+linuxalive:/home/swim/SWIMANIA$ swim -qxnS
+gtkpak_0.2-1
+pak_0.2-1
+qstat_2.3e-1
+Reading Package Lists...
+Building Dependency Tree...
+The following packages will be REMOVED:
+  xqf 
+The following NEW packages will be installed:
+  gtkpak pak 
+The following held packages will be changed:
+  qstat xqf 
+1 packages upgraded, 2 newly installed, 1 to remove and 1065 not upgraded.
+Inst gtkpak
+Remv xqf
+Inst qstat
+Inst pak
+Conf gtkpak
+Conf qstat
+Conf pak
+

+ +

+Oh no, xqf is going to be removed! Let's make sure that this isn't a +package we want removed, but since we noticed a newer version of this +package is included in the unstable distribution, let's find out what's +going on here! + +

+linuxalive:/home/swim/SWIMANIA$ swim -qnxi xqf
+Package: xqf                         Status: > hold ok installed (0.5-1)
+Version: 0.8.99-1                    Essential: no
+Section: games                       Priority: optional
+Installed-Size: 182
+Size: 80426                          Architecture: i386
+Distribution: unstable
+Maintainer: Michael Alan Dorman <mdorman@debian.org>
+Description: X-based Quake Server Browser
+ XQF allows one to browse and choose quake servers to play on.
+Reading Package Lists...
+Building Dependency Tree...
+Some packages could not be installed. This may mean that you have
+requested an impossible situation or if you are using the unstable
+distribution that some required packages have not yet been created
+or been moved out of Incoming.
+
+Since you only requested a single operation it is extremely likely that
+the package is simply not installable and a bug report against
+that package should be filed.
+The following information may help to resolve the situation:
+
+Sorry, but the following packages have unmet dependencies:
+  xqf: Conflicts: qstat (< 2.1z-2.1a-0.1) but 2.0b-1 is to be installed
+E: Sorry, broken packages
+linuxalive:/home/swim/SWIMANIA$ swim -qnT qstat
+qstat_2.3e-1
+Depends: libc6 (>= 2.1.2)
+Conflicts: xqf (<< 0.9.2-1)
+

+ +

As seen above, the reason why xqf has to be removed is due to a +dependency in qstat which the packager (Michael Alan Dorman +<mdorman@debian.org>) will have to resolve by uploading a newer version of +xqf to the distribution. Sometimes necessary packages are still in +Debian's Incoming directory at the ftp site, and not in the distribution, +so we may want to check there first. If this isn't the case we will send +a bug report to Debian's Bug Tracking System pointing out that there needs +to be a newer version of xqf. In the meantime we have decided that we +only want gtkpak and pak. We will use swim's editing capabilities to take +gstat off the list. Notes: Another possibility for the bug shown above +is that apt's cache needs to be updated to reflect the changes in Debain's +distribution by using "swim --apt --update." When the history is edited +with "--stdin" the history makes a new entry reflecting the change. The +full history is accessible from "--stdin." Anybody can send a bug to +Debian's Bug Tracking System. + +

+linuxalive:/home/swim/SWIMANIA$ swim -qxznS --stdin 
+swim: type exit to finish --stdin
+swim: gtkpak pak      
+swim: exit
+Reading Package Lists... Done
+Building Dependency Tree... Done
+The following NEW packages will be installed:
+  gtkpak pak 
+0 packages upgraded, 2 newly installed, 0 to remove and 1067 not upgraded.
+Need to get 69.6kB of archives. After unpacking 220kB will be used.
+Get:1 ftp://ftp.debian.org unstable/main gtkpak 0.2-1 [32.2kB]
+Get:2 ftp://ftp.debian.org unstable/main pak 0.2-1 [37.4kB]                    
+Fetched 69.6kB in 1m15s (922B/s)                                               
+Selecting previously deselected package gtkpak.
+(Reading database ... 106015 files and directories currently installed.)
+Unpacking gtkpak (from .../archives/gtkpak_0.2-1_i386.deb) ...
+Selecting previously deselected package pak.
+Unpacking pak (from .../archives/pak_0.2-1_i386.deb) ...
+Setting up gtkpak (0.2-1) ...
+
+Setting up pak (0.2-1) ...
+gtkpak_0.2-1
+pak_0.2-1
+

+ +

+If we don't have apt we can still download these packages, and their sources. Here is another +way to do the same thing we did above without using apt. Notes: This time we saved some +typing by doing "--stdin" with "--research." We specified "--source" with "--ftp" to get the +sources as well as the packages, or we could have just gotten the sources by themselves by +specifying "--source_only" with "--ftp." Changes made while in "--stdin" are written to the +history. + +

+linuxalive:/home/swim/SWIMANIA$ swim -n --search quake/i --no
+swim: found 17 package(s)
+linuxalive:/home/swim/SWIMANIA$ swim -n --research tool --no --stdin --ftp --source
+swim: found 3 package(s)
+swim: type exit to finish --stdin
+swim: gtkpak pak      
+swim: exit
+swim: connected to ftp.debian.org
+swim: logged in to ftp.debian.org
+swim: downloading gtkpak_0.2-1.deb (32182 bytes)
+gtkpak_0.2-1  49823b28c9599dbf94e290e28e695bc2  OK
+swim: successful retrieval of gtkpak_0.2-1.deb
+swim: downloading pak_0.2-1.diff.gz (2623 bytes)
+swim: successful retrieval of pak_0.2-1.diff.gz
+swim: downloading pak_0.2-1.dsc (825 bytes)
+swim: successful retrieval of pak_0.2-1.dsc
+swim: downloading pak_0.2.orig.tar.gz (26972 bytes)
+swim: successful retrieval of pak_0.2.orig.tar.gz
+swim: downloading pak_0.2-1.deb (37412 bytes)
+pak_0.2-1  55842f97f80c5c37415a93a7f0709171  OK
+swim: successful retrieval of pak_0.2-1.deb
+swim: pak_0.2-1.diff.gz already exists
+swim: pak_0.2-1.dsc already exists
+swim: pak_0.2.orig.tar.gz already exists
+swim: logged out
+

+ +

+We notice that the sources only had to be downloaded once. Looking at the packages' +information we notice both packages share the same sources as indicated in the "Source" field. +The field is absent for the pak package because the source name is exactly the same as the +package's name, but for the gtkpak package this isn't the case, so the "Source" field is +present. + +

+We can find the packages and the sources in their proper location on our local archive mirror. + +

+linuxalive:/home/swim/SWIMANIA$ ls ~/.swim/pub/debian/dists/unstable/main/source/games
+pak_0.2-1.diff.gz  pak_0.2-1.dsc  pak_0.2.orig.tar.gz
+linuxalive:/home/swim/SWIMANIA$ ls ~/.swim/pub/debian/dists/unstable/main/binary-i386/games/
+gtkpak_0.2-1.deb  pak_0.2-1.deb
+

+ +

+We can go examine the packages. It is useful to check out the changelog and the copyright. +This is the initial release for this program. Note: "-v" will show the files in long format +(ls -l), "--df" show the directories as well as the files. + +

+linuxalive:/home/swim/SWIMANIA$ cd ~/.swim/pub/debian/dists/unstable/main/binary-i386/games/
+linuxalive:~/.swim/pub/debian/dists/unstable/main/binary-i386/games$ swim -qpl --copyright --changelog gtkpak_0.2-1.deb 
+#####copyright for gtkpak_0.2-1.deb#####
+
+taken from the README:
+
+(c) Michael Vance, 1999
+    briareos@lokigames.com
+    mkv102@psu.edu
+
+0. Intro
+
+gtkpak is a PAK file viewer for Gtk+. What are PAK files? A PAK file is used
+in id software games such as Quake and Quake 2, and their spin-offs. Just
+imagine collapsing an entire directory scheme into a big wad of files, and
+there you have a PAK file.
+
+The three binaries are built around the interface provided in pakfile.h,
+which is a C++ class that allows access to the contents of a PAKFile, including
+searching and extracting from an already existing PAK file, to add files and
+then writing a new PAK file. The three binaries are then just front-ends
+to this functionality, in one way or another.
+
+While it's tempting to make the classes provided in pakfile.h into a shared
+library, it's probably unnecessary. But it does make one tingly, eh?
+
+And all this is GPL'ed, of course. See the file COPYING for license details.
+
+
+#####changelog.Debian.gz for gtkpak_0.2-1.deb#####
+
+pak (0.2-1) unstable; urgency=low
+
+  * Initial Release.
+
+ -- Joseph Carter   Thu,  8 Jul 1999 17:35:38 -0700
+
+Local variables:
+mode: debian-changelog
+End:
+
+usr/bin/gtkpak
+usr/share/man/man6/gtkpak.6.gz
+usr/doc/gtkpak/README
+usr/doc/gtkpak/copyright
+usr/doc/gtkpak/examples/pak0.pak
+usr/doc/gtkpak/changelog.Debian.gz
+usr/lib/menu/gtkpak
+

+ +

Let's see if there is a menu entry, and check the MD5 checksum. + +

+linuxalive:~/.swim/pub/debian/dists/unstable/main/binary-i386/games$ swim -qpm gtkpak_0.2-1.deb --md5sum
+#####menu for gtkpak_0.2-1.deb(gtkpak)#####
+?package(gtkpak):needs=X11 section=Games/Adventure\
+  title="GtkPak" hints=Quake command="/usr/bin/gtkpak"
+
+gtkpak_0.2-1  49823b28c9599dbf94e290e28e695bc2  OK
+

+ +

It would be interesting to look at the man page for gtkpak. + +

+linuxalive:~/.swim/pub/debian/dists/unstable/main/binary-i386/games$ swim -qpd gtkpak_0.2-1.deb 
+gtkpak_0.2-1
+
+usr/share/man/man6/gtkpak.6.gz
+usr/doc/gtkpak/README
+usr/doc/gtkpak/copyright
+usr/doc/gtkpak/examples/pak0.pak
+usr/doc/gtkpak/changelog.Debian.gz
+
+linuxalive:~/.swim/pub/debian/dists/unstable/main/binary-i386/games$ swim -qp gtkpak_0.2-1.deb --extract PWD\!usr/share/man/man6/gtkpak.6.gz
+gtkpak_0.2-1
+
+
+swim: gtkpak.6.gz has been extracted
+linuxalive:~/.swim/pub/debian/dists/unstable/main/binary-i386/games$ ls
+gtkpak.6.gz  gtkpak_0.2-1.deb  pak_0.2-1.deb
+linuxalive:~/.swim/pub/debian/dists/unstable/main/binary-i386/games$ zcat gtkpak.6.gz | nroff -man | less
+"man page for gtkpak will be visible"
+

+ +

+We could also extract the whole archive onto our system. Note: First, we checked to make +sure we wouldn't copy over any files from other installed packages. + +

+linuxalive:~/.swim/pub/debian/dists/unstable/main/binary-i386/games/test$ cd /
+linuxalive:/$ swim -qp ~/.swim/pub/debian/dists/unstable/main/binary-i386/games/gtkpak_0.2-1.deb --extract ALL
+gtkpak_0.2-1
+
+
+swim: gtkpak_0.2-1.deb has been extracted
+

+ +

+If we have installed the packages with apt, we can check to see what kind of changes have been +made to our system. + +

+linuxalive:/home/swim/SWIMANIA$ swim --db --check
+checking for new, changed, and removed packages
+NEW gtkpak
+NEW pak
+
+       TOTAL
+       -----
+NEW 2
+GONE 0
+CHANGED 0
+CHANGED STATUS 0
+

+ +

At this point the database for our installation hasn't been updated. + +

+linuxalive:/home/swim/SWIMANIA$ swim -q pak 
+package pak is not installed
+linuxalive:/home/swim/SWIMANIA$ 
+
+To update the database we will issue "--db" without "--check."
+
+linuxalive:/home/swim/SWIMANIA$ swim --db        
+checking for new, changed, and removed packages
+NEW gtkpak
+NEW pak
+
+       TOTAL
+       -----
+NEW 2
+GONE 0
+CHANGED 0
+CHANGED STATUS 0
+
+
+N|C|CS 2
+#2 N|C pak.list
+linuxalive:/home/swim/SWIMANIA$ swim -q pak
+pak_0.2-1
+

+ +

+We can check to see if the uninstalled distribution had any changes. Notes: The results below +indicate the changes found in the new Package databases that have been downloaded by updating +apt; if we don't have apt then swim's major mode "--ftp" can be used with "DF." With "--ndb" +use APT to indicate apt sources, or DF to indicate Package databases gotten directly through +swim's "--ftp". If we originally made the uninstalled distribution with an uninstalled +filesystem by using "--Contents DF" then to update the uninstalled distribution "--Contents +DF" should be used again; this isn't necessary when running a check. To rebuild +(--rebuildndb), update (--ndb), or check a distribution other than the default one, use +"--dists stable", "--dists frozen" or "--dists unstable." The newest Packages can +automatically be picked by using "--cron." + +

+A little blurb: Although not Debian approved or sanctioned, we find the unstable distribution +acceptably stable in relation to certain well-known commercial distributions despite +infrequent packaging bugs like the one shown in the xqf example above. The Debian +distribution adheres to a self-imposed level of quality found in no other distribution in the +world. Usually, unstable undergoes many changes so there isn't a time advantage over updating +DF versus rebuilding DF, but this process is easier on system resources. On the other hand, +updating FDBDF (no uninstalled filesystem) is faster. + + +

+linuxalive:/home/swim/SWIMANIA$ swim --apt --update; swim --ftp --Contents DF --onec;
+"output not shown"
+linuxalive:/home/swim/SWIMANIA$ swim --ndb --check APT 2> changes-today
+###         Site                     Date              Size (bytes)  Release
+
+                                     CONTRIB
+  1     ftp.debian.org       Mon Jan 17 17:57:57 2000    112774        2.2
+
+                                     NON-FREE
+  1     ftp.debian.org       Sun Jan 16 17:26:23 2000    279821        2.2
+
+                                       MAIN
+  1     ftp.debian.org       Mon Jan 17 17:57:12 2000    3048732       2.2
+
+swim: for CONTRIB, which ### do you want?: 1
+swim: for NON-FREE, which ### do you want?: 1
+swim: for MAIN, which ### do you want?: 1
+checking for new, changed, and removed packages
+
+       TOTAL
+       -----
+NEW 12
+GONE 16
+CHANGED 54
+CHANGED REVISION 162
+

+ +

+We can view all the changes because we stored them in a file. We can use swim to look at all +the changed packages except for the new ones which will be visible once we rebuild or update. +By looking at this file we are provided a view of the inner workings of Debian development. + +

+linuxalive:/home/swim/SWIMANIA$ cat changed-today | less
+CHANGED-REVISION gnujsp
+CHANGED iraf
+CHANGED iraf-common
+CHANGED iraf-ibin
+CHANGED iraf-noaobin
+CHANGED-REVISION jserv
+CHANGED-REVISION mailcrypt
+CHANGED plugger
+CHANGED-REVISION sarien
+NEW webrt
+"part of output not shown"
+GONE tinytable-zope
+GONE tip
+

+ +

We decide to update with "--ndb" rather than to rebuild with +"--rebuildndb." + +

+linuxalive:/home/swim/SWIMANIA$ swim --ndb APT --Contents DF --cron 2> changed-today
+checking for new, changed, and removed packages
+
+       TOTAL
+       -----
+NEW 12
+GONE 16
+CHANGED 54
+CHANGED REVISION 162
+G|C|CR 232
+#232 VIRTUAL G|C|CR zicq.list                                        
+Copying new Contents
+Compressing Contents
+N|C|CR 228
+#228 VIRTUAL N|C|CR zicq.list                                         
+#22 NO-C zope-siteaccess.list                        
+Appending search databases
+Updating status
+
+Sun Jan 23 14:59:04 2000  to  Sun Jan 23 16:39:23 2000
+

+ +

+We were wondering whether it was time to update gv, but we found out that there was only a +debian-revision change "r>" which means that the source code hasn't changed. There is no need +to update right now. + +

+linuxalive:/usr/lib/perl5/SWIM$ which gv
+/usr/X11R6/bin/gv
+linuxalive:/usr/lib/perl5/SWIM$ cd /usr/X11R6/bin
+linuxalive:/usr/X11R6/bin$ swim -qf gv
+gv_1:3.5.8-7
+linuxalive:/usr/X11R6/bin$ swim -qfni gv
+Package: gv                          Status: r> hold ok installed (1:3.5.8-7)
+Version: 1:3.5.8-15                  Essential: no
+Section: text                        Priority: optional
+Installed-Size: 477
+Size: 224778                         Architecture: i386
+Distribution: unstable
+Maintainer: Marco Pistore <pistore@debian.org>
+Description: A PostScript and PDF viewer for X using 3d Athena Widgets
+ `gv' is a comfortable viewer of PostScript and PDF files for the X
+ Window System.
+ .
+ It uses the `ghostscript' PostScript(tm) interpreter and is based
+ on the classic X front-end for `gs', `ghostview'. It is more
+ comfortable and more powerful than `ghostview'.
+ .
+ Some features as e.g. PDF files or anti-aliasing are only supported
+ if a recent ghostscript (4.0 or later) is installed.  With
+ anti-aliasing turned on, the text is very crisp and readable, with no
+ `stepping' on the slants at all.
+

+ +

+While we were in this directory we decided to do a little research. It is interesting to note +that for the installed system there are 14 files which don't belong to any packages. There +could be a variety of reasons for this (maybe we are slobs); this is good stuff to know. +Notes: To see the total list just add "-t" to the existing command-line options. There is a +big difference in using "." and "*", "." is the same as saying "./" but it only lists the +same package once, whereas "*" would look at all the files in the immediate directory and if +two files belong to the same package, that package will be shown twice for each file, it also +reports if a file doesn't belong to a package. + +

+linuxalive:/usr/X11R6/bin$ swim -qf .
+use --total or -t to see all 202 packages
+linuxalive:/usr/X11R6/bin$ swim -qfn .
+use --total or -t to see all 420 packages
+linuxalive:/usr/X11R6/bin$ swim -qft * | grep "not owned" | wc -l
+     14
+linuxalive:/usr/X11R6/bin$ swim -qfnt * | grep "not owned" | wc -l
+    162
+

+ +

+We notice a file in the lib directory, and we wonder what it belongs to. + +

+linuxalive:/lib$ swim -qf libthread_db-1.0.so --shlibs
+libc6_2.1.2-11
+Shlibs:
+ld-linux 2 libc6 (>= 2.1.2)
+libBrokenLocale 1 libc6 (>= 2.1.2)
+.. everything not shown ..
+libthread_db 1 libc6 (>= 2.1.2)
+libutil 1 libc6 (>= 2.1.2)
+

+ +

+We want to find out what dependencies apt has. + +

+linuxalive:/lib$ swim -qfnT /usr/bin/apt-get
+apt_0.3.16
+Depends: libc6, libc6 (>= 2.1), libc6 (>= 2.1.2), libstdc++2.10
+Suggests: dpkg-dev
+Provides: libapt-pkg2.6
+Replaces: deity, libapt-pkg-doc (<< 0.3.7), libapt-pkg-dev (<< 0.3.7)
+Conflicts: deity
+

+ +

+We need a header file called w32skrnl.h. We are in luck it's already on our system. Notes: +We could have done "locate w32skrnl.h" and then done a "swim -qf", but we haven't updated our +locatedb in months. The package installation will be tested by apt if it exists. + +

+linuxalive:/usr/include/wine$ swim -xn --ps w32skrnl\.h
+Package: libwine-dev                 Status: install ok installed
+Version: 0.0.20000109-1              Essential: no
+Section: otherosfs                   Priority: optional
+Installed-Size: 3680                 Source: wine
+Size: 729818                         Architecture: i386
+Distribution: unstable
+Maintainer: Andrew D. Lenharth <andrewl@debian.org>
+Description: Windows Emulator (Development files)
+ This is an ALPHA release of Wine, the MS-Windows emulator.  This is
+ still a developers release and many applications may still not work.
+ .
+ This package consists of the C header files.
+ .
+ Wine is often updated.
+
+swim: found 1 package(s)
+Reading Package Lists...
+Building Dependency Tree...
+Sorry, libwine-dev is already the newest version
+0 packages upgraded, 0 newly installed, 0 to remove and 1067 not upgraded.
+

+ +

+Sometimes it is nice to know the total of what we have installed. + +

+linuxalive:/usr/X11R6/bin$ swim -qa
+use --total or -t to see all 1449 packages
+linuxalive:/usr/X11R6/bin$ swim -qf /
+use --total or -t to see all 1449 packages
+linuxalive:/home/swim/SWIMANIA$ swim -qan   
+use --total or -t to see all 4525 packages
+

+ +

+We can check the MD5 checksum for all the configuation files on the system. Notes: MD5 +checksum can be performed on "-l", "-d", "-c", or "-p." This can only be performed on the +installed system. + +

+linuxalive:/home/swim/SWIMANIA$ swim -qact --md5sum
+a2ps_4.10.2-4
+ /etc/a2ps.cfg  eb909349a1bb2d1f4b4adc7ab1f75e56  OK
+
+acct_6.3.2-4
+ /etc/cron.daily/acct  d5e16c7f601c3a43d88fc8ede714c6e2  OK
+ /etc/cron.monthly/acct  9ca2c358e430f94c9ae00a1ce54e6e96  OK
+ /etc/init.d/acct  2f978d8517077c77e3262d7a6096fe2f  OK
+
+autolog_0.34-5
+ /etc/autolog.conf  b6ae10782ce13c45cbe72f9308b4caa1  OK
+ /etc/cron.d/autolog  805d268ea44c645299defc1c14495282  MISSING
+
+cfengine_1.4.9-2
+ /etc/cfengine/cfengine.conf  fd79d9462e92f88aa6c563f39e3e10d5  OK
+ /etc/cron.daily/cfengine  ac6a42f3be907b50e52834ae9d41fdbd  FAILED
+ /etc/cron.weekly/cfengine  fbdd90ecf2e68a4ced6a6abbffd32f62  OK
+"rest of output not shown"
+

+ +

We check to see what groups exist. + +

+linuxalive:/usr/lib/perl5/SWIM$ swim -q --allgroups
+"output not shown"
+linuxalive:/usr/lib/perl5/SWIM$ swim -qn --allgroups
+admin                     base                      comm
+contrib/admin             contrib/devel             contrib/doc
+contrib/games             contrib/graphics          contrib/interpreters
+contrib/libs              contrib/mail              contrib/math
+contrib/misc              contrib/net               contrib/news
+"rest of output not shown"
+

+ +

+We happen to be hamradio enthusiasts. Let's see what packages exist in the hamradio group. + +

+linuxalive:/usr/lib/perl5/SWIM$ swim -qng hamradio
+acfax_981011-3
+ax25-apps_0.0.4-1
+ax25-tools_0.0.5-1
+colrconv_0.99.2-4
+dgipip_0.1-2
+gc_1.07-3
+hamsoft_0.1.1-1
+"rest of the output not shown"
+

+ +

+We edit the hamradio group package list with "--stdin." Notes: "--stdin" needs to be +called with either "--ftp", "-x", "-xyz", "-xz", "--purge", "-r", or "--remove" to work. This +is a readline interface. If we are in emacs mode (see man bash) here are some commands we can +use to make the process easier. + +

+Note: The key bindings may be different on your system. +
Ctrl-a = move to the beginning of the line +
Ctrl-e = move to the end of the line +
Ctrl-w = erase (kill) one word backward +
Esc-d = kill one word forward +
Esc-b = move one word backward +
Esc-f = move one word forward +
Ctrl-k = kill forward to the end of the line +
Ctrl-y = retrieve (yank) last item killed +
Ctrl-r = search backward +
Esc-< = move to the beginning of the history +
Esc-> = move to the end of the history + +

+linuxalive:/usr/lib/perl5/SWIM$ swim -qng hamradio --stdin --ftp  
+swim: type exit to finish --stdin
+swim: acfax ax25-apps ax25-tools colrconv dgipip gc hamsoft icom jiffy jiffy-per
+l-tk libax25 libax25-dev logconv morse nec node p10cfgd pileup predict rspfd sccw twclock twcw
+twlog unixcw wwl wxd xconvers xnecview z8530-utils z8530-utils2
+

+ +

+We are finding new ways to swim everyday; we often solve problems in minutes which used +to take an hour or more to solve. If you find a novel use for swim, please tell us, and we +will add it to these examples. + + + + diff --git a/swimrc b/swimrc new file mode 100644 index 0000000..252de94 --- /dev/null +++ b/swimrc @@ -0,0 +1,29 @@ +# Read QUICKSTART in /usr/doc/swim for important information and to +# quickly prepare the swimrc, then read the swimrc(5) manpage for more +# enlightenment and configuration options like "Do you want to use apt?", +# "How about non-us?". + +# Which do you have on your system? Pick dpkg if Debian, ar if non-Debian. +#$package_tool = "/usr/bin/dpkg"; +#$package_tool = "/usr/bin/ar"; + +# Do you have apt installed? +#$apt = "yes"; + +# Pick one. +#$architecture = "alpha"; +#$architecture = "arm"; +#$architecture = "hurd-i386"; +#$architecture = "i386"; +#$architecture = "m68k"; +#$architecture = "powerpc"; +#$architecture = "sparc"; + +# Which distribution? Pick one. +#$distribution = "stable"; +#$distribution = "unstable"; +#$distribution = "frozen"; + +# Remove sections after qw that you do not want. Use non-US for non-us. +#@user_defined_section = qw(main contrib non-free); + diff --git a/swimrc.5 b/swimrc.5 new file mode 100644 index 0000000..5c25e87 --- /dev/null +++ b/swimrc.5 @@ -0,0 +1,402 @@ +.rn '' }` +''' $RCSfile$$Revision$$Date$ +''' +''' $Log$ +''' +.de Sh +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp +.if t .sp .5v +.if n .sp +.. +.de Ip +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.de Vb +.ft CW +.nf +.ne \\$1 +.. +.de Ve +.ft R + +.fi +.. +''' +''' +''' Set up \*(-- to give an unbreakable dash; +''' string Tr holds user defined translation string. +''' Bell System Logo is used as a dummy character. +''' +.tr \(*W-|\(bv\*(Tr +.ie n \{\ +.ds -- \(*W- +.ds PI pi +.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +.ds L" "" +.ds R" "" +''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of +''' \*(L" and \*(R", except that they are used on ".xx" lines, +''' such as .IP and .SH, which do another additional levels of +''' double-quote interpretation +.ds M" """ +.ds S" """ +.ds N" """"" +.ds T" """"" +.ds L' ' +.ds R' ' +.ds M' ' +.ds S' ' +.ds N' ' +.ds T' ' +'br\} +.el\{\ +.ds -- \(em\| +.tr \*(Tr +.ds L" `` +.ds R" '' +.ds M" `` +.ds S" '' +.ds N" `` +.ds T" '' +.ds L' ` +.ds R' ' +.ds M' ` +.ds S' ' +.ds N' ` +.ds T' ' +.ds PI \(*p +'br\} +.\" If the F register is turned on, we'll generate +.\" index entries out stderr for the following things: +.\" TH Title +.\" SH Header +.\" Sh Subsection +.\" Ip Item +.\" X<> Xref (embedded +.\" Of course, you have to process the output yourself +.\" in some meaninful fashion. +.if \nF \{ +.de IX +.tm Index:\\$1\t\\n%\t"\\$2" +.. +.nr % 0 +.rr F +.\} +.TH swimrc 5 " " "27/May/99" " " +.UC +.if n .hy 0 +.if n .na +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.de CQ \" put $1 in typewriter font +.ft CW +'if n "\c +'if t \\&\\$1\c +'if n \\&\\$1\c +'if n \&" +\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 +'.ft R +.. +.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2 +. \" AM - accent mark definitions +.bd B 3 +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds ? ? +. ds ! ! +. ds / +. ds q +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10' +. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#] +.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u' +.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u' +.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#] +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +.ds oe o\h'-(\w'o'u*4/10)'e +.ds Oe O\h'-(\w'O'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds v \h'-1'\o'\(aa\(ga' +. ds _ \h'-1'^ +. ds . \h'-1'. +. ds 3 3 +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +. ds oe oe +. ds Oe OE +.\} +.rm #[ #] #H #V #F C +.SH "NAME" +swimrc \- swim configuration file +.SH "DESCRIPTION" +\fBswimrc\fR 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 \fBSWIW::Conf\fR to be altered. +.SH "USAGE" +Values for variable can be altered for \fBswim\fR by assigning different +values enclosed in quotes or quoted whitespace (\fIqw()\fR), and ended with a +semi-colon. +.PP +.Vb 2 +\& $variable = "value"; +\& $variable = "qw(value1 value2 ..)"; +.Ve +.SH "VARIABLES" +This is a list of variables with explanations. The default values for +\fBswim\fR are shown. +.Sh "\s-1OUTPUT\s0 \s-1VARIABLE\s0 " +$my_number can be changed to how many lines you would like \*(L"swim \-qf <>\*(R" +to print out, before the program asks for \f(CW-t\fR or \f(CW--total\fR. Exception: +If \f(CW-i\fR is used in the query and there is more than one package then the +total will be presented. +.PP +Hint: \f(CW-t\fR can be used with all the various \f(CW--scripts\fR family members +to view the title of the script file regardless of this variable setting, +and if \f(CW-t\fR has to be used, the titles will be displayed, which makes +sense. +.PP +\fB$my_number = 23;\fR +.Sh "\s-1HISTORY\s0" +This is a shell-like history kept in relation to searches and the most +recent edit when \f(CW--stdin\fR is used. +.PP +\fB$\s-1HISTORY\s0 = 10;\fR +.Sh "\s-1AR\s0 or \s-1DPKG\s0?" +Debian packages are ar archives. If you are using a Debian Distribution +assign \*(L"dpkg\*(R" to \f(CW$package_tool\fR, otherwise assign \*(L"ar\*(R" to \f(CW$package_tool\fR. +.PP +\fB$package_tool = \*(L"/usr/bin/ar\*(R";\fR +.Sh "\s-1APT\s0" +\fBSwim\fR does not assign a value for apt. To use \f(CW--apt\fR and \f(CW-xyz\fR +assign \f(CW$apt\fR the value \*(L"yes\*(R". +.PP +Example: \fB$apt = \*(L"yes\*(R";\fR +.Sh "\s-1PAGER\s0" +less is a nice pager, unless you like more! Pager is used for \f(CW--help\fR +and \fBswim\fR called without any options. There is an option \f(CW--nopager\fR or +\f(CW-n\fR. more comes from the required package util-linux, whereas less +comes from a standard package called less. Values: \*(L"less\*(R", \*(L"more\*(R", or +\*(L"most\*(R" or... +.PP +\fB$\s-1ENV\s0{\s-1PAGER\s0} = \*(L"less\*(R";\fR +.Sh "\s-1NOT\s0\-\s-1INSTALLED\s0 \s-1VARIABLES\s0 " +Assign values for \f(CW$architecture\fR and/or \f(CW$distribution\fR to avoid having to +use \f(CW--arch\fR and \f(CW--dists\fR everytime the not-installed databases are +accessed with \f(CW-n\fR or made or altered. +.PP +Architectures are always being added so check with Debian to find a list. +There is \fIalpha, arm, hurd-i386 (alternative kernel to linux), i386, +m68k, powerpc, sparc\fR. Just use the arch found after the hyphen in the +Contents-(arch) file. +.PP +\fB$architecture = \*(L"i386\*(R";\fR +.PP +The distribution can be either \fIstable, unstable, frozen, or experimental +(rare)\fR. 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. +.PP +\fB$distribution = \*(L"unstable\*(R";\fR +.PP +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. +.PP +You can determine which of the sections \fImain, non-free, contrib or +non-\s-1US\s0\fR to pull out of the Contents file if you don't want to use +\f(CW--main\fR, \f(CW--contrib\fR, \f(CW--non-free\fR, and \f(CW--non-us\fR to selectively +pick the sections. +.PP +For efficiency, you should choose the sections which you will be pulling +out of the Packages \fIfile\fR\|(s) being targetted. +.PP +Rule: Use \*(L"non-\s-1US\s0\*(R" not \*(L"non-us\*(R". +.PP +\fB@user_defined_section = qw(main contrib non-free non-\s-1US\s0);\fR +.Sh "\s-1DF\s0 \s-1LOCATION\s0" +A little philosophy: \fBswim\fR 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 \fBswim\fR for distribution +development, \fBswim\fR provides a way. +.PP +The next two variables determine the location of the \s-1DF\s0 (default +directory/file system) +.PP +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. +.PP +\fB$default_directory = \*(L'/root/.swim\*(R';\fR +.PP +The default root directory (\s-1DRD\s0) 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 \s-1DRD\s0 is always placed below the value +assigned to \f(CW$default_directory\fR. According to the previous assignment to +\f(CW$default_directory\fR, if the \s-1DRD\s0 is \*(L"/pub/a/debian\*(R" then the full path +would be \*(L"/root/.swim/pub/a/debian\*(R". +.PP +Example: When a package is downloaded it will be placed in +dists/distribution/section/architecture/subject below the \s-1DRD\s0. +.PP +Rule: debian must be the final directory before dists, this is because +other distributions are placed alongside debian, like debian-non-\s-1US\s0 or +personal (specialized distribution). +.PP +\fB$default_root_directory = \*(L'/pub/debian\*(R';\fR +.PP +Because you may be using a real ftp site, this variable allows you to +determine what permissions \fBswim\fR will assign for directories it creates +below the \s-1DRD\s0. +.PP +\fB$permission = \*(L'0755\*(R';\fR +.Sh "\s-1TEMPORARY\s0 \s-1DIRECTORY\s0" +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 +\f(CW$tmp\fR a \s-1RAM\s0 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. +.PP +\fB$tmp = \*(L"/tmp\*(R";\fR +.Sh "\s-1FTP\s0" +You can alter the Firewall, Port, Timeout, Debug and Passive +characteristics of the ftp client as defined in \fINet::\s-1FTP\s0\fR\|(3pm) by providing +arguments to these variables. All variables but \f(CW$timeout\fR are set to untrue +by default. +.PP +.Vb 5 +\& $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) +.Ve +.SH "OTHER VARIABLES" +see SWIM::Conf +.SH "FILES" +.PP +.Vb 2 +\& /etc/swim/swimrc +\& ~/.swim/swimrc +.Ve +.SH "SEE ALSO" +\fIswim\fR\|(8), \fINet::FTP\fR\|(3pm) +.SH "BUGS" +Send directly to mttrader@access.mountain.net. +.SH "AUTHOR" +Jonathan D. Rosenbaum +.SH "COPYRIGHT" +Copyright (c) 1999 Jonathan Rosenbaum. All rights reserved. This program +is free software; you can redistribute it and/or modify it under the GPL. + +.rn }` '' +.IX Title "swimrc 5" +.IX Name "swimrc - swim configuration file" + +.IX Header "NAME" + +.IX Header "DESCRIPTION" + +.IX Header "USAGE" + +.IX Header "VARIABLES" + +.IX Subsection "\s-1OUTPUT\s0 \s-1VARIABLE\s0 " + +.IX Subsection "\s-1HISTORY\s0" + +.IX Subsection "\s-1AR\s0 or \s-1DPKG\s0?" + +.IX Subsection "\s-1APT\s0" + +.IX Subsection "\s-1PAGER\s0" + +.IX Subsection "\s-1NOT\s0\-\s-1INSTALLED\s0 \s-1VARIABLES\s0 " + +.IX Subsection "\s-1DF\s0 \s-1LOCATION\s0" + +.IX Subsection "\s-1TEMPORARY\s0 \s-1DIRECTORY\s0" + +.IX Subsection "\s-1FTP\s0" + +.IX Header "OTHER VARIABLES" + +.IX Header "FILES" + +.IX Header "SEE ALSO" + +.IX Header "BUGS" + +.IX Header "AUTHOR" + +.IX Header "COPYRIGHT" + diff --git a/swimrc.html/ch-description.html b/swimrc.html/ch-description.html new file mode 100644 index 0000000..56557f3 --- /dev/null +++ b/swimrc.html/ch-description.html @@ -0,0 +1,26 @@ + +swimrc - swim configuration file - DESCRIPTION + + + +

+swimrc - swim configuration file - chapter 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. +

+swimrc - swim configuration file +- + Copyright � 1999 Jonathan D. Rosenbaum + +
+Contents; next. +
+

27 May 1999
+Jonathan D. Rosenbaummttrader@access.mountain.net

+ diff --git a/swimrc.html/ch-files.html b/swimrc.html/ch-files.html new file mode 100644 index 0000000..f33a68a --- /dev/null +++ b/swimrc.html/ch-files.html @@ -0,0 +1,26 @@ + +swimrc - swim configuration file - FILES + + + +

+swimrc - swim configuration file - chapter 5
+FILES + +

+ + /etc/swim/swimrc

+ +~/.swim/swimrc + +

+swimrc - swim configuration file +- + Copyright � 1999 Jonathan D. Rosenbaum + +
+Contents; next; back. +
+

27 May 1999
+Jonathan D. Rosenbaummttrader@access.mountain.net

+ diff --git a/swimrc.html/ch-othervars.html b/swimrc.html/ch-othervars.html new file mode 100644 index 0000000..3ac3f37 --- /dev/null +++ b/swimrc.html/ch-othervars.html @@ -0,0 +1,23 @@ + +swimrc - swim configuration file - OTHER VARIABLES + + + +

+swimrc - swim configuration file - chapter 4
+OTHER VARIABLES + +

+ +see SWIM::Conf +

+swimrc - swim configuration file +- + Copyright � 1999 Jonathan D. Rosenbaum + +
+Contents; next; back. +
+

27 May 1999
+Jonathan D. Rosenbaummttrader@access.mountain.net

+ diff --git a/swimrc.html/ch-restrictions.html b/swimrc.html/ch-restrictions.html new file mode 100644 index 0000000..73948fb --- /dev/null +++ b/swimrc.html/ch-restrictions.html @@ -0,0 +1,35 @@ + +swimrc - swim configuration file - RESTRICTIONS + + + +

+swimrc - swim configuration file - chapter 6
+RESTRICTIONS + +

+ +Strange Situations: If the same package happens to exist in two different +sections, main and non-us for example, and you make the +databases, you will still be able to find this package in the non-us +group, but its section and locations will be the one which main recognizes +assuming that you use the order in the example below. + +

+ + +Example: You just want to pull out main and contrib every time you run +--initndb, --rebuildndb, or --ndb. +

+@user_defined_section = ``qw(main contrib non-US)''; +

+swimrc - swim configuration file +- + Copyright � 1999 Jonathan D. Rosenbaum + +
+Contents; back. +
+

14 May 1999
+Jonathan D. Rosenbaummttrader@access.mountain.net

+ diff --git a/swimrc.html/ch-usage.html b/swimrc.html/ch-usage.html new file mode 100644 index 0000000..bdde5c5 --- /dev/null +++ b/swimrc.html/ch-usage.html @@ -0,0 +1,29 @@ + +swimrc - swim configuration file - USAGE + + + +

+swimrc - swim configuration file - chapter 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 ..)''; +

+swimrc - swim configuration file +- + Copyright � 1999 Jonathan D. Rosenbaum + +
+Contents; next; back. +
+

27 May 1999
+Jonathan D. Rosenbaummttrader@access.mountain.net

+ diff --git a/swimrc.html/ch-variables.html b/swimrc.html/ch-variables.html new file mode 100644 index 0000000..86bbf3e --- /dev/null +++ b/swimrc.html/ch-variables.html @@ -0,0 +1,284 @@ + +swimrc - swim configuration file - VARIABLES + + + +

+swimrc - swim configuration file - chapter 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 + +

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

+swimrc - swim configuration file +- + Copyright � 1999 Jonathan D. Rosenbaum + +
+Contents; next; back. +
+

27 May 1999
+Jonathan D. Rosenbaummttrader@access.mountain.net

+ diff --git a/swimrc.html/ch6.html b/swimrc.html/ch6.html new file mode 100644 index 0000000..7ddeaad --- /dev/null +++ b/swimrc.html/ch6.html @@ -0,0 +1,20 @@ + +swimrc - swim configuration file - BUGS + + +

+swimrc - swim configuration file - chapter 6
+BUGS +

+Send directly to mttrader@access.mountain.net. +

+swimrc - swim configuration file +- + Copyright � 1999 Jonathan D. Rosenbaum + +
+Contents; back. +
+

27 May 1999
+Jonathan D. Rosenbaummttrader@access.mountain.net

+ diff --git a/swimrc.html/index.html b/swimrc.html/index.html new file mode 100644 index 0000000..d91369b --- /dev/null +++ b/swimrc.html/index.html @@ -0,0 +1,76 @@ + +swimrc - swim configuration file + + +

swimrc - swim configuration file

+ +

+0.1 Table of 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

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

+swimrc - swim configuration file +- + Copyright � 1999 Jonathan D. Rosenbaum + +
+Contents. +
+

27 May 1999
+Jonathan D. Rosenbaummttrader@access.mountain.net

+ diff --git a/swimrc.sgml b/swimrc.sgml new file mode 100644 index 0000000..65946ec --- /dev/null +++ b/swimrc.sgml @@ -0,0 +1,354 @@ + + + + + + + + + swimrc - swim configuration file + + + Jonathan D. Rosenbaum + mttrader@access.mountain.net + + + + + + + + Copyright © 1999 Jonathan D. Rosenbaum + + +

+ +

+ + + + + + + + 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. + +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 ..)''; + +

+ +

+VARIABLES + +

+This is a list of variables with explanations. The default values for +swim are shown. + + + +OUTPUT VARIABLE + +

+ +$my_number = 23; + + +HISTORY + +

+ +This is a shell-like history kept in relation to searches and the most +recent edit when --stdin is used. + +

+ +$HISTORY = 10; + + +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"; + +APT + +

+Swim does not assign a value for apt. To use +--apt and -xyz assign $apt the +value ``yes''. + + +

+ +Example: $apt = "yes"; + +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"; + +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); + + +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'; + + +TEMPORARY DIRECTORY + +

+ +$tmp = "/tmp"; + +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) + + +OTHER VARIABLES + +

+see SWIM::Conf + +FILES + +

+ /etc/swim/swimrc +

+~/.swim/swimrc + + +BUGS +

Send directly to mttrader@access.mountain.net. + + + + diff --git a/swimrc.text b/swimrc.text new file mode 100644 index 0000000..850c670 --- /dev/null +++ b/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 + diff --git a/swimz.list b/swimz.list new file mode 100644 index 0000000..ad86b0e --- /dev/null +++ b/swimz.list @@ -0,0 +1,11 @@ +# Read QUICKSTART for a quick start, and check out the SWIMZ.LIST +# section in swim(8) for much more information. This list is read +# sequentially, so earlier entries are read before later entries +# +# Debian users: Unlike apt which only downloads Packages, swim reads this +# list based on the specified or default distribution/architecture to +# make handling the downloading of both the Contents and Packages files +# easier. Look at the Cron example in /usr/doc/swim/examples. +# +# deb ftp://ftp.debian.org/pub/debian unstable contrib non-free main +# deb ftp://ftp.debian.org/pub/debian stable contrib non-free main

QUICKSTART

READ THE REQUIREMENTS

REQUIRMENTS:

+swim - chapter 8 +PREPARING YOUR INSTALLATION FOR APT + +

+swim - chapter 2 +COMMAND LINE OPTION SYNTAX + +

+swim - chapter 1 +DESCRIPTION + +

+swim - chapter 4 +HISTORY + +

+swim - chapter 6 +IMPORTANT DEBIAN DATABASES FOR NOT-INSTALLED +DATABASES + +

+swim - chapter 5 +MAKING INSTALLED SYSTEM DATABASES + +

+swim - chapter 7 +MAKING NOT-INSTALLED DATABASES + +

+swim - chapter 9 +QUERYING THE INSTALLED AND NOT-INSTALLED DATABASES + +

+swim - chapter 12 +RAMDISK + +

+swim - chapter 11 +SEARCHING + +

+swim - chapter 14 +SEE ALSO + +

+swim - chapter 3 +VERSION + +

+swim - chapter 10 +UPGRADING WITH APT + +

+swim - chapter 12 +FILES + +

+swim - chapter 13 +FILES + +

+swim - chapter 15 +BUGS +

+swim - chapter 9 +UPGRADING WITH APT + +

swim

The Swift, Wise, and Intuitive package Manager.

+swimrc - swim configuration file - chapter 1 +DESCRIPTION + +

+swimrc - swim configuration file - chapter 5 +FILES + +

+swimrc - swim configuration file - chapter 4 +OTHER VARIABLES + +

+swimrc - swim configuration file - chapter 6 +RESTRICTIONS + +

+swimrc - swim configuration file - chapter 2 +USAGE + +

+swimrc - swim configuration file - chapter 3 +VARIABLES + +

+swimrc - swim configuration file - chapter 6 +BUGS +

swimrc - swim configuration file

+swim - chapter 8
+PREPARING YOUR INSTALLATION FOR APT + +

+swim - chapter 2
+COMMAND LINE OPTION SYNTAX + +

+swim - chapter 1
+DESCRIPTION + +

+swim - chapter 4
+HISTORY + +

+swim - chapter 6
+IMPORTANT DEBIAN DATABASES FOR NOT-INSTALLED +DATABASES + +

+swim - chapter 5
+MAKING INSTALLED SYSTEM DATABASES + +

+swim - chapter 7
+MAKING NOT-INSTALLED DATABASES + +

+swim - chapter 9
+QUERYING THE INSTALLED AND NOT-INSTALLED DATABASES + +

+swim - chapter 12
+RAMDISK + +

+swim - chapter 11
+SEARCHING + +

+swim - chapter 14
+SEE ALSO + +

+swim - chapter 3
+VERSION + +

+swim - chapter 10
+UPGRADING WITH APT + +

+swim - chapter 12
+FILES + +

+swim - chapter 13
+FILES + +

+swim - chapter 15
+BUGS +

+swim - chapter 9
+UPGRADING WITH APT + +

+swimrc - swim configuration file - chapter 1
+DESCRIPTION + +

+swimrc - swim configuration file - chapter 5
+FILES + +

+swimrc - swim configuration file - chapter 4
+OTHER VARIABLES + +

+swimrc - swim configuration file - chapter 6
+RESTRICTIONS + +

+swimrc - swim configuration file - chapter 2
+USAGE + +

+swimrc - swim configuration file - chapter 3
+VARIABLES + +

+swimrc - swim configuration file - chapter 6
+BUGS +