FreeBSD-Portindex
    =================

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

   The cache-update process usually detects any modified Makefiles
   within the ports tree, and from there deduces what ports may have
   been modified.  Alternatively it can take the output of various
   currently supported methods of updating the ports tree to achieve
   the same result.  Finally, it can just read a list of port
   directories -- including the list output by the 'portsnap update'
   command.

   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, formally at least

     perl-5.10.1 (lang/perl5.10)

   but an up-to-date and supported recent version is definitely
   recommended.

   Additionally you will need

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

   and one of the Berkeley Database Library ports such as
   
     db5-5.3.28_2 (databases/db5).

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 65MiB 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 updating the ports by whatever
   your favourite mechanism is, and then scanning the ports tree for
   modified Makefiles:

       # svn up
       % cache-update

   See the POD pages for cache-update and find-updated for other
   possibilities.  For instance, you can parse the output from
   portsnap like this:

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

   Repeat as necessary if you update your ports 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.  Now that I have
   move portindex onto GitHub, I will also be happy to receive pull
   requests or reports of issues through there.

COPYRIGHT AND LICENCE

Copyright (C) 2004-2015 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.