NAV Wiki

User Tools

Site Tools

Trace: • source_file_headers • hacking
devel:hacking

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
devel:hacking [2009/02/09 11:24] – break list item lines (installed mllist plugin to enable this) mortendevel:hacking [2014/11/05 10:57] (current) – morten
Line 1: Line 1:
-:!: **Be warned, this information is becoming very out of date, it is currently being updated** :!: 
 ====== Hacker's guide to NAV ====== ====== Hacker's guide to NAV ======
  
-If you are contributing code to Network Administration Visualized, +This document has moved to https://nav.uninett.no/doc/dev/hacking/hacking.html
-please read this first. +
- +
- +
-===== Participating in the community ===== +
-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 +
- +
-  * Join the mailing lists.  The nav-dev mailing list in particular is +
-    for discussing NAV development.  So far, this is a low traffic +
-    list. We can only hope this will change ;-) +
-  * Get a copy of the latest development sources from +
-    https://svn.itea.ntnu.no/repos/nav/navme/trunk/. New development +
-    always takes place on trunk. Bugfixes, enhancements, and new +
-    features are backported from there to the various release +
-    branches. +
-  * Take a look at the project reports from previous development +
-    projects at NTNU (NAVMe, NAVMore, tigaNAV and others) - design +
-    specifications and other useful bits of historic NAV information +
-    is mostly to be found in these.  Unfortunately, some of the older +
-    project documentation is in Norwegian only.  Do not hesitate to +
-    ask for help on the mailing lists. +
- +
-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. +
- +
- +
-===== Directory layout ===== +
-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. | +
- +
- +
-===== Development languages ===== +
-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 your subsystem is a new tool for the web interface, use +
-    Python. The web interface is built using mod_python. Also, the +
-    integration with Cricket uses Cricket's web front-end, which is +
-    Perl CGI. +
-  * If your subsystem is a new back-end tool/daemon, please use +
-    Python. The Python API created for NAV is more complete than for +
-    any of the other languages, and you will receive a lot for free. +
-    You may use Perl if you absolutely abhor Python, but then you will +
-    be frowned upon. +
- +
-If *YOU* are willing to invest in porting some of the existing code to +
-Python, then you will be celebrated as a NAV hero! +
- +
- +
-===== Coding style ===== +
-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: +
- +
-  * For Java code, please refer to SUN's "Code conventions for the +
-    Java Programming Language": http://java.sun.com/docs/codeconv/ +
-  * For Python code, please refer to PEP-8, "Style Guide for Python +
-    Code" http://www.python.org/doc/peps/pep-0008/ +
- +
-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. +
- +
- +
-===== Database connections ===== +
-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: +
- +
-| ''manage''      | The core knowledge database of NAV, containing all sorts of information about the monitored IP Devices, events, alerts, network topology and machine tracking data. | +
-| ''navprofiles'' | Contains NAV user accounts and groups, user preferences and alert profiles. | +
-| ''logger''      | Contains syslog entries collected by the syslog parser/browser system. | +
-| ''arnold''      | The port detention system Arnold stores it's data here. | +
- +
-To obtain a connection to the NAV database, use the API accordingly, +
-e.g.: +
- +
-<code python> +
-import nav.db +
-# Get a connection to the manage database +
-connection = nav.db.getConnection('default', 'manage') +
-</code> +
- +
-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". +
- +
- +
-===== Web interface ===== +
-When programming for NAV's web interface, a few special considerations +
-need to be made. +
- +
-==== Mod_python ==== +
-NAV uses mod_python to interface with the Apache web server.  See +
-http://www.modpython.org/. +
- +
-==== Cheetah Templates ==== +
-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. +
- +
-==== Database connections in the web interface ==== +
-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: +
- +
-  * Do not, under any circumstances, retain references to a database +
-    connection between client requests.  Make sure to retrieve a new +
-    connection at the start of each request cycle - the API will cache +
-    connections between requests, and will automagically re-open +
-    broken connections.  As the connection is shared between several +
-    modules, retained references may be invalid in the next request +
-    cycle. +
-  * Do not explicitly close database connections.  Although the API +
-    will try to reopen any closed or broken connections, you create +
-    extra overhead, and you don't play nice with the other web +
-    modules. +
-  * Do not enable/disable autocommit or alter a connection's +
-    transaction isolation level, unless you make pretty darn sure to +
-    reset them to their original states at the end of a request cycle. +
-  * NAV 3.0 makes connections autocommit by default, whereas NAV 3.1 +
-    will not - make sure to commit your transactions when needed.  NAV +
-    will help unfortunate souls by attempting to commit transactions +
-    in a mod_python cleanuphandler, but you should nevertheless +
-    explicitly call connection.commit to avoid having your +
-    transactions accidentally rolled back. +
devel/hacking.1234178650.txt.gz · Last modified: by morten
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki