INSTALL

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

Once libmtp 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/libmtp.a               Static C library
   $PREFIX/lib/libmtp.so.x.y.z        Dynamic C library
   $PREFIX/lib/libmtp.so.x            A link to the library
   $PREFIX/lib/libmtp.so              A link to the library
   $PREFIX/include/libmtp.h           C header file for libmtp API
   $PREFIX/lib/pkgconfig/libmtp.pc    pkg-config configuration file

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

Install From Distribution
-------------------------

You should probably prefer to install libmtp from the distribution
source you're using. Last time we checked, libmtp was part of Ubuntu,
Fedora, OpenSUSE, Debian testing, Gentoo, FreeBSD ports and OpenBSD 
packages/ports.


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

Shared library linking is supported. You will need to 'make install'
the library before you can execute the sample binaries, and add the
libmtp install directory to your shared library search path.

On Linux, you would add the line "/usr/local/lib" to your
"/etc/ld.so.conf" or as a oneliner in for example a
"/etc/ld.so.conf.d/local.conf" file and run the
program "ldconfig" to scan in the shared libraries at 
the new path. This is a part of the Linux shared library 
loader actually.

To access the library from real odd locations you can use
the LD_LIBRARY_PATH environment variable by setting it before
you run your program, for example:

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

This way of enabling the library to link is a workaround hack.
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 libmtp.so.4, libmtp.so.5 and so forth. This is used so
that both old and new libmtp libraries shall be able to coexist on
the same system. When you compile your programs they will typically 
bind to the latest version of the shared library. A link to the 
latest version is always provided as $PREFIX/lib/libmtp.so.

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

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

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

On Linux, please use the very latest version you can get, between
0.1.8 and 0.1.12 a lot of things happened which pertains to
the udev hotplugging support, see below.


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

To build the package:

   % ./configure
   % make
   % make install

By default, libmtp will add the program-prefix "mtp-" to all the
example programs prior to installation. The program-prefix option
makes libmtp sample programs avoid collision with other programs like
sox' "play" program. If the default prefix for some reason fail,
try to tag on "--program-prefix=mtp-" to the "configure" command.

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


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

After compilation and installation you may (and should) add hotplugging
support by running the hotplug script, if your distribution supports
hotplugging (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/libmtp.usermap to lift the device to userspace for the
current user by running the script /etc/hotplug/usb/libmtp.sh. 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 "libmtp.sh" 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 libmtp and for
example SANE backends use.

The libmtp.rules file that comes with libmtp 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 may 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 libmtp 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/*

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


Compilation for embedded devices
--------------------------------

Problems with Autoconf complaining about a missing malloc() function
during cross-compilation can be solved with this hack if you're using
glibc:

  % export ac_cv_func_malloc_0_nonnull=yes
  % ./configure

If you're using uclibc you may have to smack in a custom rpl_malloc()
function in your program, see the Autoconf texinfo documentation.

See further:
http://wiki.buici.com/wiki/Autoconf_and_RPL_MALLOC