
FreeBSD-Portindex version 2.0
=============================

$Id: README 982 2012-02-07 10:58:05Z matthew $

   portindex, portdepends, cache-init, cache-update and find-updated
   are a set of perl scripts built around the common core of the
   FreeBSD::Portindex perl modules. Their use is to generate and
   maintain the ports INDEX-N files speedily and efficiently (where N
   is one of 5, 6 or 7 depending on FreeBSD major version number) or
   to produce alternatively formatted representations of the same
   data.  Ultimately they work in a very similar way to the standard
   make index command, except that the FreeBSD::Portindex tools keep a
   cache of the make describe output from each port, and can update
   that cached data incrementally as the ports tree itself is updated.

   Incremental updating is much faster than building the INDEX
   entirely from scratch every time. Once the cache has been
   initialised, all of the changes made over the course of a day or a
   week can be incorporated in a few minutes, and an up to date INDEX
   file produced in a few seconds. Being able to quickly generate a
   fresh INDEX file from the cache is also exceedingly handy now that
   the INDEX files have been removed from CVS.

   The cache-update process can either take the output of running
   cvsup over the ports-all collection, or it can read cvsup's
   checkouts file (usually /var/db/sup/ports-all/checkouts.cvs:.) to
   work out which ports have been modified or deleted recently. Finally,
   it can just read a list of port directories -- including the list
   output by the 'portsnap update' command.  Or you can generate a list
   of recently updated ports using 'find-updated'.

   The list of ports to check for updates will automatically include
   the ports that have been affected indirectly by a change to any of
   the ports Makefiles involved in building them, and so need their
   cached description updated. By default this includes any of the
   'options' files under /var/db/ports -- or you can check for options
   changes separately by

      % cache-update -f options

   To see which ports include Makefiles out of /usr/ports/Mk, try:

      % echo /usr/ports/Mk/bsd.openssl.mk | cache-update -f plain
   
DEPENDENCIES

   Prerequisites: you will need to have installed a recent version of
   Perl, at least

     perl-5.10.1 (lang/perl5.10)

   but any more recent version will work.

   Additionally you will need

     p5-BerkeleyDB-0.50 (databases/p5-BerkeleyDB)

   and one of the Berkeley Database Library ports such as
   
     db44-4.8.30.0 (databases/db48).

   Other Perl or BDB versions will work, but have not been thoroughly
   tested.

INSTALLATION

   Of course installing via the sysutils/p5-FreeBSD-Portindex port is
   the recommended method.

   However, for completeness' sake, here are the instructions for how
   to do a manual installation.

   i) Download and unpack the portindex tar-ball, and install:

        % tar -jxvf FreeBSD-Portindex-N.NN.tar.bz2
        % cd FreeBSD-Portindex-N.NN
        % perl Makefile.PL
        % make
        % make test
        # make install
        % rehash

   ii) Initialise the Cache

   This is a slow step (slower than make index) but it only needs to be
   done once.

        # mkdir /var/db/portindex
        # chown user:group /var/db/portindex
        % cache-init

   That creates the portindex cache file (about 24MiB currently)
   containing all of the make describe output, as well as details of
   all ports Makefiles required to build the port and whether the port
   is a slave port of some other one. It also contains a timestamp
   file showing the last time that the cache was updated. Nb. while
   you can run any of the FreeBSD::Portindex programs as root safely
   enough, on general principles I recommend using a non-privileged
   user account instead.

Then, for day to day use:

  iii) Update the Cache

   Before generating a new INDEX-N file, update the FreeBSD::Portindex cache
   with the details of any recently updated ports. The recommended way to
   do this is by parsing the output of cvsup. See the POD pages for
   cache-update and find-updated for other possibilities.

       # script /tmp/cvsup.out \
            cvsup -g -L2 -h cvsupN.XX.freebsd.org \
            /usr/share/examples/cvsup/ports-supfile
       % cache-update -i /tmp/cvsup.out

   Portsnap users should do this:

       # script /tmp/portsnap.out portsnap update
       % cache-update -f plain,options -i /tmp/portsnap.out

   Repeat as necessary if you run cvsup or portsnap several times
   between generating new INDEX-N files.

  iv) Generate the INDEX-N file

       # portindex -o /usr/ports/INDEX-N

   Steps (iii) and (iv) together should only take a few minutes or so
   -- more if one of the commonly included Makefiles like
   /usr/ports/Mk/bsd.gnome.mk has been modified. Even so, it will be
   very much faster than building the INDEX-N file from scratch each
   time you update your ports.

BUGS

   Please report any bugs to me, Matthew Seaman
   (m.seaman@infracaninophile.co.uk) with as much detail as
   possible so I can try and reproduce them. Please try and include:

       FreeBSD version -- uname -a output.
       Perl version -- perl -V output.
       Transcript of session showing how the problem occurs.

   As well as anything else you think is relevant.

COPYRIGHT AND LICENCE

Copyright (C) 2004-2012 by Matthew Seaman

This library is free software; you can redistribute it and/or modify
it under the following 2-clause BSD style license:

# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
#
#    1.  Redistributions of source code must retain the above
#        copyright notice, this list of conditions and the following
#        disclaimer.
#
#    2.  Redistributions in binary form must reproduce the above
#        copyright notice, this list of conditions and the following
#        disclaimer in the documentation and/or other materials
#        provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR
# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
# USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
# OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
# SUCH DAMAGE.

