Plugin API documentation

You can generate documentation for the plugin API using the doxygen tool. Run make api-doc in the doc subdirectory. The documentation will be output to doc/reference/index.html. Alternatively you can view the API documentation online at http://www.geany.org/manual/reference/.

Keeping the plugin ABI stable

Before the 1.0 release series, the ABI can change when necessary, and even the API can change. An ABI change just means that all plugins will not load and they must be rebuilt. An API change means that some plugins might not build correctly.

If you're reordering or changing existing elements of structs that are used as part of the plugin API, you must increment GEANY_ABI_VERSION in plugindata.h. This is usually not needed if you're just appending fields to structs. The GEANY_API_VERSION value should be incremented for any changes to the plugin API, including appending elements.

If you're in any doubt when making changes to plugin API code, just ask us.

Plugin API/ABI design

You should not make plugins rely on the size of a struct. This means:

• Don't let plugins allocate any structs (stack or heap).
• Don't let plugins index any arrays of structs.
• Don't add any array fields to structs in case we want to change the array size later.

Doc-comments

• The @file tag can go in the source .c file, but use the .h header name so it appears normally in the generated documentation. See ui_utils.c for an example.
• Function doc-comments should always go in the source file, not the header, so they can be updated if/when the implementation changes.

Compiler options & warnings

Use CFLAGS='-Wfoo' ./configure or CFLAGS='-Wfoo' ./autogen.sh to set warning options (as well as anything else e.g. -g -O2).

• Enable warnings - for gcc use '-Wall -W' (and optionally -Wno-unused-parameter to avoid unused parameter warnings in Glade callbacks).
• You should try to write ISO C90 code for portability, so always use C /* */ comments and function_name(void) instead of function_name(). This is for compatibility with various Unix-like compilers. You should use -ansi to help check this. Note that MIO (tagmanager/mio) requires MIO_FORCE_ANSI preprocessor constant to be defined to build with -ansi, so you should add -DMIO_FORCE_ANSI together with -ansi.

Style

• We use a tab width of 4 and indent completely with tabs not spaces. Note the documentation files use (4) spaces instead, so you may want to use the 'Detect from file' indent pref.
• Do not add whitespace at the end of lines, this adds to commit noise. When editing with Geany set preference files->Strip trailing spaces and tabs.
• Use the multiline comment /* */ to comment small blocks of code, functions descriptions or longer explanations of code, etc. C++ single line comments will cause portability issues. The more comments are in your code the better. (See also scripts/fix-cxx-comments.pl in Git).
• Lines should not be longer than about 100 characters and after 100 characters the lines should be wrapped and indented once more to show that the line is continued.
• We don't put spaces between function names and the opening brace for argument lists.
• Variable declarations come first after an opening brace, then one newline to separate declarations and code.
• 2-operand operators should have a space each side.
• Function bodies should have 2 blank newlines after them.
• Align braces together on separate lines.
• Don't put assignments in 'if/while/etc' expressions.
• if statements without brace bodies should have the code on a separate line, then a blank line afterwards.
• Use braces after if/while statements if the body uses another if/while statement.
• Try to fit in with the existing code style.

Example:

struct Bar;

typedef struct Foo  /* struct names normally are the same as typedef names */
{
    gint    foo;    /* names are somewhat aligned visually */
    gint    bar;    /* fields don't share the same line */
    SomeLongTypeName baz; /* alignment is not strict */
    gchar   *ptr;   /* pointer symbol must go next to variable name, not type */
    Bar     public; /**< only plugin API fields have a doc-comment */
}
Foo;


gint some_func(void);

gint some_other_func(void);


/* optional function comment explains something important */
gint function_long_name(gchar arg1, <too many args to fit on this line>,
        gchar argN)
{
    /* variable declarations always go before code in each scope */
    /* variable names should NOT be aligned at all */
    gint foo, bar;  /* variables can go on the same line */
    gint baz;       /* but often don't */
    gchar *ptr;     /* pointer symbol must go next to variable name, not type */
    gchar *another; /* pointers should normally go on separate lines */

    /* Some long comment block
     * taking several different
     * lines to explain */
    if (foo)
    {
        /* variables only used in one scope should normally be declared there */
        gint dir = -1;

        bar = foo;
        if ((bar & (guint)dir) != 7)
            some_code(arg1, <too many args to fit on this line>,
                argN - 1, argN);

        some_func();
    }
}


/** Explains using doc-comments for plugin API functions.
 * First line should be short and use the third person tense - 'explains',
 * not 'explain'.
 *
 * @return Some number.
 * @since 1.22. */
