CLICK INSTALLATION INSTRUCTIONS
===============================

To compile any version of Click, you will need the GNU C compiler; the GNU
C++ compiler (version 2.95 or above); and GNU Make. The `./configure'
script should complain if it cannot find software it needs.

The user-level version of Click should compile and run on any Intel x86
Unix system. The pcap library may be necessary to communicate with the
network. See the end of this document for portability notes for other
architectures.

The Linux kernel module requires a patched Linux 2.2 or 2.4 system. We
provide patches for Linux 2.2.18 through 2.2.21 and 2.4.18 through 2.4.20.

The preliminary FreeBSD Click kernel module compiles against unpatched
FreeBSD-STABLE versions after 440002.

The clickns module for XXX.

CONFIGURING
-----------

If you plan to use the Linux kernel module, you must patch your kernel
first. See the `Linux module' section below.

Run

	./configure [--prefix=PREFIX]

This will test your system and decide the versions that will work for you
(user-level, Linux module, or both). It will tell you what is wrong if it
cannot compile a version. Run

	./configure --help

to see more options for `./configure'.

   Notes: You can also build Click in a different directory than the source
          directory. Just change into the build directory and run
          `PATH_TO_SRCDIR/configure'.

          If the distribution does not contain a `configure' script, you
          probably checked it out from CVS. Change into the source
          directory and run `autoconf', then continue as above.

After running `./configure', the `make install' command will install the
user-level executable `click', the kernel module `click.o', configuration
optimizers like `click-xform' and other tools, and manual pages for the
Click language, the kernel module, and many of the element classes, all
under PREFIX (which defaults to /usr/local).

USERLEVEL
---------

Build the user-level Click program in the `userlevel' directory:

	cd CLICKDIR/userlevel
	gmake

This will eventually create an executable named `click'. Test it by
passing it the file name of a Click-language router description
(see doc/click.5); for example,

	./click ../conf/test.click

The `conf' directory in this distribution has a few sample configuration
files.

The configure script may not be able to find your pcap library if it's in a
nonstandard place. It will report an error in this case. To fix the error,
set your `PCAP_INCLUDES' and `PCAP_LIBS' environment variables and rerun
`./configure'. `PCAP_INCLUDES' tells the C preprocessor where to find
`pcap.h', and `PCAP_LIBS' tells the linker where to find `libpcap.a'. One
example setting would be `PCAP_INCLUDES=-I/usr/local/include/pcap' and
`PCAP_LIBS=-L/usr/local/lib/pcap'.

LINUX MODULE
------------

Before you can compile or use the Click loadable kernel module, you need to
install, patch, compile, and boot a compatible Linux kernel. These
instructions assume you have at least passing familiarity with compiling
and running Linux kernels.

 1. Archive a complete, working Linux kernel and any corresponding modules.
    This is in case something goes wrong and you need to revert to an old
    kernel.

 2. Get a suitable Linux kernel source distribution, for example from
    www.kernel.org. Unpack this distribution into /usr/src/linux. (Save the
    old kernel source tree, if you had one.)

    We supply patches for Linux 2.2.18 through 2.2.21, and a
    preliminary patch for Linux 2.4.18.

 3. Install the Click Linux kernel patch:

	cd /usr/src/linux
	patch -p0 -b < CLICKDIR/etc/linux-VERSION-patch

    VERSION is generally the kernel version you chose. For Linux 2.2.20 or
    2.2.21, use `linux-2.2.19-patch'.

    The patch fixes syntax errors in several header files (the C++ compiler
    doesn't accept them), adds several new functions, and changes the
    `struct device' kernel data structure. Therefore, if you compiled your
    old kernel without module versioning, you WILL need to recompile
    modules.

 4. Configure the new kernel. The Click patch does not add any
    configuration options, so you can start from your old configuration, or
    you can do the usual `make menuconfig'.

 5. If your archived, working kernel has the same version number as the
    patched kernel (they're both 2.2.21, for example), then it is a good
    idea to change the patched kernel's `EXTRAVERSION'. This way, the
    modules for the new kernel won't overwrite the old, working modules.
    Edit /usr/src/linux/Makefile and change the line `EXTRAVERSION =' to
    `EXTRAVERSION = -click', or whatever you would like.

 6. Compile and install the kernel:

	make dep
	make bzImage			(or zImage)
	make install
	make modules
	make modules_install

 7. Edit /etc/lilo.conf to tell it about the new kernel, then run
    /sbin/lilo.

 8. Reboot your machine with the new kernel.

Now you are ready to compile and install the Click module. Rerun
`./configure' to tell the system about your new kernel:

	rm -f config.cache ; ./configure [OPTIONS]

If your Linux source is not in /usr/src/linux, give `./configure' the
`--with-linux=LINUXDIR' option. If your System.map file is not in
LINUXDIR/System.map, give it the `--with-linux-map=MAPFILE' option.

Then build and install the click module, its companion proclikefs module,
and the language tools:

	gmake install

This will create two module object files, `linuxmodule/click.o' and
`linuxmodule/proclikefs.o', and place them in `CLICKPREFIX/lib'. To install
these module and a router configuration, run

	CLICKPREFIX/sbin/click-install ROUTERCONFIGFILE

Alternatively you could use /sbin/insmod by hand.

PORTABILITY
-----------

    To run a Click configuration on a non-x86 machine, you will need to
worry about alignment. By default, Click configurations assume that
unaligned accesses are OK (for instance, that it is OK to load a word from
an address that isn't start on a four-byte boundary). On most
architectures, however, unaligned accesses cause problems. To run Click on
such an architecture, you'll need to run your configurations through the
`click-align' tool before installing them. `Click-align' (see
doc/click-align.1) figures out what alignment is required and adds elements
as necessary to make that alignment happen. It also adds an `AlignmentInfo'
element to tell every element what kind of alignment it can expect.
