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