gint another_function(void)
{
    ...

Commit messages

Follow the standard Git formatting:

• No line should use more than about 80 characters (around 72 is best).

• The first line is the commit's summary and is followed by an empty line. This summary should be one line and one line only, thus less than 80 characters. This summary should not include any punctuation unless really needed. See it as the subject of an email: keep it concise and as precise as you can, but not tool long.

• Following lines are optional detailed commit information, with paragraphs separated by blank lines. This part should be as long as needed to describe the commit in depth, should use proper punctuation and should include any useful information, like the motivation for the patch and/or any valuable details the diff itself don't provide or don't make clear. Make it as complete as you think it makes sense, but don't include an information that is better explained by the commit's diff.

  It is OK to use ASCII formatting like bullet list using "*" or "-", etc. if useful, but emphasis (bold, italic, underline) should be avoided.

Example:

Ask the user if spawn fails in utils_open_browser()

Ask the user to configure a valid browser command if spawning it
fails rather than falling back to some arbitrary hardcoded defaults.

This avoid spawning an unexpected browser when the configured one is
wrong, and gives the user a chance to correctly fix the preference.

filetypes.* configuration file

All languages need a data/filetypes.foo configuration file. See the "Filetype definition files" section in the manual and/or data/filetypes.c for an example.

Programming languages should have:

• [keywords] if the lexer supports it.
• [settings] mostly for comment settings.
• [build_settings] for commands to run.

For languages with a Scintilla lexer, there should be a [styling] section, to correspond to the styles used in highlighting_styles_FOO[] in highlightingmappings.h - see below.

Syntax highlighting

It may be possible to use an existing Scintilla lexer in the scintilla/ subdirectory - if not, you will need to find (or write) one, LexFoo.cxx. Try the official Scintilla project first.

When adding a lexer, update:

• scintilla/Makefile.am
• scintilla/makefile.win32
• wscript
• scintilla/src/Catalogue.cxx - add a LINK_LEXER command manually

For syntax highlighting, you will need to edit highlighting.c and highlightingmappings.h and add the following things:

1. In highlightingmappings.h:

   1. define highlighting_lexer_FOO to the Scintilla lexer ID for this filtype, e.g. SCLEX_CPP.
   2. define the highlighting_styles_FOO array that maps Scintilla style states to style names in the configuration file.
   3. define highlighting_keywords_FOO to EMPTY_KEYWORDS if the filtype has no keywords, or as an HLKeyword array mapping the Scintilla keyword IDs to names in the configuration file.
   4. define highlighting_properties_FOO to EMPTY_PROPERTIES, or as an array of HLProperty if the filetype requires some lexer properties to be set. However, note that properties should normally be set in the [lexer_properties] section of the configuration file instead.

   You may look at other filtype's definitions for some examples (Ada, CSS or Diff being good examples).

2. In highlighting.c:

   1. Add init_styleset_case(FOO); in highlighting_init_styles().
   2. Add styleset_case(FOO); in highlighting_set_styles().

3. Write data/filetypes.foo configuration file [styling] section. See the manual and see data/filetypes.d for a named style example.

Error message parsing

New-style error message parsing is done with an extended GNU-style regex stored in the filetypes.foo file - see the [build_settings] information in the manual for details.

Old-style error message parsing is done in msgwin_parse_compiler_error_line() of msgwindow.c - see the ParseData typedef for more information.

Other features

If the lexer has comment styles, you should add them in highlighting_is_comment_style(). You should also update highlighting_is_string_style() for string/character styles. For now, this prevents calltips and autocompletion when typing in a comment (but it can still be forced by the user).

For brace indentation, update lexer_has_braces() in editor.c; indentation after ':' is done from on_new_line_added().

If the Scintilla lexer supports user type keyword highlighting (e.g. SCLEX_CPP), update document_update_tags() in document.c.

Adding a TagManager parser

This assumes the filetype for Geany already exists.

First write or find a CTags compatible parser, foo.c. Note that there are some language patches for CTags at: http://sf.net/projects/ctags - see the tracker.

(You can also try the Anjuta project's tagmanager codebase.)

Stop on warnings

When a GLib or GTK warning is printed, often you want to get a backtrace to find out what code caused them. You can do that with the --g-fatal-warnings argument, which will abort Geany on the first warning it receives.

But for ordinary testing, you don't always want your editor to abort just because of a warning - use:

(gdb) b handler_log if level <= G_LOG_LEVEL_WARNING

Running with batch commands

Use:

$ gdb src/geany -x gdb-commands

Where gdb-commands is a file with the following lines:

set pagination off
b handler_log if level <= G_LOG_LEVEL_WARNING
r -v

Loading a plugin

This is useful so you can load plugins without installing them first. Alternatively you can use a symlink in ~/.config/geany/plugins or $prefix/lib/geany (where $prefix is /usr/local by default).

The gdb session below was run from the toplevel Geany source directory. Start normally with e.g. "gdb src/geany". Type 'r' to run. Press Ctrl-C from the gdb window to interrupt program execution.

Example:

Program received signal SIGINT, Interrupt.
0x00d16402 in __kernel_vsyscall ()
(gdb) call plugin_new("./plugins/.libs/demoplugin.so")
** INFO: Loaded:   ./plugins/.libs/demoplugin.so (Demo)
$1 = (Plugin *) 0x905a890
(gdb) c
Continuing.

Program received signal SIGINT, Interrupt.
0x00d16402 in __kernel_vsyscall ()
(gdb) call plugin_free(0x905a890)
** INFO: Unloaded: ./plugins/.libs/demoplugin.so
(gdb) c
Continuing.

Building Plugins

The geany-plugins autotools script automatically detects the installed system Geany and builds the plugins against that.

To use plugins with a development version of Geany built with a different prefix, the plugins will need to be compiled against that version if the ABI has changed.

To do this you need to specify both --prefix and --with-geany-libdir to the plugin configure. Normally the plugin prefix is the same as the Geany prefix to keep plugins with the version of Geany that they are compiled against, and with-geany-libdir is the Geany prefix/lib.

Whilst it is possible for the plugin prefix to be different to the prefix of the libdir (which is why there are two settings), it is probably better to keep the version of Geany and its plugins together.