This is an old revision of the document!
If you are contributing code to Network Administration Visualized, please read this first.
Originally, NAV was a closed source project, initiated by the Norwegian University of Science and Technology (NTNU), and eventually sponsored by UNINETT on behalf of the Norwegian higher education community. In 2004, however, NTNU and UNINETT started distributing NAV under the GNU General Public License, making it a true open source project.
While NTNU and UNINETT still are the main contributors to NAV, developing NAV to support the needs of the Norwegian higher education community, volunteer work from other interested parties is highly appreciated.
The community exists mainly through mailing lists, a wiki and a Subversion repository, although UNINETT also arranges seminars and gatherings for its target audience: Norwegian universities and university colleges. To participate:
Go to http://metanav.uninett.no/ and
If you wish to contribute code to the project, please tell us about it on the nav-dev mailing list. It is always a good idea to check if someone is already working on something similar, and to get some helpful tips on how to integrate your code with the rest of the project. If you already went ahead and wrote a patch, announce it on nav-dev and provide a link to the patch so it can be studied for possible inclusion into NAV.
A rough guide to the source tree:
* conf/
Files related to the autoconf build system.
* doc/
User and developer documentation, SQL scripts and example NAV configuration files.
* tools/
Tool scripts for the build process.
* contrib/
Stuff that works with NAV, but that NAV doesn't depend on, and that is maintained by individuals who may or may not participate in NAV development.
* packages/
Stuff to help packaging systems, like rpm and dpkg.
* src/
Source code to Java subsystems of NAV (still here for historic reasons).
* subsystem/
Source code to the rest of NAV - a lot of Python. NAV is loosely divided into subsystems, and each one of these has its own subdirectory in here.
* subsystem/lib-python/
Python libraries & APIs. Please check what's already there before you roll your own.
* subsystem/lib-perl/
Perl libraries & APIs. Please check what's already there before you roll your own.
* subsystem/webfront/
Python libraries for the web interface and front-page handler modules for mod_python.
For historic reasons, NAV today is made up of several programming languages - these are Python, Java and Perl. Although this is unfortunate in many ways, no-one has been willing to invest in the time needed to rewrite stuff to reduce the number of languages.
When contributing patches to existing code, or plugins to existing subsystems, use the language that subsystem was written in.
When writing entirely new subsystems, the following rules apply:
If *YOU* are willing to invest in porting some of the existing code to Python, then you will be celebrated as a NAV hero!
NAV has not previously bothered with having coding style guidelines. This has resulted in some chaotic combination of styles, which we hope to reduce in the future. For new code, please follow these guidelines:
If you see violations of these guidelines, don't hesitate to report them and/or fix them :) If you fix file-wide indentation problems etc., please submit this as a separate patch to make your other patches look clean and readable.
NOTE: The following is Python-specific, more info should be added for the other languages used in NAV.
The NAV database actually consists of four PostgreSQL databases (although there are plans to merge them into a single database using PostgreSQL's support for schemas). The databases are:
To obtain a connection to the NAV database, use the API accordingly, e.g.:
import nav.db # Get a connection to the manage database connection = nav.db.getConnection('default', 'manage')
The above code will open a connection to the manage database, or, if the connection had already been opened during the lifetime of the current process, returns the already existing connection from a connection cache.
The 'default' parameter is there for legacy reasons; the db.conf file allows one to configure separate database users for each subsystem (known as a script in db.conf) of NAV, but it is recommended to use only one user for all NAV database connections - hence the default “subsystem”.
When programming for NAV's web interface, a few special considerations need to be made.
NAV uses mod_python to interface with the Apache web server. See http://www.modpython.org/.
The NAV web interface makes extensive use of Cheetah templates for generating its HTML output, see http://www.cheetahtemplate.org/ .
Most of the existing Cheetah templates are to be found in subsystem/webfront/nav/web/templates, although some of NAV's subsystems store their templates along with their code in their respective subsystem subdirectories. The compiled templates should be placed in the nav.web.templates package.
If you are making a new web module for NAV, your module's Cheetah template should subclass MainTemplate.tmpl found in subsystem/webfront/nav/web/templates/. See other templates for code examples of how to inherit from this template.
As stated above, use the nav.db.getConnection function to open or retrieve an existing database connection. All NAV web modules share the same interpreter and namespace per Apache process, which also means that database connections will be shared between the modules running in each process. Therefore, the following conventions apply for connections obtained from nav.db.getConnection: