README 3.81 KB
Newer Older
Marc-André Lureau's avatar
Marc-André Lureau committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
=====
libgd
=====

Introduction
============

libgd is a library used by various GNOME 3 styled applications.
However, it is not a typical library, since it doesn't guarantee
API/ABI stability, nor does it has official releases tarballs. Only
the files actually used by your project will be shipped with its
tarball. Only the necessary dependencies will be checked during
configure time and used at runtime.

Each application can configure libgd depending on its needs and will
be able to either link dynamically (privately) or statically link with
a specific development version.

GObject Introspection based bindings generation such as Javascript or
Vala are also supported.

22
23
24
More Background
---------------

Marc-André Lureau's avatar
Marc-André Lureau committed
25
26
27
28
libgd originates from the GNOME Documents project (written by Cosimo
Cecchi), which was one of the first application to follow the novel
GNOME 3 application design.

29
Since other applications have similar needs, it makes sense to try to
Bob Hogg's avatar
Bob Hogg committed
30
31
32
reuse and improve the existing work. However, the design being not
frozen, and the code being not yet matured enough and proven, it is
not possible for the developers to guarantee API and propose the
Marc-André Lureau's avatar
Marc-André Lureau committed
33
34
35
addition to the respective projects (Gtk+, or GLib for example) right
now. Sharing the code allows to experiment, discuss and test together
before proposing it upstream.
36

Bob Hogg's avatar
Bob Hogg committed
37
38
Traditionally, this problem is solved by copying often outdated
snippets of code around (due to no API/ABI guarantee), often not
Marc-André Lureau's avatar
Marc-André Lureau committed
39
centralized (libegg).
40

Marc-André Lureau's avatar
Marc-André Lureau committed
41
42
43
In the past, there used to be some common aging GNOME application
libraries above Gtk+ which have been slowly deprecated in favour of
Gtk+ (gnomeui and friends).
44
45

All approaches have pros and cons. A configurable git submodule
Marc-André Lureau's avatar
Marc-André Lureau committed
46
has the following advantages:
47
48
49
50
51

- no direct code copying necessary because API/ABI breakage (history
  is preserved etc..)
- code is shared and maintained in a common project
- you can stick to a particular upstream version, or branch off your
Marc-André Lureau's avatar
Marc-André Lureau committed
52
  own version easily if needed (hopefully you find your way back upstream)
53
54
55
56
- update the submodule version when your project is ready
- the libgd options should help you to configure a library to suit
  your needs, taking care of some of autofoo stuff for you

Marc-André Lureau's avatar
Marc-André Lureau committed
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
Usage
=====

In order to use libgd, an application using autotools needs to:

1. from the top-level project directory, add the submodule:
    - git submodule add git://git.gnome.org/libgd

2. in autogen.sh, it is recommended to add before autoreconf call:
    - git submodule update --init --recursive

3. in top-level Makefile.am:
    - add -I libgd to ACLOCAL_AMFLAGS
    - add libgd to SUBDIRS, before the project src directory

4. in project configure.ac:
    - add LIBGD_INIT([list-of-options]) after your project
      dependencies checks
    - add libgd/Makefile to AC_CONFIG_FILES

5. from your program Makefile.am, you may now for example:
    - link with $(top_builddir)/libgd/libgd.la, and include
      <libgd/gd.h> (adjust your AM_CPPFLAGS as necessary)

81
82
83
84
85
86
87
88
89
90
You may be interested to look at the commit switching GNOME Boxes from
private libgd usage to the libgd submodule:

http://git.gnome.org/browse/gnome-boxes/commit/?id=395652458d8b311a25ecb27cc42287602a122b1f

Note for example that the submodule url is "../libgd", which is a
better alternative for projects hosted on git.gnome.org. It will allow
the submodule update to reuse the address and the credentials given to
the toplevel project.

Marc-André Lureau's avatar
Marc-André Lureau committed
91
92
93
94
95
96
97
98
99
LIBGD_INIT options
==================

- gtk-hacks

- main-icon-view

- margin-container

Pierre-Yves LUYTEN's avatar
Pierre-Yves LUYTEN committed
100
101
- notification

Marc-André Lureau's avatar
Marc-André Lureau committed
102
103
- static

Marc-André Lureau's avatar
Marc-André Lureau committed
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
- tagged-entry

- vapi

- gir

How to modify or add an API?
============================


TODO
====

- add translation support
- add some form of build test
- document: options, modification process
- eventually add documentation generation
Marc-André Lureau's avatar
Marc-André Lureau committed
121
122
- some licensing check
- more modularity (not all in libgd.m4/Makefile.am)
Pierre-Yves LUYTEN's avatar
Pierre-Yves LUYTEN committed
123
- CSS styling and data: shared only with gnome-themes-standard?