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