1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
* Don't commit directly, instead make a pull request on GitHub.
Building from git
-----------------
To build from git, or without relying on the generated files in a source
release, automake, autoconf, libtool, pkg-config and git must be installed.
(Note, the exact packages needed for certain distros may be found in
.travis.yml and appveyor.yml.)
Run
./bootstrap && ./configure --enable-relocatable
to set up and configure the source tree; optional configure arguments can be
supplied as normal.
See INSTALL (which is created by bootstrap) for instructions from this point
on.
Working in libenchant
---------------------
When writing libenchant our priorities are
1) Portable
2) Maintainable & Documented
3) Modular and well designed
When you submit code for inclusion in libenchant, please keep those
things in mind. While performance is important please note that
well-designed algorithms and data structures are fertile areas for
development; obfuscated code to make a loop 3% faster is not. Specifically,
this means:
- Clarity of design and function are paramount
- Make sure your code does not generate warnings
- Please follow the formatting style
Formatting style
----------------
The formatting style of libenchant is a mix of various styles. Please
familiarise yourself with the GNU coding standards (shipped with most
GNU/Linux systems as the standards.info file), then read the Linux
kernel coding standards and ignore Linus's jokes. Then look at the
Gtk+ header files to get acquainted with how to write nice header files
that are almost self documenting.
Emacs users should use the supplied .dir-locals.el.
Remember: Use tabs for indentation: that will keep your
code honest as you will be forced to split your routines into more
modular chunks (as detailed by Linus).
On top of that, please:
- Follow the Gtk+ cleanliness conventions for function
prototypes.
- Follow the Gtk+ namespace convention for function names:
module_submodule_operation
- Every entry point to a public routine should use the
g_return_if_fail and g_return_val_if_fail macros to verify
that the parameters passed are valid.
- Under no circumstances use magic variables. Use typedef
enum { ... } type; to create enumerations. Do not use
integers to hold enumeration values: the compiler can help
catch various errors.
- Use g_warning to mark spots that need to be reviewed or are
not finished.
- Do not submit code that is just a temporary workaround for a
full fledged feature. We do not want to maintain limited
features. It is better to submit an implementation designed
to be expanded and enhanced, even if it is not completely
finished.
- Follow the libenchant commenting style, which is not the Gtk
style;
/* ie. use this for
* multi-line comments
*/
All of this is to ensure the libenchant code will be kept within
reasonable margins of maintainability for the future: Remember, in two years
you will probably be far too busy to maintain your own contributions, and they
might become a burden to the program maintainers.
libenchant is intended to be a foundation for a various document-centric
projects.
Cleaning code in libenchant is more important than trying not to break
existing code. Code clean-ups are always welcome.
API documentation
-----------------
To generate API documentation, simply run
doxygen
and see doxygen/html/index.html in a web browser.
Making a release
----------------
To make a release, you'll need woger:
https://github.com/rrthomas/woger
and github-release, suitably configured:
https://github.com/aktau/github-release
Having tested and pushed all the changes, update the version number in
configure.ac and write the NEWS entry and push those too.
Then execute:
make release
|
