• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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