diff options
author | Linus Walleij <triad@df.lth.se> | 2006-05-04 18:47:07 +0000 |
---|---|---|
committer | Linus Walleij <triad@df.lth.se> | 2006-05-04 18:47:07 +0000 |
commit | 0dd71e92986ef3bf43f0edf0f8b1d54d3078b757 (patch) | |
tree | 82d92f3888982226e15a512d33802a9916f78c3c /INSTALL | |
parent | 43dcb93b3fcae6a4169d178daeca1129213090e0 (diff) | |
download | libmtp-0dd71e92986ef3bf43f0edf0f8b1d54d3078b757.tar.gz |
General clean-up and documentation.
Diffstat (limited to 'INSTALL')
-rw-r--r-- | INSTALL | 166 |
1 files changed, 158 insertions, 8 deletions
@@ -1,14 +1,164 @@ INSTALLATION OVERVIEW ===================== -COMPILATION ------------ +Once libmtp is built and installed, you will have the following files +($PREFIX is the --prefix option given to the "configure" script and +defaults to /usr/local/): -Problems with compilation under FC4: GCC4 related problem. -Run this: + $PREFIX/lib/libmtp.a Static C library + $PREFIX/lib/libmtp.so.x.y.z Dynamic C library + $PREFIX/lib/libmtp.so.x A link to the library + $PREFIX/lib/libmtp.so A link to the library + $PREFIX/include/libmtp.h C header file for libmtp API + $PREFIX/lib/pkgconfig/libmtp.pc pkg-config configuration file -CC=gcc32 -export CC -./configure -make +Sample programs will be built in the "example" directory, and should +help you get used to using the libmtp API, as well as provide some +immediate gratification. Links to other programs using the libmtp +API may be found at the homepage: http://libmtp.sourceforge.net/ +Shared Library Support +---------------------- + +Shared library linking is supported. You will need to 'make install' +the library before you can execute the sample binaries, and add the +libmtp install directory to your shared library search path. + +On Linux, you would add the line "/usr/local/lib" to your +"/etc/ld.so.conf" or as a oneliner in for example a +"/etc/ld.so.conf.d/local.conf" file and run the +program "ldconfig" to scan in the shared libraries at +the new path. This is a part of the Linux shared library +loader actually. + +To access the library from real odd locations you can use +the LD_LIBRARY_PATH environment variable by setting it before +you run your program, for example: + + % export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib + % my_program + +This way of enabling the library to link is a workaround hack. +Note that the LD_LIBRARY_PATH is actually supposed to be used for +testing, not production systems or distributions. It is commonly +used as a workaround when a user is installing libraries in her/his +home directory however. Read more about this environment variable +here: http://www.visi.com/~barr/ldpath.html + +The shared library comes with different interface version numbers, +for example libmtp.so.4, libmtp.so.5 and so forth. This is used so +that both old and new libmtp libraries shall be able to coexist on +the same system. When you compile your programs they will typically +bind to the latest version of the shared library. A link to the +latest version is always provided as $PREFIX/lib/libmtp.so. + +libusb Support +-------------- + +This package depends on libusb. Get libusb from sourceforge at: + + http://www.sourceforge.net/projects/libusb/ + + +BASIC BUILD PROCEDURE +===================== + +To build the package: + + % ./configure + % make + % make install + +By default, libmtp will add the program-prefix "mtp-" to all the +example programs prior to installation. The program-prefix option +makes libmtp sample programs avoid collision with other programs like +sox' "play" program. On Linux you should then typically type (see +below for details): + + % ./hotplug.sh + +you can achieve the same with + + % ./configure --enable-hotplugging + +you can turn off some speed enhancements (for testing) with: + + % ./configure --no-turbo + +if you want to install the documentation type: + + % make install-docs + +if you checked out the sources from CVS, you must first run the +autogen.sh script that generates all the GNU autotools files. +Notice that this requires GNU autoconf, automake and libtool. This +is done with: + + % ./autogen.sh + + +Linux hotplugging +----------------- + +After compilation and installation you may (and should) add hotplugging +support by running the hotplug script, if your distribution supports +hotplugging (all do). This typically means you have something +in /etc/hotplug and that hotplugging is started when you boot your +machine in a script named /etc/init.d/hotplug or similar. + +Activate hotplugging by running: + + %./hotplug.sh + +Hotplug will (typically) use the device map file installed by hotplug.sh +at /etc/hotplug/usb/libmtp.usermap to lift the device to userspace for the +current user by running the script /etc/hotplug/usb/libmtp.sh. If +you have the program "resmgr" installed (currently used only by SuSE to +our knowledge) that program will be used for enabling desktop user +access, otherwise the current user of the desktop will be determined +from files in /var/run. (See the script "libmtp.sh" for details.) + + +Linux udev hotplugging +---------------------- + +Newer Linux distributions have dropped support for the old hotplug system +and rely solely on udev, and rules stored below /etc/udev/rules.d to +handle permissions and actions on device connections. It's quite solid +but the whole thing is rather shaky when it comes to such things as +custom devices handled solely by libusb, which is what libmtp and for +example SANE backends use. + +The libmtp.rules file that comes with libmtp can be used as a starter. + +First you need a crazy rule that creates a device node in the +/dev/bus/usb hierarchy whenever any USB device is connected. The +script has this at the top, you can comment it in if your +distribution does not already create these device nodes. + +Then libusb may need to be patched to recognize this hierarchy. +The 0.1.12 version is the first which is properly fixed. + +The script sets the device access to "666" which is rather nasty +(not that big security issue, unless you think someone will break +into your jukebox) some systems prefer to let PAM do this by placing +a configuration file in /etc/security/ somewhere. See the Fedora Extras +SRPM source package in case you're interested in how it is handled +there. + + +If you cannot run hotplugging +----------------------------- + +If you have a distro without hotplugging enabled try this as root: + + % chmod -R a+w /proc/bus/usb + +You have to do this again every time you unplug/replug your USB cable +or restart the jukebox, every time you quit libnjb and restart it, +etc etc etc an alternative is to run libmtp as root which works just fine. +The problem is to somehow assure that you (ie the current user) always +has write access on /proc/bus/usb/* + +You can find the Linux hotplug project at: +http://linux-hotplug.sourceforge.net/ |