1INSTALLATION OVERVIEW 2===================== 3 4Once libmtp is built and installed, you will have the following files 5($PREFIX is the --prefix option given to the "configure" script and 6defaults to /usr/local/): 7 8 $PREFIX/lib/libmtp.a Static C library 9 $PREFIX/lib/libmtp.so.x.y.z Dynamic C library 10 $PREFIX/lib/libmtp.so.x A link to the library 11 $PREFIX/lib/libmtp.so A link to the library 12 $PREFIX/include/libmtp.h C header file for libmtp API 13 $PREFIX/lib/pkgconfig/libmtp.pc pkg-config configuration file 14 15Sample programs will be built in the "example" directory, and should 16help you get used to using the libmtp API, as well as provide some 17immediate gratification. Links to other programs using the libmtp 18API may be found at the homepage: http://libmtp.sourceforge.net/ 19 20 21Install From Distribution 22------------------------- 23 24You should probably prefer to install libmtp from the distribution 25source you're using. Last time we checked, libmtp was part of Ubuntu, 26Fedora, OpenSUSE, Debian testing, Gentoo, FreeBSD ports and OpenBSD 27packages/ports. 28 29 30Dependencies 31------------ 32 33To build libmtp you should only need development files for libusb. 34(Often named libusb-devel or similar.) For working with CVS versions 35you may need autoconf, automake, libtool, gettext(-devel). 36 37 38Shared Library Support 39---------------------- 40 41Shared library linking is supported. You will need to 'make install' 42the library before you can execute the sample binaries, and add the 43libmtp install directory to your shared library search path. 44 45On Linux, you would add the line "/usr/local/lib" to your 46"/etc/ld.so.conf" or as a oneliner in for example a 47"/etc/ld.so.conf.d/local.conf" file and run the 48program "ldconfig" to scan in the shared libraries at 49the new path. This is a part of the Linux shared library 50loader actually. 51 52To access the library from real odd locations you can use 53the LD_LIBRARY_PATH environment variable by setting it before 54you run your program, for example: 55 56 % export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib 57 % my_program 58 59This way of enabling the library to link is a workaround hack. 60Note that the LD_LIBRARY_PATH is actually supposed to be used for 61testing, not production systems or distributions. It is commonly 62used as a workaround when a user is installing libraries in her/his 63home directory however. Read more about this environment variable 64here: http://www.visi.com/~barr/ldpath.html 65 66The shared library comes with different interface version numbers, 67for example libmtp.so.4, libmtp.so.5 and so forth. This is used so 68that both old and new libmtp libraries shall be able to coexist on 69the same system. When you compile your programs they will typically 70bind to the latest version of the shared library. A link to the 71latest version is always provided as $PREFIX/lib/libmtp.so. 72 73libusb Support 74-------------- 75 76This package depends on libusb. Get libusb from sourceforge at: 77 78 http://www.sourceforge.net/projects/libusb/ 79 80On Linux, please use the very latest version you can get, between 810.1.8 and 0.1.12 a lot of things happened which pertains to 82the udev hotplugging support, see below. 83 84 85BASIC BUILD PROCEDURE 86===================== 87 88To build the package: 89 90 % ./configure 91 % make 92 % make install 93 94By default, libmtp will add the program-prefix "mtp-" to all the 95example programs prior to installation. The program-prefix option 96makes libmtp sample programs avoid collision with other programs like 97sox' "play" program. If the default prefix for some reason fail, 98try to tag on "--program-prefix=mtp-" to the "configure" command. 99 100On Linux you should then typically type (see below for details): 101 102 % ./hotplug.sh 103 104you can achieve the same with 105 106 % ./configure --enable-hotplugging 107 108you can turn off some speed enhancements (for testing) with: 109 110 % ./configure --no-turbo 111 112if you want to install the documentation type: 113 114 % make install-docs 115 116if you checked out the sources from CVS, you must first run the 117autogen.sh script that generates all the GNU autotools files. 118Notice that this requires GNU autoconf, automake and libtool and 119possibly some other packages like gettext, readline, intltool and 120other M4 macro sources. This is done with: 121 122 % ./autogen.sh 123 124 125Linux hotplugging 126----------------- 127 128After compilation and installation you may (and should) add hotplugging 129support by running the hotplug script, if your distribution supports 130hotplugging (all do). This typically means you have something 131in /etc/hotplug and that hotplugging is started when you boot your 132machine in a script named /etc/init.d/hotplug or similar. 133 134Activate hotplugging by running: 135 136 %./hotplug.sh 137 138Hotplug will (typically) use the device map file installed by hotplug.sh 139at /etc/hotplug/usb/libmtp.usermap to lift the device to userspace for the 140current user by running the script /etc/hotplug/usb/libmtp.sh. If 141you have the program "resmgr" installed (currently used only by SuSE to 142our knowledge) that program will be used for enabling desktop user 143access, otherwise the current user of the desktop will be determined 144from files in /var/run. (See the script "libmtp.sh" for details.) 145 146 147Linux udev hotplugging 148---------------------- 149 150Newer Linux distributions have dropped support for the old hotplug system 151and rely solely on udev, and rules stored below /etc/udev/rules.d to 152handle permissions and actions on device connections. It's quite solid 153but the whole thing is rather shaky when it comes to such things as 154custom devices handled solely by libusb, which is what libmtp and for 155example SANE backends use. 156 157The libmtp.rules file that comes with libmtp can be used as a starter. 158 159First you need a crazy rule that creates a device node in the 160/dev/bus/usb hierarchy whenever any USB device is connected. The 161script has this at the top, you can comment it in if your 162distribution does not already create these device nodes. 163 164Then libusb may need to be patched to recognize this hierarchy. 165The 0.1.12 version is the first which is properly fixed. 166 167The script sets the device access to "666" which is rather nasty 168(not that big security issue, unless you think someone will break 169into your jukebox) some systems prefer to let PAM do this by placing 170a configuration file in /etc/security/ somewhere. See the Fedora Extras 171SRPM source package in case you're interested in how it is handled 172there. 173 174 175If you cannot run hotplugging 176----------------------------- 177 178If you have a distro without hotplugging enabled try this as root: 179 180 % chmod -R a+w /proc/bus/usb 181 182You have to do this again every time you unplug/replug your USB cable 183or restart the jukebox, every time you quit libnjb and restart it, 184etc etc etc an alternative is to run libmtp as root which works just fine. 185The problem is to somehow assure that you (ie the current user) always 186has write access on /proc/bus/usb/* 187 188You can find the Linux hotplug project at: 189http://linux-hotplug.sourceforge.net/ 190 191 192Compilation for embedded devices 193-------------------------------- 194 195Problems with Autoconf complaining about a missing malloc() function 196during cross-compilation can be solved with this hack if you're using 197glibc: 198 199 % export ac_cv_func_malloc_0_nonnull=yes 200 % ./configure 201 202If you're using uclibc you may have to smack in a custom rpl_malloc() 203function in your program, see the Autoconf texinfo documentation. 204 205See further: 206http://wiki.buici.com/wiki/Autoconf_and_RPL_MALLOC