blob: 64bd2b88b663f002ea0e5920f82a787e070f72fa [file] [log] [blame]
Linus Walleij6c04caa2006-03-29 17:33:51 +00001INSTALLATION OVERVIEW
2=====================
3
Linus Walleij0dd71e92006-05-04 18:47:07 +00004Once 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/):
Linus Walleij6c04caa2006-03-29 17:33:51 +00007
Linus Walleij0dd71e92006-05-04 18:47:07 +00008 $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 Walleij6c04caa2006-03-29 17:33:51 +000014
Linus Walleij0dd71e92006-05-04 18:47:07 +000015Sample 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/
Linus Walleij6c04caa2006-03-29 17:33:51 +000019
Linus Walleijd4637502009-06-14 23:03:33 +000020
Linus Walleijb8ee9252009-01-03 00:02:58 +000021Install 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,
Linus Walleijd4637502009-06-14 23:03:33 +000026Fedora, OpenSUSE, Debian testing, Gentoo, FreeBSD ports and OpenBSD
Linus Walleijb8ee9252009-01-03 00:02:58 +000027packages/ports.
28
29
Linus Walleijd4637502009-06-14 23:03:33 +000030Dependencies
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
37
Linus Walleij0dd71e92006-05-04 18:47:07 +000038Shared Library Support
39----------------------
40
41Shared library linking is supported. You will need to 'make install'
42the library before you can execute the sample binaries, and add the
43libmtp install directory to your shared library search path.
44
45On 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 Walleijd4637502009-06-14 23:03:33 +000048program "ldconfig" to scan in the shared libraries at
49the new path. This is a part of the Linux shared library
Linus Walleij0dd71e92006-05-04 18:47:07 +000050loader actually.
51
52To access the library from real odd locations you can use
53the LD_LIBRARY_PATH environment variable by setting it before
54you run your program, for example:
55
56 % export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
57 % my_program
58
59This way of enabling the library to link is a workaround hack.
60Note that the LD_LIBRARY_PATH is actually supposed to be used for
61testing, not production systems or distributions. It is commonly
62used as a workaround when a user is installing libraries in her/his
63home directory however. Read more about this environment variable
64here: http://www.visi.com/~barr/ldpath.html
65
66The shared library comes with different interface version numbers,
67for example libmtp.so.4, libmtp.so.5 and so forth. This is used so
68that both old and new libmtp libraries shall be able to coexist on
Linus Walleijd4637502009-06-14 23:03:33 +000069the same system. When you compile your programs they will typically
70bind to the latest version of the shared library. A link to the
Linus Walleij0dd71e92006-05-04 18:47:07 +000071latest version is always provided as $PREFIX/lib/libmtp.so.
72
73libusb Support
74--------------
75
76This package depends on libusb. Get libusb from sourceforge at:
77
78 http://www.sourceforge.net/projects/libusb/
79
Linus Walleij63a92582006-06-03 20:36:35 +000080On Linux, please use the very latest version you can get, between
810.1.8 and 0.1.12 a lot of things happened which pertains to
82the udev hotplugging support, see below.
83
Linus Walleij0dd71e92006-05-04 18:47:07 +000084
85BASIC BUILD PROCEDURE
86=====================
87
88To build the package:
89
Linus Walleij1774a8e2010-12-05 20:01:53 +000090 % ./configure --libexecdir=/lib/udev
Linus Walleij0dd71e92006-05-04 18:47:07 +000091 % make
92 % make install
93
94By default, libmtp will add the program-prefix "mtp-" to all the
95example programs prior to installation. The program-prefix option
96makes libmtp sample programs avoid collision with other programs like
Linus Walleij284aacb2007-08-11 21:17:36 +000097sox' "play" program. If the default prefix for some reason fail,
98try to tag on "--program-prefix=mtp-" to the "configure" command.
99
Linus Walleij1774a8e2010-12-05 20:01:53 +0000100The "--libexecdir=/lib/udev" parameter is a Linux pecularity to
101make the mtp-probe (which is built for Linux only) install into
102that directory. Library executables are executables bound to the
103library and for udev programs this specific directory shall hold
104such executables.
Linus Walleij0dd71e92006-05-04 18:47:07 +0000105
106if you want to install the documentation type:
107
108 % make install-docs
109
110if you checked out the sources from CVS, you must first run the
111autogen.sh script that generates all the GNU autotools files.
Linus Walleij362d13e2009-08-02 19:59:21 +0000112Notice that this requires GNU autoconf, automake and libtool and
113possibly some other packages like gettext, readline, intltool and
114other M4 macro sources. This is done with:
Linus Walleij0dd71e92006-05-04 18:47:07 +0000115
116 % ./autogen.sh
117
118
119Linux hotplugging
120-----------------
121
122After compilation and installation you may (and should) add hotplugging
123support by running the hotplug script, if your distribution supports
124hotplugging (all do). This typically means you have something
125in /etc/hotplug and that hotplugging is started when you boot your
126machine in a script named /etc/init.d/hotplug or similar.
127
128Activate hotplugging by running:
129
130 %./hotplug.sh
131
132Hotplug will (typically) use the device map file installed by hotplug.sh
133at /etc/hotplug/usb/libmtp.usermap to lift the device to userspace for the
134current user by running the script /etc/hotplug/usb/libmtp.sh. If
135you have the program "resmgr" installed (currently used only by SuSE to
136our knowledge) that program will be used for enabling desktop user
137access, otherwise the current user of the desktop will be determined
138from files in /var/run. (See the script "libmtp.sh" for details.)
139
140
141Linux udev hotplugging
142----------------------
143
144Newer Linux distributions have dropped support for the old hotplug system
145and rely solely on udev, and rules stored below /etc/udev/rules.d to
146handle permissions and actions on device connections. It's quite solid
147but the whole thing is rather shaky when it comes to such things as
148custom devices handled solely by libusb, which is what libmtp and for
149example SANE backends use.
150
151The libmtp.rules file that comes with libmtp can be used as a starter.
152
153First you need a crazy rule that creates a device node in the
154/dev/bus/usb hierarchy whenever any USB device is connected. The
155script has this at the top, you can comment it in if your
156distribution does not already create these device nodes.
157
158Then libusb may need to be patched to recognize this hierarchy.
159The 0.1.12 version is the first which is properly fixed.
160
161The script sets the device access to "666" which is rather nasty
162(not that big security issue, unless you think someone will break
163into your jukebox) some systems prefer to let PAM do this by placing
164a configuration file in /etc/security/ somewhere. See the Fedora Extras
165SRPM source package in case you're interested in how it is handled
166there.
167
168
169If you cannot run hotplugging
170-----------------------------
171
172If you have a distro without hotplugging enabled try this as root:
173
174 % chmod -R a+w /proc/bus/usb
175
176You have to do this again every time you unplug/replug your USB cable
177or restart the jukebox, every time you quit libnjb and restart it,
178etc etc etc an alternative is to run libmtp as root which works just fine.
179The problem is to somehow assure that you (ie the current user) always
180has write access on /proc/bus/usb/*
181
182You can find the Linux hotplug project at:
183http://linux-hotplug.sourceforge.net/
Linus Walleijd3b78572007-08-24 21:28:24 +0000184
185
186Compilation for embedded devices
187--------------------------------
188
189Problems with Autoconf complaining about a missing malloc() function
190during cross-compilation can be solved with this hack if you're using
191glibc:
192
193 % export ac_cv_func_malloc_0_nonnull=yes
194 % ./configure
195
196If you're using uclibc you may have to smack in a custom rpl_malloc()
197function in your program, see the Autoconf texinfo documentation.
198
199See further:
200http://wiki.buici.com/wiki/Autoconf_and_RPL_MALLOC