Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 606 lines (484 sloc) 23.091 kB
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
1 =============
2 Hacking Geany
3 =============
4 .. contents::
5
6 General
7 =======
8
1e41e97 @ntrel Added 'About this file' and links for some Windows developer tools.
ntrel authored
9 About this file
10 ---------------
49c0715 @ntrel Reformat text width with fmt. Add comment about running Glade 2.10 un…
ntrel authored
11 This file contains information for anyone wanting to work on the Geany
12 codebase. You should be aware of the open source licenses used - see
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
13 the README file or the documentation. It is reStructuredText; the
14 source file is HACKING. You can generate hacking.html by running ``make
15 hacking-doc`` from the doc/ subdirectory.
1e41e97 @ntrel Added 'About this file' and links for some Windows developer tools.
ntrel authored
16
498964e @ntrel Replace Plugins chapter with 'Writing plugins' section.
ntrel authored
17 Writing plugins
18 ---------------
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
19 * src/plugindata.h contains the plugin API data types.
20 * See plugins/demoplugin.c for a very basic example plugin.
21 * src/plugins.c loads and unloads plugins (you shouldn't need to read
22 this really).
84fc755 @eht16 Add a few notes about basic plugin writing guidelines.
eht16 authored
23 * The API documentation contains a few basic guidelines and hints to
24 write plugins.
498964e @ntrel Replace Plugins chapter with 'Writing plugins' section.
ntrel authored
25
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
26 You should generate and read the plugin API documentation, see below.
498964e @ntrel Replace Plugins chapter with 'Writing plugins' section.
ntrel authored
27
28 Plugin API documentation
29 ^^^^^^^^^^^^^^^^^^^^^^^^
30 You can generate documentation for the plugin API using the doxygen
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
31 tool. Run ``make api-doc`` in the doc subdirectory. The documentation
32 will be output to doc/reference/index.html.
4afed6d @eht16 Add link for online API documentation.
eht16 authored
33 Alternatively you can view the API documentation online at
34 http://www.geany.org/manual/reference/.
498964e @ntrel Replace Plugins chapter with 'Writing plugins' section.
ntrel authored
35
5325bd1 @ntrel Add HACKING file for new contributors.
ntrel authored
36 Patches
37 -------
49c0715 @ntrel Reformat text width with fmt. Add comment about running Glade 2.10 un…
ntrel authored
38 We are happy to receive patches, but it's best to check with us by email
39 or mailing list whether a new feature is appropriate, and whether someone
40 is already working on similar code.
5325bd1 @ntrel Add HACKING file for new contributors.
ntrel authored
41
ca33ea6 @b4n Update HACKING for Git switch
b4n authored
42 In general it's best to provide git-formatted patches made from the
43 current Git (see `Committing`_)::
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
44
ca33ea6 @b4n Update HACKING for Git switch
b4n authored
45 $ git commit -a
46 $ git format-patch HEAD^
5325bd1 @ntrel Add HACKING file for new contributors.
ntrel authored
47
ca33ea6 @b4n Update HACKING for Git switch
b4n authored
48 We also accept patches against other releases, but it's more work for us.
49
50 If you're not using Git, although you're strongly suggested to used it,
51 you can use the diff command::
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
52
faa4e73 @ntrel Remove accidentally added tab indentation.
ntrel authored
53 $ diff -u originalpath modifiedpath > new-feature.patch
5325bd1 @ntrel Add HACKING file for new contributors.
ntrel authored
54
ca33ea6 @b4n Update HACKING for Git switch
b4n authored
55 However, such a patch won't contain the authoring information nor the
56 patch's description.
57
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
58 .. note::
59 Please make sure patches follow the style of existing code - In
60 particular, use tabs for indentation. See `Coding`_.
61
62 Windows tools
63 -------------
ca33ea6 @b4n Update HACKING for Git switch
b4n authored
64 * Git: http://git-scm.com/ and http://code.google.com/p/msysgit/
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
65 * diff, grep, etc: http://mingw.org/ or http://unxutils.sourceforge.net/
9bbf07f @ntrel note: Please make sure patches follow the style of existing code.
ntrel authored
66
1e41e97 @ntrel Added 'About this file' and links for some Windows developer tools.
ntrel authored
67 See also the 'Building on Windows' document on the website.
68
5325bd1 @ntrel Add HACKING file for new contributors.
ntrel authored
69 File organization
70 -----------------
dd4eb19 @ntrel Add coding note about not writing long functions with a lot of variab…
ntrel authored
71 callbacks.c is just for Glade callbacks.
5325bd1 @ntrel Add HACKING file for new contributors.
ntrel authored
72 Avoid adding code to geany.h if it will fit better elsewhere.
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
73 See the top of each ``src/*.c`` file for a brief description of what
74 it's for.
5325bd1 @ntrel Add HACKING file for new contributors.
ntrel authored
75
87ec6a3 @ntrel Add 'Doc-comments' plugin API subsection.
ntrel authored
76 Plugin API code
77 ---------------
498964e @ntrel Replace Plugins chapter with 'Writing plugins' section.
ntrel authored
78 Please be aware that anything with a doc-comment (a comment with an
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
79 extra asterix: ``/**``) is something in the plugin API. Things like
80 enums and structs can usually still be appended to, ensuring that all
81 the existing elements stay in place - this will keep the ABI stable.
82
83 .. warning::
2d4fddb @ntrel Add note about not appending to structs like KeyBindingGroup and
ntrel authored
84
48cd3cb @ntrel Deprecate PLUGIN_KEY_GROUP() macro - use plugin_set_key_group()
ntrel authored
85 Some structs like GeanyCallback cannot be appended to without
86 breaking the ABI because they are used to declare structs by
87 plugins, not just for accessing struct members through a pointer.
88 Normally structs should never be allocated by plugins.
498964e @ntrel Replace Plugins chapter with 'Writing plugins' section.
ntrel authored
89
87ec6a3 @ntrel Add 'Doc-comments' plugin API subsection.
ntrel authored
90 Keeping the plugin ABI stable
91 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
498964e @ntrel Replace Plugins chapter with 'Writing plugins' section.
ntrel authored
92 Before the 1.0 release series, the ABI can change when necessary, and
93 even the API can change. An ABI change just means that all plugins will
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
94 not load and they must be rebuilt. An API change means that some plugins
498964e @ntrel Replace Plugins chapter with 'Writing plugins' section.
ntrel authored
95 might not build correctly.
96
2955303 @ntrel Add section 'Plugin API/ABI design'.
ntrel authored
97 If you're reordering or changing existing elements of structs that are
87ec6a3 @ntrel Add 'Doc-comments' plugin API subsection.
ntrel authored
98 used as part of the plugin API, you must increment GEANY_ABI_VERSION
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
99 in plugindata.h. This is usually not needed if you're just appending
100 fields to structs. The GEANY_API_VERSION value should be incremented
101 for any changes to the plugin API, including appending elements.
498964e @ntrel Replace Plugins chapter with 'Writing plugins' section.
ntrel authored
102
103 If you're in any doubt when making changes to plugin API code, just ask us.
104
2955303 @ntrel Add section 'Plugin API/ABI design'.
ntrel authored
105 Plugin API/ABI design
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
106 ^^^^^^^^^^^^^^^^^^^^^
2955303 @ntrel Add section 'Plugin API/ABI design'.
ntrel authored
107 You should not make plugins rely on the size of a struct. This means:
108
109 * Don't let plugins allocate any structs (stack or heap).
110 * Don't let plugins index any arrays of structs.
111 * Don't add any array fields to structs in case we want to change the
112 array size later.
113
87ec6a3 @ntrel Add 'Doc-comments' plugin API subsection.
ntrel authored
114 Doc-comments
115 ^^^^^^^^^^^^
116 * The @file tag can go in the source .c file, but use the .h header name so
117 it appears normally in the generated documentation. See ui_utils.c for an
118 example.
119 * Function doc-comments should always go in the source file, not the
120 header, so they can be updated if/when the implementation changes.
121
5325bd1 @ntrel Add HACKING file for new contributors.
ntrel authored
122 Glade
123 -----
4fbabc1 @codebrainz Update Glade section in HACKING file
codebrainz authored
124 Add user-interface widgets to the Glade 3 file ``data/geany.glade``.
125 Callbacks for the user-interface should go in ``src/callbacks.c``.
672365a @eht16 Add note about patching Glade 2.12 to compile it with newer GTK versi…
eht16 authored
126
769dbde @ntrel Change GTK 2.8 -> 2.12.
ntrel authored
127 GTK versions & API documentation
128 --------------------------------
a23e999 @codebrainz Bump GTK+ version to 2.16
codebrainz authored
129 Geany requires GTK >= 2.16 and GLib >= 2.20. API symbols from newer
cc045b6 @elextr Document building plugins for hacked Geany
elextr authored
130 GTK/GLib versions should be avoided or made optional to keep the source
769dbde @ntrel Change GTK 2.8 -> 2.12.
ntrel authored
131 code building on older systems.
132
a23e999 @codebrainz Bump GTK+ version to 2.16
codebrainz authored
133 The official GTK 2.16 API documentation may not be available online
cc045b6 @elextr Document building plugins for hacked Geany
elextr authored
134 anymore, so we put it on http://www.geany.org/manual/gtk/. There
135 is also a tarball with all available files for download and use with
769dbde @ntrel Change GTK 2.8 -> 2.12.
ntrel authored
136 devhelp.
137
a23e999 @codebrainz Bump GTK+ version to 2.16
codebrainz authored
138 Using the 2.16 API documentation of the GTK libs (including GLib, GDK
cc045b6 @elextr Document building plugins for hacked Geany
elextr authored
139 and Pango) has the advantages that you don't get confused by any
140 newer API additions and you don't have to take care about whether
769dbde @ntrel Change GTK 2.8 -> 2.12.
ntrel authored
141 you can use them or not.
8f49698 @eht16 Add note and link for GTK 2.6 API docs.
eht16 authored
142
5325bd1 @ntrel Add HACKING file for new contributors.
ntrel authored
143 Coding
144 ------
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
145 * Don't write long functions with a lot of variables and/or scopes - break
146 them down into smaller static functions where possible. This makes code
147 much easier to read and maintain.
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
148 * Use GLib types and functions - gint not int, g_free() not free().
a23e999 @codebrainz Bump GTK+ version to 2.16
codebrainz authored
149 * Your code should build against GLib 2.20 and GTK 2.16. At least for the
150 moment, we want to keep the minimum requirement for GTK at 2.16 (of
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
151 course, you can use the GTK_CHECK_VERSION macro to protect code using
152 later versions).
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
153 * Variables should be declared before statements. You can use
154 gcc's -Wdeclaration-after-statement to warn about this.
155 * Don't let variable names shadow outer variables - use gcc's -Wshadow
156 option.
822240d @ntrel Add Style example for structs, doc-comments
ntrel authored
157 * Do not use G_LIKELY or G_UNLIKELY (except in critical loops). These
158 add noise to the code with little real benefit.
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
159
160 Compiler options & warnings
161 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
162 Use ``CFLAGS='-Wfoo' ./configure`` or ``CFLAGS='-Wfoo' ./autogen.sh``
163 to set warning options (as well as anything else e.g. -g -O2).
164
165 * Enable warnings - for gcc use '-Wall -W' (and optionally
166 -Wno-unused-parameter to avoid unused parameter warnings in Glade
167 callbacks).
168 * You should try to write ISO C90 code for portability, so always
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
169 use C ``/* */`` comments and function_name(void) instead of
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
170 function_name(). This is for compatibility with various Unix-like
171 compilers. You should use -ansi to help check this.
59e8466 @b4n Update HACKING to suggest MIO_FORCE_ANSI for building with -ansi
b4n authored
172 Note that MIO (tagmanager/mio) requires ``MIO_FORCE_ANSI``
173 preprocessor constant to be defined to build with ``-ansi``, so you
174 should add ``-DMIO_FORCE_ANSI`` together with ``-ansi``.
5325bd1 @ntrel Add HACKING file for new contributors.
ntrel authored
175
2c4cb09 @ntrel Add tip about gcc optimization & warnings/debugging.
ntrel authored
176 .. tip::
177 Remember for gcc you need to enable optimization to get certain
178 warnings like uninitialized variables, but for debugging it's
179 better to have no optimization on.
180
5325bd1 @ntrel Add HACKING file for new contributors.
ntrel authored
181 Style
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
182 ^^^^^
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
183 * We use a tab width of 4 and indent completely with tabs not spaces.
2866d0e @ntrel Note the documentation files use (4) spaces for indentation.
ntrel authored
184 Note the documentation files use (4) spaces instead, so you may want
185 to use the 'Detect from file' indent pref.
f926553 @elextr Mention trailing whitespace in style
elextr authored
186 * Do not add whitespace at the end of lines, this adds to commit noise.
187 When editing with Geany set preference files->Strip trailing spaces
188 and tabs.
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
189 * Use the multiline comment ``/* */`` to comment small blocks of code,
190 functions descriptions or longer explanations of code, etc. C++ single
191 line comments will cause portability issues. The more comments are in
ca33ea6 @b4n Update HACKING for Git switch
b4n authored
192 your code the better. (See also ``scripts/fix-cxx-comments.pl`` in Git).
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
193 * Lines should not be longer than about 100 characters and after 100
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
194 characters the lines should be wrapped and indented once more to
195 show that the line is continued.
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
196 * We don't put spaces between function names and the opening brace for
197 argument lists.
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
198 * Variable declarations come first after an opening brace, then one
199 newline to separate declarations and code.
200 * 2-operand operators should have a space each side.
201 * Function bodies should have 2 blank newlines after them.
202 * Align braces together on separate lines.
203 * Don't put assignments in 'if/while/etc' expressions.
204 * if statements without brace bodies should have the code on a separate
205 line, then a blank line afterwards.
206 * Use braces after if/while statements if the body uses another
207 if/while statement.
208 * Try to fit in with the existing code style.
209
210 .. note::
ca33ea6 @b4n Update HACKING for Git switch
b4n authored
211 A few of the above can be done with the Git
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
212 ``scripts/fix-alignment.pl``, but it is quite dumb and it's much better
213 to write it correctly in the first place.
f926553 @elextr Mention trailing whitespace in style
elextr authored
214 ``scripts/rstrip-whitespace.py`` just removes trailing whitespace.
215
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
216
217 .. below tabs should be used, but spaces are required for reST.
218
219 Example::
220
822240d @ntrel Add Style example for structs, doc-comments
ntrel authored
221 struct Bar;
222
223 typedef struct Foo /* struct names normally are the same as typedef names */
224 {
225 gint foo; /* names are somewhat aligned visually */
226 gint bar; /* fields don't share the same line */
227 SomeLongTypeName baz; /* alignment is not strict */
228 gchar *ptr; /* pointer symbol must go next to variable name, not type */
229 Bar public; /**< only plugin API fields have a doc-comment */
230 }
231 Foo;
232
233
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
234 gint some_func(void);
235
822240d @ntrel Add Style example for structs, doc-comments
ntrel authored
236 gint some_other_func(void);
237
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
238
822240d @ntrel Add Style example for structs, doc-comments
ntrel authored
239 /* optional function comment explains something important */
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
240 gint function_long_name(gchar arg1, <too many args to fit on this line>,
241 gchar argN)
242 {
822240d @ntrel Add Style example for structs, doc-comments
ntrel authored
243 /* variable declarations always go before code in each scope */
244 /* variable names should NOT be aligned at all */
b00d39b @ntrel Add example of pointer declarations and more operator spacing.
ntrel authored
245 gint foo, bar; /* variables can go on the same line */
822240d @ntrel Add Style example for structs, doc-comments
ntrel authored
246 gint baz; /* but often don't */
b00d39b @ntrel Add example of pointer declarations and more operator spacing.
ntrel authored
247 gchar *ptr; /* pointer symbol must go next to variable name, not type */
2866d0e @ntrel Note the documentation files use (4) spaces for indentation.
ntrel authored
248 gchar *another; /* pointers should normally go on separate lines */
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
249
fdf62f3 @ntrel Add some Style example comments.
ntrel authored
250 /* Some long comment block
251 * taking several different
252 * lines to explain */
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
253 if (foo)
254 {
822240d @ntrel Add Style example for structs, doc-comments
ntrel authored
255 /* variables only used in one scope should normally be declared there */
256 gint dir = -1;
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
257
258 bar = foo;
b00d39b @ntrel Add example of pointer declarations and more operator spacing.
ntrel authored
259 if ((bar & (guint)dir) != 7)
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
260 some_code(arg1, <too many args to fit on this line>,
261 argN - 1, argN);
262
263 some_func();
264 }
265 }
266
267
822240d @ntrel Add Style example for structs, doc-comments
ntrel authored
268 /** Explains using doc-comments for plugin API functions.
269 * First line should be short and use the third person tense - 'explains',
270 * not 'explain'.
271 *
272 * @return Some number.
273 * @since 1.22. */
51dc7f0 @ntrel Add 'Compiler options & warnings' section.
ntrel authored
274 gint another_function(void)
275 {
276 ...
277
5325bd1 @ntrel Add HACKING file for new contributors.
ntrel authored
278
ca33ea6 @b4n Update HACKING for Git switch
b4n authored
279 Committing
280 ----------
281
2aafa6a @b4n Improve the part about committing in HACKING
b4n authored
282 * Commit one thing at a time, do small commits. Commits should be
283 meaningful and not too big when possible; multiple small commits are
284 good if there is no good reason to group them.
285 * Use meaningful name and email in the Author and Committer fields.
286 This helps knowing who did what and allows to contact the author if
287 there is a good reason to do so (unlikely, but can happen).
288 * When working on a new feature, create a new branch for it. When
289 merging it, use the --no-ff option to make sure a merge commit will
290 be created to better track what happened. However, if the feature
291 only took one commit you might merge it fast-forward since there is
292 not history to keep together.
ca33ea6 @b4n Update HACKING for Git switch
b4n authored
293
294 Commit messages
295 ^^^^^^^^^^^^^^^
296 Follow the standard Git formatting:
297
2aafa6a @b4n Improve the part about committing in HACKING
b4n authored
298 * No line should use more than about 80 characters (around 72 is best).
299 * The first line is the commit's summary and is followed by an empty
300 line. This summary should be one line and one line only, thus less
301 than 80 characters. This summary should not include any punctuation
302 unless really needed. See it as the subject of an email: keep it
303 concise and as precise as you can, but not tool long.
ca33ea6 @b4n Update HACKING for Git switch
b4n authored
304 * Following lines are optional detailed commit information, with
2aafa6a @b4n Improve the part about committing in HACKING
b4n authored
305 paragraphs separated by blank lines. This part should be as long as
306 needed to describe the commit in depth, should use proper
307 punctuation and should include any useful information, like the
308 motivation for the patch and/or any valuable details the diff itself
309 don't provide or don't make clear. Make it as complete as you think
310 it makes sense, but don't include an information that is better
311 explained by the commit's diff.
312
313 It is OK to use ASCII formatting like bullet list using "*" or "-",
314 etc. if useful, but emphasis (bold, italic, underline) should be
315 avoided.
ca33ea6 @b4n Update HACKING for Git switch
b4n authored
316
317 Example::
318
319 Ask the user if spawn fails in utils_open_browser()
320
321 Ask the user to configure a valid browser command if spawning it
322 fails rather than falling back to some arbitrary hardcoded defaults.
323
324 This avoid spawning an unexpected browser when the configured one is
325 wrong, and gives the user a chance to correctly fix the preference.
326
327
2c4cb09 @ntrel Add tip about gcc optimization & warnings/debugging.
ntrel authored
328 Testing
329 -------
330 * Run with ``-v`` to print any debug messages.
331 * You can use a second instance (``geany -i``).
332 * To check first-run behaviour, use an alternate config directory by
333 passing ``-c some_dir`` (but make sure the directory is clean first).
334 * For debugging tips, see `GDB`_.
335
c97ce77 @ntrel Add 'Bugs to watch out for' section.
ntrel authored
336 Bugs to watch out for
337 ---------------------
338 * Forgetting to check *doc->is_valid* when looping through
339 *documents_array* - instead use *foreach_document()*.
3c0d7a9 @ntrel Add 3 bugs to watch out for.
ntrel authored
340 * Inserting fields into structs in the plugin API instead of appending.
c97ce77 @ntrel Add 'Bugs to watch out for' section.
ntrel authored
341 * Not breaking the plugin ABI when necessary.
342 * Using an idle callback that doesn't check main_status.quitting.
6e46a7b @ntrel Fix existing leak when a matching ignore.tags item is parsed
ntrel authored
343 * Forgetting to call vStringTerminate in CTags code.
3c0d7a9 @ntrel Add 3 bugs to watch out for.
ntrel authored
344 * Forgetting CRLF line endings on Windows.
dcf24a5 @ntrel Combine, move, remove, edit 0.20 items.
ntrel authored
345 * Not handling Tabs & Spaces indent mode.
c97ce77 @ntrel Add 'Bugs to watch out for' section.
ntrel authored
346
5325bd1 @ntrel Add HACKING file for new contributors.
ntrel authored
347 Libraries
348 ---------
2c4cb09 @ntrel Add tip about gcc optimization & warnings/debugging.
ntrel authored
349 We try to use an unmodified version of Scintilla - any new lexers or
350 other changes should be passed on to the maintainers at
351 http://scintilla.org. We normally update to a new Scintilla release
ab6bde0 @ntrel Add README for Scintilla explaining keeping in sync with scintilla.or…
ntrel authored
352 shortly after one is made. See also scintilla/README.
49c0715 @ntrel Reformat text width with fmt. Add comment about running Glade 2.10 un…
ntrel authored
353
354 Tagmanager was originally taken from Anjuta 1.2.2, and parts of it
355 (notably c.c) have been merged from later versions of Anjuta and
356 CTags. The independent Tagmanager library itself ceased development
357 before Geany was started. It's source code parsing is mostly taken from
2c4cb09 @ntrel Add tip about gcc optimization & warnings/debugging.
ntrel authored
358 Exuberant CTags (see http://ctags.sf.net). If appropriate it's good to
359 pass language parser changes back to the CTags project.
5325bd1 @ntrel Add HACKING file for new contributors.
ntrel authored
360
361
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
362 Notes
0e9a9eb @ntrel Add note about Adding a TagManager parser.
ntrel authored
363 =====
49c0715 @ntrel Reformat text width with fmt. Add comment about running Glade 2.10 un…
ntrel authored
364 Some of these notes below are brief (or maybe incomplete) - please
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
365 contact the geany-devel mailing list for more information.
1e41e97 @ntrel Added 'About this file' and links for some Windows developer tools.
ntrel authored
366
1d57381 @eht16 Add note about using autotools macros like DATADIR.
eht16 authored
367 Using pre-defined autotools values
368 ----------------------------------
3fef2dc @eht16 Prefix autotools macros with GEANY to avoid problems with already def…
eht16 authored
369 When you are use macros supplied by the autotools like GEANY_PREFIX,
370 GEANY_LIBDIR, GEANY_DATADIR and GEANY_LOCALEDIR be aware that these
371 might not be static strings when Geany is configured with
372 --enable-binreloc. Then these macros will be replaced by function calls
373 (in src/prefix.h). So, don't use anything like
374 printf("Prefix: " GEANY_PREFIX); but instead use
375 printf("Prefix: %s", GEANY_PREFIX);
1d57381 @eht16 Add note about using autotools macros like DATADIR.
eht16 authored
376
76e9f77 @ntrel Move adding a lexer notes to 'Syntax highlighting' section; mention
ntrel authored
377 Adding a source file foo.[hc] in src/ or plugins/
378 -------------------------------------------------
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
379 * Add foo.c, foo.h to SRCS in path/Makefile.am.
380 * Add foo.o to OBJS in path/makefile.win32.
cbe2c05 @ntrel Mention updating wscript.
ntrel authored
381 * Add path/foo.c to geany_sources in wscript.
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
382 * Add path/foo.c to po/POTFILES.in (for string translation).
1e41e97 @ntrel Added 'About this file' and links for some Windows developer tools.
ntrel authored
383
384 Adding a filetype
385 -----------------
49c0715 @ntrel Reformat text width with fmt. Add comment about running Glade 2.10 un…
ntrel authored
386 You can add a filetype without syntax highlighting or tag parsing, but
387 check to see if those features have been written in other projects first.
0f3ffc3 @ntrel Add more information for adding a filetype.
ntrel authored
388
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
389 * Add GEANY_FILETYPES_FOO to filetypes.h.
390 * Initialize GEANY_FILETYPES_FOO in init_builtin_filetypes() of
01e2679 @ntrel Mention using filetype_make_title() when adding a filetype.
ntrel authored
391 filetypes.c. You should use filetype_make_title() to avoid a
392 translation whenever possible.
6bd8f44 @ntrel Remove --generate-data-files argument & code - just edit
ntrel authored
393 * Update data/filetype_extensions.conf.
af91a81 @ntrel Add more complete information for adding a filetype.
ntrel authored
394
8fcf207 @ntrel Update adding a filetype section, make clearer.
ntrel authored
395 filetypes.* configuration file
396 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
f7df2ff @ntrel Add a default configuration file for reStructuredText.
ntrel authored
397 All languages need a data/filetypes.foo configuration file. See
fd2f439 @ntrel Update docs for named styles in filetypes.* files.
ntrel authored
398 the "Filetype definition files" section in the manual and/or
8fcf207 @ntrel Update adding a filetype section, make clearer.
ntrel authored
399 data/filetypes.c for an example.
af91a81 @ntrel Add more complete information for adding a filetype.
ntrel authored
400
401 Programming languages should have:
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
402
403 * [keywords] if the lexer supports it.
404 * [settings] mostly for comment settings.
405 * [build_settings] for commands to run.
af91a81 @ntrel Add more complete information for adding a filetype.
ntrel authored
406
8fcf207 @ntrel Update adding a filetype section, make clearer.
ntrel authored
407 For languages with a Scintilla lexer, there should be a [styling] section,
a00366b @b4n Update HACKING for highlighting setup refactoring
b4n authored
408 to correspond to the styles used in highlighting_styles_FOO[] in
409 highlightingmappings.h - see below.
8fcf207 @ntrel Update adding a filetype section, make clearer.
ntrel authored
410
411 Syntax highlighting
412 ^^^^^^^^^^^^^^^^^^^
76e9f77 @ntrel Move adding a lexer notes to 'Syntax highlighting' section; mention
ntrel authored
413 It may be possible to use an existing Scintilla lexer in the scintilla/
414 subdirectory - if not, you will need to find (or write) one,
01e2679 @ntrel Mention using filetype_make_title() when adding a filetype.
ntrel authored
415 LexFoo.cxx. Try the official Scintilla project first.
416
417 .. warning::
418 We won't accept adding a lexer that conflicts with one in
419 Scintilla. All new lexers should be submitted back to the Scintilla
420 project to save duplication of work.
421
422 When adding a lexer, update:
76e9f77 @ntrel Move adding a lexer notes to 'Syntax highlighting' section; mention
ntrel authored
423
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
424 * scintilla/Makefile.am
425 * scintilla/makefile.win32
cbe2c05 @ntrel Mention updating wscript.
ntrel authored
426 * wscript
1ce4b1f @b4n Fix a reference to a file in HACKING
b4n authored
427 * scintilla/src/Catalogue.cxx - add a LINK_LEXER command *manually*
76e9f77 @ntrel Move adding a lexer notes to 'Syntax highlighting' section; mention
ntrel authored
428
a00366b @b4n Update HACKING for highlighting setup refactoring
b4n authored
429 For syntax highlighting, you will need to edit highlighting.c and
430 highlightingmappings.h and add the following things:
431
432 1. In highlightingmappings.h:
433
434 a. define ``highlighting_lexer_FOO`` to the Scintilla lexer ID for
435 this filtype, e.g. ``SCLEX_CPP``.
436 b. define the ``highlighting_styles_FOO`` array that maps Scintilla
437 style states to style names in the configuration file.
438 c. define ``highlighting_keywords_FOO`` to ``EMPTY_KEYWORDS`` if the
439 filtype has no keywords, or as an ``HLKeyword`` array mapping
440 the Scintilla keyword IDs to names in the configuration file.
441 d. define ``highlighting_properties_FOO`` to ``EMPTY_PROPERTIES``, or
442 as an array of ``HLProperty`` if the filetype requires some lexer
443 properties to be set. However, note that properties should
444 normally be set in the ``[lexer_properties]`` section of the
445 configuration file instead.
446
447 You may look at other filtype's definitions for some examples
448 (Ada, CSS or Diff being good examples).
449
450 2. In highlighting.c:
451
452 a. Add ``init_styleset_case(FOO);`` in ``highlighting_init_styles()``.
453 b. Add ``styleset_case(FOO);`` in ``highlighting_set_styles()``.
454
455 3. Write data/filetypes.foo configuration file [styling] section. See
fc344b6 @ntrel Update notes about data/filetypes.foo configuration file [styling] se…
ntrel authored
456 the manual and see data/filetypes.d for a named style example.
457
458 .. note::
459 Please try to make your styles fit in with the other filetypes'
460 default colors, and to use named styles where possible (e.g.
461 "commentline=comment"). Filetypes that share a lexer should have
462 the same colors. If not using named styles, leave the background color
463 empty to match the default color.
c3db657 @ntrel Update 'Adding a filetype' section for new highlighting.c code.
ntrel authored
464
bf3ea6c @ntrel Add filetypes.* [build_settings] key 'error_regex' to support custom
ntrel authored
465 Error message parsing
466 ^^^^^^^^^^^^^^^^^^^^^
467 New-style error message parsing is done with an extended GNU-style regex
468 stored in the filetypes.foo file - see the [build_settings] information
469 in the manual for details.
470
471 Old-style error message parsing is done in
472 msgwin_parse_compiler_error_line() of msgwindow.c - see the ParseData
473 typedef for more information.
474
8fcf207 @ntrel Update adding a filetype section, make clearer.
ntrel authored
475 Other features
476 ^^^^^^^^^^^^^^
7e93252 @ntrel Fix for moved highlighting_is_{comment,string}_style().
ntrel authored
477 If the lexer has comment styles, you should add them in
478 highlighting_is_comment_style(). You should also update
479 highlighting_is_string_style() for string/character styles. For now,
480 this prevents calltips and autocompletion when typing in a comment
481 (but it can still be forced by the user).
482
c3db657 @ntrel Update 'Adding a filetype' section for new highlighting.c code.
ntrel authored
483 For brace indentation, update lexer_has_braces() in editor.c;
484 indentation after ':' is done from on_new_line_added().
af91a81 @ntrel Add more complete information for adding a filetype.
ntrel authored
485
8fcf207 @ntrel Update adding a filetype section, make clearer.
ntrel authored
486 If the Scintilla lexer supports user type keyword highlighting (e.g.
9bffb94 @codebrainz Real-time type keyword highlighting
codebrainz authored
487 SCLEX_CPP), update document_update_tags() in document.c.
0f3ffc3 @ntrel Add more information for adding a filetype.
ntrel authored
488
0e9a9eb @ntrel Add note about Adding a TagManager parser.
ntrel authored
489 Adding a TagManager parser
76e9f77 @ntrel Move adding a lexer notes to 'Syntax highlighting' section; mention
ntrel authored
490 ^^^^^^^^^^^^^^^^^^^^^^^^^^
8fcf207 @ntrel Update adding a filetype section, make clearer.
ntrel authored
491 This assumes the filetype for Geany already exists.
0e9a9eb @ntrel Add note about Adding a TagManager parser.
ntrel authored
492
49c0715 @ntrel Reformat text width with fmt. Add comment about running Glade 2.10 un…
ntrel authored
493 First write or find a CTags compatible parser, foo.c. Note that there
494 are some language patches for CTags at:
0e9a9eb @ntrel Add note about Adding a TagManager parser.
ntrel authored
495 http://sf.net/projects/ctags - see the tracker.
496
1e41e97 @ntrel Added 'About this file' and links for some Windows developer tools.
ntrel authored
497 (You can also try the Anjuta project's tagmanager codebase.)
498
3462cc9 @ntrel Add note about using GRegex for tag parsers instead of POSIX regex.
ntrel authored
499 .. note::
cc045b6 @elextr Document building plugins for hacked Geany
elextr authored
500 From Geany 1.22 GLib's GRegex engine is used instead of POSIX
501 regex, unlike CTags. It should be close enough to POSIX to work
3462cc9 @ntrel Add note about using GRegex for tag parsers instead of POSIX regex.
ntrel authored
502 OK.
cc045b6 @elextr Document building plugins for hacked Geany
elextr authored
503 We no longer support regex parsers with the "b" regex flag
504 option set and Geany will print debug warnings if it's used.
505 CTags supports it but doesn't currently (2011) include any
506 parsers that use it. It should be easy to convert to extended
3462cc9 @ntrel Add note about using GRegex for tag parsers instead of POSIX regex.
ntrel authored
507 regex syntax anyway.
508
509 Method
510 ``````
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
511 * Add foo.c to SRCS in Makefile.am.
512 * Add foo.o to OBJS in makefile.win32.
cbe2c05 @ntrel Mention updating wscript.
ntrel authored
513 * Add path/foo.c to geany_sources in wscript.
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
514 * Add Foo to parsers.h & fill in comment with parser number for foo.
0e9a9eb @ntrel Add note about Adding a TagManager parser.
ntrel authored
515
516 In foo.c:
517 Edit FooKinds 3rd column to match a s_tag_type_names string in tm_tag.c.
2f8df12 @ntrel Add some info about making the parser tag kinds and symbol list compa…
ntrel authored
518 (You may want to make the symbols.c change before doing this).
0e9a9eb @ntrel Add note about Adding a TagManager parser.
ntrel authored
519
bf3ea6c @ntrel Add filetypes.* [build_settings] key 'error_regex' to support custom
ntrel authored
520 In filetypes.c, init_builtin_filetypes():
1e41e97 @ntrel Added 'About this file' and links for some Windows developer tools.
ntrel authored
521 Set filetypes[GEANY_FILETYPES_FOO].lang = foo's parser number.
0e9a9eb @ntrel Add note about Adding a TagManager parser.
ntrel authored
522
523 In symbols.c:
2f8df12 @ntrel Add some info about making the parser tag kinds and symbol list compa…
ntrel authored
524 Unless your parser uses C-like tag type kinds, update
525 add_top_level_items() for foo, calling tag_list_add_groups(). See
526 get_tag_type_iter() for which tv_iters fields to use.
6e53eac @ntrel Added very basic plugin support - any plugins found in
ntrel authored
527
528
e726bf9 @ntrel Add GDB 'Stop on warnings' and 'Running with batch commands'
ntrel authored
529 GDB
530 ---
531
532 Stop on warnings
533 ^^^^^^^^^^^^^^^^
534 When a GLib or GTK warning is printed, often you want to get a
535 backtrace to find out what code caused them. You can do that with the
536 ``--g-fatal-warnings`` argument, which will abort Geany on the first
537 warning it receives.
538
539 But for ordinary testing, you don't always want your editor to abort
540 just because of a warning - use::
541
542 (gdb) b handler_log if level <= G_LOG_LEVEL_WARNING
543
544
545 Running with batch commands
546 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
547 Use::
548
549 $ gdb src/geany -x gdb-commands
550
551 Where ``gdb-commands`` is a file with the following lines::
552
553 set pagination off
554 b handler_log if level <= G_LOG_LEVEL_WARNING
ab81ef9 @frlan Remove deprecated --debug flag. Please use --verbose/-v instead.
frlan authored
555 r -v
e726bf9 @ntrel Add GDB 'Stop on warnings' and 'Running with batch commands'
ntrel authored
556
557
558 Loading a plugin
559 ^^^^^^^^^^^^^^^^
6e53eac @ntrel Added very basic plugin support - any plugins found in
ntrel authored
560 This is useful so you can load plugins without installing them first.
d7caf0f @eht16 Follow XDG Base Directory specification and use $XDG_CONFIG_HOME/gean…
eht16 authored
561 Alternatively you can use a symlink in ~/.config/geany/plugins or
49c0715 @ntrel Reformat text width with fmt. Add comment about running Glade 2.10 un…
ntrel authored
562 $prefix/lib/geany (where $prefix is /usr/local by default).
6e53eac @ntrel Added very basic plugin support - any plugins found in
ntrel authored
563
564 The gdb session below was run from the toplevel Geany source directory.
565 Start normally with e.g. "gdb src/geany".
566 Type 'r' to run.
567 Press Ctrl-C from the gdb window to interrupt program execution.
568
6d4068f @ntrel Reformat HACKING as true reStructuredText.
ntrel authored
569 Example::
570
faa4e73 @ntrel Remove accidentally added tab indentation.
ntrel authored
571 Program received signal SIGINT, Interrupt.
572 0x00d16402 in __kernel_vsyscall ()
573 (gdb) call plugin_new("./plugins/.libs/demoplugin.so")
574 ** INFO: Loaded: ./plugins/.libs/demoplugin.so (Demo)
575 $1 = (Plugin *) 0x905a890
576 (gdb) c
577 Continuing.
578
579 Program received signal SIGINT, Interrupt.
580 0x00d16402 in __kernel_vsyscall ()
581 (gdb) call plugin_free(0x905a890)
582 ** INFO: Unloaded: ./plugins/.libs/demoplugin.so
583 (gdb) c
584 Continuing.
cc045b6 @elextr Document building plugins for hacked Geany
elextr authored
585
586 Building Plugins
587 ^^^^^^^^^^^^^^^^
588
589 The geany-plugins autotools script automatically detects the
590 installed system Geany and builds the plugins against that.
591
592 To use plugins with a development version of Geany built with
593 a different prefix, the plugins will need to be compiled against
594 that version if the ABI has changed.
595
596 To do this you need to specify both --prefix and --with-geany-libdir
597 to the plugin configure. Normally the plugin prefix is the
598 same as the Geany prefix to keep plugins with the version of Geany
599 that they are compiled against, and with-geany-libdir is the Geany
600 prefix/lib.
601
602 Whilst it is possible for the plugin prefix to be different to
603 the prefix of the libdir (which is why there are two settings),
604 it is probably better to keep the version of Geany and its plugins
605 together.
Something went wrong with that request. Please try again.