Contents
This file contains information for anyone wanting to work on the Geany codebase. You should be aware of the open source licenses used - see the README file or the documentation. It is reStructuredText; the source file is HACKING.
You can generate this file by:
You should generate and read the plugin API documentation, see below.
You can generate documentation for the plugin API using the doxygen tool:
The documentation will be output to doc/reference/index.html. Alternatively you can view the API documentation online at https://www.geany.org/manual/reference/.
Making pull requests on Github is the preferred way of contributing for geany.
Note
For helping you to get started: https://help.github.com/articles/fork-a-repo
See Rules to contribute for more information.
We are happy to receive patches, but the preferred way is to make a pull request on our Github repository. If you don't want to make a pull request, you can send your patches on the devel mailing list, but the rules are the same: see Rules to contribute for more information.
In general it's best to provide git-formatted patches made from the current Git (see Committing):
$ git commit -a $ git format-patch HEAD^
We also accept patches against other releases, but it's more work for us.
If you're not using Git, although you're strongly suggested to use it, you can use the diff command:
$ diff -u originalpath modifiedpath > new-feature.patch
However, such a patch won't contain the authoring information nor the patch's description.
Note
Please make sure patches follow the style of existing code - In particular, use tabs for indentation. See Coding.
Keep in mind this is best to check with us by email on mailing list whether a new feature is appropriate and whether someone is already working on similar code.
Please, make sure contributions you make follow these rules:
See Committing for more information.
See also the Geany wiki on how to build Geany on Windows at https://wiki.geany.org/howtos/win32/msys2.
callbacks.c is just for Glade callbacks. Avoid adding code to geany.h if it will fit better elsewhere. See the top of each src/*.c file for a brief description of what it's for.
Please be aware that anything with a doc-comment (a comment with an extra asterisk: /**) is something in the plugin API. Things like enums and structs can usually still be appended to, ensuring that all the existing elements stay in place - this will keep the ABI stable.
Warning
Some structs like GeanyCallback cannot be appended to without breaking the ABI because they are used to declare structs by plugins, not just for accessing struct members through a pointer. Normally structs should never be allocated by plugins.
In general the ABI changes as little as we can manage. The ABI number must match exactly between Geany and plugins, so an ABI change breaks all plugins until they are re-compiled. But sometimes it is absolutely necessary. Removing a feature or significantly changing the semantics of an existing feature require an ABI change since existing plugins may no longer work with the modified version of Geany.
The API identifying number is increased whenever anything is added to the API so plugins can test if the feature is available. The API number required by a plugin needs only to be lower than the API Geany provides, so an increase in API number without a change in ABI will not stop plugins that need a lower number from working.
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.
You should not make plugins rely on the size of a struct. This means:
Add user-interface widgets to the Glade 3 file data/geany.glade. Callbacks for the user-interface should go in src/callbacks.c.
Use Glade 3.8.5. The 3.8 series still supports GTK+ 2, and earlier point releases did not preserve the order of XML elements, leading to unmanageable diffs.
Geany requires GTK >= 3.0 and GLib >= 2.32. API symbols from newer GTK/GLib versions should be avoided or made optional to keep the source code building on older systems.
It is recommended to use the 3.0 API documentation of the GTK libs (including GLib, GDK and Pango) has the advantages that you don't get confused by any newer API additions and you don't have to take care about whether you can use them or not.
You might want to pass the -DGLIB_VERSION_MAX_ALLOWED=GLIB_VERSION_2_32 C preprocessor flag to get warnings about newer symbols from the GLib.
On the contrary, you might also want to get deprecation warnings for symbols deprecated in newer versions, typically when preparing a dependency bump or trying to improve forward compatibility. To do so, use the -UGLIB_VERSION_MIN_REQUIRED flag for GLib deprecations, and -UGDK_DISABLE_DEPRECATION_WARNINGS for GTK and GDK ones. To change the lower deprecation bound for GLib (and then get warnings about symbols deprecated more recently) instead of simply removing it entirely, use -UGLIB_VERSION_MIN_REQUIRED -DGLIB_VERSION_MIN_REQUIRED=GLIB_VERSION_X_YY.
See Compiler options & warnings for how to set such flags.
Use CFLAGS='-Wfoo' ./configure or CFLAGS='-Wfoo' ./autogen.sh to set warning options (as well as anything else e.g. -g -O2).
Tip
Remember for gcc you need to enable optimization to get certain warnings like uninitialized variables, but for debugging it's better to have no optimization on.
Note
A few of the above can be done with the Git scripts/fix-alignment.pl, but it is quite dumb and it's much better to write it correctly in the first place. scripts/rstrip-whitespace.py just removes trailing whitespace.
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) { ...
In order to make including various headers in Geany more convenient, each file should include what it uses. If there is a file named foo.c, and a file named foo.h, it should be possible to include foo.h on its own without depending on stuff in foo.c that is included for the first time before foo.h.
If there is some data that needs to be shared between various parts of the core code, put them in a "private header", that is, if the public header is called foo.h, then make a fooprivate.h header that contains the non-public functions, types, globals, etc that are needed. Other core source files can then just include the foo.h and/or fooprivate.h depending what they need, without exposing that stuff to plugins.
Inside a source file the includes section should be ordered like this:
Always include the config.h file at the start of every source file, for example:
#ifdef HAVE_CONFIG_H # include "config.h" #endif
This allows the Autotools and other build systems use the ./configure time settings. If you don't do this, there's likely to be a number of macros that you'll have to define in the build system or custom headers.
Warning: Never include config.h in headers, and especially in "public" headers that plugins might include.
Then include the header that has the same name as the source file (if applicable). For example, for a source file named foo.c, include the foo.h below the config.h include. If there is a fooprivate.h, foo.c will most likely want to include that too, put it in with includes in #3.
At this point, it should be safe to include all the headers that declare whatever is needed. If everything generally "includes what it uses" and all files included contain the appropriate multiple-declaration guards then the order of includes is fairly arbitrary. Prefer to use English alphabetic order if possible.
By now it doesn't really matter about the order, nothing below here is "our problem". Semi-arbitrarily, you should use an include order like this:
- Standard C headers
- Non-standard system headers (eg. windows.h or unistd.h)
- GLib/GTK+ or related headers
Everything else that should not influence 1-4.
Headers should also include what they use. All of the types should defined in order to allow the header to be included stand-alone. For example, if a header uses a GtkWidget*, it should #include <gtk/gtk.h>. Or, if a headers uses a GPtrArray*, it should #include <glib.h> to ensure that all of the types are declared, whether by pointers/opaquely or fully, as required. Since all headers will use a G_BEGIN_DECLS and G_END_DECLS guard for C++, the bare minimum for a header is to include glib.h or <gtk/gtk.h> or gtkcompat.h or some other header that makes those macros available.
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.
We try to use an unmodified version of Scintilla - any new lexers or other changes should be passed on to the maintainers at https://scintilla.org. We normally update to a new Scintilla release shortly after one is made. See also scintilla/README.
We use an unmodified subset of universal-ctags sources (https://github.com/universal-ctags/ctags) to parse open documents. We also use the great majority of unmodified universal-ctags parsers except a few outliers that are maintained by us (those whose file names start with geany_). We normally update to the latest version of universal-ctags shortly after making a Geany release and keep this version during the rest of the development cycle.
Some of these notes below are brief (or maybe incomplete) - please contact the geany-devel mailing list for more information.
When you are use macros supplied by the autotools like GEANY_PREFIX, GEANY_LIBDIR, GEANY_DATADIR and GEANY_LOCALEDIR be aware that these might not be static strings when Geany is configured with --enable-binreloc. Then these macros will be replaced by function calls (in src/prefix.h). So, don't use anything like printf("Prefix: " GEANY_PREFIX); but instead use printf("Prefix: %s", GEANY_PREFIX);
You can add a filetype without syntax highlighting or tag parsing, but check to see if those features have been written in upstream projects first (scintilla or ctags).
Custom:
If you want to reuse an existing lexer and/or tag parser, making a custom filetype is probably easier - it doesn't require any changes to the source code. Follow instructions in the manual: https://geany.org/manual/index.html#custom-filetypes. Don't forget to update the [Groups] section in filetype_extensions.conf.
Warning
You should use the newer [build-menu] section for default build commands - the older [build_settings] may not work correctly for custom filetypes.
Built-in:
The remaining notes relate mostly to built-in filetypes.
All languages need a data/filedefs/filetypes.foo configuration file. See the "Filetype definition files" section in the manual and/or data/filedefs/filetypes.c for an example.
Programming languages should have:
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.
Don't forget to add the newly created filetype file to data/Makefile.am.
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.
Warning
We won't accept adding a lexer that conflicts with one in Scintilla. All new lexers should be submitted back to the Scintilla project to save duplication of work.
When adding a lexer:
For syntax highlighting, you will need to edit highlighting.c and highlightingmappings.h and add the following things:
In highlightingmappings.h:
You may look at other filtype's definitions for some examples (Ada, CSS or Diff being good examples).
In highlighting.c:
Write data/filedefs/filetypes.foo configuration file [styling] section. See the manual and see data/filedefs/filetypes.d for a named style example.
Note
Please try to make your styles fit in with the other filetypes' default colors, and to use named styles where possible (e.g. "commentline=comment"). Filetypes that share a lexer should have the same colors. If not using named styles, leave the background color empty to match the default color.
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.
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_highlight_tags() in document.c.
If the filetype is a scripting language and the interpreter can be started using a shebang, update find_shebang() in filetypes.c.
Update editor_set_indentation_guides() in editor.c if needed.
This assumes the filetype for Geany already exists.
First write or find a CTags compatible parser, foo.c. Check this fork: https://github.com/universal-ctags/ctags
In src/tagmanager/tm_parser.c: Add a map_FOO TMParserMapEntry mapping each kind's letter from foo.c's FooKinds to the appropriate TMTagType, and add the corresponding MAP_ENTRY(FOO) to parser_map.
In src/tagmanager/tm_parser.c: Add a group_FOO TMParserMapGroup defining root nodes of the symbol tree, used icons and TMTagType values grouped under the specified root. Multiple TMTagType values can be combined under a single root using | (bitwise OR).
In src/tagmanager/tm_parser.c: Update various functions at the end of tm_parser.c to adjust Geany behavior to the behavior of the added parser. In particular, update tm_parser_scope_separator() and tm_parser_has_full_scope() so scope-related functionality works correctly.
In filetypes.c, init_builtin_filetypes(): Set the 2nd argument of the FT_INIT() macro for this filetype to FOO.
The tag parser tests checks if the proper tags are emitted for a given source. Tests for tag parsers consist of two files: the source to parse, and the expected output. Tests are run using make check.
The source to parse should be in the file tests/ctags/mytest.ext, where mytest is the name you choose for your test, and ext is an extension recognized by Geany as the language the test file is for. This file should contain a snippet of the language to test for. It can be either long or short, depending on what it tests.
The expected output should be in the file tests/ctags/mytest.ext.tags (which is the same name as the source, but with .tags appended), and should be in the format generated by:
$ geany -g tmp.ext.tags tests/ctags/mytest.ext $ scripts/print-tags.py < tmp.ext.tags > tests/ctags/mytest.ext.tags
This file contains the tag information expected to be generated from the corresponding source file together with its human-readable form.
When you have these two files, you have to list your new test along the other ones in the test_source variable in tests/ctags/Makefile.am and tests/meson.build. Please keep this list sorted alphabetically.
To upgrade the local Scintilla copy, use the scripts/update-scintilla.sh script.
To use it, you need to first obtain a copy of the Scintilla sources you want to update to. This will generally mean checking out a release tag from the Scintilla Mercurial repository, or extracting a tarball.
Then, just run the script from Geany's to source directory passing the path to the Scintilla source directory as first argument, and follow the instructions, if any:
./scripts/update-scintilla.sh /path/to/scintilla/
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
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
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.
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.