[[https://blueprints.launchpad.net/nav/+spec/unified-source-tree|Blueprint at launchpad]]
===== Unified Source layout =====

This is a blueprint on how to make the source-tree of NAV a bit less complex,
and how to make it easier to develop in an local matter (no more "sudo make install")

==== Todays layout ====

Out current source code tree is heavily influenced by the fact that NAV started out
by using a number of different programming languages. This made the installation dependent
on numerous Makefiles for handling each subsytem to their needs. 

This is how it looks today:
<code>
|-- subsystem
|   |-- alertengine
|   |   |-- Makefile.in
|   |   |-- README
|   |   |-- alertengine.conf
|   |   |-- alertengine.in
|   |   |-- alertengine.py
|   |   `-- nav
|   |-- alertprofiles
|   |   |-- Makefile.in
|   |   |-- alertprofiles.tool
|   |   |-- config
|   |   |-- htaccess
|   |   |-- images
|   |   |-- media
|   |   |-- nav
|   |   `-- templates
|   |-- arnold
|   |   |-- ArnoldTemplate.tmpl
|   |   |-- Makefile.in
|   |   |-- arnold.py
|   |   |-- arnold.tool
|   |   |-- arnoldhandler.py
|   |   |-- autoenable.py
|   |   |-- config
|   |   |-- images
|   |   |-- lib
|   |   |-- start_arnold.py
|   |   `-- t1000.py
|   |-- dbTools
|   |   |-- Makefile.in
|   |   |-- README
|   |   |-- dump.py
|   |   `-- navclean.py
...
</code>

=== The problems with the old style layout ===

There are several issues with this design. As we converge to use more and more python,
we also try to collect all common modules in the ''lib-python''-subsystem. This is great and all
for keeping code-duplication down. However, since we do all import from the ''nav''-module (which is they everything is installed),
we cant reach this code from other subsystem without installing our changes system wide. This also imposes the same problems on
testing as the modules in question needs to be installed globally unless we have our tests in the same module as the code itself
and only do local imports.

==== New source layout proposal ====

The proposed new layout is based upon how most django based projects are organized.

<code>
../nav
|-- bin
|   |-- system1.py
|   `-- system2.py
|-- etc
|   |-- nav.conf
|   |-- system1.conf
|   `-- system2.conf
|-- doc
|   |-- getting-started.txt
|   |-- system1-setup.txt
|   `-- system2-setup.txt
|-- java
|   `-- java_app1
|-- media
|   |-- images
|   |-- js
|   `-- style
|-- python
|   `-- nav
|       |-- __init__.py
|       |-- system1
|       |   `-- __init__.py
|       |-- system2
|       |   `-- __init__.py
|       |-- system3
|       |   `-- __init__.py
|       `-- system4
|           `-- __init__.py
|-- sql
|   |-- nav-3.5.sql
|   |-- nav-3.6.sql
|   `-- trunk.sql
|-- templates
|   |-- system1
|   |-- system2
|   |-- system3
|   `-- system4
`-- tests
    |-- system1
    |-- system2
    |-- system3
    `-- system4
</code>

  * The ''bin'' directory holds all scripts that are to be used as executable commands, or "binaries", if you will.
  * The ''etc'' directory holds all configuration files. 
  * The ''doc'' directory holds documentation outside of the scope of the generic README/INSTALL/CHANGES/HACKING in the top level. 
  * The ''java'' directory holds the legacy java subsystems and other java code.
  * The ''sql'' directory holds our SQL schema baselines, initial data and upgrade scripts.
  * The ''templates'' directory holds all Django templates organized into the system they belong to
  * The ''tests'' directory holds our tests.
  * The ''media'' directory holds most of the static media files to be served by a web server (stylesheets, graphics, javascript).

This allows us to easily reach all other systems in nav without touching the system-wide installed files. Tests can be neatly organized and run on the development code
by supplying the PYTHONPATH to our source code.

This change does require quite some work though. All Makefiles must be changed, and systems dependand on relative paths to their configfile must be updated.
I do think it will be worth the job in the long run though.