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 37To enable the optional MTPZ support using libgcrypt you need the 38libgcrypt library installed as well. 39 40 41Shared Library Support 42---------------------- 43 44Shared library linking is supported. You will need to 'make install' 45the library before you can execute the sample binaries, and add the 46libmtp install directory to your shared library search path. 47 48On Linux, you would add the line "/usr/local/lib" to your 49"/etc/ld.so.conf" or as a oneliner in for example a 50"/etc/ld.so.conf.d/local.conf" file and run the 51program "ldconfig" to scan in the shared libraries at 52the new path. This is a part of the Linux shared library 53loader actually. 54 55To access the library from real odd locations you can use 56the LD_LIBRARY_PATH environment variable by setting it before 57you run your program, for example: 58 59 % export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib 60 % my_program 61 62To check whether you need to do something this: 63 64 % ldd /usr/lib/rhytmbox/plugins/mtpdevice/libmtpdevice.so | grep mtp 65 % ldd /usr/bin/gnomad2 | grep mtp 66 67If the program is linking to a packaged version of libmtp 68it will likely say something like this: 69 70 libmtp.so.N => /usr/lib/libmtp.so.N (0xb4e4b000) 71 72In this case you may have your freshly compiled library in 73/usr/local/lib or something like that, and you need to do the 74LD_LIBRARY_PATH trick. Verify by using "ldd" again. 75 76This way of enabling the library to link is a workaround hack. 77Note that the LD_LIBRARY_PATH is actually supposed to be used for 78testing, not production systems or distributions. It is commonly 79used as a workaround when a user is installing libraries in her/his 80home directory however. Read more about this environment variable 81here: http://www.visi.com/~barr/ldpath.html 82 83The shared library comes with different interface version numbers, 84for example libmtp.so.4, libmtp.so.5 and so forth. This is used so 85that both old and new libmtp libraries shall be able to coexist on 86the same system. When you compile your programs they will typically 87bind to the latest version of the shared library. A link to the 88latest version is always provided as $PREFIX/lib/libmtp.so. 89 90libusb support 91-------------- 92 93This package depends on libusb. Get libusb from sourceforge at: 94 95 http://www.sourceforge.net/projects/libusb/ 96 97libusb 1.0 and later is preferred for libmtp, but currently also 98older 0.1.x versions of libusb are supported. 99 100 101libgcrypt support 102----------------- 103 104The MTPZ extension to libmtp requires libgcrypt to be installed. 105 106 http://www.gnu.org/software/libgcrypt/ 107 108MTPZ support will not be built unless the configure script finds 109libgcrypt. 110 111 112BASIC BUILD PROCEDURE 113===================== 114 115To build the package: 116 117 % ./configure 118 % make 119 % make install 120 121By default, libmtp will add the program-prefix "mtp-" to all the 122example programs prior to installation. The program-prefix option 123makes libmtp sample programs avoid collision with other programs like 124sox' "play" program. If the default prefix for some reason fail, 125try to tag on "--program-prefix=mtp-" to the "configure" command. 126 127The "libexedir" in the configure file is hardcoded to /lib/udev to 128make the mtp-probe (which is built for Linux only) install into 129that directory. This is the only location that makes sens for this 130executable. 131 132if you want to install the documentation type: 133 134 % make install-docs 135 136if you checked out the sources from CVS, you must first run the 137autogen.sh script that generates all the GNU autotools files. 138Notice that this requires GNU autoconf, automake and libtool and 139possibly some other packages like gettext, readline, intltool and 140other M4 macro sources. This is done with: 141 142 % ./autogen.sh 143 144 145Linux hotplugging 146----------------- 147 148After compilation and installation you may (and should) add hotplugging 149support by running the hotplug script, if your distribution supports 150hotplugging (all do). This typically means you have something 151in /etc/hotplug and that hotplugging is started when you boot your 152machine in a script named /etc/init.d/hotplug or similar. 153 154Activate hotplugging by running: 155 156 %./hotplug.sh 157 158Hotplug will (typically) use the device map file installed by hotplug.sh 159at /etc/hotplug/usb/libmtp.usermap to lift the device to userspace for the 160current user by running the script /etc/hotplug/usb/libmtp.sh. If 161you have the program "resmgr" installed (currently used only by SuSE to 162our knowledge) that program will be used for enabling desktop user 163access, otherwise the current user of the desktop will be determined 164from files in /var/run. (See the script "libmtp.sh" for details.) 165 166 167Linux udev hotplugging 168---------------------- 169 170Newer Linux distributions have dropped support for the old hotplug system 171and rely solely on udev, and rules stored below /etc/udev/rules.d to 172handle permissions and actions on device connections. It's quite solid 173but the whole thing is rather shaky when it comes to such things as 174custom devices handled solely by libusb, which is what libmtp and for 175example SANE backends use. 176 177The libmtp.rules file that comes with libmtp can be used as a starter. 178 179This will set the environment variables ID_MEDIA_PLAYER and 180ID_MTP_DEVICE to "1" and the former one will be recognized by the 181scripts distributed by recent versions of udev to be a 182console-writable device that should be accessible for all 183users. 184 185Ancient udev, HAL, libusb 186------------------------- 187 188The old script for udev used to set the device access to "666" 189which is rather nasty (not that big security issue, unless you 190think someone will break into your jukebox) some systems used 191to let PAM do this by placing a configuration file in 192/etc/security/ somewhere. Then it was replaced with simple 193udev rules. 194 195At one point HAL was used to take devices detected by udev and 196signal to userspace that they were available and provide some 197information about them. This was unnecessary middleware, it has 198been killed and most userspace applications now get their 199information directly from udev instead. 200 201In old libusb first you need a crazy rule that creates a device 202node in the /dev/bus/usb hierarchy whenever any USB device is 203connected. The script has this at the top, you can comment it 204in if your distribution does not already create these device 205nodes. 206 207Then libusb may need to be patched to recognize this hierarchy. 208The 0.1.12 version is the first which is properly fixed. 209 210 211 212If you cannot run hotplugging 213----------------------------- 214 215If you have a distro without hotplugging enabled try this as root: 216 217 % chmod -R a+w /dev/bus/usb 218 219Or if it's *really* ancient you could try: 220 221 % chmod -R a+w /proc/bus/usb 222 223You have to do this again every time you unplug/replug your USB cable 224or restart the jukebox, every time you quit libnjb and restart it, 225etc etc etc an alternative is to run libmtp as root which works just fine. 226The problem is to somehow assure that you (ie the current user) always 227has write access to these files. 228 229You can find the Linux hotplug project at: 230http://linux-hotplug.sourceforge.net/ 231 232 233Compilation for embedded devices 234-------------------------------- 235 236Problems with Autoconf complaining about a missing malloc() function 237during cross-compilation can be solved with this hack if you're using 238glibc: 239 240 % export ac_cv_func_malloc_0_nonnull=yes 241 % ./configure 242 243If you're using uclibc you may have to smack in a custom rpl_malloc() 244function in your program, see the Autoconf texinfo documentation. 245 246See further: 247http://wiki.buici.com/wiki/Autoconf_and_RPL_MALLOC 248 249Compilation for Solaris/SunOS 250----------------------------- 251 252libmtp builds on Solaris/SunOS with either gcc or SunStudio 12. It does 253require GNU Make (aka gmake) to be installed. Building libmtp on Solaris 25410 and Solaris 11 differ slightly, so alternate instructions are provided 255for each Solaris version. 256 257For Solaris 10 258-------------- 259 260To build using GCC: 261 262 % CFLAGS="I/usr/sfw/lib -L/usr/sfw/lib -R/usr/sfw/lib" MAKE=gmake \ 263 INSTALL=/usr/ucb/install ./configure 264 % gmake 265 % gmake install 266 267Custom CLFAGS are required for libusb.so as it lives in /usr/sfw/lib, 268and this path is not in the default search path for ld. If these 269CFLAGS are not set, several components of ./configure will fail leading 270to a failed build. 271 272To build using SunStudio 12: 273 274 % CFLAGS="I/usr/sfw/lib -L/usr/sfw/lib -R/usr/sfw/lib" MAKE=gmake \ 275 INSTALL=/usr/ucb/install CC=cc ./configure 276 % gmake 277 % gmake install 278 279 280General Notes: 281All MTP devices on Solaris 10u2+ are driven by the usb_mid driver, which 282will automatically export ugen device interfaces with the correct device 283permissions. No special configuration is required. See the usb_mid(7D) 284and ugen(7D) manpages and /usr/sfw/share/doc/libusb/libusb.txt for 285more information. 286 287For Solaris 11 288-------------- 289 290Building libmtp on Solaris 11 is very similar to those instructions for 291Solaris 10, however libusb now lives in /usr/lib, and openusb is also 292available as an alternative USB library. Oracle does not provide a 293libusb v1.0 API compatible version of libusb, instead providing the older 294v0.1 API interface version of libusb. As mentioned, Oracle also provides 295the OpenUSB USB library as an alternate to libusb v1.0, however OpenUSB is 296not source or binary compatible with libusb. 297 298Before building/installing libmtp there are some components missing from 299the base Solaris 11 installation, and are required to be installed prior 300to building/installing libmtp. The 'libusbugen' package must be installed 301before libusb itself is usable on Solaris 11, alternatively the 'openusb' 302package may be used. 303 304To build using GCC: 305 % ./configure 306 % gmake 307 % sudo gmake install 308 309To build using SunStudio 12: 310 % CC=cc ./configure 311 % gmake 312 % sudo gmake install 313 314 315General Notes: 316All MTP devices on Solaris 11+ are driven by the usb_mid driver, which 317will automatically export ugen device interfaces with the correct device 318permissions. No special configuration is required. See the usb_mid(7D) 319and ugen(7D) manpages and /usr/share/doc/libusb/libusb.txt for more 320information. 321