\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename zippo.info
@settitle 
@setchapternewpage odd
@paragraphindent 0
@c %**end of header

@c $Id: zippo.txi,v 1.21 2002/03/10 21:25:03 richdawe Exp $

@include version.txi

@titlepage
@title zippo @value{ZIPPO-VERSION} Manual
@subtitle Copyright @copyright{} @value{ZIPPO-COPYRIGHT-YEARS} by Richard Dawe
@page
@end titlepage

@ifinfo
@dircategory DJGPP Package Management
@direntry
* zippo: (zippo).             zippo, a command-line package manager
@end direntry
@end ifinfo

@node Top, Introduction, (dir), (dir)
@top

@c Author: Richard Dawe @email{rich@@phekda.freeserve.co.uk}

@ifnottex

zippo @value{ZIPPO-VERSION} Manual
Copyright @copyright{} @value{ZIPPO-COPYRIGHT-YEARS} by Richard Dawe

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts.  A copy of the license is included in the section
entitled "GNU Free Documentation License"
(@pxref{GNU Free Documentation License}).

@menu
* Introduction::
* Installation::
* Getting started::
* Package operations::
* Configuration::
* How-tos::
* Invoking zippo::

Getting started:
* Dependencies::
* The package database::
* The package operations::
* Getting started with zippo::

Package operations:
* Initialising the package database::
* Synchronising the package database::
* Package specifiers::
* Querying packages::
* Installing packages::
* Uninstalling packages::
* Upgrading packages::
* Backups::
* Checking the integrity of installed packages::

Configuration:
* zipporc::
* simtelrc::

How-tos:
* How to install DJGPP using zippo::
* How to upgrade zippo using zippo::
* How to report bugs in zippo::

Licences:
* GNU Free Documentation License::

Indices:
* Concept Index::
@end menu

@end ifnottex

@c TODO: Put examples of zippo's output in manual.
@c TODO: Describe root, prefix
@c TODO: Describe helper apps.
@c TODO: When implemented, describe auto-download of packages.

@node Introduction, Installation, Top, (dir)
@chapter Introduction

@section What is zippo?

zippo is a package manager for DJGPP, loosely modelled on RPM, a package
manager for Linux and other Unices.  A @dfn{package} is a collection of
programs or files, e.g. the base DJGPP distribution @samp{djdev} or gcc.

zippo has been designed with the following goals:

@itemize @bullet
@item
Ability to install DJGPP and associated packages from scratch, i.e. without
requiring any other packages;
@item
RPM-like command-line syntax;
@item
Ability to download packages using HTTP (web) or FTP;
@end itemize

Please note that there is nothing in zippo's design that ties it to DJGPP.
It could be used for any type of package. It has been designed with
the DJGPP community in mind, but could be configured easily as
a general package management tool.

@node Installation, Getting started, Introduction, Top
@chapter Installation

@section Installing the Binary Distribution

If you want to install DJGPP from scratch, please see the How-To
(@pxref{How to install DJGPP using zippo}).

Installing the binary distribution (ready-to-run) version of zippo is
relatively straightforward.  Extract the ZIP file into the DJGPP directory
(e.g. c:\djgpp), preserving directory names - e.g. use PKUNZIP's '-d' option.

To install the info files properly, you will need GNU texinfo
4.0 (available from the DJGPP archive as @code{v2gnu/txi40b.zip}).
Run the following commands:

@example
install-info --info-file=/dev/env/DJDIR/info/zippo.inf \
             --info-dir=/dev/env/DJDIR/info

install-info --info-file=/dev/env/DJDIR/info/dsmcheck.inf \
             --info-dir=/dev/env/DJDIR/info

install-info --info-file=/dev/env/DJDIR/info/dsm.inf \
             --info-dir=/dev/env/DJDIR/info
@end example

Please note that some lines have been split with the @samp{\} character -
these should be typed as one line.

zippo should now be installed correctly and ready to use - please read
how to get started with zippo (@pxref{Getting started}).

@section Building from the Source Distribution

@subsection Required and Optional Packages

To build zippo the following packages are required:

@itemize @bullet
@item
GNU C compiler - versions 2.8.0, 2.8.1, 2.95.2, 2.95.3 have been used.
@item
GNU binutils - versions 2.8.1, 2.9.5.1 beta, 2.10 have been used.
@item
GNU make
@item
GNU autoconf 2.13
@item
GNU m4 1.4 (or later) (required by GNU autoconf)
@item
GNU awk (required by GNU autoconf)
@item
GNU grep (required by GNU autoconf)
@item
GNU sed
@item
GNU bash
@item
GNU fileutils
@item
GNU findutils
@item
GNU shellutils
@item
GNU textutils 2.0 (or later)
@item
GNU texinfo 4.0 (or later)
@item
GNU flex
@item
GNU bison
@item
zlib (available from the DJGPP archive in @code{v2tk/})
@item
popt (available from the DJGPP archive in @code{v2tk/})
@end itemize

Optional packages are as follows:

@itemize @bullet
@item
The Memory Supervision System (MSS) can provide memory allocation
debugging.  MSS is available from the DJGPP archive in @code{v2tk/}.
@item
PMODE/DJ can be used to build executables that have a built-in DOS extender
(i.e. CWSDPMI not required), so that zippo can be used to install DJGPP
"from nothing".  PMODE/DJ is available from the DJGPP archive in
@code{v2misc/}.
@end itemize

These packages should be detected and used automatically during the configure
process.

@subsection Configuration and Compilation

In the following instructions, I have assumed that bash is the shell.
If not, type 'bash' and then follow the instructions.

@enumerate 1
@item
Regenerate the configure scripts:

@example
./scripts/mkconfig.sh
@end example

This executes the following commands:

@example
autoconf config.in \
    | sed -e 's/config\.guess/config.gue/' > config
