mirror of
https://github.com/Gnucash/gnucash.git
synced 2024-12-02 05:29:20 -06:00
15a35e6a3b
There are more, but these are most common ones. There are also a number of urls that don't behave well when https, so those are skipped At some point I have also started marking non-working URLs as [DEAD LINK], though that's not a full coverage.
97 lines
4.0 KiB
Plaintext
97 lines
4.0 KiB
Plaintext
-*-text-*-
|
|
|
|
This file is intended to contain information for those interested in
|
|
working on the guile bits of GnuCash.
|
|
|
|
I've recently added some GUI functions callable from scheme. This is
|
|
generally pretty straightforward, and you can look in the code to see
|
|
how I did it, but there are a few bits you have to be careful about.
|
|
|
|
One of the main sources of useful information is "info guile-ref".
|
|
This contains the documentation for all the guile C-side functions
|
|
like SCM_CAR(), scm_append(), etc. that manipulate opaque SCM objects
|
|
from the guile side.
|
|
|
|
Given that and a reasonable understanding of GTK/GNOME, you should be
|
|
able to follow what I've done.
|
|
|
|
Introduction To Scheme and guile(rgmerk)
|
|
--------------------------------
|
|
Please skip this if you already know what Scheme is and why it's
|
|
so cool . . .
|
|
|
|
Scheme is a dialect of LISP (List Programming), one of the earliest
|
|
programming languages. It makes so many things easy it's just not
|
|
funny. It can be a little confusing for people raised on C and Java,
|
|
but any time taken to learn it is made up for with easier-to-write,
|
|
easier-to-debug, more reusable, and more robust code.
|
|
|
|
Guile is an implementation of standard Scheme which is easily
|
|
embeddable in C, making multi-language development relatively
|
|
straightforward. You can easily access data and procedures from
|
|
either end. Guile supports a superset of R4RS (the Scheme standard).
|
|
For initial experimentation, you can use Guile as an interactive Scheme
|
|
shell to play around with the system.
|
|
|
|
FIXME: Starting gnucash as a guile shell. ..
|
|
|
|
While the Guile documentation (in info format) explains
|
|
Guile specifics, it doesn't have much information about Scheme,
|
|
the language. The Internet Scheme Repository:
|
|
|
|
https://www.cs.indiana.edu/scheme-repository/home.html [DEAD LINK]
|
|
|
|
has quite a useful collection of information, including
|
|
FAQs, online copies of the Scheme standard (which is actually
|
|
quite readable and useful), and pointers to web tutorials
|
|
and other resources.
|
|
|
|
Garbage collection:
|
|
-------------------
|
|
|
|
One issue to keep in mind is that of garbage collection. You cannot
|
|
pass a scheme side item to the C side (through a SCM) and then store
|
|
that object off somewhere on the C side such that it lives longer than
|
|
all of it's guile side references. If you do, you're likely to get a
|
|
crash. The problem is that guile's garbage collector only knows to
|
|
save guile items that still have guile side pointers, or that are
|
|
found somewhere on the current C side stack. If you store a SCM item
|
|
off in a C data structure (say a callback pointer), and then return to
|
|
the guile side and drop the guile-side reference to the item, guile
|
|
may garbage collect it before it's used by the C side.
|
|
|
|
For example, this psudeo-code is a problem:
|
|
|
|
void gnc_some_function(SCM scm_thunk) {
|
|
gnc_set_push_button_callback(some_button, scm_thunk);
|
|
}
|
|
|
|
(define (unsafe-guile-function)
|
|
(let ((my-callback (lambda () (display "Hello\n"))))
|
|
(gnc:some-function my-callback)))
|
|
|
|
The problem here is that if you call unsafe-guile-function, it
|
|
registers the pointer to the anonymous lambda created in the let
|
|
construct with the button on the C-side and then returns. As soon as
|
|
it returns, guile has no more references to the anonymous lambda, and
|
|
it's not on the C stack, so guile thinks it's OK to garbage collect
|
|
the function even though the C side has a pointer to it and may still
|
|
use it.
|
|
|
|
The moral of this story is that if you need to have the C side ferret
|
|
away a scheme item for later, you must also keep at least one
|
|
reference to that item on the guile side until the C side is finished
|
|
with it.
|
|
|
|
You can protect an object using scm_gc_protect_object. When you're done
|
|
with it you can release it using scm_gc_unprotect_object.
|
|
|
|
Guile Interrupts:
|
|
-----------------
|
|
|
|
Another issue that I'm not quite sure of myself yet is that of
|
|
interrupts. Guile has the ability to protect certain segments of code
|
|
with SCM_DEFER_INTS/SCM_ALLOW_INTS, but at the moment I'm not sure
|
|
when this is required. If anyone gets the chance to check this out
|
|
before I do, then please edit this file and put your findings here.
|