
		NOID COMMAND SCRIPT INSTALLATION INSTRUCTIONS


NOID OVERVIEW

The noid utility creates minters (identifier generators) and accepts
commands that operate them.  Once created, a minter can be used to produce
persistent, globally unique names for documents, databases, images,
vocabulary terms, etc.  Properly managed, these identifiers can be used as
long term durable information object references within naming schemes such
as ARK, PURL, URN, DOI, and LSID.  At the same time, alternative minters
can be set up to produce short-lived names for transaction identifiers,
compact web server session keys, and other ephemera.

In general, a noid minter efficiently generates, tracks, and binds
unique identifiers, which are produced without replacement in random or
sequential order, and with or without a check character that can be used
for detecting transcription errors.  A minter can bind identifiers to
arbitrary element names and element values that are either stored or
produced upon retrieval from rule-based transformations of requested
identifiers; the latter has application in identifier resolution.  Noid
minters are very fast, scalable, easy to create and tear down, and have a
relatively small footprint.  They use BerkeleyDB as the underlying database.

Identifiers generated by a noid minter are also known as "noids" (nice
opaque identifiers -- rhymes with void).  While a minter can record and
bind any identifiers that you bring to its attention, often it is used
to generate, bringing to your attention, identifier strings that carry
no widely recognizable meaning.  This semantic opaqueness reduces their
vulnerability to era- and language-specific change, and helps persistence
by making for identifiers that can age and travel well.


INSTALLATION -- SIMPLE

This simple installation section assumes that the noid pre-requisites
are already installed at a default system location.  The final step of
the simple installation (make install) usually requires system privleges.

If not already unpacked, unpack the Noid suite with

   tar xzf Noid-0.424.tar.gz

after adjusting the version number as needed.  Version 0.422 is known to
pass build tests on Linux (SuSE 9.0, RH 9, RH 7), SunOS 5.8, Mac OS X,
and NetBSD 1.6.2.

To install the module and script, type the following:

   perl Makefile.PL
   make
   make test
   make install

For the "make install" you may have to become the superuser, as in,

   sudo make install

If installing in a non-standard place, such as your home directory,
change the first of the above 4 lines to "perl Makefile.PL PREFIX=~".


INSTALLATION -- ADVANCED (UNIX)

You may need this advanced installation section if the noid pre-requisites
are not already installed, or if you are installing and relying on things
in non-default system locations.  The final step for installing the Perl
modules (make install) would require system privleges, as in,

   sudo make install
   
if it meant copying files into areas normally not writable by you.

Noid requires the Perl module, BerkeleyDB.pm, which in turn relies on
the Berkeley DB system library, libdb.  For completeness this section
assumes that you are installing everything from the ground up.  In this
case you'd install the library first, available from www.sleepycat.com ,
followed by the BerkeleyDB Perl module.  If you fetch the latest release
(at least as of April 2006), a Perl module suitable for the next step is
conveniently located in in the "perl/" subdirectory; it is also available
from www.cpan.org (CPAN).  To summarize, the prerequisites are

   db-N.N.NN.tar.gz		from www.sleepycat.com
   BerkeleyDB-0.NN.tar.gz	from the above tarball or from CPAN

where the N's represent the release numbers that you will be using.

Each of these packages has its own installation instructions, which you
should have handy as you go through this example of installing everything
in one non-standard location, /home/jak/genid .  For concreteness, some
particular locations and Perl releases that work under one version of
Linux will be used.

In general, you'll need to change the examples to work in your environment.
To discover how to change the examples you'll likely have to poke around
in the directory trees rooted in your chosen locations to find out exactly
where the things will have been installed.

To install the system library, libdb, first fetch and unpack (tar xzf)
db-N.N.NN.tar.gz from www.sleepycat.com .  Then in db-N.N.NN/,

   cd build_unix
   ../dist/configure --prefix=/home/jak/genid/usr/local/BerkeleyDB.4.4
   make
   make install

which builds using the --prefix configuration parameter so that the
resulting library will be installed in your non-standard location.

Before installing the Perl module, BerkeleyDB.pm, you may first need to
move instances of the library and Perl module out of the way, if any
exist.  This may require system privileges, for example, under Mac OS X,

   cd /System/Library/Perl/Extras/5.8.6/darwin-thread-multi-2level/
   sudo mv BerkeleyDB xBerkeleyDB
   sudo mv auto/BerkeleyDB auto/xBerkeleyDB

And don't forget to move an existing "include" file out of the way:

   cd /usr/include/
   sudo mv db.h xdb.h

After unpacking BerkeleyDB-0.NN.tar.gz, in BerkeleyDB-0.NN/ edit the
configuration file for your library installation; for example,

   vi config.in		# then change the INCLUDE and LIB settings:

	INCLUDE = /home/jak/genid/usr/local/BerkeleyDB.4.4/include
	LIB     = /home/jak/genid/usr/local/BerkeleyDB.4.4/lib

So that the system library will be found later at run time, do

   LD_LIBRARY_PATH=/home/jak/genid/usr/local/BerkeleyDB.4.4/lib
   export PERL5LIB

That sets up BerkeleyDB.pm's pre-requisites.  Now, to cause the BerkeleyDB
module that you are about to build to end up in your non-standard location,
begin the installation process with the correct PREFIX= argument, as in,

   perl Makefile.PL PREFIX=/home/jak/genid
   make
   make test
   make install

That finishes installing noid's pre-requisites.

To install the noid, which mostly means the Perl module, Noid.pm, and the
script, "noid", first set the PERL5LIB environment variable so that the
new Perl modules and system library will be found,

   PERL5LIB=/home/jak/genid/lib/perl/5.8.4:/home/jak/genid/share/perl/5.8.4
   export PERL5LIB

(Under Mac OS X, the value of PERL5LIB might include something like
/Users/jak/genid/lib/perl5/site_perl/5.8.6/darwin-thread-multi-2level .)

Assuming that you've unpacked Noid-0.NNN.tar.gz, go to the Noid-0.NNN/
directory and build Noid using the correct PREFIX= argument so that it
will be installed in your non-standard location, as in,

   perl Makefile.PL PREFIX=/home/jak/genid
   make
   make test
   make install

That should complete your installation.


DEPENDENCIES

This module requires these other modules:

	Noid
	BerkeleyDB
	Fcntl
	Config
	Getopt::Long
	Sys::Hostname
	Text::ParseWords

Also required is the C library, libdb (version greater that 2.7.7) for

	Berkeley DB     from     http://www.sleepycat.com/


COPYRIGHT AND LICENCE

Copyright 2002-2006 UC Regents.  BSD-type open source license.

Permission to use, copy, modify, distribute, and sell this software and
its documentation for any purpose is hereby granted without fee, provided
that (i) the above copyright notices and this permission notice appear in
all copies of the software and related documentation, and (ii) the names
of the UC Regents and the University of California are not used in any
advertising or publicity relating to the software without the specific,
prior written permission of the University of California.

THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, 
EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY 
WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  

IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE FOR ANY
SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY
THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE
OR PERFORMANCE OF THIS SOFTWARE.


ACKNOWLEDGEMENTS

Thanks to Brian Tingle, Kirk Hastings, Paul Fogel, and Stu Sugarman for
their feedback during development, and to Raymund Ramos, Michael Giarlo,
Charles Blair, and Archie Warnock for their testing help.

