INSTALL

   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.