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 % make % make install By default, libnjb will add the program-prefix "njb-" to all the example programs prior to installation. The program-prefix option makes libnjb sample programs avoid collision with other programs like sox' "play" program. 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. libnjb desperately needs to be in the "ports" tree for FreeBSD, can someone please get it in there? 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 libnjb5" to install libnjb if you are using Debian 3.1. The figure after the library may change: libnjb0, libnjb1 ... libnjb5 are the current versions. You can see if there are newer versions like libnjb6 available. (For your information, this figure is the same as the API revision number.) If you want to develop using libnjb you also need to install the package libnjb-dev (or similar number) and perhaps libnjb-doc which contains documentation. The -dev and -doc versions always target the latest version of libnjb. * Gentoo Linux has libnjb in their "portage" tree, just type "emerge libnjb" to install libnjb. See: http://gentoo-portage.com/media-libs/libnjb * Fedora Core packages (formerly Red Hat Linux) is available through the Fedora Extras project, which is essetially a repository of add-on packages to Fedora Core. Since Fedora Core 4 this repository is enabled by default. On Fedora libnjb consists of three sub-packages, all of which may be installed by issuing: yum install libnjb libnjb-devel libnjb-examples 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. * Mandrake Linux packages libnjb by default and it is readily available in the base distribution. * SuSE Linux has traditionally been something of a troublesome issue, but Packman (http://packman.links2linux.de/, packager Herbert Graeber) now has packages for SuSE. Like with Fedora it consists of three subpackages: libnjb, libnjb-devel and libnjb-examples. Hotplugging needs a tweak to work on SuSE, alteast from SuSE version 10.0 the following comes from Mariano Stokle: * Go to /etc/fstab and change the usbfs line - change noauto for devmode=0666. * Then go to /etc/udev/rules.d/50-udev.rules, go to almost the final line and find the comment # libusb device access (mount usbfs or usbdev nodes) and in the next line change RUN+="/bin/mount -t usbfs usbfs /proc/bus/usb" for RUN+="/bin/mount -a -t usbfs" * Linspire has libnjb installed by default. Duane Maxwell wrote a python wrapper for libnjb and that is what Linspire Lsongs uses. For sources see: http://software.linspire.com/pool-src/libn/libnjb/ 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.) Linux udev hotplugging ---------------------- Newer Linux distributions have dropped support for the old hotplug system and rely solely on udev, and rules stored below /etc/udev/rules.d to handle permissions and actions on device connections. It's quite solid but the whole thing is rather shaky when it comes to such things as custom devices handled solely by libusb, which is what libnjb and for example SANE backends use. The nomad.rules file that comes with libnjb can be used as a starter. First you need a crazy rule that creates a device node in the /dev/bus/usb hierarchy whenever any USB device is connected. The script has this at the top, you can comment it in if your distribution does not already create these device nodes. Then libusb need to be patched to recognize this hierarchy. The 0.1.12 version is the first which is properly fixed. The script sets the device access to "666" which is rather nasty (not that big security issue, unless you think someone will break into your jukebox) some systems prefer to let PAM do this by placing a configuration file in /etc/security/ somewhere. See the Fedora Extras SRPM source package in case you're interested in how it is handled there. 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/