Commit | Line | Data |
---|---|---|
3229f68b MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
7e23d9d0 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2011 |
3229f68b MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
7 | @node Linking Guile with Libraries | |
8 | @section Linking Guile with Libraries | |
9 | ||
10 | The previous section has briefly explained how to write programs that | |
11 | make use of an embedded Guile interpreter. But sometimes, all you | |
12 | want to do is make new primitive procedures and data types available | |
13 | to the Scheme programmer. Writing a new version of @code{guile} is | |
14 | inconvenient in this case and it would in fact make the life of the | |
15 | users of your new features needlessly hard. | |
16 | ||
17 | For example, suppose that there is a program @code{guile-db} that is a | |
18 | version of Guile with additional features for accessing a database. | |
19 | People who want to write Scheme programs that use these features would | |
20 | have to use @code{guile-db} instead of the usual @code{guile} program. | |
21 | Now suppose that there is also a program @code{guile-gtk} that extends | |
22 | Guile with access to the popular Gtk+ toolkit for graphical user | |
23 | interfaces. People who want to write GUIs in Scheme would have to use | |
24 | @code{guile-gtk}. Now, what happens when you want to write a Scheme | |
25 | application that uses a GUI to let the user access a database? You | |
26 | would have to write a @emph{third} program that incorporates both the | |
27 | database stuff and the GUI stuff. This might not be easy (because | |
28 | @code{guile-gtk} might be a quite obscure program, say) and taking this | |
29 | example further makes it easy to see that this approach can not work in | |
30 | practice. | |
31 | ||
32 | It would have been much better if both the database features and the GUI | |
33 | feature had been provided as libraries that can just be linked with | |
34 | @code{guile}. Guile makes it easy to do just this, and we encourage you | |
35 | to make your extensions to Guile available as libraries whenever | |
36 | possible. | |
37 | ||
38 | You write the new primitive procedures and data types in the normal | |
39 | fashion, and link them into a shared library instead of into a | |
40 | stand-alone program. The shared library can then be loaded dynamically | |
41 | by Guile. | |
42 | ||
43 | @menu | |
44 | * A Sample Guile Extension:: | |
45 | @end menu | |
46 | ||
47 | ||
48 | @node A Sample Guile Extension | |
49 | @subsection A Sample Guile Extension | |
50 | ||
51 | This section explains how to make the Bessel functions of the C library | |
52 | available to Scheme. First we need to write the appropriate glue code | |
53 | to convert the arguments and return values of the functions from Scheme | |
54 | to C and back. Additionally, we need a function that will add them to | |
55 | the set of Guile primitives. Because this is just an example, we will | |
56 | only implement this for the @code{j0} function. | |
57 | ||
58 | Consider the following file @file{bessel.c}. | |
59 | ||
60 | @smallexample | |
61 | #include <math.h> | |
62 | #include <libguile.h> | |
63 | ||
64 | SCM | |
65 | j0_wrapper (SCM x) | |
66 | @{ | |
7e23d9d0 | 67 | return scm_from_double (j0 (scm_to_double (x))); |
3229f68b MV |
68 | @} |
69 | ||
70 | void | |
71 | init_bessel () | |
72 | @{ | |
73 | scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper); | |
74 | @} | |
75 | @end smallexample | |
76 | ||
77 | This C source file needs to be compiled into a shared library. Here is | |
78 | how to do it on GNU/Linux: | |
79 | ||
80 | @smallexample | |
4b93693d AW |
81 | gcc `pkg-config --cflags guile-@value{EFFECTIVE-VERSION}` \ |
82 | -shared -o libguile-bessel.so -fPIC bessel.c | |
3229f68b MV |
83 | @end smallexample |
84 | ||
5f30c653 KR |
85 | For creating shared libraries portably, we recommend the use of GNU |
86 | Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}). | |
3229f68b MV |
87 | |
88 | A shared library can be loaded into a running Guile process with the | |
89 | function @code{load-extension}. In addition to the name of the | |
8c3fa3e5 | 90 | library to load, this function also expects the name of a function from |
3229f68b MV |
91 | that library that will be called to initialize it. For our example, |
92 | we are going to call the function @code{init_bessel} which will make | |
93 | @code{j0_wrapper} available to Scheme programs with the name | |
94 | @code{j0}. Note that we do not specify a filename extension such as | |
95 | @file{.so} when invoking @code{load-extension}. The right extension for | |
96 | the host platform will be provided automatically. | |
97 | ||
aba0dff5 | 98 | @lisp |
3229f68b MV |
99 | (load-extension "libguile-bessel" "init_bessel") |
100 | (j0 2) | |
101 | @result{} 0.223890779141236 | |
aba0dff5 | 102 | @end lisp |
3229f68b MV |
103 | |
104 | For this to work, @code{load-extension} must be able to find | |
105 | @file{libguile-bessel}, of course. It will look in the places that | |
106 | are usual for your operating system, and it will additionally look | |
107 | into the directories listed in the @code{LTDL_LIBRARY_PATH} | |
108 | environment variable. | |
109 | ||
110 | To see how these Guile extensions via shared libraries relate to the | |
111 | module system, @xref{Putting Extensions into Modules}. | |
5f30c653 KR |
112 | |
113 | ||
114 | @c Local Variables: | |
115 | @c TeX-master: "guile.texi" | |
116 | @c End: |