| qof_book_merge: 'Query Object Framework: Design and direction.' | ||
|---|---|---|
| Prev | Chapter 4. Creating GnuCash Invoices using a Palm PDA | Next |
This section is meant to be helpful and useful - nothing here is intended as a rule or to be interpreted as the only way to do things. It is not meant as patronising either, I made mistakes when starting this mini-project because this kind of project was so unfamiliar to me.
The critical areas for me are highlighted above. The up to date source documentation provided by Doxygen is always the first place to look for answers. General overviews and design texts do exist but you need to use and understand the program before most of this will make any sense. All documentation must choose a starting level and mine will mimic my own start:
Experience of C++ more than C - able to write and compile console programs, design C++ classes and implement inheritance. Includes some gaps in C knowledge, specifically function pointers.
A real need, not just curiosity. GnuCash is a large program and trying to learn it all is more than most people need. To pick up GnuCash, QOF and the vagaries of using only C, I can only recommend a clear objective that relates to an existing GnuCash objective - you can't expect a lot of assistance from GnuCash developers if you are not working on a project that is seen to be useful to the rest of GnuCash.
Experience of GnuCash itself, preferably in situations where the figures are real and the calculations matter. A tax return focuses the mind very well.
Time - always more than you had originally planned.
Patience. If you don't have much patience, you probably wouldn't still be reading!
http://www.gnucash.org/. Read the "Developer Information" section and join the gnucash-devel mailing list.
Make sure what you want GnuCash / QOF to do coincides with what the rest of the developers consider useful. Explain your ideas and like my experience above, be prepared to:
Alter your own plans substantially.
Provide good reasons for not altering the bits you want to keep.
Acknowledge your strengths AND weaknesses and ask for help.
Keep to what you know you can achieve - don't be tempted into taking on a larger project than you can manage.
Keep it simple, concise and informative - other developers are busy too.
Download the CVS HEAD and build it.
Spend lots of time understanding the current Doxygen output.
There are lots of sites that have helped me understand QOF, GnuCash, automake, doxygen, glib, libxml and Glade. In the hope that some might be useful . . .
http://www.gnu.org/manual/manual.html GNU Manuals Online, autoconf, autogen and automake.
http://developer.gnome.org/doc/API/2.0/glib/index.html GLib Reference Manual - GLib is a general-purpose utility library, which provides many useful data types, macros, type conversions, string utilities, file utilities, a main loop abstraction, and so on. It works on many UNIX-like platforms, Windows, OS/2 and BeOS. GLib is released under the GNU Library General Public License (GNU LGPL).
QOF does NOT require Gtk or any GUI elements. These are provided to aid GnuCash development.
http://developer.gnome.org/doc/API/2.0/gtk/index.html GTK+ Reference Manual
http://glade.gnome.org/ Glade is a free user interface builder for GTK+ and GNOME. It is released under the GNU General Public License (GPL).
http://www.yolinux.com/TUTORIALS/GnomeLibXml2.html YoLinux Tutorial - XML and Gnome libXML2
http://www.w3.org/TR/xmlschema-0/primer.html#Intro XML Schema Part 0: Primer Second Edition, Introduction.
http://www.xmlsoft.org/ The XML C parser and toolkit of Gnome.
http://www.eskimo.com/~scs/cclass/int/sx10a.html Declaring, Assigning, and Using Function Pointers.
The current XML data store format used within GnuCash has served well but is slated for removal in a future release. XML is better suited to data interchange than permanent data storage and QSF represents the best way to continue the use of XML for interchange between QOF programs using existing (and trusted) code. The current GnuCash XML format is too hierarchical for generic QOF use and uses non QOF structures to write out the file.
Use src/engine/gnc-trace.c gnc_log_modules to your advantage. The version in CVS tends to favour the area of largest development need. This will produce debugging logs that concentrate on those sections of the codebase. If you are working on another section, change the log levels to suit your needs and compile. The sequence is laid out in gncLogLevel in the header file: src/engine/gnc-trace.h - GNC_LOG_WARNING will ignore all but the most serious errors. To see more of what is going on, change the log level for the module to a more inclusive setting like GNC_LOG_DEBUG. Keep the comments intact to identify which line affects which module! The output is written, by default, to /tmp/gnucash.trace although this can also be changed in gnc-trace. Remember NOT to commit these changes back to CVS!
Use ENTER (" ");, LEAVE (" "); and PINFO(" "); in your code to create your own log messages like:
Info: qof_session_load(): new book=0x84266b8
Note that the function name is added automatically. To output variable values, use printf() syntax. e.g. the command to generate that log message is:
PINFO ("new book=%p", newbook);Try to avoid using log functions in callback routines or iterative loops - at least in the code committed to CVS. The log output needs to be clear for others, not bloated with hundreds of identical entries.
Use the comments in HACKING to link into GDB or Valgrind. You can also use gdb by using two terminal windows:
term1 gnucash/bin>$ ./gnucash term2 ~>$ ps waux | grep guile term2 ~>$ gdb gdb> attach 1234 gdb> continue
Replace 1234 with the process ID of the guile process identified by ps. GDB will then load a lot of debugging symbols before you can enter the continue command. The advantage of this method is that the initialisation of GnuCash does not operate within the supervision of GDB and therefore runs at normal speed. You can use GnuCash to create a test environment, load the relevant files etc., without the penalty of gdb inspecting every call until you need it. I use this method to find the cause of segmentation faults within the program more quickly than using gdb from the beginning.
GnuCash saves user space settings in ~/.gnucash/ and in ~/.gnome/GnuCash - if you use the gnucash-gnome2-dev branch, it uses ~/.gnome2/GnuCash. General configuration settings go in ~/.gnucash, file history and others go in ~/.gnome or ~/.gnome2