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 provide git-formatted patches made from the
43 current Git (see `Committing`_)::
46 $ git format-patch HEAD^
48 We also accept patches against other releases, but it's more work for us.
50 If you're not using Git, although you're strongly suggested to used it,
51 you can use the diff command::
53 $ diff -u originalpath modifiedpath > new-feature.patch
55 However, such a patch won't contain the authoring information nor the
59 Please make sure patches follow the style of existing code - In
60 particular, use tabs for indentation. See `Coding`_.
64 * Git: http://git-scm.com/ and http://code.google.com/p/msysgit/
65 * diff, grep, etc: http://mingw.org/ or http://unxutils.sourceforge.net/
67 See also the 'Building on Windows' document on the website.
71 callbacks.c is just for Glade callbacks.
72 Avoid adding code to geany.h if it will fit better elsewhere.
73 See the top of each ``src/*.c`` file for a brief description of what
78 Please be aware that anything with a doc-comment (a comment with an
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.
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.
90 Keeping the plugin ABI stable
91 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
94 not load and they must be rebuilt. An API change means that some plugins
95 might not build correctly.
97 If you're reordering or changing existing elements of structs that are
98 used as part of the plugin API, you must increment GEANY_ABI_VERSION
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.
103 If you're in any doubt when making changes to plugin API code, just ask us.
105 Plugin API/ABI design
106 ^^^^^^^^^^^^^^^^^^^^^
107 You should not make plugins rely on the size of a struct. This means:
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
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
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.
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``.
127 GTK versions & API documentation
128 --------------------------------
129 Geany requires GTK >= 2.16 and GLib >= 2.20. API symbols from newer
130 GTK/GLib versions should be avoided or made optional to keep the source
131 code building on older systems.
133 The official GTK 2.16 API documentation may not be available online
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
138 Using the 2.16 API documentation of the GTK libs (including GLib, GDK
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
141 you can use them or not.
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.
148 * Use GLib types and functions - gint not int, g_free() not free().
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
151 course, you can use the GTK_CHECK_VERSION macro to protect code using
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
157 * Do not use G_LIKELY or G_UNLIKELY (except in critical loops). These
158 add noise to the code with little real benefit.
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).
165 * Enable warnings - for gcc use '-Wall -W' (and optionally
166 -Wno-unused-parameter to avoid unused parameter warnings in Glade
168 * You should try to write ISO C90 code for portability, so always
169 use C ``/* */`` comments and function_name(void) instead of
170 function_name(). This is for compatibility with various Unix-like
171 compilers. You should use -ansi to help check this.
174 Remember for gcc you need to enable optimization to get certain
175 warnings like uninitialized variables, but for debugging it's
176 better to have no optimization on.
180 * We use a tab width of 4 and indent completely with tabs not spaces.
181 Note the documentation files use (4) spaces instead, so you may want
182 to use the 'Detect from file' indent pref.
183 * Do not add whitespace at the end of lines, this adds to commit noise.
184 When editing with Geany set preference files->Strip trailing spaces
186 * Use the multiline comment ``/* */`` to comment small blocks of code,
187 functions descriptions or longer explanations of code, etc. C++ single
188 line comments will cause portability issues. The more comments are in
189 your code the better. (See also ``scripts/fix-cxx-comments.pl`` in Git).
190 * Lines should not be longer than about 100 characters and after 100
191 characters the lines should be wrapped and indented once more to
192 show that the line is continued.
193 * We don't put spaces between function names and the opening brace for
195 * Variable declarations come first after an opening brace, then one
196 newline to separate declarations and code.
197 * 2-operand operators should have a space each side.
198 * Function bodies should have 2 blank newlines after them.
199 * Align braces together on separate lines.
200 * Don't put assignments in 'if/while/etc' expressions.
201 * if statements without brace bodies should have the code on a separate
202 line, then a blank line afterwards.
203 * Use braces after if/while statements if the body uses another
205 * Try to fit in with the existing code style.
208 A few of the above can be done with the Git
209 ``scripts/fix-alignment.pl``, but it is quite dumb and it's much better
210 to write it correctly in the first place.
211 ``scripts/rstrip-whitespace.py`` just removes trailing whitespace.
214 .. below tabs should be used, but spaces are required for reST.
220 typedef struct Foo /* struct names normally are the same as typedef names */
222 gint foo; /* names are somewhat aligned visually */
223 gint bar; /* fields don't share the same line */
224 SomeLongTypeName baz; /* alignment is not strict */
225 gchar *ptr; /* pointer symbol must go next to variable name, not type */
226 Bar public; /**< only plugin API fields have a doc-comment */
231 gint some_func(void);
233 gint some_other_func(void);
236 /* optional function comment explains something important */
237 gint function_long_name(gchar arg1, <too many args to fit on this line>,
240 /* variable declarations always go before code in each scope */
241 /* variable names should NOT be aligned at all */
242 gint foo, bar; /* variables can go on the same line */
243 gint baz; /* but often don't */
244 gchar *ptr; /* pointer symbol must go next to variable name, not type */
245 gchar *another; /* pointers should normally go on separate lines */
247 /* Some long comment block
248 * taking several different
249 * lines to explain */
252 /* variables only used in one scope should normally be declared there */
256 if ((bar & (guint)dir) != 7)
257 some_code(arg1, <too many args to fit on this line>,
265 /** Explains using doc-comments for plugin API functions.
266 * First line should be short and use the third person tense - 'explains',
269 * @return Some number.
271 gint another_function(void)
279 * Commit one thing at a time, do small commits. Commits should be
280 meaningful and not too big when possible; multiple small commits are
281 good if there is no good reason to group them.
282 * Use meaningful name and email in the Author and Committer fields.
283 This helps knowing who did what and allows to contact the author if
284 there is a good reason to do so (unlikely, but can happen).
285 * When working on a new feature, create a new branch for it. When
286 merging it, use the --no-ff option to make sure a merge commit will
287 be created to better track what happened. However, if the feature
288 only took one commit you might merge it fast-forward since there is
289 not history to keep together.
293 Follow the standard Git formatting:
295 * No line should use more than about 80 characters (around 72 is best).
296 * The first line is the commit's summary and is followed by an empty
297 line. This summary should be one line and one line only, thus less
298 than 80 characters. This summary should not include any punctuation
299 unless really needed. See it as the subject of an email: keep it
300 concise and as precise as you can, but not tool long.
301 * Following lines are optional detailed commit information, with
302 paragraphs separated by blank lines. This part should be as long as
303 needed to describe the commit in depth, should use proper
304 punctuation and should include any useful information, like the
305 motivation for the patch and/or any valuable details the diff itself
306 don't provide or don't make clear. Make it as complete as you think
307 it makes sense, but don't include an information that is better
308 explained by the commit's diff.
310 It is OK to use ASCII formatting like bullet list using "*" or "-",
311 etc. if useful, but emphasis (bold, italic, underline) should be
316 Ask the user if spawn fails in utils_open_browser()
318 Ask the user to configure a valid browser command if spawning it
319 fails rather than falling back to some arbitrary hardcoded defaults.
321 This avoid spawning an unexpected browser when the configured one is
322 wrong, and gives the user a chance to correctly fix the preference.
327 * Run with ``-v`` to print any debug messages.
328 * You can use a second instance (``geany -i``).
329 * To check first-run behaviour, use an alternate config directory by
330 passing ``-c some_dir`` (but make sure the directory is clean first).
331 * For debugging tips, see `GDB`_.
333 Bugs to watch out for
334 ---------------------
335 * Forgetting to check *doc->is_valid* when looping through
336 *documents_array* - instead use *foreach_document()*.
337 * Inserting fields into structs in the plugin API instead of appending.
338 * Not breaking the plugin ABI when necessary.
339 * Using an idle callback that doesn't check main_status.quitting.
340 * Forgetting CRLF line endings on Windows.
341 * Not handling Tabs & Spaces indent mode.
345 We try to use an unmodified version of Scintilla - any new lexers or
346 other changes should be passed on to the maintainers at
347 http://scintilla.org. We normally update to a new Scintilla release
348 shortly after one is made. See also scintilla/README.
350 Tagmanager was originally taken from Anjuta 1.2.2, and parts of it
351 (notably c.c) have been merged from later versions of Anjuta and
352 CTags. The independent Tagmanager library itself ceased development
353 before Geany was started. It's source code parsing is mostly taken from
354 Exuberant CTags (see http://ctags.sf.net). If appropriate it's good to
355 pass language parser changes back to the CTags project.
360 Some of these notes below are brief (or maybe incomplete) - please
361 contact the geany-devel mailing list for more information.
363 Using pre-defined autotools values
364 ----------------------------------
365 When you are use macros supplied by the autotools like GEANY_PREFIX,
366 GEANY_LIBDIR, GEANY_DATADIR and GEANY_LOCALEDIR be aware that these
367 might not be static strings when Geany is configured with
368 --enable-binreloc. Then these macros will be replaced by function calls
369 (in src/prefix.h). So, don't use anything like
370 printf("Prefix: " GEANY_PREFIX); but instead use
371 printf("Prefix: %s", GEANY_PREFIX);
373 Adding a source file foo.[hc] in src/ or plugins/
374 -------------------------------------------------
375 * Add foo.c, foo.h to SRCS in path/Makefile.am.
376 * Add foo.o to OBJS in path/makefile.win32.
377 * Add path/foo.c to geany_sources in wscript.
378 * Add path/foo.c to po/POTFILES.in (for string translation).
382 You can add a filetype without syntax highlighting or tag parsing, but
383 check to see if those features have been written in other projects first.
385 * Add GEANY_FILETYPES_FOO to filetypes.h.
386 * Initialize GEANY_FILETYPES_FOO in init_builtin_filetypes() of
387 filetypes.c. You should use filetype_make_title() to avoid a
388 translation whenever possible.
389 * Update data/filetype_extensions.conf.
391 filetypes.* configuration file
392 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
393 All languages need a data/filetypes.foo configuration file. See
394 the "Filetype definition files" section in the manual and/or
395 data/filetypes.c for an example.
397 Programming languages should have:
399 * [keywords] if the lexer supports it.
400 * [settings] mostly for comment settings.
401 * [build_settings] for commands to run.
403 For languages with a Scintilla lexer, there should be a [styling] section,
404 to correspond to the styles used in highlighting_styles_FOO[] in
405 highlightingmappings.h - see below.
409 It may be possible to use an existing Scintilla lexer in the scintilla/
410 subdirectory - if not, you will need to find (or write) one,
411 LexFoo.cxx. Try the official Scintilla project first.
414 We won't accept adding a lexer that conflicts with one in
415 Scintilla. All new lexers should be submitted back to the Scintilla
416 project to save duplication of work.
418 When adding a lexer, update:
420 * scintilla/Makefile.am
421 * scintilla/makefile.win32
423 * scintilla/KeyWords.cxx - add a LINK_LEXER command *manually*
425 For syntax highlighting, you will need to edit highlighting.c and
426 highlightingmappings.h and add the following things:
428 1. In highlightingmappings.h:
430 a. define ``highlighting_lexer_FOO`` to the Scintilla lexer ID for
431 this filtype, e.g. ``SCLEX_CPP``.
432 b. define the ``highlighting_styles_FOO`` array that maps Scintilla
433 style states to style names in the configuration file.
434 c. define ``highlighting_keywords_FOO`` to ``EMPTY_KEYWORDS`` if the
435 filtype has no keywords, or as an ``HLKeyword`` array mapping
436 the Scintilla keyword IDs to names in the configuration file.
437 d. define ``highlighting_properties_FOO`` to ``EMPTY_PROPERTIES``, or
438 as an array of ``HLProperty`` if the filetype requires some lexer
439 properties to be set. However, note that properties should
440 normally be set in the ``[lexer_properties]`` section of the
441 configuration file instead.
443 You may look at other filtype's definitions for some examples
444 (Ada, CSS or Diff being good examples).
446 2. In highlighting.c:
448 a. Add ``init_styleset_case(FOO);`` in ``highlighting_init_styles()``.
449 b. Add ``styleset_case(FOO);`` in ``highlighting_set_styles()``.
451 3. Write data/filetypes.foo configuration file [styling] section. See
452 the manual and see data/filetypes.d for a named style example.
455 Please try to make your styles fit in with the other filetypes'
456 default colors, and to use named styles where possible (e.g.
457 "commentline=comment"). Filetypes that share a lexer should have
458 the same colors. If not using named styles, leave the background color
459 empty to match the default color.
461 Error message parsing
462 ^^^^^^^^^^^^^^^^^^^^^
463 New-style error message parsing is done with an extended GNU-style regex
464 stored in the filetypes.foo file - see the [build_settings] information
465 in the manual for details.
467 Old-style error message parsing is done in
468 msgwin_parse_compiler_error_line() of msgwindow.c - see the ParseData
469 typedef for more information.
473 If the lexer has comment styles, you should add them in
474 highlighting_is_comment_style(). You should also update
475 highlighting_is_string_style() for string/character styles. For now,
476 this prevents calltips and autocompletion when typing in a comment
477 (but it can still be forced by the user).
479 For brace indentation, update lexer_has_braces() in editor.c;
480 indentation after ':' is done from on_new_line_added().
482 If the Scintilla lexer supports user type keyword highlighting (e.g.
483 SCLEX_CPP), update document_update_tags() in document.c.
485 Adding a TagManager parser
486 ^^^^^^^^^^^^^^^^^^^^^^^^^^
487 This assumes the filetype for Geany already exists.
489 First write or find a CTags compatible parser, foo.c. Note that there
490 are some language patches for CTags at:
491 http://sf.net/projects/ctags - see the tracker.
493 (You can also try the Anjuta project's tagmanager codebase.)
496 From Geany 1.22 GLib's GRegex engine is used instead of POSIX
497 regex, unlike CTags. It should be close enough to POSIX to work
499 We no longer support regex parsers with the "b" regex flag
500 option set and Geany will print debug warnings if it's used.
501 CTags supports it but doesn't currently (2011) include any
502 parsers that use it. It should be easy to convert to extended
507 * Add foo.c to SRCS in Makefile.am.
508 * Add foo.o to OBJS in makefile.win32.
509 * Add path/foo.c to geany_sources in wscript.
510 * Add Foo to parsers.h & fill in comment with parser number for foo.
513 Edit FooKinds 3rd column to match a s_tag_type_names string in tm_tag.c.
514 (You may want to make the symbols.c change before doing this).
516 In filetypes.c, init_builtin_filetypes():
517 Set filetypes[GEANY_FILETYPES_FOO].lang = foo's parser number.
520 Unless your parser uses C-like tag type kinds, update
521 add_top_level_items() for foo, calling tag_list_add_groups(). See
522 get_tag_type_iter() for which tv_iters fields to use.
530 When a GLib or GTK warning is printed, often you want to get a
531 backtrace to find out what code caused them. You can do that with the
532 ``--g-fatal-warnings`` argument, which will abort Geany on the first
535 But for ordinary testing, you don't always want your editor to abort
536 just because of a warning - use::
538 (gdb) b handler_log if level <= G_LOG_LEVEL_WARNING
541 Running with batch commands
542 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
545 $ gdb src/geany -x gdb-commands
547 Where ``gdb-commands`` is a file with the following lines::
550 b handler_log if level <= G_LOG_LEVEL_WARNING
556 This is useful so you can load plugins without installing them first.
557 Alternatively you can use a symlink in ~/.config/geany/plugins or
558 $prefix/lib/geany (where $prefix is /usr/local by default).
560 The gdb session below was run from the toplevel Geany source directory.
561 Start normally with e.g. "gdb src/geany".
563 Press Ctrl-C from the gdb window to interrupt program execution.
567 Program received signal SIGINT, Interrupt.
568 0x00d16402 in __kernel_vsyscall ()
569 (gdb) call plugin_new("./plugins/.libs/demoplugin.so")
570 ** INFO: Loaded: ./plugins/.libs/demoplugin.so (Demo)
571 $1 = (Plugin *) 0x905a890
575 Program received signal SIGINT, Interrupt.
576 0x00d16402 in __kernel_vsyscall ()
577 (gdb) call plugin_free(0x905a890)
578 ** INFO: Unloaded: ./plugins/.libs/demoplugin.so
585 The geany-plugins autotools script automatically detects the
586 installed system Geany and builds the plugins against that.
588 To use plugins with a development version of Geany built with
589 a different prefix, the plugins will need to be compiled against
590 that version if the ABI has changed.
592 To do this you need to specify both --prefix and --with-geany-libdir
593 to the plugin configure. Normally the plugin prefix is the
594 same as the Geany prefix to keep plugins with the version of Geany
595 that they are compiled against, and with-geany-libdir is the Geany
598 Whilst it is possible for the plugin prefix to be different to
599 the prefix of the libdir (which is why there are two settings),
600 it is probably better to keep the version of Geany and its plugins