----------
Quickstart
----------

To build cqcam, do this:
  ./configure
  make
To install it:
  make install

The useful binaries are as follows:
  ./cli/cqcam     : command-line version, for cron jobs, scripts, etc.
  ./xfe/xcqcam    : old X11 version with optional XV or Tk widgets
  ./gtkfe/gtkcam  : nifty new X11 version with GTK+ widgets
  ./webcam/webcam : streaming-JPEG-webcam binary, see "Webcam support" below
All four of these end up in /usr/local/bin by default when you run
'make install'.

Now, more detailed notes:

---------------
X11 compilation
---------------

xcqcam requires libX11 and libXext, no matter what.  If you don't have 
(and can't get) these, don't try to compile xcqcam.  cqcam still works
fine with just libc.

I highly recommend using the GTK+ binary.  It has a far better interface
than the older xcqcam binary.  The GTK+ one is the one that I'm most
actively improving and maintaining.

If you don't have GTK+ (and for some reason don't want to get it), xcqcam
can be compiled to use XV widgets, Tk widgets, or no widgets at all.
Autoconf will figure out which libraries you have installed and will
build the appropriate binaries accordingly.

Want to shrink the xcqcam and gtkcam executables dramatically?  Make sure
that you have dynamic versions of XV, Tk, or GTK+ as appropriate and that
the appropriate symbolic links exist:

(for xview)
libxview.so -> libxview.so.x
libolgx.so -> libolgx.so.x

(for tcl/tk)
libtcl.so -> libtcl.so.x.y
libtk.so -> libtk.so.x.y

(for GTK+)
libgtk.so -> libgtk.so.x.y.z
libgdk.so -> libgdk.so.x.y.z
libglib.so -> libglib.so.x.y.z

If these links don't exist, most linkers will link xcqcam and gtkcam
statically, 1-3 MB.


-----------------
Operating systems
-----------------

Currently supported operating systems are Linux (x86, ARM, and probably
Alpha), QNX, FreeBSD, BSDI, OpenBSD, LynxOS, and Solaris.  A DOS version
is in the works.  If anyone cares about a port to other Linuxes, SCO, or
whatever, I'm always accepting patches.

The only platform that I can test extensively is x86 Linux, but the others
seem to work for other people. 

Each OS has its own way of regulating access to hardware ports.
Linux:    you have to be root
FreeBSD:  you have to have write access to /dev/io (and /dev/io has to exist)
QNX:      no limitations
LynxOS:   you have to have uid=0 or gid=0
BSDI:     anyone can access the ports once root has run (usually at boot):
            /usr/sbin/ioport -m 0x378 3  # [ or 0x278, or 0x3BC ]
OpenBSD:  you have to be root
Solaris:  you have to be in kernel space.  Read the documentation in
          solaris-io/ for details about installing the kernel I/O driver.
DOS:      DOS protecting hardware resources?  Ha!


-----
JPEGs
-----

Cqcam now has support for JPEG images built in.  This requires the JPEG
library v6 or newer, available from ftp://ftp.uu.net/graphics/jpeg/.  Note
that /usr/lib/libjpeg.so (or .a) is used if it's found, so on systems
where you have installed a newer version in /usr/local/lib, you'll have to
fix your libraries (try deleting the old version, or putting both in
/usr/lib) or change your Makefile.  If you don't want JPEG support at all,
edit the Makefile.  Note that the webcam binary requires JPEG support. 


-------
Locking
-------

NOTE: locking is broken right now, because it was quite insecure in its
former state.  I'll fix it before releasing 0.90final.

Locking is optional, because I'm not sure if all systems support it.  The 
mechanism I'm using is to create /tmp/qcam.LOCK.0xNNN (where NNN is the 
port) and lock it exclusively with fcntl.

If your system doesn't have fcntl, use the --enable-locking=no switch
when running ./configure.


-----
Paths
-----

There are lots of paths in the Makefile.  They work for me, and they're 
all pretty sane.  You should probably double-check them anyway.

If you run older versions of RedHat Linux, you may find that gcc can't
find your X includes and/or libraries.  Add the following symlink: 
  cd /usr/include ; ln -s /usr/X11R6/include/X11


--------------------
Compile-time options
--------------------

Read config.h.  In short, here's what you can customize and the associated
command-line switch, where applicable: 
  default detect mode (-d 1)
  default port (-P 0)
  private color map (-p-)
  auto-adjust default (-a+)
  SHM default (-m+)
  default BPP (-32+)
  despeckling (for cqcam, xcqcam, and webcam)


------------------------
Installation permissions
------------------------

The final binaries are installed mode 4711: SUID and world-executable.  The 
programs should not present any security holes (the risky -P option may 
only be used by root); however, when installed this way, anyone may take 
pictures with your camera.  If this isn't desired, change the BINMODE, 
BINUSER, and BINGROUP variables in the Makefile. On my system, the 
binaries are mode 4710, and for each the group is "camera," to which only 
selected users belong.

As with any SUID binary, there are plenty of potential security holes. 
Cqcam drops privileges as early as possible (except on LynxOS!), but raw
I/O ports are still accessible.  Shell-code won't work, but d-o-s's and
raw disk access may still be possible.  On a multi-user system, cqcam
should probably not be SUID.  Of course, webcam -has- to be SUID. 
Limiting execute permissions using groups is a good idea here.


--------------
Webcam support
--------------

See the docs/README.webcam document for a step-by-step recipe for setting
a webcam.  What follows is more of an overview.

Note: I have only tested webcam support with Apache httpd.  It only works
with Netscape.  If you use IE, you can't have streaming images.  So there.

Webcam support consists of two parts.  The nph-webcam script is a CGI
shell script that prints HTTP headers and calls the webcam binary.  For
Apache 1.2.x and earlier, the script must have a name beginning with
'nph-' so that the server knows not to parse or buffer any of the script's
output.  For Apache 1.3.x and later, this is no longer true.

The second part is the webcam binary itself.  This takes a series of
pictures and sends its output in JPEG-stream format to a browser.  It is
not a CGI itself; it should be called from an nph script like the one
provided.  If auto-adjust-brightness mode is enabled, pictures will be
sent immediately, as the brightness is being adjusted.  This is weird but
is probably better than having the client's browser sit blank for 5-10
seconds.


-----------
Pentium GCC
-----------

Olivier Tharan <olive@minet.net> reported troubles compiling cqcam with
the Pentium-optimized version of g++.  He says:

[G++] exited with an internal error; it comes from the optimizations which
are not quite good.  One can cope with it by switching back to plain old
gcc with the command line gcc -V2.7.2.1 -bi486-linux (or whatever appears
to be the correct version of gcc on the system). 

[ This exact patch may not work on newer versions, but I hope
Oliver's change is clear ]  ... Here is my patched Makefile:

--- cqcam-0.40b/Makefile        Fri Apr 25 07:37:39 1997
+++ cqcam-0.40b-patched/Makefile        Mon Sep  8 16:50:55 1997
@@ -82,9 +82,9 @@

 ######################################################################
 # Compiler information: where are CC and LD?
-CC = cc
+CC = gcc -V2.7.2.1 -bi486-linux
 #CC = gcc
-LD = cc
+LD = gcc
 #LD = gcc
 ######################################################################
