Developer Getting Started

Developer - Getting Started

Getting started in a new development environment is always very hard because there are a lot of things to learn all at once. I hope this page will give you a good starting point and set you on the right path. I'm pretty old school and do everything from the command line. There may be other even better ways to do a lot of this stuff and if so, I hope other will add to the documentation.

If you plan to implement something for inclusion into pgRouting, I would recommend discussing it on the pgrouting-dev list and writing an RFC that describes what you are planning and how you plan to implement it. This give you a chance to layout an initial design and get feedback for the other developers on the list. You do not need to do an RFC if you plan to fix bugs or just update the documentation. There is a PSC (at this time I may be the only active member of that left on the list), and RFC 01 describe the administrative process and it would be a good idea to read through that one page.

Overview of getting started

First and foremost, subscribe to the prgrouting-dev list pgrouting-dev@lists.osgeo.org at http://lists.osgeo.org/mailman/listinfo/pgrouting-dev

1. install postgresql 9.2+ and postgis 2.1+
2. create a fork on github of pgRouting
3. clone and compile your fork and install
4. run through the new workshop exercises
5. pick a bug and learn to debug it (see wiki pages on development)
6. ask questions - there are a lot of moving pieces and we do not expect you to understand them all initially.
7. if you get a fix, generate a pull request
8. go to #5, or pick an enhancement or new feature you would like to add and start a discussion about it on the dev list. You will get a lot of valuable feedback from the experts here.

We welcome students and developer that want to get involved with pgRouting. Most of us work on this because we love the project and devote a lot of free time to support it.

READ: Developer How to debug

Ok, lets get down to the real stuff the brought you to this page ...

Step 1 - We need some source code to work with!

So we can grab a copy from github with:

git clone git@github.com:pgRouting/pgrouting.git
cd pgrouting

Next we should try to compile and install this, and if we don't have all the prerequisites than we need to resolve them. Resolving the prerequisites is specific to the OS distribution you are using so I will not try to cover it here. If you need help post a message on the pgrouting list and ask for help.

# to keep it simple to start leave -DWITH_TSP=ON -DWITH_DD=ON off the next line 
cmake -DWITH_TSP=ON -DWITH_DD=ON .
make
sudo make install

This is the basics to compile and install. make install will copy librouting.so librouting_dd.so librouting_tsp.so to /usr/lib/postgresql/8.3/lib/ or the appropriate path on your system. the later two .so files are for -DWITH_DD=ON and -DWITH_TSP=ON respectively and will not get copied if you don't need them.

You need to restart the server if you change these libraries when developing.

Debugging is trickier. If you need to debug code running in the database in gdb you can do it like this:

# In one window start psql
psql -U postgres -h localhost mydb
mydb=# select * from pg_backend_pid();
 pg_backend_pid
----------------
           4576
(1 row)


# in another window
sudo -u postgres gdb
(gdb) attach 4576
(gdb) b my_c_code_function
Function "my_c_code_function" not defined.
Make breakpoint pending on future shared library load? (y or [n]) y

# now back in psql run a sql query that will hit this breakpoint
# and you should be in the debugger in the other window.
# you can "detach" in gdb and then "quit" to exit gdb

If you just want some simple output in the form of NOTICEs then you can add to your C code the following and you can call DBG(format, args...) if you use:

// #undef DEBUG
#define DEBUG 1

#ifdef DEBUG
#define DBG(format, arg...)                     \
    elog(NOTICE, format , ## arg)
#else
#define DBG(format, arg...) do { ; } while (0)
#endif

This will display NOTICE messages in the out put when it runs. If you are calling C++, you will need to figure out how to call this from C++ or open a log file and write messages to that. Yeah, these are stoneage tools but if you find a better way please share.

If you look at the trsp branch you will find the code in extra and this is probably a good example to follow for how to add your own code. It builds into its own librouting_trsp.so so this can be installed separate from change the core code. If you are planning to add functionality this is the preferred method of structuring your code.

extra/trsp/sql/ -- has the plpgsql wrappers that link to the library
extra/trsp/src/ -- has the C and C++ code to build the library

When this project was done, Ashraf working in Bangladesh developer the C++ code in a Windows environment and wrote his own main for testing and debuging from a postgresql free environment. Once this code was working and debuggged, I wrote the trsp.c and trsp_core.cpp on Linux to link to his code and debugged the postgresql side of things using the DBG() macros above.

So try to just walk through this much to start. I think the key here is to divide and conquer. If you notice the C code really does little more than talk to the server and create structs that get passed to the solver and then take the solver results and pass them back to postgresql. The solver should get developed and tested outside this environment and once it is vetted then drop it in and you can focus you debugging on the data handling and not the solver. Also we made the solver main so that we could easily pass create a dump of the data from sql to a text file and then read that into the solver for testing. When something broke, it was easy to verify if it was a solver or interface issue.

Need more help? ask on the list and we are all happy to help out.