blob: e592c46cfdfd35a760d17cd4dc7b1482a5663fac [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
62
63BASIC BUILD PROCEDURE
64=====================
65
66To build the package:
67
68 % ./configure
69 % make
70 % make install
71
72By default, libmtp will add the program-prefix "mtp-" to all the
73example programs prior to installation. The program-prefix option
74makes libmtp sample programs avoid collision with other programs like
75sox' "play" program. On Linux you should then typically type (see
76below for details):
77
78 % ./hotplug.sh
79
80you can achieve the same with
81
82 % ./configure --enable-hotplugging
83
84you can turn off some speed enhancements (for testing) with:
85
86 % ./configure --no-turbo
87
88if you want to install the documentation type:
89
90 % make install-docs
91
92if you checked out the sources from CVS, you must first run the
93autogen.sh script that generates all the GNU autotools files.
94Notice that this requires GNU autoconf, automake and libtool. This
95is done with:
96
97 % ./autogen.sh
98
99
100Linux hotplugging
101-----------------
102
103After compilation and installation you may (and should) add hotplugging
104support by running the hotplug script, if your distribution supports
105hotplugging (all do). This typically means you have something
106in /etc/hotplug and that hotplugging is started when you boot your
107machine in a script named /etc/init.d/hotplug or similar.
108
109Activate hotplugging by running:
110
111 %./hotplug.sh
112
113Hotplug will (typically) use the device map file installed by hotplug.sh
114at /etc/hotplug/usb/libmtp.usermap to lift the device to userspace for the
115current user by running the script /etc/hotplug/usb/libmtp.sh. If
116you have the program "resmgr" installed (currently used only by SuSE to
117our knowledge) that program will be used for enabling desktop user
118access, otherwise the current user of the desktop will be determined
119from files in /var/run. (See the script "libmtp.sh" for details.)
120
121
122Linux udev hotplugging
123----------------------
124
125Newer Linux distributions have dropped support for the old hotplug system
126and rely solely on udev, and rules stored below /etc/udev/rules.d to
127handle permissions and actions on device connections. It's quite solid
128but the whole thing is rather shaky when it comes to such things as
129custom devices handled solely by libusb, which is what libmtp and for
130example SANE backends use.
131
132The libmtp.rules file that comes with libmtp can be used as a starter.
133
134First you need a crazy rule that creates a device node in the
135/dev/bus/usb hierarchy whenever any USB device is connected. The
136script has this at the top, you can comment it in if your
137distribution does not already create these device nodes.
138
139Then libusb may need to be patched to recognize this hierarchy.
140The 0.1.12 version is the first which is properly fixed.
141
142The script sets the device access to "666" which is rather nasty
143(not that big security issue, unless you think someone will break
144into your jukebox) some systems prefer to let PAM do this by placing
145a configuration file in /etc/security/ somewhere. See the Fedora Extras
146SRPM source package in case you're interested in how it is handled
147there.
148
149
150If you cannot run hotplugging
151-----------------------------
152
153If you have a distro without hotplugging enabled try this as root:
154
155 % chmod -R a+w /proc/bus/usb
156
157You have to do this again every time you unplug/replug your USB cable
158or restart the jukebox, every time you quit libnjb and restart it,
159etc etc etc an alternative is to run libmtp as root which works just fine.
160The problem is to somehow assure that you (ie the current user) always
161has write access on /proc/bus/usb/*
162
163You can find the Linux hotplug project at:
164http://linux-hotplug.sourceforge.net/