Developer’s Guide¶

Source Tree Layout¶

cmake/: cmake scripts used as part of our build system.
src/: This is the algorithm source tree. Each algorithm is to be contained in its on sub-tree with /doc, /sql, /src, and /test sub-directories.

For example:

src/dijkstra Main direcotry for dijkstra algorithm.

src/dijkstra/doc Dijkstra’s documentation directory.

src/dijkstra/src Dijkstra’s C and/or C++ code.

src/dijkstra/sql Dijkstra’s sql code.

src/dijkstra/test Dijkstra’s tests.

Tools¶

tools/: Miscellaneous scripts and tools.

pre-commit¶

To keep version/branch/commit up to date install pelase do the following:

cp tools/pre-commit .git/hooks/pre-commit

After each commit a the file VERSION will remain. (The hash number will be one behind)

tester¶

The tester is executed from the top level of the tree layout:

tools/test-runner.pl --help

doxygen¶

Warning

Developers’s Functions documentation is going to be deleted from the pgRouting documentation and included in the doxygen documentation.

To use doxygen:

cd tools/doxygen/
make

The code’s documentation can be found in:

build/doxy/html/index.html

cpplint¶

We try to follow the following guidelines for C++ coding:

https://google-styleguide.googlecode.com/svn/trunk/cppguide.html

Sample use:

python cpplint.py ../src/dijkstra/src/dijkstra_driver.h
 ../src/dijkstra/src/dijkstra_driver.h:34:  Lines should be <= 80 characters long  [whitespace/line_length] [2]
 ../src/dijkstra/src/dijkstra_driver.h:40:  Line ends in whitespace.  Consider deleting these extra spaces.  [whitespace/end_of_line] [4]
 Done processing ../src/dijkstra/src/dijkstra_driver.h
 Total errors found: 2

Maybe line 34 is a very complicated calculation so you can just ignore the message
Delete whitespace at end of line is easy fix.
Use your judgement!!!

Some files like postgres.h are system dependant so don’t include the directory.

Other tools¶

Tools like:

doit
winnie
publish_doc.sh

are very specific for the deployment of new versions, so please ask first!

Documentation Layout¶

Note

All documentation should be in reStructuredText format. See: <http://docutils.sf.net/rst.html> for introductory docs.

Documentation is distributed into the source tree. This top level “doc” directory is intended for high level documentation cover subjects like:

Compiling and testing

Installation

Tutorials

Users’ Guide front materials

Reference Manual front materials

etc

Since the algorithm specific documentation is contained in the source tree with the algorithm specific files, the process of building the documentation and publishing it will need to assemble the details with the front material as needed.

Also, to keep the “doc” directory from getting cluttered, each major book like those listed above, should be contained in a separate directory under “doc”. Any images or other materials related to the book should also be kept in that directory.

Testing Infrastructure¶

There is a very basic testing infrastructure put in place. Here are the basics of how it works. We need more test cases. Longer term we should probably get someone to setup travis-ci or jenkins testing frameworks.

Here is the graph for the TRSP tests.

Tests are run via the script at the top level tools/test-runner.pl and it runs all the test configured tests and at the moment just dumps the results structure of the test. This can be prettied up later.

It also assumes that you have installed the libraries as it tests using the installed postgresql. This probably needs to be made smarter so we can test out of the build tree. I’ll need to think about that.

Basically each .../test/ directory should include one test.conf file that is a perl script fragment that defines what data files to load and what tests to run. I have built in some mechanisms to allow test and data to be pg version and postgis version specific, but I’m not using that yet. So for example, core/trsp/test/test-any-00.data is a sql plain text dump that will load and needed data for a set of tests. This is also the graph in the image above. You can specify multiple files to load, but as a group they need to have unique names.

core/trsp/test/test-any-00.test is a sql command to be run. It will get run as:

psql ... -A -t -q -f file.test dbname > tmpfile
diff -w file.rest tmpfile

Then if there is a difference then an test failure is reported.