INSTALLATION OVERVIEW
=====================

Once libnjb is built and installed, you will have the following files
($PREFIX is the --prefix option given to the "configure" script and
defaults to /usr/local/):

   $PREFIX/lib/libnjb.a		      Static C library
   $PREFIX/lib/libnjb.so.x.0.0	      Dynamic C library
   $PREFIX/lib/libnjb.so.x            A link to the library
   $PREFIX/lib/libnjb.so              A link to the library
   $PREFIX/include/libnjb.h	      C header file for libnjb API
   $PREFIX/lib/pkgconfig/libnjb.pc    pkg-config configuration file

Sample programs will be built in the "sample" directory, and should
help you get used to using the libnjb API, as well as provide some
immediate gratification. Links to other programs using the libnjb
API may be found at the homepage: http://libnjb.sourceforge.net/


Shared Library Support
----------------------

Shared library linking is supported. You will need to 'make install' 
the library before you can execute the sample binaries, or add the 
libnjb src directory to your shared library search path (generally 
the LD_LIBRARY_PATH environment variable). For example:

  % export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib

On Linux, to make this change permanent, you would add the line
"/usr/local/lib" to your "/etc/ld.so.conf" file and run the 
program "ldconfig" to scan in the new path. This is a part of
the Linux shared library loader actually.

Note that the LD_LIBRARY_PATH is actually supposed to be used for
testing, not production systems or distributions. It is commonly
used as a workaround when a user is installing libraries in her/his
home directory however. Read more about this environment variable
here: http://www.visi.com/~barr/ldpath.html

The shared library comes with different interface version numbers,
for example libnjb.so.4, libnjb.so.5 and so forth. This is used so
that both old and new libnjb libraries shall be able to coexist on
the same system. For example Debian name their libnjb packages after
the library version number, "libnjb0", "libnjb1" etc. When you 
compile your programs they will typically bind to the latest version
of the shared library. The latest version is always named
$PREFIX/lib/libnjb.so.

If you're building a bundled application for a distribution (like
a DEB or RPM package) consider linking libnjb statically. It is
not that big.


libusb Support
--------------

This package depends on libusb.  Get libusb from sourceforge at:

   http://www.sourceforge.net/projects/libusb/

Releases of FreeBSD prior to about 4.7-RELEASE had a conflicting, native
library named libusb.a that is NOT the libusb required by this package.
libnjb is not supported on these older FreeBSD releaeses.


BASIC BUILD PROCEDURE
=====================

To build the package:

   % ./configure --program-prefix=njb-
   % make
   % make install

The program-prefix option makes libnjb sample programs avoid collision
with other programs if you install the package. On Linux you should 
then typically type (see below for details):

   % ./hotplug.sh

you can achieve the same with

   % ./configure --enable-hotplugging

you can turn off some speed enhancements (for testing) with:

   % ./configure --no-turbo

if you want to install the documentation type:

   % make install-docs

if you checked out the sources from CVS, you must first run the
autogen.sh script that generates all the GNU autotools files. 
Notice that this requires GNU autoconf, automake and libtool. This
is done with:

   % ./autogen.sh


BSD-SPECIFIC NOTES
==================

In recent versions of FreeBSD, the default shell for root has been 
changed from /bin/sh to /bin/csh. This may cause troubles. Then run:

   % ./configure
   % make SHELL=/bin/sh
   % make install SHELL=/bin/sh

Under FreeBSD, /usr/local is not included in the default search path for
include and library files when using the compiler from the ports 
collection.  You must set the CPPFLAGS and LDFLAGS environment variables
prior to running configure:

  % setenv SHELL=/bin/sh
  % setenv CPPFLAGS=-I/usr/local/include
  % setenv LDFLAGS=-L/usr/local/lib
  % ./configure
  % make
  % make install

If you build your compiler yourself, then this may not be necessary.  It
may also not be necessary on NetBSD or OpenBSD.  If the build fails because
it cannot locate the libusb header file, however, the above may be needed.

Additionally, the sample programs use GNU getopt, which is included with
systems that use the GNU C Library (such as Linux), so on BSD you may need
to install getopt in order to compiler and run the sample programs.

Some BSD:s have a problem with USB 2.0: the EHCI driver may need a patch
(e.g. /FreeBSD-CVS/src/sys/dev/usb/ehci.c). The latest versions of 
NetBSD have the problem fixed.


LINUX-SPECIFIC NOTES
====================

You need to have libusb installed on your system, and libusb requires that
you have the usbdevfs filesystem mounted.  If you don't know how to do this,
see http://www.linux-usb.org/FAQ.html#gs3

Distribution-specific notes
---------------------------

* Debian GNU/Linux has libnjb in the "testing" package tree, just type
  "apt-get install libnjb4" to install libnjb if you are using Debian
  Testing (or Debian 3.1 / Sarge whenever that is released.) The figure
  after the library may change: libnjb0, libnjb1 ... libnjb4 are the
  current versions. You can see if there are newer versions like
  libnjb5 available. (For your information, this figure is the same 
  as the API revision number.)

* Gentoo Linux has libnjb in their "portage" tree, just type "emerge libnjb"
  to install libnjb.

* Fedora Core packages (formerly Red Hat Linux) is available at the Gnomad2
  web page at: 
  http://sourceforge.net/project/showfiles.php?group_id=65573&package_id=71501

  Also, if you compile from source, note that libnjb installs into 
  /usr/local/lib which is not part of the default library search path
  in Fedora Core / Red Hat Linux. You will have to add /usr/local/lib
  to your /etc/ld.so.conf and run "ldconfig" (as root) for the library
  loader to find it.

Linux hotplugging
-----------------

After compilation and installation you may (and should) add hotplugging 
support by running the hotplug script, if your distribution supports
hotplugging (almost all do). This typically means you have something 
in /etc/hotplug and that hotplugging is started when you boot your 
machine in a script named /etc/init.d/hotplug or similar.

Activate hotplugging by running:

   %./hotplug.sh

Hotplug will (typically) use the device map file installed by hotplug.sh
at /etc/hotplug/usb/nomad.usermap to lift the device to userspace for the
current user by running the script /etc/hotplug/usb/nomadjukebox. If 
you have the program "resmgr" installed (currently used only by SuSE to 
our knowledge) that program will be used for enabling desktop user 
access, otherwise the current user of the desktop will be determined 
from files in /var/run. (See the script "nomadjukebox" for details.)

If you cannot run hotplugging
-----------------------------

If you have a distro without hotplugging enabled try this as root: 

  % chmod -R a+w /proc/bus/usb

You have to do this again every time you unplug/replug your USB cable 
or restart the jukebox, every time you quit libnjb and restart it, 
etc etc etc an alternative is to run libnjb as root which works just fine. 
The problem is to somehow assure that you (ie the current user) always 
has write access on  /proc/bus/usb/*

Other distributions hotplugging
-------------------------------

This is if you don't have hotplugging enabled and do not want to set it 
up on your machine either. You want to mount the usbfs manually.

     According to Tim Pepper, this should work in your 
     /etc/fstab:

     none  /proc/bus/usb  usbdevfs noauto,devmode=0666 0 0

You can find the Linux hotplug project at:
http://linux-hotplug.sourceforge.net/
