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

Try
  make

If that works, try
  make install

The useful binaries are 'cqcam' (command-line version) and 'xcqcam' (X11
version). 

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.

I highly recommend using the xview control panel.  For this, you'll need 
libxview and libolgx.  If you don't have these, you'll have to comment 
the xview section out of the Makefile.

If you can't use xview, how about Tcl/Tk?  For that, you'll need libm, 
libdl, libtk, and libtcl.  These are disabled by default in the Makefile.

Only enable one control panel.  The xview one is on by default.

Want to shrink the xcqcam executable by a factor of 20?  Make sure that
the following links exist: 

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

(for tcl/tk)
libtcl.so -> libtcl.so.7.6
libtk.so -> libtk.so.4.2

If these links don't exist, most linkers will link xcqcam statically, 
wasting up to 1.5 mb.


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

Currently supported operating systems are Linux, QNX, FreeBSD, BSDI, and 
LynxOS.  Anyone who wants to help with a port to SCO or DOS or something, 
let me know.

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

-DLINUX is enabled by default.  If this isn't good, change the Makefile.

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 ]


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

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 support 
this, look at config.h.


-----
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 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
  locking


------------------------
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.


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

Note: I have only tested webcam support with Apache httpd.

Webcam support consists of two parts.  The nph-webcam script is a CGI
shell script that prints HTTP headers and calls the webcam binary.  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.

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
 ######################################################################
