Source directory restructuring

John Ralls jralls at
Mon Aug 7 15:27:18 EDT 2017

> On Aug 7, 2017, at 2:56 PM, Geert Janssens <geert.gnucash at> wrote:
> So after my houskeeping message in which I have announced the changes to src/
> business and src/libqof, I'd like to bring up my eventual goal for the source 
> tree.
> My main motivation to do all this restructuring is to simplify. There are 
> currently plenty of directories and I often have to guess where to expect a 
> file. The qof vs engine story was one example. Is gnc-date something for qof 
> or for engine ? I find myself regularly searching for a file in the wrong 
> directory.
> So here follows a first proposal for the directory structure I'm targetting:
> * data (for things like art, checks, account hierarchy templates,...)
> * doc (for all documenation)
> * lib (for all source required to build "libgnucash", see below)
> * ui (for all the user interfaces the project currently supports)
> I am omitting some smaller directories here, such as util and macros. They 
> will probably stay on the current top level for now.
> I'm envisioning "libgnucash" as the core library that encapsulates all gnucash 
> related concepts (the accounting concepts such as transaction, split, as well 
> as the data backends). This library is what all applications in the gnucash 
> sphere should depend on to implement the "gnucash" experience. The most 
> obvious is of course the current gnucash as we know it. However at some point 
> this library should ideally also become the core of the Android app and *who 
> knows* one day an IOS app. And closer to the current state, it should also be 
> the library that the guile and python bindings depend on. So all functionality 
> encapsulated in one single library, the API. In practice I think the following 
> directories belong in this libgnucash: core-utils, gnc-module, engine, the 
> backends, app-utils. (Note I would like to get rid of gnc-module still, but 
> that's a whole other discussion and task).
> The ui directory will have a subdirectory for each user interface we support. 
> This is not necessarily a *graphical* user interface though. At this point 
> there are already a number of them:
> gnucash
> cutecash
> bindings (with subdirectories for python and guile)
> The bulk of the other directories are support directories for one of the ui's 
> and I propose to make them subdirectories of each respective ui.
> For example gtkmm is only used by cutecash, so let's store it there (until 
> another ui would also require it, which I consider unlikely to happen still).
> The other directories (gnome-utils, gnome-search, gnome, register, html, 
> report, import-export,...) are all used only in the gnucash application and 
> hence should be moved there. In the move I'd like to try and reduce the 3 
> gnome* directories to one and call it gtk as we're not using any gnome 
> specific technology any more.
> In a later phase I think it would be nice if the core libgnucash could also 
> spit out html reports, but that would require us to refactor the report 
> modules, which I consider too much work to be done at the same time. When this 
> eventually gets done the non-ui part of the report system can then be added in 
> libgnucash to the benefit of all consumers (gnucash/cutecash/Gnc4Android/...).
> Feedback or questions ?


These are to be top-level directories, so the current src goes away, right? The rest assumes that to be the case.

Let's call the libgnucash directory libgnucash instead of just lib and keep lib as the place put code pinched from elsewhere like the bits of libgoffice.

I want to get rid of gnc-module too, but it's not easy.

App-utils has stuff that belongs in libgnucash and other stuff (e.g. options) that belongs in the application directory (which I propose calling "gnucash" below). There's also code splattered all over everywhere else that belongs in libgnucash. How much of a prerequisite to rearrangement is getting the code in the right place?

I think that having separate documentation directories (there are two, doc and src/doc) is an abject failure from a maintenance standpoint. A lot of stuff was written 15-20 years ago and was marked obsolete 10 years ago because it's been left to rot. All documentation needs to be in the source files as Doxygen comments. We should look through the docs and src/docs stuff and copy anything that's still relevant into comments in the appropriate source files and delete the docs directories.

I'd prefer that the application code go into a directory named gnucash rather than "ui". I'm inclined toward removing cutecash entirely. It made sense for Christian to keep it in the Gnucash repository when we were using SVN, but now he should just publish it in his own Github repo.

The bindings are mostly (and should probably be entirely) libgnucash bindings. They really belong in libgnucash or failing that in their own TLD, not part of the application.

Reports might stand on their own as a separate dependency of gnucash or they could be a subdirectory of gnucash. The same is true of import-export. In one approach  the GUI parts of each would be part of the application while the functional bits would be part of libgnucash. Are the matchers libgnucash or gnucash?

Gtk+ is very much Gnome and depends on other pieces of the Gnome project. The actual name of the directory isn't really important so we can call it gtk if you'd rather, but there are lots of other Gnome project dependencies that aren't going away as long as we're using Gtk+. Remember that in addition to gnome, gnome-util, and gnome-query there's also register-gnome, report-gnome, and (until your latest changes) business-gnome. There's also Gtk+ code in import-export, html, and probably a few other places that don't immediately come to mind. Setting that aside we still have all of that GValue and g_object_set/get code that we use for communicating between the engine, the backends, and the importers.

I'll point out once again that there's an immense amount of untangling to separate the actual UI code from glue and actual bits of libgnucash that are all mangled together in the various gnome directories.

Does it really make sense to push much further with this for 2.8? I'd like to move towards releasing that as quickly as we can, then we can move on to extraction and rearrangement.

John Ralls

More information about the gnucash-devel mailing list