
  ntrack - Network Status Tracking made easy for Desktop Applications

Licensing
===========

    Copyright 2009-2011  - Alexander Sack <asac@jwsdot.com>

    ntrack is free software: you can redistribute it and/or modify
    it under the terms of the GNU Lesser General Public License as
    published by the Free Software Foundation, either version 3 of
    the License, or (at your option) any later version.

    ntrack is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with ntrack.  If not, see <http://www.gnu.org/licenses/>.

    Full license text available in COPYING and COPYING.LESSER


Project/Contact Info
======================

   Project-Home:  http://launchpad.net/ntrack
   Bug-Tracker:   http://bugs.launchpad.net/ntrack
   Email:         primary: asac@jwsdot.com (primary)
                  backups: asac@ubuntu.com, asac@debian.org or asacasa@gmail.com


Requirements - Linux
=====================

_ntrack_ has very minimal requirements on the build and runtime system. For
building you need a recent linux system with a recent _gcc_, _binutils_ as well
as _autotools_ and libc. While there surely are lower limits on versionoing on
each of them, there have been none reported which authors of ntrack interpret as
ntrack being suitable for all reasonable common linux based systems. 

_ntrack_ has a modular build and runtime approach. It supports various libnl
and kernel versions being supported on the backend site of ntrack and various
toolkit convenience and language bindings being availble on the front of ntrack
to make adoption in all kind of linux worlds easy.

If you find a linux system that cannot build/run ntrack on, please report it as
a bug and contact the authors through other means mentioned above.

Below more details on which modules and bindings are available and their
requirements on build and runtime systemes.


Modules:

in order to use ntrack you need to have at least one module matching your
runtime requirements build and installed on your system. ntrack currently
supports libnl and direct kernel (rtnetlink) backends.

_libnl_: One or multiple libnl modules suitable for different libnl versions
are supported to be produced in the same build run if you can make them
available in the path searched by your configure run. Below how the
PKG_CHECK_MODULES decides which one to enable:

  * libnl: PKG_CHECK_MODULES(LIBNL1, libnl-1, 
  * libnl2: PKG_CHECK_MODULES(LIBNL2, libnl-2.0, ...
  * libnl3: PKG_CHECK_MODULES(LIBNL3, libnl-3.0 = 3.0, ...
  * libnl3.1: PKG_CHECK_MODULES(LIBNL3_1, libnl-route-3.1, ...
  * libnl3.x: PKG_CHECK_MODULES(LIBNL3_X, libnl-route-3.0 > 3.1, ...

_rtnetlink_: On top of libnl ntrack, recent ntrack versions support direct
rtnetlink kernel interface. While more recent, ntrack authors recommend using
this module to avoid the odd/buggy behaviour of libnl*. rtnetnlink module can
be build as long as you have kernel headers available on your build system.
We use the following autoconf check to determine whether to build this module:

  * rtnetlink: AC_CHECK_HEADER(linux/netlink.h, ...


Bindings:

ntrack supports multiple language and toolkit bindings to allow pervasive and easy
adoption in all kind of linux vertical worlds. The build system can provide one
or many bindings in one run; you auto enable each by making the build requirements
available in your build environment. The following autoconf checks are used to
determine whether one language/toolkit binding can be provided:

  * qt4: PKG_CHECK_MODULES(QTCORE, QtCore,...
  * glib: PKG_CHECK_MODULES(GLIB, glib-2.0,...
  * gobject: PKG_CHECK_MODULES(GOBJECT, gobject-2.0,...
  * pygobject: PKG_CHECK_MODULES(PYGOBJECT, pygobject-2.0,...
    or pygtk (older systems): PKG_CHECK_MODULES(PYGOBJECT, pygtk-2.0,...


Getting Started (Developer Build)
==================================

If you start of from a bzr checkout you need to generate the autotools bits
before you can get started. If you have a recent autotools package installed,
following command should give you a convenient way to get the tree to that
state:

	1. Configure with autotools
		$ sh autogen.sh

Developer build searches for modules in various source places

	1. Configure the source tree:
	   (Note: run ./configure --help for options)
		$ mkdir build/
		$ cd build/
		$ ../configure --enable-developer-build

	2. Build the sources
		$ make

	3. Build tests and run automated tests
		$ make check

	4. Run the example net monitor
		$ ./common/test/mtest_monitor

	5. Submit patches \o/


Selecting Backend Module (Build)
=================================

Make requirements mentioned in "Modules" section above
available and configure your source tree like:

	$ mkdir build/
	$ ../configure

This will build the default backend (see ../configure --help
for up to date documentation what is the default). As of ntrack
015 it was:

	--enable-backend=[ARGS] select one or more backends
	                        from: libnl and rtnetlink
	                        [default=libnl]

You can select one or many backends to build through the
--enable-backend=... configure switch. In this sense

	$ ../configure --enable-backend=libnl

will build libnl backends. Remember that libnl can produce
multiple backend binaries if more than one libnl version .pc
file can be found. To build rtnetlink backend only, use

	$ ../configure --enable-backend=rtnetlink

to build both, provide a comma separated list:

	$ ../configure --enable-backend=libnl,rtnetlink

When building multiple backends, remember to read the runtime
selection info in the section below.


Selecting Backend Module (Runtime)
===================================

For now, ntrack does not implement a mean to prioritize
or select a module explicitly. The implemented strategy
will attempt to load all backends found in random order
and use the first backend that can be dlopen'ed.


Example Code
=============

There is at least one mtest that shows how to react on network state for each of the available bindings:

 * common/test/mtest-monitor.c - example for plain C with its own mainloop
 * glib/test/mtest-gsource.c - example for glib binding using a GSource derivate; hooks up into glib mainloop
 * gobject/test/mtest-gobject.c - example of gobject binding using a monitor object with signals
 * qt4/test/mtest-qmonitor.c - example of qtcore binding reusing qt4 mainloop

