\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename pakke.info @settitle @setchapternewpage odd @paragraphindent 0 @c %**end of header @c $Id: pakke.txi,v 1.29 2003/03/15 13:29:20 richdawe Exp $ @include version.txi @titlepage @title pakke @value{PAKKE-VERSION} Manual @subtitle Copyright @copyright{} @value{PAKKE-COPYRIGHT-YEARS} by Richard Dawe @page @end titlepage @ifinfo @dircategory DJGPP Package Management @direntry * pakke: (pakke). pakke, 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} @c Mailing list @email{pakke-workers@@yahoogroups.com} @ifnottex pakke @value{PAKKE-VERSION} Manual Copyright @copyright{} @value{PAKKE-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 pakke:: Getting started: * Dependencies:: * The package database:: * The package operations:: * DSMs for DJGPP packages:: * Automatic downloading of packages:: * Getting started with pakke:: Package operations: * Initialising the package database:: * Synchronising the package database:: * Package specifiers:: * Querying packages:: * Installing packages:: * Uninstalling packages:: * Upgrading packages:: * Backups:: * Non-interactive mode:: * Checking the integrity of installed packages:: Configuration: * pakkerc:: * simtelrc:: How-tos: * How to install DJGPP using pakke:: * How to upgrade pakke using pakke:: * How to report bugs in pakke:: Licences: * GNU Free Documentation License:: Indices: * Concept Index:: @end menu @end ifnottex @c TODO: Put examples of pakke'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 pakke? pakke 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. pakke 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 pakke'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. pakke has a home page @uref{http://www.phekda.freeserve.co.uk/richdawe/pakke/} and a mailing list @email{pakke-workers@@yahoogroups.com}. Please ask any questions about pakke on the mailing list. @node Installation, Getting started, Introduction, Top @chapter Installation @section Installing the Binary Distribution Filename: @file{pakk@value{PAKKE-CONDENSED-VERSION}b.zip} If you want to install DJGPP from scratch, please see the How-To (@pxref{How to install DJGPP using pakke}). Installing the binary distribution (ready-to-run) of pakke 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. The binary distribution includes documentation in info and text formats. For additional formats please see the section below on the documentation distribution. 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/pakke.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. pakke should now be installed correctly and ready to use - please read how to get started with pakke (@pxref{Getting started}). @section Installing the Documentation Distribution Filename: @file{pakk@value{PAKKE-CONDENSED-VERSION}d.zip} Installing the documentation distribution of pakke 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. The documentation is provided in DVI, PostScript and HTML formats. @section Building from the Source Distribution Filename: @file{pakk@value{PAKKE-CONDENSED-VERSION}s.zip} @subsection Required and Optional Packages To build pakke 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 pakke 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 Run @samp{./configure} to autodetect any needed libraries. The following command-line options can be passed to @samp{configure}: @table @samp @item --enable-debug Enable debugging information. @item --enable-email=xxx Set the e-mail address to be displayed with pakke'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, pakke 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 pakke, please use the @samp{--enable-email} switch and supply your e-mail address. Below is an example invocation of @samp{configure} with all the options; you may not need all these options. @example ./configure --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 ./configure --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 pakke. 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 libpakke in your own programs. It installs library header files and the library itself. @end enumerate pakke should now be built, installed correctly and ready to use - please read how to get started with pakke (@pxref{Getting started}). @node Getting started, Dependencies, Installation, Top @chapter Getting started Before getting started with pakke, some concepts need to be explained. @ifnottex @menu * Dependencies:: * The package database:: * The package operations:: * DSMs for DJGPP packages:: * Automatic downloading of packages:: * Getting started with pakke:: @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 pakke has a package database, to keep track of what has been installed/uninstalled/upgraded. This information allows pakke 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 pakke (@pxref{Initialising the package database}), some information is automatically added: @itemize @bullet @item a DSM for the operating system/platform that pakke is running on. @end itemize @cindex platform DSM @cindex platform DSMs Why would you want to install a DSM for the platform that pakke 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/pakke} in the DJGPP directory (or whatever directory is the pakke root). In this directory there are: @table @file @item pakkerc pakke'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 pakke'' (@pxref{Getting started, , Getting started with pakke}). @node The package operations, DSMs for DJGPP packages, The package database, Getting started @section The package operations pakke 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 changed or are missing, if any. @node DSMs for DJGPP packages, Automatic downloading of packages, The package operations, Getting started @section DSMs for DJGPP packages @cindex djgpp-dsms package Newer DJGPP packages are provided with DSMs. These DSMs are also available in the package ``djgpp-dsms'', which is available from the @file{v2/} directory of 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. In fact the @samp{--syncdb} operation can download the latest ``djgpp-dsms'' package for you (@pxref{Synchronising the package database}). @node Automatic downloading of packages, Getting started with pakke, DSMs for DJGPP packages, Getting started @section Automatic downloading of packages pakke can download packages automatically, if they are not found. The following operations can download packages: @itemize @item synchronising the package database (@pxref{Synchronising the package database}); @item installing packages (@pxref{Installing packages}); @item upgrading packages (@pxref{Upgrading packages}). @end itemize pakke will ask you whether you want to download packages. If pakke is running in non-interactive mode (@pxref{Non-interactive mode}), it will not download packages. You should configure pakke (@pxref{pakkerc}), so that it uses the nearest and fastest server on the Internet to you, when downloading packages. You can specify the Simtel.NET mirror to use on the command-line using the @code{--mirror} command-line option: @example pakke --mirror ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/ @end example If you use the same mirror each time, you may wish to configure pakkerc (@pxref{pakkerc}) to use it by default. pakke uses GNU wget, to download packages. See the wget home page at @uref{http://wget.sunsite.dk/} or @uref{http://www.gnu.org/software/wget/} for more details. @node Getting started with pakke, Invoking pakke, Automatic downloading of packages, Getting started @section Getting started with pakke This section assumes that you already have a DJGPP installation. For instructions on installing DJGPP from scratch with pakke, please see the How-To (@pxref{How to install DJGPP using pakke}). Using pakke with an existing DJGPP installation is straightforward. Firstly, extract the pakke binaries into the DJGPP directory. You now need to initialise and synchronise the package database, so that pakke 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/pakke -v --initdb ./bin/pakke -v --syncdb @end example These commands will create the configuration files @file{pakkerc} and @file{simtelrc} for you (@pxref{pakkerc}, @pxref{simtelrc}). You should now be able to use pakke. To check this, list all installed packages: @example pakke -v -qa @end example To read the pakke manual, you can use the info program: @example info pakke @end example Please read the manual, particularly the sections on querying (@pxref{Querying packages}) and installing packages (@pxref{Installing packages}). @node Invoking pakke, Package operations, Getting started with pakke, Top @chapter Invoking pakke @subsection Help options @example -h --help -V --version -L --license @end example @code{-h} only displays help, if an operation has not been specified on the command-line. If an operation has been specified, then @code{-h} will make pakke show its progress (see @code{-h}, @code{--hash} and @code{--show-progress} below). @subsection Global options @xref{Non-interactive mode}. @example --rcfile --root --prefix -v --verbose -Q --quiet --non-interactive -h --hash --show-progress @end example @subsection Download options @xref{Automatic downloading of packages}. @example --mirror @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 -A --available -n --test @end example @subsection Database initialisation options @xref{Initialising the package database}. @example --initdb --with-platform --with-pakke @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 pakke, 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:: * Non-interactive mode:: * 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[=[,@dots{}]] [--with-pakke] @end example Here @samp{} 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 pakke to function correctly, the package database must exist. In the simplest case, you can run pakke like so: @example pakke --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? pakke 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, pakke 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 pakke -v --initdb --with-platform=winnt4 @end example It is also possible for pakke to install a copy of itself in the package root directory, using the @samp{--with-pakke} option. This is most useful when you are installing DJGPP from scratch using pakke. For example: @example pakke -v --root c:/djgpp --initdb --with-pakke @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 pakke, pakke 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}). @samp{--syncdb} can also download and install or upgrade to the latest DSMs for DJGPP packages (@pxref{DSMs for DJGPP packages}). pakke will ask if it can download them (@pxref{Automatic downloading of packages}). It is usually best to run pakke in verbose mode (the @samp{-v} or @samp{--verbose} options), when synchronsing, to see what it is doing: @example pakke -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/pakke/db-avail}. @end itemize These paths are controlled by pakke's configuration (@pxref{pakkerc}). @node Package specifiers, Querying packages, Synchronising the package database, Package operations @chapter Package specifiers @cindex package specifiers Package specifiers are very important in pakke's operation. The format of a package specifier is: @example [] [()] @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 pakke. Otherwise your shell may interpret these characters and do something you don't expect. Consider this example: @example pakke -q 'gcc 2.95.*' --long-info @end example @section Versions The version is specified as follows: @example [.[.[.]]] [ (alpha ) | (beta ) | (pre )] [revision ] [patchlevel ] [release ] [snapshot ] [platform ] @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 pakke -q -p package.zip @end example To query a non-installed package that is in pakke's package database, one must use the @samp{-A} option with the name of the package, e.g.: @example pakke -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 pakke -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 pakke -q fileutils pakke -q 'gcc 2.95.2' pakke -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 pakke -q fileutils --short-info pakke -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 pakke -q -p package.zip -f ls.exe pakke -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 pakke. @section Querying read-me documentation These are generally good documents to read before installing a package. For example: @example pakke -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 pakke -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 pakke -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) [(-n | --test)] (-i | --install) (-A | --available) [(-n | --test)] @end example Here @samp{} 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, pakke will try to locate the DSM file within the archive (@pxref{Introduction, , DJGPP Software Manifest, dsm}). Here @samp{} is the name of an available package. This is a package that is in pakke's available database, so pakke 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 pakke, 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. If pakke cannot find all the archives, it will ask if it can download them (@pxref{Automatic downloading of packages}). When installing a package, pakke may display a warning. This warning is provided by the package and may contain important instructions or information for the package. pakke 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, pakke 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 pakke will create entries in the info directory for any info files contained in the package. @strong{WARNING:} It is important to install packages with pakke, if you want to uninstall them with pakke later. If you do install a package without using pakke, you should synchronise pakke'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 pakke in verbose mode (the @samp{-v} or @samp{--verbose} options), when installing, to see what it is doing. Here are some examples: @example pakke --install package.zip pakke -v -i package.zip pakke -v -i -A 'package (binaries)' @end example @section Installs and duplicates When installing a package with pakke, it is possible that a file will be installed that has the same name as an existing file. pakke 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. pakke does the checks listed above, displays the warning (if any) and then aborts. Test mode is most useful for checking dependencies. For example: @example pakke -v --install gmp311b.zip -n pakke -v -i fil40b.zip --test pakke -v -i -A 'bison (binaries)' --test @end example @section DSMs provided with pakke Not all DJGPP packages have DSMs. pakke 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 pakke at these DSMs, to install these packages. For example, when installing textutils 2.0 you need to use a command-line like: @example pakke -v --install --available 'textutils 2.0 (binaries)' @end example You may wish to download and install the latest DSMs for DJGPP packages, to allow you to install by package name (@pxref{DSMs for DJGPP packages}). @section Locating archives pakke searches for package archives in the directories listed in its configuration file @file{pakkerc} (@pxref{pakkerc}). It looks in the directories listed and then in the following sub-directories of them: @itemize @bullet @item @file{v2/}, @file{v2/alphas/}, @file{v2/beta/}, @item @file{v2apps/}, @file{v2apps/alphas/}, @file{v2apps/beta/}, @item @file{v2gnu/}, @file{v2gnu/alphas}, @file{v2gnu/beta/}, @item @file{v2misc/}, @file{v2misc/alphas/}, @file{v2misc/beta/}, @item @file{v2tk/}, @file{v2tk/alphas/}, @file{v2tk/beta/} @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{pakkerc} (@pxref{pakkerc}), like so: @example zips from .,c:/zips/djgpp,@@PAKKE-DOWNLOAD@@ @end example @subsection An example of pakke 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 pakke -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 pakke configuration has the @samp{zips from @dots{}} line shown above. When the install command is run, pakke 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) [(-n | --test)] @end example Here @samp{} 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, pakke 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 pakke, 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, pakke removes any entries in the info directory for any info files contained in the package. Then pakke 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. pakke cannot tell what files have been changed and will just remove them. It is usually best to run pakke in verbose mode (the @samp{-v} or @samp{--verbose} options), when uninstalling, to see what it is doing. Here are some examples: @example pakke --uninstall 'gmp 3.1.1 (binaries)' pakke -v -e fileutils @end example @section Uninstalls and modified files When uninstalling a package that was installed with pakke, 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. pakke does the checks listed above, lists changed files and then aborts. Test mode is most useful for checking dependencies. For example: @example pakke -v --uninstall 'gmp 3.1.1 (binaries)' pakke -v -e fileutils @end example @node Upgrading packages, Backups, Uninstalling packages, Package operations @chapter Upgrading packages @section Upgrade command-line @cartouche @strong{WARNING:} pakke'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) [(-n | --test)] (-U | --upgrade) (-A | --available) [(-n | --test)] @end example Here @samp{} 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, pakke will try to locate the DSM file within the archive (@pxref{Introduction, , DJGPP Software Manifest, dsm}). Here @samp{} is the name of an available package. This is a package that is in pakke's available database, so pakke knows how to install it. @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 pakke, 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 pakke. 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}). @example pakke -v --upgrade fil40b.zip pakke -v --upgrade -A 'bison 1.35 (binaries)' @end example @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. pakke does the checks listed above, lists changed files and then aborts. Test mode is most useful for checking dependencies. For example: @example pakke -v --upgrade fil40b.zip --test @end example @node Backups, Non-interactive mode, Upgrading packages, Package operations @chapter Backups When backing up a file, pakke places the files in the @file{backup/} directory off the pakke 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 pakke 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 Non-interactive mode, Checking the integrity of installed packages, Backups, Package operations @chapter Non-interactive mode When pakke is run in non-interactive mode, it automatically answers any questions that it would have asked the user. It answers the questions in cautious manner. For example: @table @asis @item Synchronise database Packages will not be downloaded. @item Install Installs will be aborted if the package has a warning message that the user must read. Installs will not automatically download packages. Files will be backed up automatically, if they will be overwritten. Packages will not be downloaded. @item Upgrade Installs will be aborted if the package has a warning message that the user must read. Packages will not be automatically downloaded. Files will be backed up automatically, if they will be overwritten or have changed. Packages will not be downloaded. @item Uninstall Files will be backed up automatically, if they have changed. @end table @node Checking the integrity of installed packages, Configuration, Non-interactive mode, Package operations @chapter Checking the integrity of installed packages @section Check integrity command-line @example --check-integrity @end example Here @samp{} 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, pakke will output a message. Here's an example: @example pakke -v -check-integrity djdev @end example To check the integrity of all packages, use: @example pakke -v --check-integrity '*' @end example This may take some time, if you have a lot of packages installed. @node Configuration, pakkerc, Checking the integrity of installed packages, Top @chapter Configuration @ifnottex @menu * pakkerc:: * simtelrc:: @end menu @end ifnottex @node pakkerc, simtelrc, Configuration, Configuration @section pakkerc @file{pakkerc} controls where pakke 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/pakke/db}; @item DSM files for available packages, e.g. @file{c:/djgpp/share/pakke/db-avail}; @item ZIP file packages; @item gzip'd tar file packages; @item bzip2'd tar file packages. @end itemize @file{pakkerc} also controls how and where pakke downloads packages using the protocols HTTP and FTP: @itemize @item what HTTP and/or FTP proxies to use, if any; @item what HTTP or FTP server to use, @item or what country the computer is in, if pakke should choose an HTTP or FTP server. @end itemize @section pakkerc's syntax @example installed mft from installed dsm from available dsm from zip from tar-gzip from tar-bzip2 from proxy http using proxy ftp using ftp from http from location is @end example where: 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. is a URL formatted like so: @example http://somehost/ @end example is a list of paths and/or URLs formatted in the same way as , e.g. @example c:/some-dir or ftp://server/remote-dir/ @end example URLs must specify the path to the root of a DJGPP archive directory, i.e.: the one containing all archives (@pxref{Installing packages, , Locating archives}). @section Configuring downloading of packages pakke can download packages from HTTP or FTP web servers. The server is chosen according to these rules: @itemize @item If an archive path list (e.g.: @samp{zip}, @samp{tar-gzip} or @samp{tar-bzip2}) contains a URL, then that URL is used. @item If @samp{http from} is specified, its URL is used. @item If @samp{ftp from} is specified, its URL is used. @item If @samp{location} is specified, then a URL is chosen from the list of Simtel.NET mirrors in @file{simtelrc} (@pxref{simtelrc}). @item Otherwise the main Simtel.NET site is used. @end itemize Please specify a @samp{location}, to reduce load on the main Simtel.NET site. @subsection Locations A @samp{location} is the country code used in URLs on the Internet, e.g.: @samp{uk}, @samp{de}, @samp{au}. Users in the US should use one of the generic top-level domain names, e.g.: @samp{com}, @samp{net} or @samp{org}. @subsection Substitutions in pakkerc @file{pakkerc} allows substitutions to be made from the environment. Other special substitutions can be made. The syntax is: @example @@@@ @end example where 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 PAKKE-ROOT This is replaced with the pakke 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 PAKKE-DOWNLOAD This is replaced with the directory that pakke places archives, when it downloads them via HTTP or FTP. @samp{PAKKE-DOWNLOAD} is expanded to @samp{@@PAKKE-ROOT@@/share/pakke/packages}, which may be, for example, @samp{c:/djgpp/share/pakke/packages}. You should have @samp{@@PAKKE-DOWNLOAD@@} in your @samp{zip}, @samp{tar-gzip} and @samp{tar-bzip2} paths. Otherwise pakke will not be able to find the archives it has downloaded. @end table @section Example pakkerc This example pakkerc is for a standard install of DJGPP. If pakke cannot find any package files, it will download them from an HTTP or FTP mirror site in the UK. @example installed mft from @@PAKKE-ROOT@@manifest installed dsm from @@PAKKE-ROOT@@share/pakke/db available dsm from .,@@PAKKE-ROOT@@share/pakke/db-avail zip from .,@@PAKKE-DOWNLOAD@@ tar-gzip from .,@@PAKKE-DOWNLOAD@@ tar-bzip2 from .,@@PAKKE-DOWNLOAD@@ proxy http using @@http_proxy@@ proxy ftp using @@ftp_proxy@@ location is uk @end example You may wish to add the directory you keep ZIP packages in, e.g.: @example zip from .,c:/djgpp-zips,@@PAKKE-DOWNLOAD@@ @end example The @file{pakkerc} file that is supplied with pakke is well commented. Hopefully this will also help you to understand how to configure pakke. @node simtelrc, How-tos, pakkerc, Configuration @section simtelrc @section simtelrc's syntax @file{simtelrc} contains a list of URLs for Simtel.NET mirror sites, which contain a mirror of the DJGPP archive. @file{simtelrc} has one URL per line. E.g.: @example ftp://ftp.demon.co.uk/pub/simtelnet ftp://ftp.nic.surfnet.nl/mirror/simtel @end example You should not need to edit @file{simtelrc}, since each release of pakke should come with an up-to-date list of Simtel.NET mirrors. If you find that the list is out-of-date, please send a mail to @email{pakke-workers@@yahoogroups.com}. @node How-tos, How to install DJGPP using pakke, simtelrc, Top @appendix How-tos @ifnottex @menu * How to install DJGPP using pakke:: * How to upgrade pakke using pakke:: * How to report bugs in pakke:: @end menu @end ifnottex @node How to install DJGPP using pakke, How to upgrade pakke using pakke, How-tos, How-tos @section How to install DJGPP using pakke @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 pakke 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 pakke --root c:/djgpp -v --initdb @end example @item Modify the pakke configuration file (@pxref{pakkerc}) 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 pakke --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 pakke using pakke, How to report bugs in pakke, How to install DJGPP using pakke, How-tos @section How to upgrade pakke using pakke The problem with upgrading pakke on DOS or Windows is that you cannot overwrite the pakke program, while it is running. To get round this problem, create a temporary copy of the current pakke program and use the copy to upgrade the main pakke program. E.g.: to upgrade to pakke 0.1.6: @example mkdir -p /temp/upgrade cp $DJDIR/bin/pakke.exe /temp/upgrade/pakke.exe /temp/upgrade/pakke.exe -Uv /path/to/zipo016b.zip rm /temp/upgrade/pakke.exe @end example @node How to report bugs in pakke, GNU Free Documentation License, How to upgrade pakke using pakke, How-tos @section How to report bugs in pakke When trying to fix bugs, some information is required: the version of pakke (see below) and how pakke failed. For instance, did pakke crash? Or did it exit with a strange error? If pakke 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 pakke. If you are using pakke on other platforms (e.g. Linux), there are other methods for analysing crashes (e.g. coredumps). Please send details of the bug to @email{pakke-workers@@yahoogroups.com}. @subsection Finding the version of pakke The version of pakke can be found using the @samp{--version} command-line option for pakke. The @samp{--verbose} option will display warnings about problems with or assumptions made in parsing the package database. @example pakke --verbose --version @end example Please send a copy of the output of this command to the person who built the version of pakke 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/' . Download prefix 'c:/djgpp/share/pakke/packages/' . Reading configuration from 'c:/djgpp/share/pakke/pakkerc' . Installed DSM path [1]: 'c:/djgpp/share/pakke/db' . Installed manifest path [1]: 'c:/djgpp/manifest' . Available DSM path [1]: '.' . Available DSM path [2]: 'c:/djgpp/share/pakke/db-avail' . Available zip path [1]: '.' . Available zip path [2]: 'c:/djgpp/share/pakke/packages/' . Available gzip'd tar path [1]: '.' . Available gzip'd tar path [2]: 'c:/djgpp/share/pakke/packages/' . Available bzip2'd tar path [1]: '.' . Available bzip2'd tar path [2]: 'c:/djgpp/share/pakke/packages/' . HTTP mirror [1]: 'http://iolanthe/djgpp/' . Location [1]: 'uk' . Simtel.NET mirror: 'http://iolanthe/djgpp/' pakke 0.2.1 - DJGPP Package Manager Copyright (C) 1999-2002 by Richard Dawe Distributed under terms of the GNU GPL ('pakke -L' to view) Compilation information: . Built on 'ATHENA' by rich . Built on Jun 30 2002 13:14:54 . libpakke 0.2.1 . DJGPP 2.03 . gcc version 3.1 . binutils 2.12.1 . zlib 1.1.4 Copyright (C) 1995-1998 Jean-loup Gailly and Mark Adler . unzip 0.15 Copyright 1998 Gilles Vollant DSM built-ins: . DSM version: 0.6.0 . 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/pakke/win32/wget/wget.exe DJGPP prefixes: v2/, v2/alphas/, v2/beta/, v2apps/, v2apps/alphas/, v2apps/beta/, v2gnu/, v2gnu/alphas/, v2gnu/beta/, v2misc/, v2misc/alphas/, v2misc/beta/, v2tk/, v2tk/alphas/, v2tk/beta/, v2tk/allegro/ @end example @node GNU Free Documentation License, Concept Index, How to report bugs in pakke, Top @appendix GNU Free Documentation License @include fdl.txi @node Concept Index, , GNU Free Documentation License, Top @unnumbered Concept Index @printindex cp @contents @bye