example library calls

[John Ralls]

On Mar 27, 2012, at 2:35 PM, Danny Holstein wrote:

> Thanks so much, that's a great link.
> 
> The first response I got to my posting (from John R.) accused me of being delusional, I didn't quite see how that was fair since a "make install" creates shared libraries in the /usr/local/lib/ directory.
> 
> To me, with the python bindings and all, and discussions on the mailing list that recommended using the library instead of posting directly to the database with MySQL -- I think my question really should never have been characterized as delusional.

> On Mar 24, 2012, at 5:34 PM, Danny Holstein wrote:
> 
>> Developers; 
>> 
>> I can't seem to find an example of how to call the Gnucash libraries. I'd like to write a program that posts invoices from a web-based shopping cart, and I can imagine a POS program or ERP program using the library for the GL backend. 

Imagining an ERP program based on the GC backend qualifies as pretty far "round the bend", and that's completely separate from the stability issues.

>> 
>> I would expect examples to be in a top level examples directory, with language-based subdirectories such as C and python. 
>> 
>> I had tried a search of the archive, but the search seemed broken and yielded no results. 
>> 

When a developer selects a library on which to base his project, he rightly expects that the library's API will be documented, that it will be stable across minor versions -- and that changes across major versions will be gradual, with functionality deprecated for some time before it's removed. A good library will have example code, as you "expected", and tutorials.

Gnucash's support libraries offer *absolutely none* of that stability and precious little of the required documentation. They exist *solely* to organize Gnucash, and we will change the API at will (or even whim). There is a huge amount of code in those libraries that Gnucash doesn't use, and as we get more testing in place to identify what it is, it's getting ripped out. No deprecation, no warning, just gone. The API itself is going to change a lot over the next few years because it's hard for *us* to keep track of everything. Again, no deprecation, no warning, just *bang* and it's changed. 

That's separate from our telling people who want to extend Gnucash that they mustn't write directly to storage without using the API. We know that if they write directly to storage they'll write unbalanced transactions, or miss some critical bit of metadata, or simply write a record that's different from the way Gnucash does, and then we'll have users complaining that Gnucash can't read its data. In the past, people who've wanted to write data have had in mind small extensions to Gnucash, generally for personal use. You implied a rather more ambitious project.

As for your POS import, the safest way to implement that would be either:
* have the POS system export a format that Gnucash can import -- Derek always recommends QIF
* if you want to get really fancy, give it an OFXdirect or HCBI interface and use Gnucash's online banking features (implemented through AQBanking -- Martin Preuß might be able to help you with the POS's server side as well).

Aside from not driving yourself insane trying to track our API, either of those would afford the advantage of working with other accounting programs.

Regards,
John Ralls