TITLE		install-log
LFS VERSION:	4.0 and newer
AUTHOR:		Andy Goth <unununium@openverse.com>

SYNOPSIS:
	How to manage packages with install-log

HINT:
Version 1.0: 2001-12-17: First release.
Version 1.1: 2002-08-13: Corrections and updates for recent lfs books.
Version 1.2: 2002-10-20: Updates regarding new developments in install-log.

The latest version of this file should be at:

http://ioioio.net/devel/install-log/install-log/LFS-HINT

And it should be mirrored at:

http://hints.linuxfromscratch.org/hints/install-log.txt

This hint covers install-log, a simple package management tool.  It discusses
how to set up install-log, how to use it to make installation logs, and how to
use those logs for package management.  It also discusses how to use
install-log during all stages of lfs installation.

This version of the hint discusses install-log 1.9, and the general ideas
should apply to any version of lfs.  In fact, much of it isn't even lfs-
specific but useful for any UNIX system that doesn't already have suitable
package management.

+-----------------------------+
  1. INSTALL-LOG INSTALLATION
+-----------------------------+

First, get install-log at one of the following mirrors:

http://prdownloads.sourceforge.net/install-log/install-log-1.9.tar.bz2
http://install-log.sourceforge.net/release/install-log-1.9.tar.bz2
http://ioioio.net/devel/install-log/install-log-1.9.tar.bz2
http://www.pengaru.com/~andy/packages/install-log-1.9.tar.bz2

The tarball is 10k in size, just like this hint. ;^)

Or, you can get the very latest code using one of the following:

http://ioioio.net/devel/install-log/install-log-cvs.tar.bz2
$ cvs -d:pserver:anonymous@ioioio.net:/var/lib/cvs/install-log co install-log
http://users.openverse.com/cgi-bin/viewcvs/install-log/install-log/

Then unpack, compile, and install:

make &&
cp install-log /usr/bin &&
cp install-log.1 /usr/share/man/man1 &&
cp install-log.rc /etc &&
mkdir /var/install-logs &&
touch /var/install-logs/.timestamp

And we're golden.  Note that the 1.9 makefile has no "install" target.  Also it
produces a couple scary-looking error messages the first time you compile.
Ignore them.

You can test install-log out right away by using this variant of the above:

make &&
cp install-log /usr/bin &&
cp install-log.1 /usr/share/man/man1 &&
cp install-log.rc /etc &&
mkdir /var/install-logs &&
touch -r . /var/install-logs/.timestamp && 
install-log install-log -E cat -e

Instead of merely creating the .timestamp file, this sets its, err, timestamp
to equal that of the install-log-1.9 source tree, which should be older than
the just-installed install-log program but newer than everything else on the
system.  It then runs install-log to take note of its own installation.  Wow.
It also cats the log to verify its contents, which should be:

/usr/bin/install-log
/usr/share/man/man1/install-log.1

This is as you'd expect, except that install-log.rc doesn't show up.  This is
because, by default, install-log doesn't scan the /etc directory.

I fixed the silly makefile problem (no install target) in versions beyond the
(ancient) 1.9, so you can skip all the above and instead type make install.  It
should even do all the compilation and then make /var/install-logs/install-log!

I recommend editing your install-log.rc right away and shaping it to match your
site.  For instance, if you don't use /usr/local, remove it from the file.
Add /usr/etc and /usr/var to EXCLUDE (install-log is not meant to track
configuration and state files, only binaries and support files that don't get
touched beyond the initial installation).  I strongly recommend that you add
/usr/share/info/dir to the EXCLUDE list; otherwise, /usr/share/info/dir will
appear to belong to every package that has an info page.

Some of the above changes are already incorporated into the install-log.rc and
the compiled-in install-log defaults in versions newer than 1.9.

+---------------------------+
  2. INSTALLING OTHER STUFF
+---------------------------+

This part is easy.  Just install said stuff like normal, and then run
install-log, thusly:

tar xjvf msword.tar.bz2 && cd msword && make install && cd .. && rm -rf msword
install-log msword

There you go.  Now, /var/install-logs/msword contains a list of every file
added or modified by the installation of msword.  Go ahead and cat it, vim it,
or whatever.

And now that you're familiar with install-log, let's put it to good use:

+--------------------+
  3. INSTALLING LFS
+--------------------+

install-log descends from a little script Gerard Beekmans suggested long ago,
so its no surprise that it's specially designed for lfs.  It can track your
installation through every phase in the book.  But first, have install-log
ready on your system.

