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
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.
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
23 * The API documentation contains a few basic guidelines and hints to
26 You should generate and read the plugin API documentation, see below.
28 Plugin API documentation
29 ^^^^^^^^^^^^^^^^^^^^^^^^
30 You can generate documentation for the plugin API using the doxygen
31 tool. Run ``make api-doc`` in the doc subdirectory. The documentation
32 will be output to doc/reference/index.html.
33 Alternatively you can view the API documentation online at
34 http://www.geany.org/manual/reference/.
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.
42 In general it's best to work from the current SVN, but we accept patches
43 against other releases::
45 $ svn diff > fix-some-bug.patch
47 If you're not using SVN, you can use the diff command::
49 $ diff -u originalpath modifiedpath > new-feature.patch
52 Please make sure patches follow the style of existing code - In
53 particular, use tabs for indentation. See `Coding`_.
57 * Subversion (SVN): http://subversion.tigris.org/
58 * diff, grep, etc: http://mingw.org/ or http://unxutils.sourceforge.net/
60 See also the 'Building on Windows' document on the website.
64 callbacks.c is just for Glade callbacks.
65 Avoid adding code to geany.h if it will fit better elsewhere.
66 See the top of each ``src/*.c`` file for a brief description of what
69 Keeping the plugin ABI stable
70 -----------------------------
71 Please be aware that anything with a doc-comment (a comment with an
72 extra asterix: ``/**``) is something in the plugin API. Things like
73 enums and structs can usually still be appended to, ensuring that all
74 the existing elements stay in place - this will keep the ABI stable.
78 Some structs like GeanyKeyGroupInfo and GeanyCallback cannot be
79 appended to without breaking the ABI because they are used to declare
80 structs by plugins, not just for accessing struct members through
83 Before the 1.0 release series, the ABI can change when necessary, and
84 even the API can change. An ABI change just means that all plugins will
85 not load and they must be rebuilt. An API change means that some plugins
86 might not build correctly.
88 If you're reordering or changing existing elements of structs that are
89 used as part of the plugin API, you should increment GEANY_ABI_VERSION
90 in plugindata.h. This is usually not needed if you're just appending
91 fields to structs. The GEANY_API_VERSION value should be incremented
92 for any changes to the plugin API, including appending elements.
94 If you're in any doubt when making changes to plugin API code, just ask us.
98 You should not make plugins rely on the size of a struct. This means:
100 * Don't let plugins allocate any structs (stack or heap).
101 * Don't let plugins index any arrays of structs.
102 * Don't add any array fields to structs in case we want to change the
107 Use the code generation features of Glade instead of editing interface.c
108 or support.c. Glade 2.12 is recommended as long as we support GTK+ 2.8,
109 because later versions of Glade are not 100% compatible with GTK+ 2.8
110 (e.g. they may use functions added in GTK+ 2.10).
112 You can build Glade 2.12 and run the binary in place, without installing
113 it - this should work fine even if you have another version of Glade
114 installed on the system.
116 GTK API documentation
117 ---------------------
118 The official GTK 2.8 API documentation is not available online anymore,
119 so we put them on http://www.geany.org/manual/gtk/.
120 There is also a tarball with all available files for download and use
123 Using the 2.8 API documentation of the GTK libs (including GLib, GDK and
124 Pango) has the advantages that you don't get confused by any newer API
125 additions and you don't have to take care about whether you can use
127 This is because Geany depends on GTK 2.8. API symbols from newer
128 GTK/GLib versions should be avoided to keep the source code building
133 * Don't write long functions with a lot of variables and/or scopes - break
134 them down into smaller static functions where possible. This makes code
135 much easier to read and maintain.
136 * Use GLib types and functions - gint not int, g_free() not free().
137 * Your code should build against GLib 2.8 and GTK 2.8. At least for the
138 moment, we want to keep the minimum requirement for GTK at 2.8 (of
139 course, you can use the GTK_CHECK_VERSION macro to protect code using
141 * Variables should be declared before statements. You can use
142 gcc's -Wdeclaration-after-statement to warn about this.
143 * Don't let variable names shadow outer variables - use gcc's -Wshadow
146 Compiler options & warnings
147 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
148 Use ``CFLAGS='-Wfoo' ./configure`` or ``CFLAGS='-Wfoo' ./autogen.sh``
149 to set warning options (as well as anything else e.g. -g -O2).
151 * Enable warnings - for gcc use '-Wall -W' (and optionally
152 -Wno-unused-parameter to avoid unused parameter warnings in Glade
154 * You should try to write ISO C90 code for portability, so always
155 use C ``/* */`` comments and function_name(void) instead of
156 function_name(). This is for compatibility with various Unix-like
157 compilers. You should use -ansi to help check this.
161 * We use a tab width of 4 and indent completely with tabs not spaces.
162 Note the documentation files use (4) spaces instead, so you may want
163 to use the 'Detect from file' indent pref.
164 * Use the multiline comment ``/* */`` to comment small blocks of code,
165 functions descriptions or longer explanations of code, etc. C++ single
166 line comments will cause portability issues. The more comments are in
167 your code the better. (See also ``scripts/fix-cxx-comments.pl`` in SVN).
168 * Lines should not be longer than about 100 characters and after 100
169 characters the lines should be wrapped and indented once more to
170 show that the line is continued.
171 * We don't put spaces between function names and the opening brace for
173 * Variable declarations come first after an opening brace, then one
174 newline to separate declarations and code.
175 * 2-operand operators should have a space each side.
176 * Function bodies should have 2 blank newlines after them.
177 * Align braces together on separate lines.
178 * Don't put assignments in 'if/while/etc' expressions.
179 * if statements without brace bodies should have the code on a separate
180 line, then a blank line afterwards.
181 * Use braces after if/while statements if the body uses another
183 * Try to fit in with the existing code style.
186 A few of the above can be done with the SVN
187 ``scripts/fix-alignment.pl``, but it is quite dumb and it's much better
188 to write it correctly in the first place.
190 .. below tabs should be used, but spaces are required for reST.
194 gint some_func(void);
197 gint function_long_name(gchar arg1, <too many args to fit on this line>,
200 gint foo, bar; /* variables can go on the same line */
201 gchar *ptr; /* pointer symbol must go next to variable name, not type */
202 gchar *another; /* pointers should normally go on separate lines */
206 gint dir = -1; /* -1 to search backwards */
209 if ((bar & (guint)dir) != 7)
210 some_code(arg1, <too many args to fit on this line>,
218 gint another_function(void)
225 We prefer to use an unmodified version of Scintilla - any changes should
226 be passed on to the maintainers at http://scintilla.org.
228 Tagmanager was originally taken from Anjuta 1.2.2, and parts of it
229 (notably c.c) have been merged from later versions of Anjuta and
230 CTags. The independent Tagmanager library itself ceased development
231 before Geany was started. It's source code parsing is mostly taken from
232 Exuberant CTags (see http://ctags.sf.net).
237 Some of these notes below are brief (or maybe incomplete) - please
238 contact the geany-devel mailing list for more information.
240 Using pre-defined autotools values
241 ----------------------------------
242 When you are use macros supplied by the autotools like GEANY_PREFIX,
243 GEANY_LIBDIR, GEANY_DATADIR and GEANY_LOCALEDIR be aware that these
244 might not be static strings when Geany is configured with
245 --enable-binreloc. Then these macros will be replaced by function calls
246 (in src/prefix.h). So, don't use anything like
247 printf("Prefix: " GEANY_PREFIX); but instead use
248 printf("Prefix: %s", GEANY_PREFIX);
250 Adding a source file foo.[hc] in src/ or plugins/
251 -------------------------------------------------
252 * Add foo.c, foo.h to SRCS in path/Makefile.am.
253 * Add foo.o to OBJS in path/makefile.win32.
254 * Add path/foo.c to po/POTFILES.in (for string translation).
258 You can add a filetype without syntax highlighting or tag parsing, but
259 check to see if those features have been written in other projects first.
261 * Add GEANY_FILETYPES_FOO to filetypes.h.
262 * Initialize GEANY_FILETYPES_FOO in init_builtin_filetypes() of
263 filetypes.c. You should use filetype_make_title() to avoid a
264 translation whenever possible.
265 * Update data/filetype_extensions.conf.
267 filetypes.* configuration file
268 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
269 All languages need a data/filetypes.foo configuration file. See
270 the "Filetype definition files" section in the manual and/or
271 data/filetypes.c for an example.
273 Programming languages should have:
275 * [keywords] if the lexer supports it.
276 * [settings] mostly for comment settings.
277 * [build_settings] for commands to run.
279 For languages with a Scintilla lexer, there should be a [styling] section,
280 to correspond to the styles used in styleset_foo() in highlighting.c -
285 It may be possible to use an existing Scintilla lexer in the scintilla/
286 subdirectory - if not, you will need to find (or write) one,
287 LexFoo.cxx. Try the official Scintilla project first.
290 We won't accept adding a lexer that conflicts with one in
291 Scintilla. All new lexers should be submitted back to the Scintilla
292 project to save duplication of work.
294 When adding a lexer, update:
296 * scintilla/Makefile.am
297 * scintilla/makefile.win32
298 * scintilla/KeyWords.cxx - add a LINK_LEXER command *manually*
300 For syntax highlighting, you will need to edit highlighting.c and add
301 the following things:
303 1. Write styleset_foo_init() to setup default styles and load style
304 settings from the filetypes.foo configuration file. You should probably
305 start by copying and adapting another filetype's initialization, such
306 as styleset_tcl_init(). Another way is to use load_style_entries()
307 to make style initialization simpler - see styleset_c_like_init().
310 Please try to make your styles fit in with the other filetypes' default
311 colors, and to use named styles where possible. Filetypes that share a
312 lexer should have the same colors. Normally, styles should leave the
313 background color empty to match the default color.
315 2. Write styleset_foo() to apply styles when a new scintilla widget
316 is created. Again you could copy and adapt a function like
318 3. In highlighting_init_styles(), add
319 ``init_styleset_case(GEANY_FILETYPES_FOO, styleset_foo_init);``.
320 4. In highlighting_set_styles(), add
321 ``styleset_case(GEANY_FILETYPES_FOO, styleset_foo);``.
323 Error message parsing
324 ^^^^^^^^^^^^^^^^^^^^^
325 New-style error message parsing is done with an extended GNU-style regex
326 stored in the filetypes.foo file - see the [build_settings] information
327 in the manual for details.
329 Old-style error message parsing is done in
330 msgwin_parse_compiler_error_line() of msgwindow.c - see the ParseData
331 typedef for more information.
335 For brace indentation, update lexer_has_braces() in editor.c;
336 indentation after ':' is done from on_new_line_added().
338 If the lexer has comment styles, you should add them in is_comment_style()
339 in editor.c. You should also update is_string_style() for string/character
340 styles. For now, this prevents calltips and autocompletion when typing
341 in a comment (but it can still be forced by the user).
343 If the Scintilla lexer supports user type keyword highlighting (e.g.
344 SCLEX_CPP), update editor_lexer_get_type_keyword_idx() in editor.c.
346 Adding a TagManager parser
347 ^^^^^^^^^^^^^^^^^^^^^^^^^^
348 This assumes the filetype for Geany already exists.
350 First write or find a CTags compatible parser, foo.c. Note that there
351 are some language patches for CTags at:
352 http://sf.net/projects/ctags - see the tracker.
354 (You can also try the Anjuta project's tagmanager codebase.)
356 * Add foo.c to SRCS in Makefile.am.
357 * Add foo.o to OBJS in makefile.win32.
358 * Add Foo to parsers.h & fill in comment with parser number for foo.
361 Edit FooKinds 3rd column to match a s_tag_type_names string in tm_tag.c.
363 In filetypes.c, init_builtin_filetypes():
364 Set filetypes[GEANY_FILETYPES_FOO].lang = foo's parser number.
367 If your parser doesn't use C-like tag type names, update
368 add_top_level_items() for foo, calling tag_list_add_groups().
376 When a GLib or GTK warning is printed, often you want to get a
377 backtrace to find out what code caused them. You can do that with the
378 ``--g-fatal-warnings`` argument, which will abort Geany on the first
381 But for ordinary testing, you don't always want your editor to abort
382 just because of a warning - use::
384 (gdb) b handler_log if level <= G_LOG_LEVEL_WARNING
387 Running with batch commands
388 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
391 $ gdb src/geany -x gdb-commands
393 Where ``gdb-commands`` is a file with the following lines::
396 b handler_log if level <= G_LOG_LEVEL_WARNING
402 This is useful so you can load plugins without installing them first.
403 Alternatively you can use a symlink in ~/.config/geany/plugins or
404 $prefix/lib/geany (where $prefix is /usr/local by default).
406 The gdb session below was run from the toplevel Geany source directory.
407 Start normally with e.g. "gdb src/geany".
409 Press Ctrl-C from the gdb window to interrupt program execution.
413 Program received signal SIGINT, Interrupt.
414 0x00d16402 in __kernel_vsyscall ()
415 (gdb) call plugin_new("./plugins/.libs/demoplugin.so")
416 ** INFO: Loaded: ./plugins/.libs/demoplugin.so (Demo)
417 $1 = (Plugin *) 0x905a890
421 Program received signal SIGINT, Interrupt.
422 0x00d16402 in __kernel_vsyscall ()
423 (gdb) call plugin_free(0x905a890)
424 ** INFO: Unloaded: ./plugins/.libs/demoplugin.so