


Camwire installation notes
==========================

These notes pertain to Camwire 1, which is based on libdc1394 version 1.
There will soon be a Camwire 2 as well.


Requirements

Camwire 1 needs:

  * Linux kernel 2.6 or later.

  * libdc1394 version 1.2 or later, but not version 2.0.

  * Whatever other libraries libdc1394 needs in turn (libraw1394,
    raw1394, ieee1394, video1394, and ohci1394).  See their
    documentation on http://www.linux1394.org/.

The cammonitor example also needs:

  * SDL (http://www.libsdl.org/index.php).

  * Xv (http://www.xfree86.org/4.8.0/Xv.3.html)

  * Netpbm (http://netpbm.sourceforge.net/)

You may use the UNIX `locate' tool to check if and where these libraries
are installed on your system.  You only need them if you want to run or
compile cammonitor; the Camwire library itself does not need them.

If you want to compile Camwire from source, you will need CMake
(http://www.cmake.org/) installed on your computer (see the Compile
section below).


Download

You can download the latest Camwire release from
http://kauri.auck.irl.cri.nz/~johanns/camwire/.  It has both binary and
source packages.


Compile (optional)

You can choose to compile Camwire from source (in which case you need to
download the source package), or you can skip the compile step and
install the pre-compiled binaries (in which case you need to download
the binary package matching your platform).

Assuming you wish to compile from source, Camwire is built with CMake
(http://www.cmake.org/).  If you don't use CMake, my apologies for
adding another requirement.  CMake is a capable platform-independent
generator of build configuration files (in the case of Unix and
GNU/Linux, CMake generates Makefiles).  It is used by well-known
projects like KDE.

  * Create two temporary directories: one to hold the source files and
    one to build the binaries in.

  * Copy the source package camwire1-x.x.x-Source... to the temporary
    source directory and extract the compressed archive.  Note the name
    of the subdirectory (something like camwire1-x.x.x-Source) which
    holds the source files.

  * cd to the temporary build directory.

  * Run CMake (GUI or command line), supplying the build directory
    (current) and source directory (subdirectory noted above).

  * Use CMake to configure and generate the Makefiles, choosing default
    native compilers and setting CMake variables as follows:

    CMAKE_BUILD_TYPE      "Release"
    CMAKE_INSTALL_PREFIX  The base of the Camwire install tree (usually
                          /usr/local).

  * Still in the build directory, run from the command line:

    make

If CMake or make fails to find required libraries like libdc1394, you
may have to edit CMakeLists.txt in the source directory and add
find_library commands or edit the existing find_library commands to
provide more hints for the PATHS argument.  Then repeat the configure,
generate and make steps.

If you don't want to compile the cammonitor example (because you don't
have the required libraries for instance), edit examples/CMakeLists.txt
in the source directory tree and # comment out the line
"add_subdirectory(cammonitor)".


Install

  * If you compiled from source (Compile section above), stay in the
    build directory and run from the command line:

    make install

    (It also installs the examples if you built them.)

  * If you downloaded the binary package, extract it in a temporary
    build directory.  The archive will put the binaries in a
    subdirectory called something like camwire1-x.x.x-Linux-...  From
    there you can move the following subdirectories to your preferred
    install location:

    include
    lib
    etc
    [optional] share
    [optional] bin

    The etc directory contains camera configuration data; see the
    documentation in CONFIGURATION.  The optional share directory
    contains some Camwire icon images for your viewing pleasure.  The
    bin directory is optional because you may never need to run any of
    the example executables.

  * [Optional] You may remove the temporary source and build directory
    trees.

  * If you installed Camwire in a non-standard place, you may have to do
    help your system find the example binaries and the Camwire library.
    Either make symbolic links in directories already listed in your
    PATH and LD_LIBRARY_PATH environment variables, or add your Camwire
    bin and lib installation directories to those variables; see `man
    ld'.

For example, to access the Camwire library for linking with your camera
application either

    cd /usr/local/lib
    (As root:)
    ln -s /my_preferred_location/lib/libcamwire_1394.a libcamwire_1394.a
    ln -s /my_preferred_location/lib/libcamwire_1394.so libcamwire_1394.so
    ln -s /my_preferred_location/lib/libcamwire_1394.so.y libcamwire_1394.so.y
    (where y is the so version number)
or
    export LD_LIBRARY_PATH=LD_LIBRARY_PATH:/my_preferred_location/lib

Likewise, to access the example executable (e.g. cammonitor) either

    cd /usr/local/bin
    (As root:)
    ln -s /my_preferred_location/bin/cammonitor cammonitor
    which cammonitor  # Test whether cammonitor is recognized.
or
    export PATH=$PATH:/my_preferred_location/bin
    which cammonitor  # Test whether cammonitor is recognized.


Uninstall

  * Simply remove the installed directories and files.  Check the
    contents of the relevant version of the Camwire binary package to
    see which files were installed.  You may have to download the binary
    package again if you compiled from source or had not kept the one
    you originally installed from.


Troubleshooting

  * Camwire won't compile without SDL/Xv/Netpbm: Only the cammonitor
    example needs SDL, Xv and Netpbm.  You can avoid having to compile
    it by changing into the examples subdirectory of the source tree and
    editing CMakeLists.txt by # commenting out the line
    "add_subdirectory(cammonitor)".  Or you could install the missing
    libraries.

  * "Permission denied" error messages while installing: You don't have
    sufficient privilege to create files in the installation directory.
    Try being root if you can, or install it somewhere where you have
    write permission.  See the comments in the Install section above.

  * Camwire can't find a configuration file when I first run it: Read
    and follow the instructions printed to stdout.  Also see
    CONFIGURATION.  There are configuration files for some cameras in
    the etc/camwire directory.  Feel free to add your own, and send them
    to me for inclusion in future releases.

  * Auto-generated configuration suggests a strange mode: Camwire
    searches for the highest-numbered mode.  This works well for most
    people, but in some cases you may want to select another mode or
    format from you camera's user's manual and edit that into the
    configuration file instead.

Bug reports are much appreciated.

Johann Schoonees
Industrial Research Limited, PO Box 2225, Auckland, New Zealand
Email: myinitial_dot_mysurname_at_irl_dot_cri_dot_nz

$Id: INSTALL,v 20.0 2011/02/17 02:08:29 johanns Exp $
