blob: a8bdeff7a53c7e80c9e7c3729d04ff65e2878b05 [file] [log] [blame]
Linus Walleij0dd71e92006-05-04 18:47:07 +00001Building and Installing
2-----------------------
Linus Walleij6fd2f082006-03-28 07:19:22 +00003
Linus Walleij0dd71e92006-05-04 18:47:07 +00004See the "INSTALL" file.
5
6
7Heritage
8--------
9
10libmtp is based on several ancestors:
11
12* libptp2 by Mariusz Woloszyn was the starting point used
13 by Richard A. Low for the initial starter port. You can
14 find it at http://libptp.sourceforge.net/
15
16* libgphoto2 by Mariusz Woloszyn and Marcus Meissner was
17 used at a later stage since it was (is) more actively
18 maintained. libmtp tracks the PTP implementation in
19 libgphoto2 and considers it an upstream project. We will
20 try to submit anything generally useful back to libgphoto2
21 and not make double efforts. In practice this means we
22 use ptp.c, ptp.h and ptp-pack.c verbatim from the libgphoto2
23 source code. If you need to change things in these files,
24 make sure it is so general that libgphoto2 will want to
25 merge it to their codebase too. You find libgphoto2 as part
26 of gPhoto: http://gphoto.sourceforge.net/
27
28* libnjb was a project that Richard and Linus were working
Linus Walleijfcf88912006-06-05 13:23:33 +000029 on before libmtp. When Linus took Richards initial port
Linus Walleij0dd71e92006-05-04 18:47:07 +000030 and made an generic C API he re-used the philosophy and
31 much code from libnjb. Many of the sample programs are for
32 example taken quite literally from libnjb. You find it here:
33 http://libnjb.sourceforge.net/
34
35
36Compiling programs for libmtp
37-----------------------------
38
39libmtp has support for the pkg-config script by adding a libmtp.pc
40entry in $(prefix)/lib/pkgconfig. To compile a libmtp program,
41"just" write:
42
43gcc -o foo `pkg-config --cflags --libs libmtp` foo.c
44
45This also simplifies compilation using autoconf and pkg-config: just
46write e.g.
47
48PKG_CHECK_MODULES(MTP, libmtp)
49AC_SUBST(MTP_CFLAGS)
50AC_SUBST(MTP_LIBS)
51
52To have libmtp LIBS and CFLAGS defined. Needless to say, this will
53only work if you have pkgconfig installed on your system, but most
54people have nowadays.
55
56If your library is installed in e.g. /usr/local you may have to tell
57this to pkgconfig by setting the PKG_CONFIG_PATH thus:
58
59export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
60
61
62Documentation
63-------------
64
65Read the API documentation that can be generated with doxygen.
66It will be output in doc/html if you have Doxygen properly
67installed. (It will not be created unless you have Doxygen!)
68
69For information about the Media Transfer Protocol, see:
70http://en.wikipedia.org/wiki/Media_Transfer_Protocol
71
72
73Contributing
74------------
75
76See the project page at http://libmtp.sourceforge.net/
Linus Walleijee73ef22006-08-27 19:56:00 +000077We always need your help. There is a mailinglist and a
78bug report system there.
Linus Walleij6fd2f082006-03-28 07:19:22 +000079
Linus Walleija1b66f22007-05-10 20:02:16 +000080
81New Devices
82-----------
83
Linus Walleijfcf88912006-06-05 13:23:33 +000084If you happen upon a device which libmtp claims it cannot
85autodetect, please submit the vendor ID and device ID
86as a bug, patch or feature request on the Sourceforge
Linus Walleijda558be2007-03-10 21:42:25 +000087bug tracker at our homepage. If it gives a sensible
88output from "mtp-detect" then please attach the result as
Linus Walleija1b66f22007-05-10 20:02:16 +000089well as it teach us some stuff about your device. If you've
90done some additional hacking, join our mailinglist and
91post your experiences there.
Linus Walleijda558be2007-03-10 21:42:25 +000092
Linus Walleija1b66f22007-05-10 20:02:16 +000093If you want to be able to hack some more and you're not
94afraid of C hacking, add an entry for your device's
95vendor/product ID and a descriptive string to the database
96in the file src/libusb-glue.c. It is close to the top of the
97file.
98
99If you want to poke around to see if your device has some
100special pecularities, you can test some special device
101flags (defined in src/libusb-glue.h) by inserting them
102together with your device entry in src/libusb-glue.c.
103Flags can be tested in isolation or catenated with "|"
104(binary OR). If relatives to your device use a certain
105flag, chances are high that a new device will need it
106too, typically from the same manufacturer.
107
108The most common flag that needs to be set is the
109DEVICE_FLAG_UNLOAD_DRIVER that detach any Linux kernel
110drivers that may have attached to the device making
Linus Walleij94f23d52007-08-04 19:37:28 +0000111MTP access impossible. This is however not expected to
112really work: this is a problem being tracked as of
113now (2007-08-04). See the "last resort" solutions below
114if you really need to get your dual-mode device to work
115with MTP.
Linus Walleija1b66f22007-05-10 20:02:16 +0000116
117If your device is very problematic we are curious of how it
Linus Walleijda558be2007-03-10 21:42:25 +0000118works under Windows, so we enjoy reading USB packet sniffs
119that reveal the low-level traffic carried out between
120Windows Media Player and your device. This can be done
121using the trial version of HHD Softwares software-only
122USB monitor. You need to get a copy of version 2.37 since
123the newer trial versions won't let you carry out the
124needed packet sniffs. (As of 2007-03-10 a copy can be found
125at: http://www.cobbleware.com/files/usb-monitor-237.exe)
126There are other USB monitors as well, some more expensive
127alternatives use hardware and even measure electronic
128characteristics of the traffic (which is far too much
129detail for us).
130
Linus Walleija1b66f22007-05-10 20:02:16 +0000131If you are a device vendor, please consider assigning one
132of your employees as a contact person for libmtp, have them
133sign up to the libmtp development list and answer questions
134and post new device ID:s as they are released to our
135mailing list. By the way: do you have spare devices you
136can give us? Send them to Richard (Mac support) or Linus
137(Linux support). (So far nobody did that except for Microsoft
138who sent us a Zune by proxy!)
Linus Walleijfcf88912006-06-05 13:23:33 +0000139
Linus Walleij6fd2f082006-03-28 07:19:22 +0000140
Linus Walleijbd7624c2007-05-28 10:48:54 +0000141Devices does not work - last resort:
142------------------------------------
143
144Some devices that are dual-mode are simply impossible to get
145to work under Linux because the usb-storage(.ko) kernel
146module hook them first, and refuse to release them, even
Linus Walleij94f23d52007-08-04 19:37:28 +0000147when we specify the DEVICE_FLAG_UNLOAD_DRIVER flag. (Maybe
148it DOES release it but the device will immediately be probed
149at the USB mass storage interface AGAIN because it
150enumerates.)
Linus Walleijbd7624c2007-05-28 10:48:54 +0000151
152Try this, if you have a recent 2.6.x Linux kernel:
153
Linus Walleij94f23d52007-08-04 19:37:28 +0000154* Edit /etc/modprobe.d/blacklist
Linus Walleijbd7624c2007-05-28 10:48:54 +0000155
156* Add the line "blacklist usb-storage"
157
158* Reboot.
159
160Now none of you USB disks, flash memory sticks etc will be
161working (you just disabled them all). However you *can* try
162your device, and it might have started working because there
163is no longer a USB mass storage driver that tries to hook onto
164the mass storage interface of your device.
165
Linus Walleij94f23d52007-08-04 19:37:28 +0000166If not even blacklisting works (check with
167"lsmod | grep usb-storage"), there is some problem with
168something else and you may need to remove or rename the file
169/lib/modules/<VERSION>/kernel/drivers/usb/storage/usb-storage.ko
170manually.
171
Linus Walleijbd7624c2007-05-28 10:48:54 +0000172If you find the PerfectSolution(TM) to this dilemma, so you
173can properly switch for individual devices whether to use it
174as USB mass storage or not, please tell us how you did it. We
175know we cannot use udev, because udev is called after-the-fact:
176the device is already configured for USB mass storage when
177udev is called.
178
179
Linus Walleij15def332006-09-19 14:27:02 +0000180Calendar and contact support:
181-----------------------------
Linus Walleijd3bdf762006-02-20 22:21:56 +0000182
Linus Walleij3c16fe42006-04-30 07:53:41 +0000183The Creative Zen series can read VCALENDAR2 (.ics) files
Linus Walleij15def332006-09-19 14:27:02 +0000184and VCard (.vcf) files from programs like for example
185Evolution with the following limitations/conditions:
Linus Walleijd3bdf762006-02-20 22:21:56 +0000186
Linus Walleij3c16fe42006-04-30 07:53:41 +0000187- The file must be in DOS (CR/LF) format, use the unix2dos
188 program to convert if needed
Linus Walleij15def332006-09-19 14:27:02 +0000189
190- Repeat events in calendar files do not seem to be supported,
191 entries will only appear once.
192
193- Calendar (.ics) files should be stored in the folder "My Organizer"
194 when sent to the device (this directory should be autodetected
Linus Walleij80b2c722006-06-22 17:57:17 +0000195 for use with calendar files, otherwise use the option
Linus Walleij15def332006-09-19 14:27:02 +0000196 -f "My Organizer" to sendfile for this) Apparently this file can
197 also contain tasklists.
198
199- Contact (.vcf) files should be stored in the folder "My Contacts"
200 when sent to the device. (-f "My Contacts")
201
202- Some devices are picky about the name of the calendar and
203 contact files. For example the Zen Microphoto wants:
204
Linus Walleijb1318d12006-09-25 14:59:26 +0000205 Calendar: My Organizer/6651416.ics
206 Contacts: My Organizer/6651416.vcf
207
208
209Syncing in with Evolution and Creative Devices
210----------------------------------------------
211
212Evolution can easily export .ics an .vcf files, but you currently
213need some command-line hacking to get you stuff copied over in
214one direction host -> device. The examples/ directory contains a script
215created for the Creative Zen Microphoto by Nicolas Tetreault.
216
Linus Walleij6e8cef42006-12-03 20:45:04 +0000217
218It's Not Our Bug!
219-----------------
220
221Some MTP devices have strange pecularities. We try to work around
222these whenever we can, sometimes we cannot work around it or we
223cannot test your solution.
224
225* The Zen Vision:M (possibly more Creative Zens) has a firmware bug
226 that makes it drop the last two characters off a playlist name.
227 It is fixed in later firmware.
228
Linus Walleijc41f2e82007-03-12 22:26:00 +0000229* For Creative Technology devices, there are hard limits on how
230 many files can be put onto the device. For a 30 GiB device (like
231 the Zen Xtra) the limit is 6000, for a 60 GiB device the limit
232 is 15000 files. For further Creative pecularities, see the
233 FAQ sections at www.nomadness.net.
234
Linus Walleijd24a7ab2007-03-07 21:48:43 +0000235* Sandisk sansa c150 and probably several other Sandisk devices
236 (and possibly devices from other manufacturers) have a dual
237 mode with MTP and USB mass storage. The device will initially
238 claim to be mass storage so udev will capture is and make the
Linus Walleijda558be2007-03-10 21:42:25 +0000239 use of MTP mode impossible. One way of avoiding it could be to
Linus Walleijd24a7ab2007-03-07 21:48:43 +0000240 be to blacklist the "usb-storage" module in
241 /etc/modprobe.c/blacklist with a row like this:
Linus Walleijda558be2007-03-10 21:42:25 +0000242 "blacklist usb-storage". Some have even removed the
243 "usb-storage.ko" (kernel module file) to avoid loading.
Linus Walleijd24a7ab2007-03-07 21:48:43 +0000244
Linus Walleijda558be2007-03-10 21:42:25 +0000245* The iriver devices (possibly all of them) cannot handle the
Linus Walleij6e8cef42006-12-03 20:45:04 +0000246 enhanced GetObjectPropList MTP command (0x9805) properly. So
247 they have been banned from using it.
248
Linus Walleijda558be2007-03-10 21:42:25 +0000249* iriver devices have problems with older versions of libmtp and
Linus Walleij82265222007-03-04 19:47:08 +0000250 with new devices libmtp does not know of as of yet, since it
251 has an oldstyle USB device controller that cannot handle zero
Linus Walleijda558be2007-03-10 21:42:25 +0000252 writes. (Register your device with us!) All their devices are
253 likely to need a special device flag in the src/libusb-glue.c
254 database.
Linus Walleij82265222007-03-04 19:47:08 +0000255
Linus Walleij6e8cef42006-12-03 20:45:04 +0000256* The Samsung Yepp T9 has several strange characteristics, some
257 that we've managed to work around. (For example it will return
258 multiple PTP packages in a single transaction.)
259
Linus Walleijf2711b32007-02-26 20:18:40 +0000260* The early firmware for Philips HDD players is known to be
261 problematic. Please upgrade to as new firmware as you can get.
262 (Yes this requires some kind of Windows Installation I think.)
263
Linus Walleij6e8cef42006-12-03 20:45:04 +0000264* Very few devices that implement GetObjectPropList (0x9805) will
265 return the entire object list if you request a list for object
266 0xffffffffu. (But they should.) So we're currently not using
267 that feature.
Linus Walleijd132d8e2007-04-03 23:24:54 +0000268
269
270Lost symbols
271------------
272
273Shared libraries can be troublesome to users not experienced with
274them. The following is a condensed version of a generic question
275that has appeared on the libmtp mailing list from time to time.
276
277> PTP: Opening session
278> Queried Creative Zen Vision:M
279> gnomad2: relocation error: gnomad2: undefined symbol:
280> LIBMTP_Get_Storageinfo
281> (...)
282> Are these type of errors related to libmtp or something else?
283
284The problem is of a generic nature, and related to dynamic library
285loading. It is colloquially known as "dependency hell".
286(http://en.wikipedia.org/wiki/Dependency_hell)
287
288The gnomad2 application calls upon the dynamic linker in Linux to
289resolve the symbol "LIBMTP_Get_Storageinfo" or any other symbol
290(ELF symbol, or link point or whatever you want to call them, a
291symbol is a label on a memory address that the linker shall
292resolve from label to actual address.)
293For generic information on this subject see the INSTALL file and
294this Wikipedia page:
295
296http://en.wikipedia.org/wiki/Library_(computing)
297
298When Linux /lib/ld-linux.so.X is called to link the symbols compiled
299into gnomad2 (or any other executable using libmtp), it examines the
300ELF file for the libmtp.so.X file it finds first and cannot resolve
301the symbol "LIBMTP_Get_Storageinfo" (or whichever symbol you have a
302problem witj) from it, since it's probably not there. There are many
303possible causes of this symbol breakage:
304
3051) You installed precompiled libmtp and gnomad2 packages (RPMs, debs
306 whatever) that do not match up. Typical cause: your gnomad2 package was
307 built against a newer version of libmtp than what's installed on your
308 machine. Another typical cause: you installed a package you found on
309 the web, somewhere, the dependency resolution system did not protest
310 properly (as it should) or you forced it to install anyway, ignoring
311 some warnings.
312
3132) You compiled libmtp and/or gnomad2 from source, installing both or
314 either in /usr/local/lib and /usr/local/bin. This means at compile-time
315 gnomad2 finds the libmtp library in /usr/local/lib but at runtime, it
316 depends on the Linux system wide library loader (/lib/ld-linux.so.X) in
317 order to resolve the symbols. This loader will look into the file
318 /etc/ld.so.conf and/or the folder /etc/ld.so.conf.d in order to find
319 paths to libraries to be used for resolving the symbols. If you have
320 some older version of libmtp in e.g. /usr/lib (typically installed by a
321 package manager) it will take precedence over the new version you just
322 installed in /usr/local/lib and the newly compiled library in
323 /usr/local/lib will *not* be used, resulting in this error message.
324
3253) You really did install the very latest versions (as of writing libmtp
326 0.1.5 and gnomad2 2.8.11) from source and there really is no
327 pre-installed package of either on your machine. In that case I'm
328 totally lost, I have no idea what's causing this.
329
330Typical remedies:
331
3321) If you don't want to mess around with your system and risk these
333 situations, only use pre-packaged software that came with the
334 distribution or its official support channels. If it still breaks,
335 blame your distribution, they're not packaging correctly. Relying on
336 properly packaged software and not installing things yourself *is* the
337 Linux solution to the "dependency hell" problem.
338
3392) Read about dynamically linked library handling until the stuff I wrote
340 about in the previous list sounds like music to your ears, inspect
341 your /lib, /usr/lib, /usr/local/lib, /etc/ld.so.conf and the
342 /etc/ld.so.conf.d, remove all pre-packed versions using RPM, APT,
343 YaST or whatever your distribution uses, compile libmtp and gnomad2
344 (or whatever) from source only and you will be enlighted.
345
346I don't know if this helps you, it's the best answer we can give.