chmod ug+x config
autoheader config.in > config.hin
@end example

It may be necessary to regenerate the configure script, because the DJGPP
port of @code{autoconf} has some extra m4 macros that make it work on DOS.
If a Linux (or other Unix) configure script is used under DOS, it will not
work properly.

The usage of @code{sed} above is necessary to convert the filename
@samp{config.guess} to the short filename @samp{config.gue} that is used in
the zippo distribution (so that zippo can be compiled on plain ol' DOS).

@cartouche
Note that source distributions of zippo should be set up for compilation
with DJGPP, so this step shouldn't be necessary.  If it doesn't work, try
running @code{autoconf}.  I may have forgotten to run @code{autoconf} when
making a source snapshot. ;)
@end cartouche

@item
Run @samp{./config} to autodetect any needed libraries.  The following
command-line options can be passed to @samp{config}:

@table @samp
@item --enable-debug
Enable debugging information.
@item --enable-email=xxx
Set the e-mail address to be displayed with zippo's @samp{-V} command-line
option.
@item --with-bzip2
Enable support for bzip2-compressed packages (@pxref{Top, , bzip2.info}).
@item --with-mss
Enable memory allocation tracking with MSS - if MSS isn't installed,
then this will be ignored.
@item --with-pmode-stub
Enable building with the PMODE/DJ protected mode stub.  When built with
this stub, zippo and dsmcheck can be used on any computer without needing
a DPMI server to be installed.  This is useful for installing DJGPP from
scratch under DOS, where no DPMI server is available by default.

Note: The versions built with the PMODE/DJ stub @emph{may} be less stable
than those built without.  Problems have been reported with programs built
with PMODE/DJ.
@end table

If you are going to distribute your binaries of zippo, please use the
@samp{--enable-email} switch and supply your e-mail address.

Below is an example invocation of @samp{config} with all the options; you may
not need all these options.

@example
./config --enable-debug --with-mss \
         --enable-email=barney.rubble@@bedrock.az.us
@end example

The @samp{--prefix} option is used to specify the prefix used when installing
the built package.  This should probably be the DJGPP directory, but you
can install it elsewhere if you want.  If you have a recent enough DJGPP
toolchain, you can use the @file{/dev/env/DJDIR} syntax for the prefix, e.g.:

@example
./config --prefix=/dev/env/DJDIR
@end example

@item
Run @samp{make} to compile.

@item
(@emph{Optional}, but recommended) Run @samp{make check} to check that
the programs have been built correctly.

@item
(@emph{Optional}) Run @samp{make -C doc all} to build documentation in
formats other than the defaults of info and HTML.

@item
(@emph{Optional}) Run @samp{make install} to install zippo.  If you want
to see what would be installed, use @samp{make -n install} instead.

@item
(@emph{Optional}) Run @samp{make install-lib} if you are going to use
libzippo in your own programs.  It installs library header files and
the library itself.
@end enumerate

zippo should now be built, installed correctly and ready to use -
please read how to get started with zippo (@pxref{Getting started}).

@node Getting started, Dependencies, Installation, Top
@chapter Getting started

Before getting started with zippo, some concepts need to be explained.

@ifnottex
@menu
* Dependencies::
* The package database::
* The package operations::
* Getting started with zippo::
@end menu
@end ifnottex

@node Dependencies, The package database, Getting started, Getting started
@section Dependencies
@cindex dependency
@cindex dependencies

Dependencies are the interactions between different packages.  For instance,
if one has some C source code, it is only useful, if there is a C compiler
to compile it with.  The source code depends on the C compiler.

@cindex requires
@cindex hard dependency
@cindex depends-on
@cindex soft dependency

The DSM specification (@pxref{Top, , dsm.inf}) actually has two kinds of
dependencies - @samp{requires} and @samp{depends-on}.  These are
@dfn{hard dependencies} and @dfn{soft dependencies} respectively.  A hard
dependency must be satisfied.  A package with a hard dependency will not work,
if this dependency is not satisfied.  A soft dependency may not be satisfied,
but the package will still work with some of its functionality impaired.

@c TODO: Some example of dependencies.

@cindex virtual dependencies
@cindex capabilities

It is also possible to have @dfn{virtual dependencies}, which specify
capabilities.  These capabilities may be provided by multiple packages.
A capability is something like the ability to read web pages or provide
certain system calls, e.g. DPMI, that packages require.

@node The package database, The package operations, Dependencies, Getting started
@section The package database

zippo has a package database, to keep track of what has been
installed/uninstalled/upgraded.  This information allows zippo to
install/uninstall/upgrade packages safely.  It contains the following
information:

@itemize @bullet
@item
descriptions of the packages (DSMs);
@item
manifest files for the packages (@code{.mft} files);
@item
MD5 hashes of each file in the packages, to detect when they have changed.
@end itemize

When the package database is created by zippo
(@pxref{Initialising the package database}), some information is
automatically added:

@itemize @bullet
@item
a DSM for the operating system/platform that zippo is running on.
@end itemize

@cindex platform DSM
@cindex platform DSMs

Why would you want to install a DSM for the platform that zippo is running on?
These @dfn{platform DSMs} list what capabilities the operating system
provides.

An important capability for DJGPP programs is DPMI, since all DJGPP
programs require a DPMI server to be running.  Please note that some DJGPP
programs appear not to need a DPMI server.  They do, but the DPMI server
has been linked into them.  Windows provides a DPMI 0.9 server, so there
is a capability in the Windows DSMs for DPMI.

The package database is stored in @file{share/zippo} in the DJGPP directory
(or whatever directory is the zippo root).  In this directory there are:

@table @file
@item zipporc
zippo's configuration file;
@item simtelrc
a list of URLs for mirror sites for the DJGPP archive;
@item db/
a directory containing installed package database;
@item db-avail/
a directory containing available package database;
@item win32/
a directory (if present) containing helper programs for running
under 32-bit versions of Windows, i.e.: any version later than
Windows 3.x.
@end table

