readme

COPE the first practical network coding scheme which is developped on click

A SAMPLE PACKAGE
================

    Click supports dynamically linked 'packages' containing extra elements.
The two drivers -- specifically, the 'click' user-level driver and the
'click-install' program for the Linux kernel driver -- automatically link
with whatever packages are mentioned in a configuration's 'require'
statements. If you are building a collection of your own elements, it may
make sense to compile that collection as a package. Then you can keep your
Click sources separate from your package sources.

    This directory demonstrates how to write a simple package. You can copy
most of the files into your own package with minimal changes.


INSTALLATION
------------

    This section describes how you can install this package -- which is
named 'sample' -- and, by extension, any package you build based on this
one.

    Before you can build a package, you must install Click into some
directory DIR. (You set DIR with the '--prefix=DIR' option to Click's
'./configure'.) We often use '/usr/local/click', but if you do not have
permission on that directory, '$HOME' or '$HOME/click' works just as well.

    Now you must configure your package, telling it where the Click install
directory is. The best way to do this is to run './configure --prefix=DIR',
where DIR is the Click install directory. The package will be installed in
DIR, where the Click drivers can find it. (The package './configure' has
several interesting options, like '--disable-linuxmodule'; run './configure
--help' to see them.)

    Next, just run 'make install'. This will build and install element
collections for both drivers, manual pages for the package's elements, and
an 'elementmap' for the package.

    We have supplied a simple configuration that tests the 'sample'
package, 'test.click'. Note the 'require(sample);' line: this is what tells
the Click drivers to load the 'sample' package.


GUIDE TO THE SOURCE
-------------------

    This section describes the files that make up a simple package, and how
you will need to alter the 'etc/samplepackage' files for your own package.


'configure.in'
..............

    Autoconf generates './configure' from this script. You will not
generally need to alter existing parts of 'configure.in', but you might
want to add tests to it. Since package sources '#include <click/config.h>'
as well as their own 'config.h', you do not need to duplicate tests Click
performs already.

    Autoconf has a useful info(1) manual.


'install-sh', 'missing', 'mkinstalldirs', 'acclick.m4', 'aclocal.m4'
....................................................................

    These files support './configure'. Use them unchanged.


'config.h.in'
.............

    If you add tests to 'configure.in', you will want to change
'config.h.in' so that the results make it to 'config.h'.


'Makefile.in'
.............

    './configure' generates a Makefile from 'Makefile.in'. Change the
'package' variable to the name of your package.

    The rest of 'Makefile.in' can generally stay as is. However, if you
develop a complex source hierarchy -- where the element source code is in a
separate directory, for example -- you will need to alter 'Makefile.in'.
Look particularly at the 'top_builddir' and 'subdir' variables. You might
also want to rerun './configure' automatically when 'configure.in' changes.


'kernelversion.c'
.................

    This file helps build a package for the Linux kernel driver. Use it
unchanged.


Element source
..............

    Element source code designed for a package looks just like normal
element source code. This is normally the only actual C++ code you will
need to write; Click automatically generates the boilerplate that turns
your elements into a package. Take a look at 'sampleelt.cc' and
'sampleelt.hh'.

    'make elemlist' is useful when you add or remove elements from the
package. It rebuilds the lists of valid element source files stored in
'kelements.conf' and 'uelements.conf'.


GENERATED FILES
---------------

    Building a package creates a bunch of files with unusual extensions.
Here are the files, and what they are for.


'kelements.conf', 'uelements.conf'
..................................

    These files list the element source code to be compiled into the kernel
package and user-level package, respectively. They are automatically
generated by 'click-buildtool findelem'. 'Click-buildtool' only considers
C++ source files named 'WHATEVER.cc' that contain an 'EXPORT_ELEMENT' or
'ELEMENT_PROVIDES' line.

    Run 'make elemlist' to rebuild 'kelements.conf' and 'uelements.conf'.


'elements.mk'
.............

    This file contains definitions for the 'K_ELEMENT_OBJS' and
'U_ELEMENT_OBJS' Make variables, which tell Make what element source code
to compile. It is generated by 'click-buildtool elem2make' from
'kelements.conf' and 'uelements.conf'.


'kpackage.cc', 'upackage.cc'
............................

    These files define the 'init_module' and 'cleanup_module' functions
that actually export your new elements to the relevant driver. They are
generated by 'click-buildtool elem2package' from 'kelements.conf' and
'uelements.conf', respectively.


'FILE.ko', 'FILE.uo'
....................

    These are object files destined for the Linux kernel package and the
user-level package, respectively.


'FILE.kd', 'FILE.ud'
....................

    These files automatically track dependencies for '.ko' objects and
'.uo' objects, respectively. GCC generates them.


'elementmap-PACKAGENAME.xml'
............................

    This file lists the elements included in the package. Tools like
'click-check', 'click-devirtualize', and 'click-undead' look for your
package's elementmap in order to determine the properties of your elements.
It is generated by 'click-mkelemmap'.