Custom Reports

From GnuCash
Revision as of 17:00, 27 February 2007 by Oanjao (talk | contribs)
Jump to: navigation, search

Custom Reports in GnuCash

Unfortunately, at the present time writing a custom report for GnuCash requires a little bit of hacking. This wiki page should contain some information to help you get started, since there is no official documentation.

Note: I am using GnuCash 2.0.1 as I write this.

Example Reports

A good place to start is to examine the source code of the reports included with GnuCash. On my Gentoo system, they are located in

/usr/share/gnucash/guile-modules/gnucash/report

hello-world.scm is specially written to demonstrate the basic structure of a report.

The GnuCash API

The GnuCash application programming interface is quite intimidating. Luckily, for the reports, most of the stuff needed can be found in the scheme sources. Here some random examples of handy procedures (paths shown are based on a mac OS X 10.3.9 Fink installation):

  • create a monetary object: gnc:make-gnc-monetary /sw/share/gnucash/scm/gnc-numeric.scm
  • get the amount of a monetary object: gnc:gnc-monetary-amount /sw/share/gnucash/scm/gnc-numeric.scm
  • get an account name: gnc:account-get-name /sw/share/gnucash/guile-modules/g-wrapped/gw-engine-spec.scm

Programming tools

First of all, Scheme is a powerful and wonderful programming language. That said, without a proper editor the parenthesis balancing will drive you mad. Without the help of drScheme I would not touch any reasonable sized Scheme sourcecode. The killer function drScheme offers is the highlighting of the enclosed lines of code when clicking a start or end parenthesis. So you can quickly find out whether the hierarchy is as planned. drScheme is released under the GNU Library General Public License (LGPL).

Any reasonable editor, including emacs and vi, should provide basic syntax help for source-code editing.

Differences between Scheme implementations

Be aware of small differences in Scheme between various references and programming tools! For example, Dr. Scheme (and its associated programming book, How to Design Programs allow the use of square parenthesis in cond expressions, but this causes an error in Guile (the GnuCash interpreter). Other differences:

  • Dr. Scheme allows first in place of car and rest in place of cdr but Guile does not.
  • add more as you find them...

Loading the Report

There are two ways to load a report at startup of GnuCash: from a user account, or from the installation tree. You will likely want to use the user account approach.

From a user account

In your home directory, edit ~/.gnucash/config.user to add a line of the form: 

    (load-from-path "/path/to/my/personal/report.scm")

You will also have to comment out the line in the code for your report that defines the module: 

 ;(define-module (gnucash report my-report-module))

Then restart GnuCash.

See gnucash-user email from Derek Atkins.

From the installed report directory

Alternatively, you can copy the report to the installed report directory. Make sure you have included a module definition as shown above. Then edit the appropriate Scheme file to register your report with the reporting system. You will have to register the report in one of the following places, depending on which submenu you want it to appear.

  • Standard Reports: standard-reports.scm
  • Business Reports: business-reports.scm
  • Utility Reports: utility-reports.scm

Then restart GnuCash.

You will need to restart GnuCash every time you change a report.

If, like me, you run GC from within X11, you best start GC from a X11 terminal window. For debugging you might add log messages with gnc:warn, e.g. (gnc:warn "here I am")

gnc:debug only displays when some environment variable is set. I don't know where and how so I use gnc:warn instead.

Other Resources

Old GnuCash Report Information

(may be very out of date)

Learning Scheme

Retrieved from "https://wiki.gnucash.org/wiki/index.php?title=Custom_Reports&oldid=3321"