If the configuration and package database has not been created, you may
see the following error:

@example
Error: Unable to read configuration file!
@end example

Please see the later section ``Getting started with zippo''
(@pxref{Getting started, , Getting started with zippo}).

@node The package operations, Getting started with zippo, The package database, Getting started
@section The package operations

zippo has different modes of operation, depending on the packages involved:

@itemize @bullet
@item
The package database can be initialised.
@item
The package database can be synchronised with updated DSMs, when
they become available.
@item
Installed packages can be queried, uninstalled, upgraded or verified.
@item
Available packages can be queried or installed.
@end itemize

These operations are described in the chapter ``Package operations''
(@pxref{Package operations}).

The method of selecting packages depends on the operation.  See the section
of package specifiers for more details (@pxref{Package specifiers}).

@cindex integrity check

Verification of a package is called an @dfn{integrity check}.  This will
show which files in the package have change or are missing, if any.

@node Getting started with zippo, Invoking zippo, The package operations, Getting started
@section Getting started with zippo

This section assumes that you already have a DJGPP installation.  For
instructions on installing DJGPP from scratch with zippo, please see
the How-To (@pxref{How to install DJGPP using zippo}).

Using zippo with an existing DJGPP installation is straightforward.
Firstly, extract the zippo binaries into the DJGPP directory.  You now need
to initialise and synchronise the package database, so that zippo knows about
all the packages you have.  I have assumed that you are using the bash shell -
if not, type @samp{bash} to run it.  Then change into the DJGPP directory
(e.g. @file{c:/djgpp}) and then execute the following commands:

@example
./bin/zippo -v --initdb
./bin/zippo -v --syncdb
@end example

These commands will create the configuration files @file{zipporc}
and @file{simtelrc} for you (@pxref{zipporc}, @pxref{simtelrc}).

You should now be able to use zippo.  To check this, list all installed
packages:

@example
zippo -v -qa
@end example

To read the zippo manual, you can use the info program:

@example
info zippo
@end example

Please read the manual, particularly the sections on querying
(@pxref{Querying packages}) and installing packages
(@pxref{Installing packages}).

@node Invoking zippo, Package operations, Getting started with zippo, Top
@chapter Invoking zippo

@subsection Help options

@example
-h --help -V --version -L --license
@end example

@subsection Overall options

@example
--rcfile --root --prefix -v --verbose -Q --quiet
@end example

@subsection Query options

@xref{Querying packages}.

@example
-q --query -p -a --installed -A --available
-i --longinfo --long-info --short --short-info -l -f
-R --requires --depends-on --conflicts-with --replaces --provides
--install-before --install-after --all-deps --all-dependencies
--changelog --pre-install-readme --post-install-readme
--pre-uninstall-readme --post-uninstall-readme --install-warning
@end example

@subsection Install options

@xref{Installing packages}.

@example
-i --install -A --available -n --test
@end example

@subsection Uninstall options

@xref{Uninstalling packages}.

@example
-e --uninstall -n --test
@end example

@subsection Upgrade options

@xref{Upgrading packages}.

@example
-U --upgrade -n --test
@end example

@subsection Database initialisation options

@xref{Initialising the package database}.

@example
--initdb --with-platform --with-zippo
@end example

@subsection Database synchronisation options

@xref{Synchronising the package database}.

@example
--syncdb
@end example

@subsection Integrity checking options

@xref{Checking the integrity of installed packages}.

@example
--check-integrity
@end example

@node Package operations, Initialising the package database, Invoking zippo, Top
@chapter Package operations

@ifnottex
@menu
* Initialising the package database::
* Synchronising the package database::
* Package specifiers::
* Querying packages::
* Installing packages::
* Uninstalling packages::
* Upgrading packages::
* Backups::
* Checking the integrity of installed packages::
@end menu
@end ifnottex

@node Initialising the package database, Synchronising the package database, Package operations, Package operations
@chapter Initialising the package database

@section Initialisation command-line

