gnucash/HACKING

237 lines
8.5 KiB
Plaintext
Raw Normal View History

Hacking Guidelines
==================
This document is an introduction to hacking on GnuCash.
Related Documents
-----------------
In addition to this file, you should read the README file, which
explains the details of getting the SVN source, building GnuCash,
and creating patches for submission.
The src/doc/design directory contains a preliminary design document
which you should read as well. You should also feel free to hack on
the design document.
Coding Style Conventions
------------------------
General:
* When modifying a file, the style convention in that file should be
followed.
* When creating a new file, the style of existing files should be
followed.
* When creating lots of new files in a new directory, you may use
your own coding standards, but please try to stick as closely as
possible to the GNU coding standards.
* Do not submit patches that consist of (gratuitous) stylistic changes.
C:
* Use ISO C.
* Use glib memory routines where possible. This means you should be
using g_malloc(), g_new(), g_free(), etc., instead of malloc(),
free(), etc. Do not mix glib memory calls with libc calls!
* Where possible, use glib data abstractions instead of rolling your
own. Glib linked lists and pointer arrays are very convenient and
have been extensively used and tested.
* All gnucash functions and global variables are prefixed with gnc_
* Use static functions whenever possible
* Use const whenever possible
Scheme:
* All gnucash functions and global variables are prefixed with gnc:
* All global variables are enclosed in ** (i.e. gnc:*load-path*)
* All private functions are enclosed in __ (i.e. gnc:_do-not-call_)
* All C functions wrapped into scheme have dashes in place of underscores.
(xaccSplitGetBalance --> gnc:split-get-balance) - but FIXME:
This policy seems to have been dropped in favor of having
identical function names. cstim, 2006-10-30.
Dave Peticolas <dave@krondo.com>
August 22, 2000
==============
TIPS AND HINTS
==============
Starting GnuCash from the build tree
------------------------------------
This is known to not work very well. Instead, `--prefix` your build into /opt/gnc/svn/ (or some such).
Getting Trace Messages From GnuCash
-----------------------------------
See the doxygen comments in lib/libqof/qof/qoflog.h (and .c)
Starting GnuCash in GDB
-----------------------
To run gdb on an installed version of gnucash (installed in /opt/gnc/unstable:)
% gdb /opt/gnc/unstable/bin/gnucash
OS X/Quartz developers can't run gnucash in gdb this way. They should instead use:
% /opt/gnc/unstable/bin/gnucash-gdb
You'll also probably want to know about these:
gdb> catch fork
gdb> set follow-fork-mode child
-----
It may be the case that running GDB from within emacs doesn't work for you,
with the following error:
[C-u M-x gdb /opt/gnucash-cvs/bin/gnucash
...in buffer *gud-gdb*:]
(gdb) attach <pid>
jsled needed to re-define a gud.el function as such:
(defun gud-gdb-massage-args (file args)
(let ((l (copy-list args)))
(nconc l (list "-cd" (expand-file-name default-directory) "-fullname"))))
jsled does not need the above with emacs-22, thankfully. It was getting quite tiresome.
Using Electric Fence with GnuCash
---------------------------------
% configure --enable-efence
(except this doesn't actually enable efence :-( need to hack
configure.in and add $LIBS = -lefence and re-run ./autogen.sh)
Don't know why, efence does not currently work with gnucash:
I get a bunch of errors:
warning: Cannot initialize thread debugging library: unknown thread_db error '22'
If you know how to fix this, please update these instructions.
Using Valgrind with GnuCash
---------------------------
-- run ${prefix}/bin/gnucash-valgrind
However, I did not find valgrind to be useful. It reported a bunch of
guile bugs, some g_hash_table bugs, and then the program exited prematurely
for no apparent reason. :-(
For the moment, gnucash-valgrind uses the suppressions in
src/debug/valgrind/valgrind-*.supp
2004-03-07 Joshua Sled <jsled@asynchronous.org> * HACKING: Added instructions about running under valgrind. * lib/gnucash_valgrind.supp: Added a large set of valgrind suppressions for both guile and gnucash. * src/register/ledger-core/gnc-ledger-display.c (gnc_ledger_display_template_gl): Change the reg_type to SEARCH_LEDGER so all the 'action' types appear. Bug#108833. * src/gnome/glade/sched-xact.glade: Remove unused 'ledger_status' widget. Bug#102269. * src/gnome-utils/gnc-dense-cal.c (gnc_dense_cal_draw_to_buffer): At least be consistent about the background coloring of the month labels, even if we're still not using GTK themeage correctly. * src/gnome-utils/gnc-dense-cal.c (gnc_dense_cal_destroy): Destroy the transient window when the widget is destroyed. Bug#103910. * src/gnome/dialog-scheduledxaction.c (gnc_ui_scheduled_xaction_editor_dialog_create): Make the advance and remind spin-buttons editable [Bug#94963]. * src/gnome/glade/sched-xact.glade: Change the upper bound on the advance and remind spins to 365 [days], with a page-size of 30 [days]. * src/gnome/dialog-sx-from-trans.c (gnc_sx_create_from_trans): Disallow the Scheduling of being-editing transactions in the Register, preventing a class of unbalacned SX template transactions from being entered and propogated through the system. See Bug#130330. * src/engine/FreqSpec.c (xaccFreqSpecGetFreqStr): Fix nasty memory-corruption issue; insufficent bounds checking on array index. Bug#125600. * src/gnome/dialog-sxsincelast.c (create_each_transaction_helper): Better handling of various error cases in transaction-creation. Bug#120311; Bug#130330. 2004-03-01 Joshua Sled <jsled@asynchronous.org> * src/gnome/dialog-scheduledxaction.c (gnc_sxed_check_consistent): Fix for part of Bug#121740 -- only allow auto-create SXes which have splits to be created. 2004-02-07 Joshua Sled <jsled@asynchronous.org> * src/gnome/dialog-scheduledxaction.c (editor_ok_button_clicked): * src/gnome-utils/gnc-frequency.c (gnc_frequency_save_state): * src/backend/file/gnc-freqspec-xml-v2.c (fs_none_handler): * src/engine/FreqSpec.c (xaccFreqSpecGetFreqStr): Adding "NONE" as an allowable FreqSpec [Bug#103968]. git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@9858 57a11ea4-9604-0410-9ed3-97b8803252fd
2004-03-10 19:17:14 -06:00
For valgrind-gnucash.supp, this comment was made (but is perhaps outdated
by now ?):
2004-03-07 Joshua Sled <jsled@asynchronous.org> * HACKING: Added instructions about running under valgrind. * lib/gnucash_valgrind.supp: Added a large set of valgrind suppressions for both guile and gnucash. * src/register/ledger-core/gnc-ledger-display.c (gnc_ledger_display_template_gl): Change the reg_type to SEARCH_LEDGER so all the 'action' types appear. Bug#108833. * src/gnome/glade/sched-xact.glade: Remove unused 'ledger_status' widget. Bug#102269. * src/gnome-utils/gnc-dense-cal.c (gnc_dense_cal_draw_to_buffer): At least be consistent about the background coloring of the month labels, even if we're still not using GTK themeage correctly. * src/gnome-utils/gnc-dense-cal.c (gnc_dense_cal_destroy): Destroy the transient window when the widget is destroyed. Bug#103910. * src/gnome/dialog-scheduledxaction.c (gnc_ui_scheduled_xaction_editor_dialog_create): Make the advance and remind spin-buttons editable [Bug#94963]. * src/gnome/glade/sched-xact.glade: Change the upper bound on the advance and remind spins to 365 [days], with a page-size of 30 [days]. * src/gnome/dialog-sx-from-trans.c (gnc_sx_create_from_trans): Disallow the Scheduling of being-editing transactions in the Register, preventing a class of unbalacned SX template transactions from being entered and propogated through the system. See Bug#130330. * src/engine/FreqSpec.c (xaccFreqSpecGetFreqStr): Fix nasty memory-corruption issue; insufficent bounds checking on array index. Bug#125600. * src/gnome/dialog-sxsincelast.c (create_each_transaction_helper): Better handling of various error cases in transaction-creation. Bug#120311; Bug#130330. 2004-03-01 Joshua Sled <jsled@asynchronous.org> * src/gnome/dialog-scheduledxaction.c (gnc_sxed_check_consistent): Fix for part of Bug#121740 -- only allow auto-create SXes which have splits to be created. 2004-02-07 Joshua Sled <jsled@asynchronous.org> * src/gnome/dialog-scheduledxaction.c (editor_ok_button_clicked): * src/gnome-utils/gnc-frequency.c (gnc_frequency_save_state): * src/backend/file/gnc-freqspec-xml-v2.c (fs_none_handler): * src/engine/FreqSpec.c (xaccFreqSpecGetFreqStr): Adding "NONE" as an allowable FreqSpec [Bug#103968]. git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@9858 57a11ea4-9604-0410-9ed3-97b8803252fd
2004-03-10 19:17:14 -06:00
This file needs to be cleaned up in two ways:
1/ There are a bunch of duplicate suppressions in the file.
* The suppressions in place were auto-generated by valgrind itself
2004-03-07 Joshua Sled <jsled@asynchronous.org> * HACKING: Added instructions about running under valgrind. * lib/gnucash_valgrind.supp: Added a large set of valgrind suppressions for both guile and gnucash. * src/register/ledger-core/gnc-ledger-display.c (gnc_ledger_display_template_gl): Change the reg_type to SEARCH_LEDGER so all the 'action' types appear. Bug#108833. * src/gnome/glade/sched-xact.glade: Remove unused 'ledger_status' widget. Bug#102269. * src/gnome-utils/gnc-dense-cal.c (gnc_dense_cal_draw_to_buffer): At least be consistent about the background coloring of the month labels, even if we're still not using GTK themeage correctly. * src/gnome-utils/gnc-dense-cal.c (gnc_dense_cal_destroy): Destroy the transient window when the widget is destroyed. Bug#103910. * src/gnome/dialog-scheduledxaction.c (gnc_ui_scheduled_xaction_editor_dialog_create): Make the advance and remind spin-buttons editable [Bug#94963]. * src/gnome/glade/sched-xact.glade: Change the upper bound on the advance and remind spins to 365 [days], with a page-size of 30 [days]. * src/gnome/dialog-sx-from-trans.c (gnc_sx_create_from_trans): Disallow the Scheduling of being-editing transactions in the Register, preventing a class of unbalacned SX template transactions from being entered and propogated through the system. See Bug#130330. * src/engine/FreqSpec.c (xaccFreqSpecGetFreqStr): Fix nasty memory-corruption issue; insufficent bounds checking on array index. Bug#125600. * src/gnome/dialog-sxsincelast.c (create_each_transaction_helper): Better handling of various error cases in transaction-creation. Bug#120311; Bug#130330. 2004-03-01 Joshua Sled <jsled@asynchronous.org> * src/gnome/dialog-scheduledxaction.c (gnc_sxed_check_consistent): Fix for part of Bug#121740 -- only allow auto-create SXes which have splits to be created. 2004-02-07 Joshua Sled <jsled@asynchronous.org> * src/gnome/dialog-scheduledxaction.c (editor_ok_button_clicked): * src/gnome-utils/gnc-frequency.c (gnc_frequency_save_state): * src/backend/file/gnc-freqspec-xml-v2.c (fs_none_handler): * src/engine/FreqSpec.c (xaccFreqSpecGetFreqStr): Adding "NONE" as an allowable FreqSpec [Bug#103968]. git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@9858 57a11ea4-9604-0410-9ed3-97b8803252fd
2004-03-10 19:17:14 -06:00
[--gen-suppressions=yes], and it makes no effort to output the
suppression only once.
2/ There are a bunch of suppressions which need to not be suppressions, but
2004-03-07 Joshua Sled <jsled@asynchronous.org> * HACKING: Added instructions about running under valgrind. * lib/gnucash_valgrind.supp: Added a large set of valgrind suppressions for both guile and gnucash. * src/register/ledger-core/gnc-ledger-display.c (gnc_ledger_display_template_gl): Change the reg_type to SEARCH_LEDGER so all the 'action' types appear. Bug#108833. * src/gnome/glade/sched-xact.glade: Remove unused 'ledger_status' widget. Bug#102269. * src/gnome-utils/gnc-dense-cal.c (gnc_dense_cal_draw_to_buffer): At least be consistent about the background coloring of the month labels, even if we're still not using GTK themeage correctly. * src/gnome-utils/gnc-dense-cal.c (gnc_dense_cal_destroy): Destroy the transient window when the widget is destroyed. Bug#103910. * src/gnome/dialog-scheduledxaction.c (gnc_ui_scheduled_xaction_editor_dialog_create): Make the advance and remind spin-buttons editable [Bug#94963]. * src/gnome/glade/sched-xact.glade: Change the upper bound on the advance and remind spins to 365 [days], with a page-size of 30 [days]. * src/gnome/dialog-sx-from-trans.c (gnc_sx_create_from_trans): Disallow the Scheduling of being-editing transactions in the Register, preventing a class of unbalacned SX template transactions from being entered and propogated through the system. See Bug#130330. * src/engine/FreqSpec.c (xaccFreqSpecGetFreqStr): Fix nasty memory-corruption issue; insufficent bounds checking on array index. Bug#125600. * src/gnome/dialog-sxsincelast.c (create_each_transaction_helper): Better handling of various error cases in transaction-creation. Bug#120311; Bug#130330. 2004-03-01 Joshua Sled <jsled@asynchronous.org> * src/gnome/dialog-scheduledxaction.c (gnc_sxed_check_consistent): Fix for part of Bug#121740 -- only allow auto-create SXes which have splits to be created. 2004-02-07 Joshua Sled <jsled@asynchronous.org> * src/gnome/dialog-scheduledxaction.c (editor_ok_button_clicked): * src/gnome-utils/gnc-frequency.c (gnc_frequency_save_state): * src/backend/file/gnc-freqspec-xml-v2.c (fs_none_handler): * src/engine/FreqSpec.c (xaccFreqSpecGetFreqStr): Adding "NONE" as an allowable FreqSpec [Bug#103968]. git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@9858 57a11ea4-9604-0410-9ed3-97b8803252fd
2004-03-10 19:17:14 -06:00
instead just not be generated by valgrind.
Look up exported and imported symbols
-------------------------------------
These commands may be useful to find out the library that actually
exported a particular symbol, and to check which import symbol one
particular library depends upon and where they are imported
from. Run these from the top-level of the build tree.
# Create a table of all exported symbols and where they come from
nm -A `find . -name '*.so'` | grep ' T ' | \
sed 's/^\([^:]*\).* \([^ ]*\)$/\1: \2/' > exportedsymbols
# For a particular library, check symbol import requirements,
# listing all symbols (needs the file from above)
A=src/gnc-module/.libs/libgw-gnc-module.so && echo "$A requirements:" \
&& nm $A | grep ' U ' | sed 's/^.* \([^ ]*\)$/\1/' | \
grep -wFf- exportedsymbols
# For a particular library, check import requirements,
# summarized by library
A=src/gnc-module/.libs/libgw-gnc-module.so && echo "$A requirements:" \
&& nm $A | grep ' U ' | sed 's/^.* \([^ ]*\)$/\1/' | \
grep -wFf- exportedsymbols | cut -d: -f1 | sort | uniq
# For a particular library, check import requirements,
# summarized by library, formatted for Makefile.am
A=src/gnc-module/.libs/libgw-gnc-module.so && echo "$A requirements:" \
&& nm $A | grep ' U ' | sed 's/^.* \([^ ]*\)$/\1/' | \
grep -wFf- exportedsymbols | cut -d: -f1 | sort | uniq | \
sed 's!.libs/!!' | sed 's/.so$/.la \\/' | sed 's!^.! \${top_builddir}!'
# List all import requirements summarized by library for a full
# recursive directory tree
for A in `find src/business/business-core -name '*.so'`; do \
echo -e "\n##$A requirements:" && nm $A | grep ' U ' | \
sed 's/^.* \([^ ]*\)$/\1/' | grep -wFf- exportedsymbols | \
cut -d: -f1 | sort | uniq; done
2014-02-20 00:11:22 -06:00
XCode project
-------------
There is an XCode project available in gnucash.xcodeproj at the root of the
source tree. This project can be used with XCode on a Macintosh to debug
GnuCash. It is not set up to build GnuCash, but only to debug it. Building must
be done using the normal command line tools.
This project is designed to be used with the X Window version of GnuCash, not
the native Quartz version. To use it you must build and install GnuCash into
directories "build" and "install" parallel to the source directory. Furthermore
the architecture dependent parts of the install are put in a subdirectory
"install/darwin".
To build, then, if the source directory is somewhere/gnucash you must create the
directories somewhere/build/darwin and somewhere/install/darwin/bin, cd into
somewhere/build/darwin and execute
../../gnucash/configure --prefix=../../install \
--exec-prefix=../../install/bin \
--enable-debug \
...other options...
make
make install
This will build and install a copy of GnuCash that can be debugged using the
XCode project.
The debug target in the project is set with a build tool of /usr/bin/true so
building in XCode won't hurt anything, it just won't do much. It is also set to
not launch GnuCash automatically, but rather to wait for it to be launched
manually. This lets you run it from a command prompt and see the console output
which can often be useful. Hence to initiate a debugging session in XCode, tell
XCode to run GnuCash then go to a terminal window and launch install/darwin/bin/gnucash
with whatever options you want. XCode will notice that it has been launched and
attach to the process.
Since there seems to be no way to make the path to the executable a relative
path, you must make one change to the debug scheme before you can run gnucash
under XCode. In XCode 5 (other versions may be different) go to
Product->Scheme->Edit Scheme and select the "info" tab of the "Run gnucash"
pane. Select "Other..." in the "Executable" menu and select the installed binary
for gnucash in the resulting file open dialog. This should be
install/darwin/bin/gnucash as described above. This, and the act of opening the
project in XCode, will change some of the files in the XCode project directory.
You can, or course, commit these locally, but please don't push them upstream.