blob: acf26515080170bc79ea99c354717060b4852739 [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 Walleijfcf88912006-06-05 13:23:33 +000080If you happen upon a device which libmtp claims it cannot
81autodetect, please submit the vendor ID and device ID
82as a bug, patch or feature request on the Sourceforge
83bug tracker at our homepage.
84
Linus Walleij6fd2f082006-03-28 07:19:22 +000085
Linus Walleij15def332006-09-19 14:27:02 +000086Calendar and contact support:
87-----------------------------
Linus Walleijd3bdf762006-02-20 22:21:56 +000088
Linus Walleij3c16fe42006-04-30 07:53:41 +000089The Creative Zen series can read VCALENDAR2 (.ics) files
Linus Walleij15def332006-09-19 14:27:02 +000090and VCard (.vcf) files from programs like for example
91Evolution with the following limitations/conditions:
Linus Walleijd3bdf762006-02-20 22:21:56 +000092
Linus Walleij3c16fe42006-04-30 07:53:41 +000093- The file must be in DOS (CR/LF) format, use the unix2dos
94 program to convert if needed
Linus Walleij15def332006-09-19 14:27:02 +000095
96- Repeat events in calendar files do not seem to be supported,
97 entries will only appear once.
98
99- Calendar (.ics) files should be stored in the folder "My Organizer"
100 when sent to the device (this directory should be autodetected
Linus Walleij80b2c722006-06-22 17:57:17 +0000101 for use with calendar files, otherwise use the option
Linus Walleij15def332006-09-19 14:27:02 +0000102 -f "My Organizer" to sendfile for this) Apparently this file can
103 also contain tasklists.
104
105- Contact (.vcf) files should be stored in the folder "My Contacts"
106 when sent to the device. (-f "My Contacts")
107
108- Some devices are picky about the name of the calendar and
109 contact files. For example the Zen Microphoto wants:
110
Linus Walleijb1318d12006-09-25 14:59:26 +0000111 Calendar: My Organizer/6651416.ics
112 Contacts: My Organizer/6651416.vcf
113
114
115Syncing in with Evolution and Creative Devices
116----------------------------------------------
117
118Evolution can easily export .ics an .vcf files, but you currently
119need some command-line hacking to get you stuff copied over in
120one direction host -> device. The examples/ directory contains a script
121created for the Creative Zen Microphoto by Nicolas Tetreault.
122
Linus Walleij6e8cef42006-12-03 20:45:04 +0000123
124It's Not Our Bug!
125-----------------
126
127Some MTP devices have strange pecularities. We try to work around
128these whenever we can, sometimes we cannot work around it or we
129cannot test your solution.
130
131* The Zen Vision:M (possibly more Creative Zens) has a firmware bug
132 that makes it drop the last two characters off a playlist name.
133 It is fixed in later firmware.
134
135* The iRiver devices (possibly all of them) cannot handle the
136 enhanced GetObjectPropList MTP command (0x9805) properly. So
137 they have been banned from using it.
138
139* The Samsung Yepp T9 has several strange characteristics, some
140 that we've managed to work around. (For example it will return
141 multiple PTP packages in a single transaction.)
142
143* Very few devices that implement GetObjectPropList (0x9805) will
144 return the entire object list if you request a list for object
145 0xffffffffu. (But they should.) So we're currently not using
146 that feature.