Difference between revisions of "Custom Reports"

Revision as of 12:53, 8 September 2010

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.

Update June 2009

A new method of creating reports is now available. See Custom Reports Using Eguile.

Example Reports

A good place to start is to examine the source code of the reports included with GnuCash. The location varies a little with different operating systems:

• On BSD look in /usr/local/share/gnucash/guile-modules/gnucash/report
• On OpenSuse look in /opt/gnome/share/gnucash/guile-modules/gnucash/report
• On Gentoo, Ubuntu, Foresight look in /usr/share/gnucash/guile-modules/gnucash/report
• On Windows look in C:\Program Files\gnucash\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 refer to the location in a source tarball; might be copied into the location as above in your installation):

• create a monetary object: gnc:make-gnc-monetary src/engine/gnc-numeric.scm
• get the amount of a monetary object: gnc:gnc-monetary-amount src/engine/gnc-numeric.scm
• get an account name: gnc-account-get-name src/engine/swig-engine.c
• create a commodity collector: gnc:make-commodity-collector src/report/report-system/report-utilities.scm

Watch out for the gnucash version in use: In 2.0.x, the Scheme wrappers were created by G-WRAP, started with gnc: (with a colon) and were written into scheme files of the name gw-something.scm. In 2.1.x and later, the Scheme wrappers are created by SWIG, start with gnc- (a dash, not a colon) and were written into C files of the name swig-something.c. Please keep that in mind if the old documentation points you towards functions like these: Get an account name: gnc:account-get-name src/engine/gw-engine-spec.scm

Programming tools

Any reasonable source/text editor, including emacs and vi, should provide basic syntax support for source-code editing. One of the most basic and important for editings scheme/lisp sources is parenthesis matching. Other scheme environments (such as drScheme) might also be useful for editing the sources, but note that they might allow constructs that are not valid in guile.

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.

Before you load the report

• To avoid symbol definition conflicts with other reports, make sure your report code begins with a define-module statement:

  (define-module (gnucash report unique-report-name))

  like for example

  (define-module (gnucash report my-custom-invoice))

• Make sure your report has a unique name (for GnuCash 2.2.x and before) or a unique id (GnuCash 2.3.x and later). These are set at the end of your code in a gnc:define-report statement.

From a user account

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

    (load "/path/to/my/personal/report.scm") ;; Linux
    (load "X:\\path\\to\\my\\personal\\report.scm")  ;; Windows

Note that in Windows, double backslashes are required since backslash is a special character and must be escaped. In Windows, your GnuCash settings folder is usually C:\Users\YourName\.gnucash, or in Windows XP, C:\Documents and Settings\YourName\.gnucash

Note: Without a leading '/', all paths are taken relative to ~/.gnucash

Then restart GnuCash. You will have to do this every time you change a report.

Thanks to DeanCording for clarifying the define-module/load bits

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 have to do this every time you change a report.

Debugging your report

There is not really a debugger available for guile, but you can have your code write debug messages to help you trace your code.

• Start GnuCash like

  gnucash --debug --log gnc.scm=debug

  to enable debugging messages.
• Add debugging messages with the (gnc:debug) variable, e.g. (gnc:debug "here I am").
• There are also (gnc:msg), (gnc:warn) and (gnc:error) functions; see src/scm/main.scm for more details.
• Messages will be logged to /tmp/gnucash.trace by default, you can change this with --logto (try 'stderr' or 'stdout').

Other Resources

Old GnuCash Report Information

(may be very out of date)

• Version 1.6 report documentation
• FAQ#Q:_I.27d_like_to_write_my_own_custom_reports._Where_should_I_start.3F
• From the mailing list

Learning Scheme

• MIT Scheme Index
• Teach Yourself Scheme in Fixnum Days
• Structure and Interpretation of Computer Programs
• How to Design Programs
• Mastering Scheme is highly eased after reading The Scheme Progamming Language by R. Kent Dybvig
• Guile documentation