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

Next revision		Previous revision
devel:hacking [2009/02/09 10:15] – pasted in NAV's HACKING file. 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, +
-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.+
  
 +This document has moved to https://nav.uninett.no/doc/dev/hacking/hacking.html
devel/hacking.1234174507.txt.gz · Last modified: by morten
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki