Return to INSTALL CVS log

Up to [PDOS] / click / release / one

add patch for 2.6.19.2

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

To compile any version of Click, you will need the GNU C compiler; a recent
version of the GNU C++ compiler; 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 Unixlike
system, including Mac OS X.  The pcap library may be necessary to
communicate with the network.  See the end of this document for portability
notes for architectures other than the x86.

The Linux kernel module requires a patched Linux 2.2, 2.4, or 2.6 system.
We provide patches for Linux 2.2.18 through 2.2.21, 2.4.18 through 2.4.32,
2.6.16.13, and 2.6.19.2.  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.

The ns module requires a patched version of the NS simulator.  We provide
patches for ns versions 2.29 and 2.30.  See the NS SIMULATOR section below.


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

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

Change to the Click source directory and 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 the 'PCAP_INCLUDES' and 'PCAP_LIBS' variables in the options to
'./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 './configure
PCAP_INCLUDES=-I/usr/local/include/pcap 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 vanilla Linux kernel source distribution from www.kernel.org or
    one of its mirrors.  (Patched kernels, such as Red Hat kernels, usually
    do 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-32, 2.6.16.13, and
    2.6.19.2.  A patch may or may not work for a slightly different kernel
    version; we suggest you try it.

 3. Install the Click Linux kernel patch:

	cd LINUXSRCDIR
	patch -p0 -b < CLICKDIR/etc/linux-VERSION-patch

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

    Kernel version	Patch
    2.6.19.2		linux-2.6.19.2-patch
    2.6.16.13		linux-2.6.16.13-patch
    2.4.32		linux-2.4.32-patch
    2.4.28		linux-2.4.26-patch
    2.4.27		linux-2.4.26-patch
    2.4.26		linux-2.4.26-patch
    2.4.26-Debian	debian-2.4.26-patch
    2.4.21		linux-2.4.21-patch
    2.4.20		linux-2.4.20-patch
    2.4.19		linux-2.4.18-patch
    2.4.18		linux-2.4.18-patch
    2.2.21		linux-2.2.19-patch
    2.2.20		linux-2.2.19-patch
    2.2.19		linux-2.2.19-patch
    2.2.18		linux-2.2.18-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 LINUXSRCDIR/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.

    Click is not currently safe for kernels with involuntary preemption.
    Make sure that the CONFIG_PREEMPT option is off.
    CONFIG_PREEMPT_VOLUNTARY is OK.  We welcome patches to improve Click's
    preemption behavior.

 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. Reboot your machine with the new kernel.

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

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

10. This will create two module object files, 'linuxmodule/click.ko' and
    'linuxmodule/proclikefs.ko', and place them in 'CLICKPREFIX/lib'.  (In
    Linux 2.4 and prior versions, the files end in '.o'.)  To install these
    modules and a router configuration, run

	CLICKPREFIX/sbin/click-install ROUTERCONFIGFILE

    Alternatively you could use /sbin/insmod by hand; see click.o(8).


NS MODULE
---------

Support for integrating Click with the NS simulator was originally
developed by Michael Neufeld at the University of Colorado.

To compile a Click-enabled version of the NS simulator, you must first
configure and install Click with NS support.  Change to the Click source
directory and run

	./configure --prefix=CLICKPREFIX [other options] --enable-nsclick
	make install

Now, prepare to compile the NS simulator.  This may involve first compiling
and installing several external packages, such as tclcl and otcl.  Then
unpack the latest version of NS; we provide patches for versions 2.29 and
2.30, but a patch may apply to later versions.  Apply the appropriate patch
from Click's etc/ directory, like so:

	cd ns-VERSION
	patch -p1 < CLICKDIR/etc/ns-VERSION-patch

Now configure NS, supplying the prefix you installed for Click.

	./configure [--prefix=PREFIX] --with-click=CLICKPREFIX

Compile and install NS.  To test nsclick, run the ns simulator on one of
the sample scripts we provide:

	cd ns-VERSION/tcl/ex
	ns nsclick-simple-lan.tcl

If you get a shared library error when running ns, make sure that the
LD_LIBRARY_PATH environment variable includes the CLICKDIR/lib directory.
You should see some NS printouts intermixed with some Click printouts,
which begin with "tokernel", "discard", "fromkernel", and so forth.

Please note that the NS patch no longer requires libnet.


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.