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 | |
| 37 | |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 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 |
Linus Walleij | d463750 | 2009-06-14 23:03:33 +0000 | [diff] [blame] | 48 | program "ldconfig" to scan in the shared libraries at |
| 49 | the new path. This is a part of the Linux shared library |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 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 |
Linus Walleij | d463750 | 2009-06-14 23:03:33 +0000 | [diff] [blame] | 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 |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 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 | |
Linus Walleij | 63a9258 | 2006-06-03 20:36:35 +0000 | [diff] [blame] | 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 | |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 84 | |
| 85 | BASIC BUILD PROCEDURE |
| 86 | ===================== |
| 87 | |
| 88 | To build the package: |
| 89 | |
Linus Walleij | 925cd45 | 2010-12-05 21:26:48 +0000 | [diff] [blame] | 90 | % ./configure |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 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 |
Linus Walleij | 284aacb | 2007-08-11 21:17:36 +0000 | [diff] [blame] | 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 | |
Linus Walleij | 925cd45 | 2010-12-05 21:26:48 +0000 | [diff] [blame] | 100 | The "libexedir" in the configure file is hardcoded to /lib/udev to |
Linus Walleij | 1774a8e | 2010-12-05 20:01:53 +0000 | [diff] [blame] | 101 | make the mtp-probe (which is built for Linux only) install into |
Linus Walleij | 925cd45 | 2010-12-05 21:26:48 +0000 | [diff] [blame] | 102 | that directory. This is the only location that makes sens for this |
| 103 | executable. |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 104 | |
| 105 | if you want to install the documentation type: |
| 106 | |
| 107 | % make install-docs |
| 108 | |
| 109 | if you checked out the sources from CVS, you must first run the |
| 110 | autogen.sh script that generates all the GNU autotools files. |
Linus Walleij | 362d13e | 2009-08-02 19:59:21 +0000 | [diff] [blame] | 111 | Notice that this requires GNU autoconf, automake and libtool and |
| 112 | possibly some other packages like gettext, readline, intltool and |
| 113 | other M4 macro sources. This is done with: |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 114 | |
| 115 | % ./autogen.sh |
| 116 | |
| 117 | |
| 118 | Linux hotplugging |
| 119 | ----------------- |
| 120 | |
| 121 | After compilation and installation you may (and should) add hotplugging |
| 122 | support by running the hotplug script, if your distribution supports |
| 123 | hotplugging (all do). This typically means you have something |
| 124 | in /etc/hotplug and that hotplugging is started when you boot your |
| 125 | machine in a script named /etc/init.d/hotplug or similar. |
| 126 | |
| 127 | Activate hotplugging by running: |
| 128 | |
| 129 | %./hotplug.sh |
| 130 | |
| 131 | Hotplug will (typically) use the device map file installed by hotplug.sh |
| 132 | at /etc/hotplug/usb/libmtp.usermap to lift the device to userspace for the |
| 133 | current user by running the script /etc/hotplug/usb/libmtp.sh. If |
| 134 | you have the program "resmgr" installed (currently used only by SuSE to |
| 135 | our knowledge) that program will be used for enabling desktop user |
| 136 | access, otherwise the current user of the desktop will be determined |
| 137 | from files in /var/run. (See the script "libmtp.sh" for details.) |
| 138 | |
| 139 | |
| 140 | Linux udev hotplugging |
| 141 | ---------------------- |
| 142 | |
| 143 | Newer Linux distributions have dropped support for the old hotplug system |
| 144 | and rely solely on udev, and rules stored below /etc/udev/rules.d to |
| 145 | handle permissions and actions on device connections. It's quite solid |
| 146 | but the whole thing is rather shaky when it comes to such things as |
| 147 | custom devices handled solely by libusb, which is what libmtp and for |
| 148 | example SANE backends use. |
| 149 | |
| 150 | The libmtp.rules file that comes with libmtp can be used as a starter. |
| 151 | |
| 152 | First you need a crazy rule that creates a device node in the |
| 153 | /dev/bus/usb hierarchy whenever any USB device is connected. The |
| 154 | script has this at the top, you can comment it in if your |
| 155 | distribution does not already create these device nodes. |
| 156 | |
| 157 | Then libusb may need to be patched to recognize this hierarchy. |
| 158 | The 0.1.12 version is the first which is properly fixed. |
| 159 | |
| 160 | The script sets the device access to "666" which is rather nasty |
| 161 | (not that big security issue, unless you think someone will break |
| 162 | into your jukebox) some systems prefer to let PAM do this by placing |
| 163 | a configuration file in /etc/security/ somewhere. See the Fedora Extras |
| 164 | SRPM source package in case you're interested in how it is handled |
| 165 | there. |
| 166 | |
| 167 | |
| 168 | If you cannot run hotplugging |
| 169 | ----------------------------- |
| 170 | |
| 171 | If you have a distro without hotplugging enabled try this as root: |
| 172 | |
| 173 | % chmod -R a+w /proc/bus/usb |
| 174 | |
| 175 | You have to do this again every time you unplug/replug your USB cable |
| 176 | or restart the jukebox, every time you quit libnjb and restart it, |
| 177 | etc etc etc an alternative is to run libmtp as root which works just fine. |
| 178 | The problem is to somehow assure that you (ie the current user) always |
| 179 | has write access on /proc/bus/usb/* |
| 180 | |
| 181 | You can find the Linux hotplug project at: |
| 182 | http://linux-hotplug.sourceforge.net/ |
Linus Walleij | d3b7857 | 2007-08-24 21:28:24 +0000 | [diff] [blame] | 183 | |
| 184 | |
| 185 | Compilation for embedded devices |
| 186 | -------------------------------- |
| 187 | |
| 188 | Problems with Autoconf complaining about a missing malloc() function |
| 189 | during cross-compilation can be solved with this hack if you're using |
| 190 | glibc: |
| 191 | |
| 192 | % export ac_cv_func_malloc_0_nonnull=yes |
| 193 | % ./configure |
| 194 | |
| 195 | If you're using uclibc you may have to smack in a custom rpl_malloc() |
| 196 | function in your program, see the Autoconf texinfo documentation. |
| 197 | |
| 198 | See further: |
| 199 | http://wiki.buici.com/wiki/Autoconf_and_RPL_MALLOC |