Linus Walleij | 6c04caa | 2006-03-29 17:33:51 +0000 | [diff] [blame] | 1 | INSTALLATION OVERVIEW |
| 2 | ===================== |
| 3 | |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 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/): |
Linus Walleij | 6c04caa | 2006-03-29 17:33:51 +0000 | [diff] [blame] | 7 | |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 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 |
Linus Walleij | 6c04caa | 2006-03-29 17:33:51 +0000 | [diff] [blame] | 14 | |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 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/ |
Linus Walleij | 6c04caa | 2006-03-29 17:33:51 +0000 | [diff] [blame] | 19 | |
Linus Walleij | d463750 | 2009-06-14 23:03:33 +0000 | [diff] [blame] | 20 | |
Linus Walleij | b8ee925 | 2009-01-03 00:02:58 +0000 | [diff] [blame] | 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, |
Linus Walleij | d463750 | 2009-06-14 23:03:33 +0000 | [diff] [blame] | 26 | Fedora, OpenSUSE, Debian testing, Gentoo, FreeBSD ports and OpenBSD |
Linus Walleij | b8ee925 | 2009-01-03 00:02:58 +0000 | [diff] [blame] | 27 | packages/ports. |
| 28 | |
| 29 | |
Linus Walleij | d463750 | 2009-06-14 23:03:33 +0000 | [diff] [blame] | 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 | |
Linus Walleij | ff3d279 | 2012-02-18 21:45:15 +0100 | [diff] [blame] | 37 | To enable the optional MTPZ support using libgcrypt you need the |
| 38 | libgcrypt library installed as well. |
| 39 | |
Linus Walleij | d463750 | 2009-06-14 23:03:33 +0000 | [diff] [blame] | 40 | |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 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 |
Linus Walleij | d463750 | 2009-06-14 23:03:33 +0000 | [diff] [blame] | 51 | program "ldconfig" to scan in the shared libraries at |
| 52 | the new path. This is a part of the Linux shared library |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 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 | |
Linus Walleij | b2d4ff4 | 2012-07-17 14:43:31 +0200 | [diff] [blame] | 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 | |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 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 |
Linus Walleij | d463750 | 2009-06-14 23:03:33 +0000 | [diff] [blame] | 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 |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 88 | latest version is always provided as $PREFIX/lib/libmtp.so. |
| 89 | |
Linus Walleij | 1a86fff | 2012-09-17 20:47:39 +0200 | [diff] [blame^] | 90 | libusb support |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 91 | -------------- |
| 92 | |
Linus Walleij | 1a86fff | 2012-09-17 20:47:39 +0200 | [diff] [blame^] | 93 | This package depends on libusb. Get libusb from sourceforge at: |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 94 | |
| 95 | http://www.sourceforge.net/projects/libusb/ |
| 96 | |
Linus Walleij | 1a86fff | 2012-09-17 20:47:39 +0200 | [diff] [blame^] | 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. |
Linus Walleij | 63a9258 | 2006-06-03 20:36:35 +0000 | [diff] [blame] | 110 | |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 111 | |
| 112 | BASIC BUILD PROCEDURE |
| 113 | ===================== |
| 114 | |
| 115 | To build the package: |
| 116 | |
Linus Walleij | 925cd45 | 2010-12-05 21:26:48 +0000 | [diff] [blame] | 117 | % ./configure |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 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 |
Linus Walleij | 284aacb | 2007-08-11 21:17:36 +0000 | [diff] [blame] | 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 | |
Linus Walleij | 925cd45 | 2010-12-05 21:26:48 +0000 | [diff] [blame] | 127 | The "libexedir" in the configure file is hardcoded to /lib/udev to |
Linus Walleij | 1774a8e | 2010-12-05 20:01:53 +0000 | [diff] [blame] | 128 | make the mtp-probe (which is built for Linux only) install into |
Linus Walleij | 925cd45 | 2010-12-05 21:26:48 +0000 | [diff] [blame] | 129 | that directory. This is the only location that makes sens for this |
| 130 | executable. |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 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. |
Linus Walleij | 362d13e | 2009-08-02 19:59:21 +0000 | [diff] [blame] | 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: |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 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 | |
Linus Walleij | c4cd50b | 2011-01-08 22:50:07 +0000 | [diff] [blame] | 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. |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 184 | |
Linus Walleij | c4cd50b | 2011-01-08 22:50:07 +0000 | [diff] [blame] | 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. |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 208 | The 0.1.12 version is the first which is properly fixed. |
| 209 | |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 210 | |
| 211 | |
| 212 | If you cannot run hotplugging |
| 213 | ----------------------------- |
| 214 | |
| 215 | If you have a distro without hotplugging enabled try this as root: |
| 216 | |
Linus Walleij | 1a86fff | 2012-09-17 20:47:39 +0200 | [diff] [blame^] | 217 | % chmod -R a+w /dev/bus/usb |
| 218 | |
| 219 | Or if it's *really* ancient you could try: |
| 220 | |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 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 |
Linus Walleij | 1a86fff | 2012-09-17 20:47:39 +0200 | [diff] [blame^] | 227 | has write access to these files. |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 228 | |
| 229 | You can find the Linux hotplug project at: |
| 230 | http://linux-hotplug.sourceforge.net/ |
Linus Walleij | d3b7857 | 2007-08-24 21:28:24 +0000 | [diff] [blame] | 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: |
Linus Walleij | c868cbc | 2011-02-09 20:19:25 +0100 | [diff] [blame] | 247 | http://wiki.buici.com/wiki/Autoconf_and_RPL_MALLOC |
| 248 | |
| 249 | Compilation for Solaris/SunOS |
| 250 | ----------------------------- |
| 251 | |
Darran Kartaschew | 11082d3 | 2011-12-13 00:42:01 +0100 | [diff] [blame] | 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 | -------------- |
Linus Walleij | c868cbc | 2011-02-09 20:19:25 +0100 | [diff] [blame] | 259 | |
Darran | 90ec6e5 | 2011-02-13 17:53:20 +0100 | [diff] [blame] | 260 | To build using GCC: |
Darran Kartaschew | 11082d3 | 2011-12-13 00:42:01 +0100 | [diff] [blame] | 261 | |
Darran | 90ec6e5 | 2011-02-13 17:53:20 +0100 | [diff] [blame] | 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 |
Linus Walleij | c868cbc | 2011-02-09 20:19:25 +0100 | [diff] [blame] | 266 | |
Darran Kartaschew | 11082d3 | 2011-12-13 00:42:01 +0100 | [diff] [blame] | 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 |
Darran | 90ec6e5 | 2011-02-13 17:53:20 +0100 | [diff] [blame] | 270 | to a failed build. |
Linus Walleij | c868cbc | 2011-02-09 20:19:25 +0100 | [diff] [blame] | 271 | |
Darran | 90ec6e5 | 2011-02-13 17:53:20 +0100 | [diff] [blame] | 272 | To build using SunStudio 12: |
Linus Walleij | c868cbc | 2011-02-09 20:19:25 +0100 | [diff] [blame] | 273 | |
Darran | 90ec6e5 | 2011-02-13 17:53:20 +0100 | [diff] [blame] | 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 |
Linus Walleij | c868cbc | 2011-02-09 20:19:25 +0100 | [diff] [blame] | 278 | |
Linus Walleij | c868cbc | 2011-02-09 20:19:25 +0100 | [diff] [blame] | 279 | |
Darran | 90ec6e5 | 2011-02-13 17:53:20 +0100 | [diff] [blame] | 280 | General Notes: |
Darran Kartaschew | 11082d3 | 2011-12-13 00:42:01 +0100 | [diff] [blame] | 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 |
Darran | 90ec6e5 | 2011-02-13 17:53:20 +0100 | [diff] [blame] | 285 | more information. |
Darran Kartaschew | 11082d3 | 2011-12-13 00:42:01 +0100 | [diff] [blame] | 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. |