@example
--initdb [--with-platform[=<Plaform>[,<Platform>@dots{}]] [--with-zippo]
@end example

Here @samp{<Platform>} is the abbreviated name of a platform.  Currently
the following names are recognised:

@table @samp
@item msdos
MS-DOS and all variants;
@item win95
Windows '95, all versions;
@item win98
Windows '98, all versions;
@item winme
Windows ME, all versions;
@item winnt4
Windows NT 4, all Service Pack levels;
@item win2k
Windows 2000, all Service Pack levels;
@item winxp
Windows XP, all Service Pack levels;
@item dosemu
dosemu, the DOS emulator for Linux.
@end table

@section Initialising the database

For zippo to function correctly, the package database must exist.  In
the simplest case, you can run zippo like so:

@example
zippo --initdb
@end example

You may also want to run in verbose mode, using the @samp{-v} or
@samp{--verbose} option.

@c TODO: Description of root somewhere?
zippo will create the root directory that will be used to install packages,
unless it already exists.  It will then create the package database off this
root directory.

After creating the package database, zippo will try to detect the platform
that it is running on.  It will install a DSM for the platform into
the package database - a @dfn{platform DSM}.  If you use the same DJGPP
installation on multiple platforms, you should install multiple platform DSMs
using the @samp{--with-platform} option.  For example, here's how to install
a platform DSM for Windows NT 4:

@example
zippo -v --initdb --with-platform=winnt4
@end example

It is also possible for zippo to install a copy of itself in the package
root directory, using the @samp{--with-zippo} option.  This is most useful
when you are installing DJGPP from scratch using zippo.  For example:

@example
zippo -v --root c:/djgpp --initdb --with-zippo
@end example

@c TODO: Note about copying helper apps.

@node Synchronising the package database, Package specifiers, Initialising the package database, Package operations
@chapter Synchronising the package database

@section Synchronisation command-line

@example
--syncdb
@end example

@section Synchronising the database

The package database may require synchronising periodically.  If you install
any packages without using zippo, zippo needs to update its database with
information about these packages, if it can.  Namely it creates MD5 hashes
and copies the package's DSM to the database.  Note that it can only do this
for packages that have a DSM available.

It is important to create MD5 hashes for a package, so that uninstall can
detect whether any of them have been modified.  If there are no MD5 hashes
for a package, then data loss may results, since uninstall will just remove
the package's files (@pxref{Uninstalling packages}).

It is usually best to run zippo in verbose mode (the @samp{-v} or
@samp{--verbose} options), when synchronsing, to see what it is doing:

@example
zippo -v --syncdb
@end example

@section Synchronisation sources

DSMs are synchronised from the following places:

@itemize @bullet
@item
the @file{manifest} directories, e.g. @file{c:/djgpp/manifest};
@item
the available DSM directories, e.g. @file{c:/djgpp/share/zippo/db-avail}.
@end itemize

These paths are controlled by zippo's configuration (@pxref{zipporc}).

@node Package specifiers, Querying packages, Synchronising the package database, Package operations
@chapter Package specifiers

@cindex package specifiers

Package specifiers are very important in zippo's operation.  The format of
a package specifier is:

@example
<Name> [<Version>] [(<Type>)]
@end example

Here are some examples:

@example
fileutils
gcc 2.95.2
binutils 2.10 (sources)
zlib (binaries)
@end example

@cindex version wildcards

@dfn{Wildcards} are allowed in package specifiers.  Shell-style wildcards
are allowed in the name.  Any part of the version can be replaced with
a @samp{?}. For example, to match all versions of gcc 2.95.x
(2.95.1, 2.95.2, 2.95.3), you could use:

@example
gcc 2.95.?
@end example

You can match any remaining parts of the version with a @samp{*}.
For example, to match all versions of gcc 3.x (e.g.: 3.0.3, 3.1),
you could use:

@example
gcc 3.*
@end example

You could match all binary packages ending in @samp{zip},
but with any first letter:

@example
?zip (binaries)
@end example

You can also match the type with a wildcard. For example, you can
find all packages beginning with @samp{e}:

@example
e* (?)
@end example

NB: If you don't specify the type, then all types will be matched.

NB: Make sure you quote spaces and wildcards, when passing arguments to
zippo.  Otherwise your shell may interpret these characters and do
something you don't expect. Consider this example:

@example
zippo -q 'gcc 2.95.*' --long-info
@end example

@section Versions

The version is specified as follows:

@example
<Major>[.<Minor>[.<Subminor>[.<Subsubminor>]]]
[  (alpha <Alpha number>)
 | (beta <Beta number>)
 | (pre <Pre-release number>)]
[revision <Revision number>] [patchlevel <Patchlevel number>]
[release <Release number>]
[snapshot <ISO 8061 hyphenless date>] [platform <Platform specifier>]
@end example

Versions are explained in detail in the DSM specification
(@pxref{Descriptive Directives, , Formats, dsm}).

@section Types

The following types can be used in a package specifier:

@itemize @bullet
@item
binaries
@item
sources
@item
documentation
@item
virtual
@end itemize

The types of package are explained in more detail in the DSM specification
(@pxref{Descriptive Directives, , Information Directives, dsm}).

@node Querying packages, Installing packages, Package specifiers, Package operations
@chapter Querying packages
@cindex query
@cindex queries
@cindex query types

Packages can be queried in several different ways:

@itemize @bullet
@item
by the package's file name (for a package that is not installed);
@item
by the package's name and version (@pxref{Package specifiers});
@item
by matching a file owned by one or more packages.
@end itemize

There may be multiple matched packages.  For example, if one has installed
the binaries and sources for a package, both may be matched.  If multiple
versions of a package are installed, then they may all be matched.

Different types of query give different information - one can query the
following information about one or more packages:

@c TODO: Beef up the summary/detailed info descriptions.

@itemize @bullet
@item
the package's name and version;
@item
a summary description, for a brief overview;
@item
a detailed description;
@item
other packages required by the package to function;
@item
other packages that the package can optionally use;
@item
other packages that the package conflicts with;
@item
other packages that the package replaces;
@item
capabilities provided by the package;
@item
packages that the package should be installed before or after;
@item
change history (a changelog) for the package;
@item
documentation to be read before or after installing or uninstalling;
@item
the warning that will be printed on installing the package.
@end itemize

@section Querying a non-installed package

To query a non-installed package file, one must use the @samp{-p} option
with the file name of the package, e.g.

@example
zippo -q -p package.zip
@end example

To query a non-installed package that is in zippo's package database, one
must use the @samp{-A} option with the name of the package, e.g.:

@example
zippo -q -A bison
@end example

If there are multiple matches, a more specific query including the version
may be used (@pxref{Package specifiers}), e.g.

@example
zippo -q -A 'bison 1.28 (binaries)'
@end example

@section Querying an installed package

To query an installed package, one can just use the package's name.  If there
are multiple matches, a more specific query including the version should be
used (@pxref{Package specifiers}).

Here are some examples:

@example
zippo -q fileutils
zippo -q 'gcc 2.95.2'
zippo -q 'binutils 2.10 (sources)'
@end example

@section Querying a package's description

A package can be described in short or long form, e.g.

@example
zippo -q fileutils --short-info
zippo -q -p gmp311b.zip --long-info
@end example

@samp{-i} is an abbreviation for the short form.

@section Querying dependencies

Dependencies can be queried using the following options - only one can be
used at a time:

@itemize @bullet
@item
@samp{-R} or @samp{--requires}
@item
@samp{--depends-on}
@item
@samp{--conflicts-with}
@item
@samp{--replaces}
@item
@samp{--provides}
@item
@samp{--install-before}
@item
@samp{--install-after}
@end itemize

Instead of using one of the above options, @samp{--all-deps} or
@samp{--all-dependencies} can be used to list all the dependency information
for a package.

@section Querying files owned by a package

File queries can match on a fully-qualified path or just the filename.
For example:

@example
zippo -q -p package.zip -f ls.exe
zippo -qa -f c:/djgpp/ls.exe
@end example

@c TODO: Is this still true?
Wildcards and relative paths are not matched.  Support will be added for
matching on these in a later version of zippo.

@section Querying read-me documentation

These are generally good documents to read before installing a package.  For
example:

@example
zippo -q -p package.zip --pre-install-readme
@end example

Similarly, before uninstalling a package, one may want to read the uninstall
document (if available):

@example
zippo -q -p package.zip --pre-uninstall-readme
@end example

If there's no pre-uninstall document, one may want to read the pre-install
documentation again.  There may also be post-install or post-uninstall
documents to read.

A list of available documents can be found querying the long description:

@example
zippo -q -p gmp311b.zip --long-info
@end example

@node Installing packages, Uninstalling packages, Querying packages, Package operations
@chapter Installing packages
@cindex install
@cindex installing

@section Install command-line

@example
(-i | --install) <Package file> [(-n | --test)]
(-i | --install) (-A | --available) <Package name> [(-n | --test)]
@end example

Here @samp{<Package file>} is the full filename of an archive
(e.g. @file{c:/zips/gmp311b.zip} or a DSM file
(e.g. @file{c:/zips/gmp311b.dsm}).  If given an archive to install,
zippo will try to locate the DSM file within the archive
(@pxref{Introduction, , DJGPP Software Manifest, dsm}).

Here @samp{<Package name>} is the name of an available package.  This is
a package that is in zippo's available database, so zippo knows how
to install it.

@section Installing a package

Before installing a package, you should read the package's readme files
(@pxref{Querying packages, , Querying read-me documentation}).

When installing a package with zippo, the following checks are performed:

@itemize @bullet
@item
the package is of binary, source, documentation or virtual type;
@item
all the archives are available
(@pxref{Installing packages, , Locating archives});
@item
the dependencies are satisfied - that is, all the packages needed by
the new package are present or not present, as required;
@end itemize

If these checks fail, then the package cannot be installed.

When installing a package, zippo may display a warning.  This warning is
provided by the package and may contain important instructions or information
for the package.  zippo will ask if you wish to continue with
the installation, so you can abort the install after reading the warning.

Once the checks have been performed and the warning message displayed and
acknowledged, zippo will create directories and extract files from
the archive - this may take some time.  Once that is complete, the package
database is updated (@pxref{Getting started, , The package database}) -
MD5 hashes are generated for all the files and the package's DSM is copied
into the package database.  Then zippo will create entries in
the info directory for any info files contained in the package.

@strong{WARNING:} It is important to install packages with zippo, if you want
to uninstall them with zippo later.  If you do install a package without using
zippo, you should synchronise zippo's package database as soon as possible,
to create MD5 hashes and DSMs in the package database
(@pxref{Synchronising the package database}).

It is usually best to run zippo in verbose mode (the @samp{-v} or
@samp{--verbose} options), when installing, to see what it is doing.

Here are some examples:

@example
zippo --install package.zip
zippo -v -i package.zip
zippo -v -i -A 'package (binaries)'
@end example

@section Installs and duplicates

When installing a package with zippo, it is possible that a file will be
installed that has the same name as an existing file.  zippo will ask you
what to do - there are four choices:

@itemize @bullet
@item
replace the file;
@item
back up the file (@pxref{Backups});
@item
skip extracting the new file, leaving the current file;
@item
abort the uninstallation.
@end itemize

Aborting the installation of package may cause problems, because
the package may be left in a half-installed state.

Here is an example:

@example
'c:/djgpp/copying' already exists
[r]eplace, [b]ackup, [s]kip or [a]bort?
@end example

@section Testing installs
@cindex testing installs

You can test whether a package can be installed or not by installing in test
mode.  zippo does the checks listed above, displays the warning (if any) and
then aborts.  Test mode is most useful for checking dependencies. For example:

@example
zippo -v --install gmp311b.zip -n
zippo -v -i fil40b.zip --test
zippo -v -i -A 'bison (binaries)' --test
@end example

@section DSMs provided with zippo

Not all DJGPP packages have DSMs.  zippo includes DSMs for many of
the popular packages that do not include a DSM.  Hopefully these packages
will include a DSM in later releases.  In the meantime, you need to point
zippo at these DSMs, to install these packages. For example, when
installing textutils 2.0 you need to use a command-line like:

@example
zippo -v --install --available 'textutils 2.0 (binaries)'
@end example

@section Getting DSMs for DJGPP packages
@cindex djgpp-dsms package
@cindex DSMs for DJGPP packages

Newer DJGPP packages are provided with DSMs.  These DSMs are also available
in the package ``djgpp-dsms'', which is available from the DJGPP archive
as the file @samp{dsXXXXXX.zip}, where @samp{XXXXXX} is the package's date,
e.g. @samp{010822}.  This can be installed, upgraded and uninstalled like
any other DJGPP package.

If one plans to install or upgrade a lot of packages to the latest from
the DJGPP archive, it may be more convenient to download all the packages,
install ``djgpp-dsms'' and then upgrade by package name.  Typing in
a large number of filenames can become tedious.

@section Locating archives

zippo searches for package archives in the directories listed in
its configuration file @file{zipporc} (@pxref{zipporc}).  It looks in
the directories listed and then in the following sub-directories of them:

@itemize @bullet
@item
@file{v2/}
@item
@file{v2apps/}
@item
@file{v2gnu/}
@item
@file{v2misc/}
@item
@file{v2tk/}
@end itemize

This supports storage of DJGPP packages in a flat directory structure
or in a directory structure like that of the DJGPP archive.

So if one has a download directory, e.g. @file{c:/zips/djgpp}, where all DJGPP
packages are downloaded, then it should be added to the list of places
to search in @file{zipporc} (@pxref{zipporc}), like so:

@example
zips from .,c:/zips/djgpp,@@HTTP-MIRROR@@,@@FTP-MIRROR@@
@end example

@subsection An example of zippo locating archives

Consider installing Fileutils 4.0 using the DSM from
the ``djgpp-dsms'' package.  Assume that the ``djgpp-dsm'' package
has been installed.  Then you can install Fileutils using
the @samp{-A} option:

@example
zippo -v --install -A 'fileutils 4.0 (binaries)'
@end example

Assume that @file{c:/zips/djgpp} contains a mirror of the DJGPP archive
from Simtel.NET.  Then the Fileutils 4.0 binary package will be
@file{c:/zips/djgpp/v2gnu/fil40b.zip}.  Also assume that
the zippo configuration has the @samp{zips from @dots{}} line shown above.

When the install command is run, zippo will look in these directories
in this order for @file{fil40b.zip}:

@example
.
./v2
./v2apps
./v2gnu
./v2misc
./v2tk
c:/zips/djgpp
c:/zips/djgpp/v2
c:/zips/djgpp/v2apps
c:/zips/djgpp/v2gnu
c:/zips/djgpp/v2misc
c:/zips/djgpp/v2tk
@dots{}
@end example

Hence it will find the file @file{c:/zips/djgpp/v2gnu/fil40b.zip}
and install it.

@node Uninstalling packages, Upgrading packages, Installing packages, Package operations
@chapter Uninstalling packages
@cindex uninstall
@cindex uninstalling

@section Uninstall command-line

@example
(-e | --uninstall) <Package> [(-n | --test)]
@end example

Here @samp{<Package>} is a package specifier (@pxref{Package specifiers}),
for example @samp{'fileutils 4.0 (binaries)'}.  If more than one package is
matched by the given package specifier, zippo will abort.  Only one package
can be uninstalled at a time.  If there are multiple matches, a more precise
package specifier is needed.

@section Uninstalling a package

Before uninstalling a package, you should read the package's readme files
(@pxref{Querying packages, , Querying read-me documentation}).

When uninstalling a package with zippo, it checks that no hard dependencies
will be broken by removing the package.  If this check fails, then
the package cannot be uninstalled.

Once the checks have been performed, zippo removes any entries in
the info directory for any info files contained in the package.  Then zippo
removes all files belonging to the package - this may take some time.
Once that is complete, the package database is updated
(@pxref{Getting started, , The package database}) -
MD5 hashes are removed and the package's DSM is removed from
the package database.

@strong{WARNING:} Packages that do not have MD5 hashes will be removed
without prompting the user.  zippo cannot tell what files have been changed
and will just remove them.

It is usually best to run zippo in verbose mode (the @samp{-v} or
@samp{--verbose} options), when uninstalling, to see what it is doing.

Here are some examples:

@example
zippo --uninstall 'gmp 3.1.1 (binaries)'
zippo -v -e fileutils
@end example

@section Uninstalls and modified files

When uninstalling a package that was installed with zippo, it will ask you
what to do with modified files.  There are four choices:

@itemize @bullet
@item
remove the file;
@item
back up the file (@pxref{Backups});
@item
keep the file;
@item
abort the uninstallation.
@end itemize

Aborting the uninstallation of package may cause problems, because
the package may be left in a half-installed state.

Here is an example:

@example
Warning: MD5 hash for file 'c:/djgpp/djgpp.env' has changed
'c:/djgpp/djgpp.env' has changed
[r]emove, [b]ackup, [k]eep or [a]bort?
@end example

@section Testing uninstalls
@cindex testing uninstalls

You can test whether a package can be uninstalled or not by uninstalling in
test mode.  zippo does the checks listed above, lists changed files and then
aborts.  Test mode is most useful for checking dependencies.  For example:

@example
zippo -v --uninstall 'gmp 3.1.1 (binaries)'
zippo -v -e fileutils
@end example

@node Upgrading packages, Backups, Uninstalling packages, Package operations
@chapter Upgrading packages

@section Upgrade command-line

@cartouche
@strong{WARNING:} zippo's upgrade feature is experimental.  It may not
handle dependencies properly in all cases, which could cause data loss.
You are strongly advised to use upgrade in test mode, before actually
upgrading.  Having said this, the author has used the upgrade feature
many times, without data loss.
@end cartouche

@example
(-U | --upgrade) <Package file> [(-n | --test)]
@end example

Here @samp{<Package file>} is the full filename of an archive
(e.g. @file{c:/zips/gmp311b.zip} or a DSM file
(e.g. @file{c:/zips/gmp311b.dsm}).  If given an archive to upgrade,
zippo will try to locate the DSM file within the archive
(@pxref{Introduction, , DJGPP Software Manifest, dsm}).

@section Upgrading a package

Before upgrading a package, you should read the old and new packages'
readme files (@pxref{Querying packages, , Querying read-me documentation}).
Because upgrading to a new package may upgrade more than one package,
this may not be straightforward.

When upgrading a package with zippo, it checks that all hard dependencies
satisfied by the old package(s) will be satisfied by the new package.
It is possible that not all hard dependencies are satisfied in normal usage -
for instance, if a user installs a DJGPP package without using zippo.  If this
check fails, then the package cannot be uninstalled.

Upgrading is basically an uninstall operation (@pxref{Uninstalling packages})
followed by an install operation (@pxref{Installing packages}).

It is described in the section on install operations, how package archives
are found (@pxref{Installing packages, , Locating archives}).

@section Upgrades, modified files and duplicates

Please see the uninstall and install sections (@pxref{Uninstalling packages}),
@pxref{Installing packages}) for information on duplicates and modified
files.  Upgrading treats files in the same manner as uninstall and install
operations.

@section Testing upgrades
@cindex testing upgrades

You can test whether a package can be upgraded or not by upgrading in
test mode.  zippo does the checks listed above, lists changed files and then
aborts.  Test mode is most useful for checking dependencies.  For example:

@example
zippo -v --upgrade fil40b.zip
@end example

@node Backups, Checking the integrity of installed packages, Upgrading packages, Package operations
@section Backups

When backing up a file, zippo places the files in the @file{backup/}
directory off the zippo root, e.g. @file{c:/djgpp/backup}.  The files are
stored in a directory named after the package.  They are stored with
the same relative paths that they had under the zippo root,
e.g. @file{bin/}.

As an example, consider a package 'fred' version 1.2 binaries.
The package file name could be @file{fred12b.zip} with a DSM called
@file{fred12b.dsm}.  Say it was stored under @file{c:/djgpp}, but is now
being uninstalled.  A user modified its configuration file
@file{c:/djgpp/share/fred/fred.ini}.  When the package is uninstalled,
the user chooses to back up @file{fred.ini}. It is backed up to:

@example
c:/djgpp/backup/fred12b.old/share/fred/fred.ini
@end example

By storing the modified files under a directory named after the package,
you should be able to find the backup easily.

@node Checking the integrity of installed packages, Configuration, Backups, Package operations
@chapter Checking the integrity of installed packages

@section Check integrity command-line

@example
--check-integrity <Package>
@end example

Here @samp{<Package>} is a package specifier (@pxref{Package specifiers}),
for example @samp{'fileutils 4.0 (binaries)'}.  Multiple packages can be
checked.

@section Checking the integrity of a package

@c TODO: Pass vs. fail?

Checking the integrity of a package checks that:

@itemize @bullet
@item whether any of its files have been changed;
@item none of its files have been deleted.
@end itemize

For any files that have been changed/deleted, zippo will output
a message.

Here's an example:

@example
zippo -v -check-integrity djdev
@end example

To check the integrity of all packages, use:

@example
zippo -v --check-integrity '*'
@end example

This may take some time, if you have a lot of packages installed.

@node Configuration, zipporc, Checking the integrity of installed packages, Top
@chapter Configuration

@ifnottex
@menu
* zipporc::
* simtelrc::
@end menu
@end ifnottex

@node zipporc, simtelrc, Configuration, Configuration
@section zipporc

@file{zipporc} controls where zippo looks for its files - namely:

@itemize
@item
manifest files (@file{.mft}) for installed packages,
e.g. @file{c:/djgpp/manifest};
@item
DSM files for installed packages, e.g. @file{c:/djgpp/share/zippo/db};
@item
DSM files for available packages, e.g. @file{c:/djgpp/share/zippo/db-avail};
@item
ZIP file packages;
@item
gzip'd tar file packages;
@item
bzip2'd tar file packages.
@end itemize

@section zipporc's syntax

@example
installed mft from <paths>
installed dsm from <paths>
available dsm from <paths>
zip from <paths and/or urls>
tar-gzip from <paths and/or urls>
tar-bzip2 from <paths and/or urls>

proxy http using <url>
proxy ftp using <url>

ftp from <url>
http from <url>

location is <country code>
@end example

where:

<paths> is a list of paths separated by commas or the word @samp{or}
surrounded by whitespace, e.g.:

@example
c:/some-dir,c:/some-other-dir or c:/yet-another-dir
@end example

If the a path has spaces in its name, enclose its name in double quotes.

<url> is a URL formatted like so:

@example
http://somehost/
@end example

<paths or urls> is a list of paths and/or URLs formatted in
the same way as <paths>, e.g.

@example
c:/some-dir or ftp://server/remote-dir/
@end example

@subsection Substitutions

@file{zipporc} allows substitutions to be made from the environment.
Other special substitutions can be made.  The syntax is:

@example
@@<substitution-name>@@
@end example

where <substitution-name> is the name of the substitution to be
performed.  If the named substitution cannot be made, then
it is replaced by empty text.

@subsection Substitutions from the environment

Examples of configuration commands using substitutions from
the environment:

@example
proxy http using @@http_proxy@@
proxy ftp using @@ftp_proxy@@
@end example

If @code{http_proxy} is not set in the environment, then no HTTP proxy
will be used.

@subsection Special substitutions

The following are special substitutions:

@table @samp

@item ZIPPO-ROOT
This is replaced with the zippo root directory, which is typically
the DJGPP directory, as given by the environment variable @samp{DJDIR},
e.g. @file{c:/djgpp}.  This should be used instead of @samp{@@DJDIR@@}.

@item HTTP-MIRROR
This is replaced with the selected HTTP mirror.

@item FTP-MIRROR
This is replaced with the selected FTP mirror.

@end table

@section Example zipporc

@example
installed mft from @@ZIPPO-ROOT@@manifest
installed dsm from @@ZIPPO-ROOT@@share/zippo/db
available dsm from .,@@ZIPPO-ROOT@@share/zippo/db-avail

zip from .,@@FTP-MIRROR@@,@@HTTP-MIRROR@@
tar-gzip from .,@@FTP-MIRROR@@,@@HTTP-MIRROR@@
tar-bzip2 from .,@@FTP-MIRROR@@,@@HTTP-MIRROR@@

proxy http using @@http_proxy@@
proxy ftp using @@ftp_proxy@@

ftp from ftp://sunsite.org.uk/packages/simtelnet/djgpp/
http from http://sunsite.org.uk/packages/simtelnet/djgpp/
@end example

You may wish to add the directory you keep ZIP packages in, e.g.:

@example
zip from .,c:/djgpp-zips,@@FTP-MIRROR@@,@@HTTP-MIRROR@@
@end example

The @file{zipporc} file that ships with zippo is well commented.
Hopefully this will also help you to understand how to configure zippo.

@node simtelrc, How-tos, zipporc, Configuration
@section simtelrc

@section simtelrc's syntax

[TODO]

@node How-tos, How to install DJGPP using zippo, simtelrc, Top
@appendix How-tos

@ifnottex
@menu
* How to install DJGPP using zippo::
* How to upgrade zippo using zippo::
* How to report bugs in zippo::
@end menu
@end ifnottex

@node How to install DJGPP using zippo, How to upgrade zippo using zippo, How-tos, How-tos
@section How to install DJGPP using zippo

@enumerate 1
@item
Create a directory to contain your DJGPP installation, e.g. @file{c:/djgpp}.
Please replace @file{c:/djgpp} with the appropriate path in
the following steps.

@item
Extract the zippo binary distribution into the DJGPP directory.

@item
Add the @file{bin} sub-directory of the DJGPP directory to your path,
e.g. add the following to your @file{autoexec.bat}:

@example
PATH=c:\djgpp\bin;%PATH%
@end example

Also execute this command from the DOS command-line.

@item
Add a line for @file{djgpp.env} to your @file{autoexec.bat}, e.g.:

@example
set DJGPP=c:\djgpp\djgpp.env
@end example

Also execute this command from the DOS command-line.

@item
Initialise the package database in the DJGPP directory, e.g.:

@example
zippo --root c:/djgpp -v --initdb
@end example

@item
Modify the zippo configuration file (@pxref{zipporc}) to point to
the directory that you store your DJGPP packages in. For example,
if you store your packages in @file{c:/zips/gnu/djgpp}, add a line
like:

@example
zip from c:/zips/gnu/djgpp
@end example

@item
Install the DJGPP development environment.  E.g.:

@example
zippo --root c:/djgpp -v --install c:/zips/gnu/djgpp/djdev203.zip
@end example

@item
Now that you have the base DJGPP environment installed, read
the DJGPP installation instructions for any other actions that may be
needed, to use it.  At this point you may want to reboot, to pick up
the changes to @file{autoexec.bat}.

@end enumerate

@node How to upgrade zippo using zippo, How to report bugs in zippo, How to install DJGPP using zippo, How-tos
@section How to upgrade zippo using zippo

The problem with upgrading zippo on DOS or Windows is that you cannot
overwrite the zippo program, while it is running.  To get round
this problem, create a temporary copy of the current zippo program
and use the copy to upgrade the main zippo program.
E.g.: to upgrade to zippo 0.1.6:

@example
mkdir -p /temp/upgrade
cp $DJDIR/bin/zippo.exe /temp/upgrade/zippo.exe
/temp/upgrade/zippo.exe -Uv /path/to/zipo016b.zip
rm /temp/upgrade/zippo.exe
@end example

@node How to report bugs in zippo, GNU Free Documentation License, How to upgrade zippo using zippo, How-tos
@section How to report bugs in zippo

When trying to fix bugs, some information is required: the version of zippo
(see below) and how zippo failed.  For instance, did zippo crash? Or did it
exit with a strange error?

If zippo crashed, please send details of its crash dump.  Analysis of crash
dumps is explained in detail in the DJGPP FAQ
(@pxref{Crash dump, , Crash dump, djgppfaq}).  Please note that this only
applies to the DJGPP version of zippo.  If you are using zippo on other
platforms (e.g. Linux), there are other methods for analysing crashes
(e.g. coredumps).

@subsection Finding the version of zippo

The version of zippo can be found using the @samp{--version} command-line
option for zippo.  The @samp{--verbose} option will display warnings about
problems with or assumptions made in parsing the package database.

@example
zippo --verbose --version
@end example

Please send a copy of the output of this command to the person who built
the version of zippo you are using.  Below is an example of the output, for
comparison.

@example
. DJGPP path 'c:/djgpp/'
. Installation prefix 'c:/djgpp/'
. Backup prefix 'c:/djgpp/backup/'
. Reading configuration from 'src/defaults/zipporc'
. Installed DSM path [1]: 'c:/djgpp/share/zippo/db'
. Installed manifest path [1]: 'c:/djgpp/manifest'
. Available DSM path [1]: '.'
. Available DSM path [2]: 'c:/djgpp/share/zippo/db-avail'
. Available zip path [1]: '.'
. Available gzip'd tar path [1]: '.'
. Available bzip2'd tar path [1]: '.'
zippo 0.1.6 - DJGPP Package Manager
Copyright (C) 1999-2002 by Richard Dawe <rich@@phekda.freeserve.co.uk>
Distributed under terms of the GNU GPL ('zippo -L' to view)

Compilation information:
. Built on 'ATHENA' by rich <rich@@phekda.freeserve.co.uk>
. Built on Mar 10 2002 15:55:34
. libzippo 0.1.6
. DJGPP 2.03
. gcc version 3.0.3
. binutils 2.11.2
. zlib 1.1.3 Copyright (C) 1995-1998 Jean-loup Gailly and Mark Adler
. unzip 0.15 Copyright 1998 Gilles Vollant

DSM built-ins:
. DSM version:   0.5.1
. Platform:      i386-pc-msdosdjgpp
. Root:          c:/djgpp/ (NB: overridden by DJDIR from environment)
. Platform DSMs: dosemu msdos win2k win3 win95 win98 winme winnt4 winxp

Helpers:
. HTTP/FTP: wget: c:/djgpp/share/zippo/win32/wget/wget.exe
@end example

@node GNU Free Documentation License, Concept Index, How to report bugs in zippo, Top
@appendix GNU Free Documentation License

@include fdl.txi

@node Concept Index, , GNU Free Documentation License, Top
@unnumbered Concept Index

@printindex cp

@contents
@bye
