File: zippo.inf,  Node: Installation,  Next: Getting started,  Prev: Introduction,  Up: Top

Installation
************

Installing the Binary Distribution
==================================

If you want to install DJGPP from scratch, please see the How-To (*note
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 `v2gnu/txi40b.zip').  Run the
following commands:

     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

Please note that some lines have been split with the `\' 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 (*note Getting started::).

Building from the Source Distribution
=====================================

Required and Optional Packages
------------------------------

To build zippo the following packages are required:

   * GNU C compiler - versions 2.8.0, 2.8.1, 2.95.2, 2.95.3 have been
     used.

   * GNU binutils - versions 2.8.1, 2.9.5.1 beta, 2.10 have been used.

   * GNU make

   * GNU autoconf 2.13

   * GNU m4 1.4 (or later) (required by GNU autoconf)

   * GNU awk (required by GNU autoconf)

   * GNU grep (required by GNU autoconf)

   * GNU sed

   * GNU bash

   * GNU fileutils

   * GNU findutils

   * GNU shellutils

   * GNU textutils 2.0 (or later)

   * GNU texinfo 4.0 (or later)

   * GNU flex

   * GNU bison

   * zlib (available from the DJGPP archive in `v2tk/')

   * popt (available from the DJGPP archive in `v2tk/')

Optional packages are as follows:

   * The Memory Supervision System (MSS) can provide memory allocation
     debugging.  MSS is available from the DJGPP archive in `v2tk/'.

   * 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 `v2misc/'.

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

Configuration and Compilation
-----------------------------

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

  1. Regenerate the configure scripts:

          ./scripts/mkconfig.sh

     This executes the following commands:

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

     It may be necessary to regenerate the configure script, because
     the DJGPP port of `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 `sed' above is necessary to convert the filename
     `config.guess' to the short filename `config.gue' that is used in
     the zippo distribution (so that zippo can be compiled on plain ol'
     DOS).

     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 `autoconf'.  I may have forgotten to
     run `autoconf' when making a source snapshot. ;)

  2. Run `./config' to autodetect any needed libraries.  The following
     command-line options can be passed to `config':

    `--enable-debug'
          Enable debugging information.

    `--enable-email=xxx'
          Set the e-mail address to be displayed with zippo's `-V'
          command-line option.

    `--with-bzip2'
          Enable support for bzip2-compressed packages (*note
          bzip2.info: Top.).

    `--with-mss'
          Enable memory allocation tracking with MSS - if MSS isn't
          installed, then this will be ignored.

    `--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 _may_ be less
          stable than those built without.  Problems have been reported
          with programs built with PMODE/DJ.

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

     Below is an example invocation of `config' with all the options;
     you may not need all these options.

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

     The `--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
     `/dev/env/DJDIR' syntax for the prefix, e.g.:

          ./config --prefix=/dev/env/DJDIR

  3. Run `make' to compile.

  4. (_Optional_, but recommended) Run `make check' to check that the
     programs have been built correctly.

  5. (_Optional_) Run `make -C doc all' to build documentation in
     formats other than the defaults of info and HTML.

  6. (_Optional_) Run `make install' to install zippo.  If you want to
     see what would be installed, use `make -n install' instead.

  7. (_Optional_) Run `make install-lib' if you are going to use
     libzippo in your own programs.  It installs library header files
     and the library itself.

zippo should now be built, installed correctly and ready to use -
please read how to get started with zippo (*note Getting started::).

File: zippo.inf,  Node: Getting started,  Next: Dependencies,  Prev: Installation,  Up: Top

Getting started
***************

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

* Menu:

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

File: zippo.inf,  Node: Dependencies,  Next: The package database,  Prev: Getting started,  Up: Getting started

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.

The DSM specification (*note dsm.inf: Top.) actually has two kinds of
dependencies - `requires' and `depends-on'.  These are "hard
dependencies" and "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.

It is also possible to have "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.

File: zippo.inf,  Node: The package database,  Next: The package operations,  Prev: Dependencies,  Up: Getting started

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:

   * descriptions of the packages (DSMs);

   * manifest files for the packages (`.mft' files);

   * MD5 hashes of each file in the packages, to detect when they have
     changed.

When the package database is created by zippo (*note Initialising the
package database::), some information is automatically added:

   * a DSM for the operating system/platform that zippo is running on.

Why would you want to install a DSM for the platform that zippo is
running on?  These "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 `share/zippo' in the DJGPP directory
(or whatever directory is the zippo root).  In this directory there are:

`zipporc'
     zippo's configuration file;

`simtelrc'
     a list of URLs for mirror sites for the DJGPP archive;

`db/'
     a directory containing installed package database;

`db-avail/'
     a directory containing available package database;

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

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

     Error: Unable to read configuration file!

Please see the later section "Getting started with zippo" (*note
Getting started with zippo: Getting started.).

File: zippo.inf,  Node: The package operations,  Next: Getting started with zippo,  Prev: The package database,  Up: Getting started

The package operations
======================

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

   * The package database can be initialised.

   * The package database can be synchronised with updated DSMs, when
     they become available.

   * Installed packages can be queried, uninstalled, upgraded or
     verified.

   * Available packages can be queried or installed.

These operations are described in the chapter "Package operations"
(*note Package operations::).

The method of selecting packages depends on the operation.  See the
section of package specifiers for more details (*note Package
specifiers::).

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

File: zippo.inf,  Node: Getting started with zippo,  Next: Invoking zippo,  Prev: The package operations,  Up: Getting started

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 (*note 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 `bash' to run it.  Then change into
the DJGPP directory (e.g. `c:/djgpp') and then execute the following
commands:

     ./bin/zippo -v --initdb
     ./bin/zippo -v --syncdb

These commands will create the configuration files `zipporc' and
`simtelrc' for you (*note zipporc::, *note simtelrc::).

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

     zippo -v -qa

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

     info zippo

Please read the manual, particularly the sections on querying (*note
Querying packages::) and installing packages (*note Installing
packages::).

