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.21. The patches do not apply against Red Hat kernels; use vanilla
kernels from kernel.org.

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

(Instructions for nsclick should follow.)

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. (Patched kernels may or may not work. Kernels from Red
    Hat, for example, may not work.) 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-21, 2.4.18-21, and 2.4.26.

 3. Install the Click Linux kernel patch:

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

    Use the VERSION that applies to your kernel, as follows:

    Kernel version	Patch
    2.2.18		linux-2.2.18-patch
    2.2.19		linux-2.2.19-patch
    2.2.20		linux-2.2.19-patch
    2.2.21		linux-2.2.19-patch
    2.4.18		linux-2.4.18-patch
    2.4.19		linux-2.4.18-patch
    2.4.20		linux-2.4.20-patch
    2.4.21		linux-2.4.21-patch
    2.4.26		linux-2.4.26-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, you WILL need to
    recompile any kernel modules that touch 'struct device'.

 4. If your archived, working kernel has the same version number as the
    patched kernel (they're both 2.4.18, 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.

 5. 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'. Use a minimal set of
    options.

 6. Compile and install the kernel:

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

    You may get errors in one of these steps, such as the 'make bzImage'
    step. This indicates that you turned on too many options when
    configuring your kernel. Return to Step 5, turn off the option that
    seems to be causing a problem, and try again.

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

 8. Reboot your machine with the new kernel.

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

    If './configure' reports "Your header files must be patched before a
    C++ program can include them", check that you applied the patch in Step
    3, and that you supplied the correct '--with-linux' option to
    './configure'.

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

	gmake install

    If you get errors while compiling the Linux kernel module (the
    'linuxmodule' directory), and the errors look like they are in Linux
    header files, you may have turned on too many options when configuring
    your kernel. Return to Step 5, turn off the option that seems to be
    causing a problem (for example, an error involving the "atalk_iface *"
    type means you should turn off AppleTalk via CONFIG_ATALK), and try
    again.

11. This will create two module object files, 'linuxmodule/click.o' and
    'linuxmodule/proclikefs.o', and place them in 'CLICKPREFIX/lib'. To
    install these modules 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.