This part of the hint used to be much more complicated, but since the lfs book
started using a /static directory, things became far simpler.

---------
Chapter 5
---------

Don't worry about tracking your files during chapter 5--the /static directory
is an unruly place, and you will either remove it soon, forget all about it, or
keep it for emergencies.  Chapter 6, though, is where tracking first comes into
play, but install-log needs to be available ahead of time.

At the end of chapter 5, install install-log itself to ${LFS}/static:

make CFLAGS="${CFLAGS} -static" &&
cp install-log ${LFS}/static/bin &&
([ -d ${LFS}/etc ] || mkdir ${LFS}/etc) &&
cp install-log.rc ${LFS}/etc &&
([ -d ${LFS}/var ] || mkdir ${LFS}/var) &&
mkdir ${LFS}/var/install-logs &&
touch ${LFS}/var/install-logs/.timestamp

Take this opportunity to edit /etc/install-log.rc.

---------
Chapter 6
---------

In chapter 6 (inside the chroot), after each installation, call install-log:

install-log bash
install-log ncurses
install-log glibc
etc.

If you for some reason skipped installing install-log in chapter 5, you can run
install-log outside of the chroot but with the LFS variable set.  install-log
will pretend to be inside a chroot based at ${LFS}--it'll even use
${LFS}/etc/install-log.rc for configuration.

Eventually, install install-log according to the instructions given in section
1 above.  Skip the installation of the install-log.rc and .timestamp files, as
they have already been created.

+-----------------------+
  4. UNINSTALLING STUFF
+-----------------------+

xargs rm < /var/install-logs/packagename &&
rm /var/install-logs/packagename

;^)

+--------------------+
  5. UPGRADING STUFF
+--------------------+

install-log can handle installing a package more than once.  Do everything like
you would normally do, except supply the -f flag to install-log:

tar xjvf msword.tar.bz2 && cd msword && make install && cd .. && rm -rf msword
install-log -f msword

If you've already logged a package, install-log won't run on it again without
the -f flag.  When install-log does run, it will scan your filesystem, as
normal, but it will also compare its results with the previous results.  Every
file in the old list that didn't turn up new in the new list is either marked
"# Old #" or "# Del #".

Old files are probably safe to delete, because when you reinstalled the package
it didn't touch them.  Del files are already gone, so just shave them out of
the log using sed or another text editor.  They're there to alert you of a
possible problem.

Note that state files, configuration files, and other files that change
throughout the life of the program should never have been logged, and therefore
you will have to keep track of them on your own (does msword need ~/.mswordrc
anymore, or does it now use a win95 registry stored on a file mounted -tvfat
-oloop?).

+------------+
  6. CAVEATS
+------------+

install-log is a very simple and naive utility designed for little more than
creating lists of new and modified files.  As such, it can't handle things that
continually change, like configuration files.  It also can't handle files
shared between packages, like /usr/share/info/dir or a BSD-style init file.  It
can't handle packages that install files with any timestamp other than "right
now".  Sometimes you need to tweak its output a little bit, by touching the
installed files, aging /var/install-logs/.timestamp, and/or editing the
resultant log.  And you had better be sure of your dependencies before you
xargs rm something.

But nine times out of eight, it works.

+-----------------+
  7. FUTURE PLANS
+-----------------+

These won't get implemented unless I run out of other projects or people
express interest and contribute their time.  But I'd like to make a 2.0 release
including a greatly expanded /var/install-logs directory, giving an actual
history of installations and removals, md5 sums, dependencies, installation,
upgrade, and uninstallation scripts, download urls, package information, and
about everything else you'd expect in a full-blown package tool.  It'll also
have builtin functions for installation, upgrading, uninstallation, querying,
verifying, and downloading updates.  You'll be able to ask it to check the
files on disk against the md5 sums and issue warnings on discrepancies.  You'll
be able to ask it to get the latest of something and, assuming that it (or you)
can find where to download or how to install, it'll... install.  I think this
thing has potential, but I also think it has a lazy maintainer. ;^)

I have also been toying with the notion of merging in some ides from the
Matthias S. Benkmann's more_control_and_pkg_man.txt hint.  I previously melted
down everything in the hint and poured it into an all-in-one shell script.
Maybe I'll merge that with install-log when I do the above.  Other ideas
include taking advantage of the alfs project and setting up an online database
of scripts and stuff for install-log to make use of.
