8
libgd is a library used by various GNOME 3 styled applications.
9
However, it is not a typical library, since it doesn't guarantee
10
API/ABI stability, nor does it has official releases tarballs. Only
11
the files actually used by your project will be shipped with its
12
tarball. Only the necessary dependencies will be checked during
13
configure time and used at runtime.
15
Each application can configure libgd depending on its needs and will
16
be able to either link dynamically (privately) or statically link with
17
a specific development version.
19
GObject Introspection based bindings generation such as Javascript or
20
Vala are also supported.
25
libgd originates from the GNOME Documents project (written by Cosimo
26
Cecchi), which was one of the first application to follow the novel
27
GNOME 3 application design.
29
Since other applications have similar needs, it makes sense to try to
30
reuse and improve the exisiting work. However, the design being not
31
frozen, and the code being not yet mattured enough and proven, it is
32
not possible for the developpers to guarantee API and propose the
33
addition to the respective projects (Gtk+, or GLib for example) right
34
now. Sharing the code allows to experiment, discuss and test together
35
before proposing it upstream.
37
Traditionnally, this problem is solved by copying often outdated
38
snippets of code around (due to no API/ABI guaratee), often not
41
In the past, there used to be some common aging GNOME application
42
libraries above Gtk+ which have been slowly deprecated in favour of
43
Gtk+ (gnomeui and friends).
45
All approaches have pros and cons. A configurable git submodule
46
has the following advantages:
48
- no direct code copying necessary because API/ABI breakage (history
50
- code is shared and maintained in a common project
51
- you can stick to a particular upstream version, or branch off your
52
own version easily if needed (hopefully you find your way back upstream)
53
- update the submodule version when your project is ready
54
- the libgd options should help you to configure a library to suit
55
your needs, taking care of some of autofoo stuff for you
60
In order to use libgd, an application using autotools needs to:
62
1. from the top-level project directory, add the submodule:
63
- git submodule add git://git.gnome.org/libgd
65
2. in autogen.sh, it is recommended to add before autoreconf call:
66
- git submodule update --init --recursive
68
3. in top-level Makefile.am:
69
- add -I libgd to ACLOCAL_AMFLAGS
70
- add libgd to SUBDIRS, before the project src directory
72
4. in project configure.ac:
73
- add LIBGD_INIT([list-of-options]) after your project
75
- add libgd/Makefile to AC_CONFIG_FILES
77
5. from your program Makefile.am, you may now for example:
78
- link with $(top_builddir)/libgd/libgd.la, and include
79
<libgd/gd.h> (adjust your AM_CPPFLAGS as necessary)
81
You may be interested to look at the commit switching GNOME Boxes from
82
private libgd usage to the libgd submodule:
84
http://git.gnome.org/browse/gnome-boxes/commit/?id=395652458d8b311a25ecb27cc42287602a122b1f
86
Note for example that the submodule url is "../libgd", which is a
87
better alternative for projects hosted on git.gnome.org. It will allow
88
the submodule update to reuse the address and the credentials given to
116
How to modify or add an API?
117
============================
123
- add translation support
124
- add some form of build test
125
- document: options, modification process
126
- eventually add documentation generation
127
- some licensing check
128
- more modularity (not all in libgd.m4/Makefile.am)
129
- CSS styling and data: shared only with gnome-themes-standard?
added
removed
libgd/README
