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