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 10:21] – reformat most of it to wiki syntax mortendevel:hacking [2014/11/05 10:57] (current) – morten
Line 1: Line 1:
 ====== 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 dta. +
-  * '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.: +
- +
-  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". +
- +
- +
-===== 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.1234174913.txt.gz · Last modified: by morten
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki