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. Dependencies ------------ To build libmtp you should only need development files for libusb. (Often named libusb-devel or similar.) For working with CVS versions you may need autoconf, automake, libtool, gettext(-devel). 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 and possibly some other packages like gettext, readline, intltool and other M4 macro sources. 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