Post release version bump
[geany-mirror.git] / HACKING
blob50971e64c6ffc4fee7cad8fe4754d2e60dbb17b9
1 =============
2 Hacking Geany
3 =============
4 .. contents::
6 General
7 =======
9 About this file
10 ---------------
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.
16 You can generate this file by:
18 * Passing the *--enable-html-docs* option to ``configure``.
19 * Running ``make`` from the doc/ subdirectory.
21 Writing plugins
22 ---------------
23 * src/plugindata.h contains the plugin API data types.
24 * See plugins/demoplugin.c for a very basic example plugin.
25 * src/plugins.c loads and unloads plugins (you shouldn't need to read
26   this really).
27 * The API documentation contains a few basic guidelines and hints to
28   write plugins.
30 You should generate and read the plugin API documentation, see below.
32 Plugin API documentation
33 ^^^^^^^^^^^^^^^^^^^^^^^^
34 You can generate documentation for the plugin API using the doxygen
35 tool:
37 * Pass the *--enable-api-docs* option to ``configure``.
38 * Run ``make`` from the doc/ subdirectory.
40 The documentation will be output to doc/reference/index.html.
41 Alternatively you can view the API documentation online at
42 https://www.geany.org/manual/reference/.
44 Pull requests
45 -------------
46 Making pull requests on Github is the preferred way of contributing for geany.
48 .. note:: For helping you to get started: https://help.github.com/articles/fork-a-repo
50 See `Rules to contribute`_ for more information.
52 Patches
53 -------
54 We are happy to receive patches, but the preferred way is to make a pull
55 request on our Github repository. If you don't want to make a pull request,
56 you can send your patches on the devel mailing list, but the rules are the same:
57 see `Rules to contribute`_ for more information.
59 In general it's best to provide git-formatted patches made from the
60 current Git (see `Committing`_)::
62     $ git commit -a
63     $ git format-patch HEAD^
65 We also accept patches against other releases, but it's more work for us.
67 If you're not using Git, although you're strongly suggested to use it,
68 you can use the diff command::
70     $ diff -u originalpath modifiedpath > new-feature.patch
72 However, such a patch won't contain the authoring information nor the
73 patch's description.
75 .. note::
76     Please make sure patches follow the style of existing code - In
77     particular, use tabs for indentation. See `Coding`_.
79 Rules to contribute
80 -------------------
82 Keep in mind this is best to check with us by email on mailing list
83 whether a new feature is appropriate and whether someone is already
84 working on similar code.
86 Please, make sure contributions you make follow these rules:
88 * changes should be made in a dedicated branch for pull requests.
89 * only one feature should be in each pull request (or patch).
90 * pull requests (or patches) should not contain changes unrelated to the feature,
91   and commits should be sensible units of change.
92 * the submitter should squash together corrections that are part of
93   the development process, especially correcting your own mistakes.
94 * Please make sure your modifications follow the style of existing code:
95   see `Coding`_ for more information.
97 See `Committing`_ for more information.
99 Windows tools
100 -------------
101 * Git: http://git-scm.com/ and http://msysgit.github.io/
102 * diff, grep, etc: http://mingw.org/ or http://unxutils.sourceforge.net/
104 See also the 'Building on Windows' document on the website.
106 File organization
107 -----------------
108 callbacks.c is just for Glade callbacks.
109 Avoid adding code to geany.h if it will fit better elsewhere.
110 See the top of each ``src/*.c`` file for a brief description of what
111 it's for.
113 Plugin API code
114 ---------------
115 Please be aware that anything with a doc-comment (a comment with an
116 extra asterix: ``/**``) is something in the plugin API. Things like
117 enums and structs can usually still be appended to, ensuring that all
118 the existing elements stay in place - this will keep the ABI stable.
120 .. warning::
122     Some structs like GeanyCallback cannot be appended to without
123     breaking the ABI because they are used to declare structs by
124     plugins, not just for accessing struct members through a pointer.
125     Normally structs should never be allocated by plugins.
127 Keeping the plugin ABI stable
128 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
129 Before the 1.0 release series, the ABI can change when necessary, and
130 even the API can change. An ABI change just means that all plugins will
131 not load and they must be rebuilt. An API change means that some plugins
132 might not build correctly.
134 If you're reordering or changing existing elements of structs that are
135 used as part of the plugin API, you must increment GEANY_ABI_VERSION
136 in plugindata.h. This is usually not needed if you're just appending
137 fields to structs. The GEANY_API_VERSION value should be incremented
138 for any changes to the plugin API, including appending elements.
140 If you're in any doubt when making changes to plugin API code, just ask us.
142 Plugin API/ABI design
143 ^^^^^^^^^^^^^^^^^^^^^
144 You should not make plugins rely on the size of a struct. This means:
146 * Don't let plugins allocate any structs (stack or heap).
147 * Don't let plugins index any arrays of structs.
148 * Don't add any array fields to structs in case we want to change the
149   array size later.
151 Doc-comments
152 ^^^^^^^^^^^^
153 * The @file tag can go in the source .c file, but use the .h header name so
154   it appears normally in the generated documentation. See ui_utils.c for an
155   example.
156 * Function doc-comments should always go in the source file, not the
157   header, so they can be updated if/when the implementation changes.
159 Glade
160 -----
161 Add user-interface widgets to the Glade 3 file ``data/geany.glade``.
162 Callbacks for the user-interface should go in ``src/callbacks.c``.
164 Use Glade 3.8.5. The 3.8 series still supports GTK+ 2, and earlier
165 point releases did not preserve the order of XML elements, leading to
166 unmanageable diffs.
168 GTK versions & API documentation
169 --------------------------------
170 Geany requires GTK >= 2.24 or GTK 3 (with the --enable-gtk3 configure option)
171 and GLib >= 2.32. API symbols from newer GTK/GLib versions should be 
172 avoided or made optional to keep the source code building on older systems.
174 It is recommended to use the 2.24 API documentation of the GTK
175 libs (including GLib, GDK and Pango) has the advantages
176 that you don't get confused by any newer API additions and you
177 don't have to take care about whether you can use them or not.
179 You might want to pass the ``-DGLIB_VERSION_MAX_ALLOWED=GLIB_VERSION_2_32`` C
180 preprocessor flag to get warnings about newer symbols from the GLib.
182 On the contrary, you might also want to get deprecation warnings for symbols
183 deprecated in newer versions, typically when preparing a dependency bump or
184 trying to improve forward compatibility.
185 To do so, use the ``-UGLIB_VERSION_MIN_REQUIRED`` flag for GLib deprecations,
186 and ``-UGDK_DISABLE_DEPRECATION_WARNINGS`` for GTK and GDK ones.
187 To change the lower deprecation bound for GLib (and then get warnings about
188 symbols deprecated more recently) instead of simply removing it entirely, use
189 ``-UGLIB_VERSION_MIN_REQUIRED -DGLIB_VERSION_MIN_REQUIRED=GLIB_VERSION_X_YY``.
191 See `Compiler options & warnings`_ for how to set such flags.
193 Coding
194 ------
195 * Don't write long functions with a lot of variables and/or scopes - break
196   them down into smaller static functions where possible. This makes code
197   much easier to read and maintain.
198 * Use GLib types and functions - gint not int, g_free() not free().
199 * Your code should build against GLib 2.32 and GTK 2.24. At least for the
200   moment, we want to keep the minimum requirement for GTK at 2.24 (of
201   course, you can use the GTK_CHECK_VERSION macro to protect code using
202   later versions).
203 * Variables should be declared (and initialized) as close as practical
204   to their first use. This reduces the chances of intervening code being
205   inserted between declaration and use, where the variable may be
206   uninitialized.
207 * Variables should be defined within the smallest scope that is practical,
208   for example inside a conditional branch which uses them or in the
209   initialization part of a for loop.
210 * Local variables that will not be modified should be marked as ``const``
211   to indicate intention. This allows the compiler to give a warning if
212   part of the code accidentally tries to change the value.
213 * Pointer parameters should be marked ``const`` if the value they point
214   to will not be mutated within the function.
215 * Don't let variable names shadow outer variables - use gcc's -Wshadow
216   option.
217 * Use the strictest possible data type where practical. For example
218   for an enumeration, use the actual enum type rather than just a
219   ``gint``, use a ``gchar`` for individual (ASCII/UTF-8) string
220   characters rather than ``gint``, and use a ``guint`` for integers
221   which cannot be negative rather than ``gint``.
222 * Do not use G_LIKELY or G_UNLIKELY (except in critical loops). These
223   add noise to the code with little real benefit.
225 Compiler options & warnings
226 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
227 Use ``CFLAGS='-Wfoo' ./configure`` or ``CFLAGS='-Wfoo' ./autogen.sh``
228 to set warning options (as well as anything else e.g. -g -O2).
230 * Enable warnings - for gcc use '-Wall -Wextra' (and optionally
231   -Wno-unused-parameter to avoid unused parameter warnings in Glade
232   callbacks). Alternatively you can use the Glib macro G_GNUC_UNUSED
233   to suppress warnings on single parameters, e.g.
234   ``void examplefunction(G_GNUC_UNUSED gchar *foo)``. Also see
235   https://developer.gnome.org/glib/stable/glib-Miscellaneous-Macros.html.
236 * You should try to write ISO C99 code for portability, so always
237   use C ``/* */`` comments and function_name(void) instead of
238   function_name(). This is for compatibility with various Unix-like
239   compilers. You should use -std=c99 to help check this.
241 .. tip::
242     Remember for gcc you need to enable optimization to get certain
243     warnings like uninitialized variables, but for debugging it's
244     better to have no optimization on.
246 Style
247 ^^^^^
248 * We use a tab width of 4 and indent completely with tabs not spaces.
249   Note the documentation files use (4) spaces instead, so you may want
250   to use the 'Detect from file' indent pref.
251 * Do not add whitespace at the end of lines, this adds to commit noise.
252   When editing with Geany set preference files->Strip trailing spaces
253   and tabs.
254 * Use the multiline comment ``/* */`` to comment small blocks of code,
255   functions descriptions or longer explanations of code, etc. The more
256   comments are in your code the better. (See also
257   ``scripts/fix-cxx-comments.pl`` in Git).
258 * Lines should not be longer than about 100 characters and after 100
259   characters the lines should be wrapped and indented once more to
260   show that the line is continued.
261 * We don't put spaces between function names and the opening brace for
262   argument lists.
263 * Variable declarations come first after an opening brace, then one
264   newline to separate declarations and code.
265 * 2-operand operators should have a space each side.
266 * Function bodies should have 2 blank newlines after them.
267 * Align braces together on separate lines.
268 * Don't put assignments in 'if/while/etc' expressions except for loops,
269   for example ``for (int i = 0; i < some_limit; i++)``.
270 * if statements without brace bodies should have the code on a separate
271   line, then a blank line afterwards.
272 * Use braces after if/while statements if the body uses another
273   if/while statement.
274 * Try to fit in with the existing code style.
276 .. note::
277     A few of the above can be done with the Git
278     ``scripts/fix-alignment.pl``, but it is quite dumb and it's much better
279     to write it correctly in the first place.
280     ``scripts/rstrip-whitespace.py`` just removes trailing whitespace.
283 .. below tabs should be used, but spaces are required for reST.
285 Example::
287     struct Bar;
289     typedef struct Foo  /* struct names normally are the same as typedef names */
290     {
291         gint    foo;    /* names are somewhat aligned visually */
292         gint    bar;    /* fields don't share the same line */
293         SomeLongTypeName baz; /* alignment is not strict */
294         gchar   *ptr;   /* pointer symbol must go next to variable name, not type */
295         Bar     public; /**< only plugin API fields have a doc-comment */
296     }
297     Foo;
300     gint some_func(void);
302     gint some_other_func(void);
305     /* optional function comment explains something important */
306     gint function_long_name(gchar arg1, <too many args to fit on this line>,
307             gchar argN)
308     {
309         /* variable declarations always go before code in each scope */
310         /* variable names should NOT be aligned at all */
311         gint foo, bar;  /* variables can go on the same line */
312         gint baz;       /* but often don't */
313         gchar *ptr;     /* pointer symbol must go next to variable name, not type */
314         gchar *another; /* pointers should normally go on separate lines */
316         /* Some long comment block
317          * taking several different
318          * lines to explain */
319         if (foo)
320         {
321             /* variables only used in one scope should normally be declared there */
322             gint dir = -1;
324             bar = foo;
325             if ((bar & (guint)dir) != 7)
326                 some_code(arg1, <too many args to fit on this line>,
327                     argN - 1, argN);
329             some_func();
330         }
331     }
334     /** Explains using doc-comments for plugin API functions.
335      * First line should be short and use the third person tense - 'explains',
336      * not 'explain'.
337      *
338      * @return Some number.
339      * @since 1.22. */
340     gint another_function(void)
341     {
342         ...
344 Header Includes
345 ---------------
347 In order to make including various headers in Geany more convenient, each
348 file should include what it uses. If there is a file named ``foo.c``, and a
349 file named ``foo.h``, it should be possible to include ``foo.h`` on its own
350 without depending on stuff in ``foo.c`` that is included for the first time
351 before ``foo.h``.
353 Private Headers
354 ^^^^^^^^^^^^^^^
356 If there is some data that needs to be shared between various parts of the
357 core code, put them in a "private header", that is, if the public header is
358 called ``foo.h``, then make a ``fooprivate.h`` header that contains the
359 non-public functions, types, globals, etc that are needed. Other core source
360 files can then just include the ``foo.h`` and/or ``fooprivate.h`` depending
361 what they need, without exposing that stuff to plugins.
363 Order of Includes
364 ^^^^^^^^^^^^^^^^^
366 Inside a source file the includes section should be ordered like this:
368 1. Always include the ``config.h`` file at the start of every source file,
369    for example::
371     #ifdef HAVE_CONFIG_H
372     # include "config.h"
373     #endif
375    This allows the Autotools and other build systems use the ``./configure``
376    time settings. If you don't do this, there's likely to be a number of
377    macros that you'll have to define in the build system or custom headers.
379    Warning: Never include ``config.h`` in headers, and especially in "public"
380    headers that plugins might include.
382 2. Then include the header that has the same name as the source file (if
383    applicable). For example, for a source file named ``foo.c``, include
384    the ``foo.h`` below the ``config.h`` include. If there is a
385    ``fooprivate.h``, ``foo.c`` will most likely want to include that too,
386    put it in with includes in #3.
388 3. At this point, it should be safe to include all the headers that declare
389    whatever is needed. If everything generally "includes what it uses" and
390    all files included contain the appropriate multiple-declaration guards
391    then the order of includes is fairly arbitrary. Prefer to use English
392    alphabetic order if possible.
394 4. By now it doesn't really matter about the order, nothing below here is
395    "our problem". Semi-arbitrarily, you should use an include order like this:
397     1. Standard C headers
398     2. Non-standard system headers (eg. ``windows.h`` or ``unistd.h``)
399     3. GLib/GTK+ or related headers
401 5. Everything else that should not influence 1-4.
403 Including in Header Files
404 ^^^^^^^^^^^^^^^^^^^^^^^^^
406 Headers should also include what they use. All of the types should defined in
407 order to allow the header to be included stand-alone. For example, if a
408 header uses a ``GtkWidget*``, it should ``#include <gtk/gtk.h>``. Or, if a
409 headers uses a ``GPtrArray*``, it should ``#include <glib.h>`` to ensure that
410 all of the types are declared, whether by pointers/opaquely or fully, as
411 required. Since all headers will use a ``G_BEGIN_DECLS`` and ``G_END_DECLS``
412 guard for C++, the bare minimum for a header is to include ``glib.h`` or
413 ``<gtk/gtk.h>`` or ``gtkcompat.h`` or some other header that makes those
414 macros available.
417 Committing
418 ----------
420 * Commit one thing at a time, do small commits.  Commits should be
421   meaningful and not too big when possible; multiple small commits are
422   good if there is no good reason to group them.
423 * Use meaningful name and email in the Author and Committer fields.
424   This helps knowing who did what and allows to contact the author if
425   there is a good reason to do so (unlikely, but can happen).
426 * When working on a new feature, create a new branch for it.  When
427   merging it, use the --no-ff option to make sure a merge commit will
428   be created to better track what happened.  However, if the feature
429   only took one commit you might merge it fast-forward since there is
430   not history to keep together.
432 Commit messages
433 ^^^^^^^^^^^^^^^
434 Follow the standard Git formatting:
436 * No line should use more than about 80 characters (around 72 is best).
437 * The first line is the commit's summary and is followed by an empty
438   line.  This summary should be one line and one line only, thus less
439   than 80 characters.  This summary should not include any punctuation
440   unless really needed.  See it as the subject of an email: keep it
441   concise and as precise as you can, but not tool long.
442 * Following lines are optional detailed commit information, with
443   paragraphs separated by blank lines.  This part should be as long as
444   needed to describe the commit in depth, should use proper
445   punctuation and should include any useful information, like the
446   motivation for the patch and/or any valuable details the diff itself
447   don't provide or don't make clear.  Make it as complete as you think
448   it makes sense, but don't include an information that is better
449   explained by the commit's diff.
451   It is OK to use ASCII formatting like bullet list using "*" or "-",
452   etc. if useful, but emphasis (bold, italic, underline) should be
453   avoided.
455 Example::
457     Ask the user if spawn fails in utils_open_browser()
459     Ask the user to configure a valid browser command if spawning it
460     fails rather than falling back to some arbitrary hardcoded defaults.
462     This avoid spawning an unexpected browser when the configured one is
463     wrong, and gives the user a chance to correctly fix the preference.
466 Testing
467 -------
468 * Run with ``-v`` to print any debug messages.
469 * You can use a second instance (``geany -i``).
470 * To check first-run behaviour, use an alternate config directory by
471   passing ``-c some_dir`` (but make sure the directory is clean first).
472 * For debugging tips, see `GDB`_.
474 Bugs to watch out for
475 ---------------------
476 * Forgetting to check *doc->is_valid* when looping through
477   *documents_array* - instead use *foreach_document()*.
478 * Inserting fields into structs in the plugin API instead of appending.
479 * Not breaking the plugin ABI when necessary.
480 * Using an idle callback that doesn't check main_status.quitting.
481 * Forgetting CRLF line endings on Windows.
482 * Not handling Tabs & Spaces indent mode.
484 Libraries
485 ---------
486 We try to use an unmodified version of Scintilla - any new lexers or
487 other changes should be passed on to the maintainers at
488 http://scintilla.org. We normally update to a new Scintilla release
489 shortly after one is made. See also scintilla/README.
491 Tagmanager was originally taken from Anjuta 1.2.2, and parts of it
492 (notably c.c) have been merged from later versions of Anjuta and
493 CTags. The independent Tagmanager library itself ceased development
494 before Geany was started. It's source code parsing is mostly taken from
495 Exuberant CTags (see http://ctags.sf.net). If appropriate it's good to
496 pass language parser changes back to the CTags project.
499 Notes
500 =====
501 Some of these notes below are brief (or maybe incomplete) - please
502 contact the geany-devel mailing list for more information.
504 Using pre-defined autotools values
505 ----------------------------------
506 When you are use macros supplied by the autotools like GEANY_PREFIX,
507 GEANY_LIBDIR, GEANY_DATADIR and GEANY_LOCALEDIR be aware that these
508 might not be static strings when Geany is configured with
509 --enable-binreloc. Then these macros will be replaced by function calls
510 (in src/prefix.h). So, don't use anything like
511 printf("Prefix: " GEANY_PREFIX); but instead use
512 printf("Prefix: %s", GEANY_PREFIX);
514 Adding a source file foo.[hc] in src/ or plugins/
515 -------------------------------------------------
516 * Add foo.c, foo.h to SRCS in path/Makefile.am.
517 * Add path/foo.c to po/POTFILES.in (for string translation).
519 Adding a filetype
520 -----------------
521 You can add a filetype without syntax highlighting or tag parsing, but
522 check to see if those features have been written in upstream projects
523 first (scintilla or ctags).
525 **Custom:**
527 If you want to reuse an existing lexer and/or tag parser, making a
528 custom filetype is probably easier - it doesn't require any
529 changes to the source code. Follow instructions in the manual:
530 http://geany.org/manual/index.html#custom-filetypes. Don't forget to
531 update the ``[Groups]`` section in ``filetype_extensions.conf``.
533 .. warning::
534   You should use the newer `[build-menu]` section for default build
535   commands - the older `[build_settings]` may not work correctly for
536   custom filetypes.
538 **Built-in:**
540 * Add GEANY_FILETYPES_FOO to filetypes.h.
541 * Initialize GEANY_FILETYPES_FOO in init_builtin_filetypes() of
542   filetypes.c.
543 * Update data/filetype_extensions.conf.
545 The remaining notes relate mostly to built-in filetypes.
547 filetypes.* configuration file
548 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
549 All languages need a data/filetypes.foo configuration file. See
550 the "Filetype definition files" section in the manual and/or
551 data/filetypes.c for an example.
553 Programming languages should have:
555 * [keywords] if the lexer supports it.
556 * [settings] mostly for comment settings.
557 * [build-menu] (or [build_settings]) for commands to run.
559 For languages with a Scintilla lexer, there should be a [styling] section,
560 to correspond to the styles used in highlighting_styles_FOO[] in
561 highlightingmappings.h - see below.
563 Don't forget to add the newly created filetype file to data/Makefile.am.
565 Syntax highlighting
566 ^^^^^^^^^^^^^^^^^^^
567 It may be possible to use an existing Scintilla lexer in the scintilla/
568 subdirectory - if not, you will need to find (or write) one,
569 LexFoo.cxx. Try the official Scintilla project first.
571 .. warning::
572     We won't accept adding a lexer that conflicts with one in
573     Scintilla. All new lexers should be submitted back to the Scintilla
574     project to save duplication of work.
576 When adding a lexer, update:
578 * scintilla/Makefile.am
579 * scintilla/src/Catalogue.cxx - add a LINK_LEXER command *manually*
581 For syntax highlighting, you will need to edit highlighting.c and
582 highlightingmappings.h and add the following things:
584 1. In highlightingmappings.h:
586    a. define ``highlighting_lexer_FOO`` to the Scintilla lexer ID for
587       this filtype, e.g. ``SCLEX_CPP``.
588    b. define the ``highlighting_styles_FOO`` array that maps Scintilla
589       style states to style names in the configuration file.
590    c. define ``highlighting_keywords_FOO`` to ``EMPTY_KEYWORDS`` if the
591       filtype has no keywords, or as an ``HLKeyword`` array mapping
592       the Scintilla keyword IDs to names in the configuration file.
593    d. define ``highlighting_properties_FOO`` to ``EMPTY_PROPERTIES``, or
594       as an array of ``HLProperty`` if the filetype requires some lexer
595       properties to be set.  However, note that properties should
596       normally be set in the ``[lexer_properties]`` section of the
597       configuration file instead.
599    You may look at other filtype's definitions for some examples
600    (Ada, CSS or Diff being good examples).
602 2. In highlighting.c:
604    a. Add ``init_styleset_case(FOO);`` in ``highlighting_init_styles()``.
605    b. Add ``styleset_case(FOO);`` in ``highlighting_set_styles()``.
607 3. Write data/filetypes.foo configuration file [styling] section. See
608    the manual and see data/filetypes.d for a named style example.
610 .. note::
611     Please try to make your styles fit in with the other filetypes'
612     default colors, and to use named styles where possible (e.g.
613     "commentline=comment"). Filetypes that share a lexer should have
614     the same colors. If not using named styles, leave the background color
615     empty to match the default color.
617 Error message parsing
618 ^^^^^^^^^^^^^^^^^^^^^
619 New-style error message parsing is done with an extended GNU-style regex
620 stored in the filetypes.foo file - see the [build_settings] information
621 in the manual for details.
623 Old-style error message parsing is done in
624 msgwin_parse_compiler_error_line() of msgwindow.c - see the ParseData
625 typedef for more information.
627 Other features
628 ^^^^^^^^^^^^^^
629 If the lexer has comment styles, you should add them in
630 highlighting_is_comment_style(). You should also update
631 highlighting_is_string_style() for string/character styles. For now,
632 this prevents calltips and autocompletion when typing in a comment
633 (but it can still be forced by the user).
635 For brace indentation, update lexer_has_braces() in editor.c;
636 indentation after ':' is done from on_new_line_added().
638 If the Scintilla lexer supports user type keyword highlighting (e.g.
639 SCLEX_CPP), update document_update_tags() in document.c.
641 Adding a TagManager parser
642 ^^^^^^^^^^^^^^^^^^^^^^^^^^
643 This assumes the filetype for Geany already exists.
645 First write or find a CTags compatible parser, foo.c. Check this fork:
646 https://github.com/universal-ctags/ctags
648 There may be some unmerged language patches for CTags at:
649 http://sf.net/projects/ctags - see the tracker.
651 (You can also try the Anjuta project's anjuta-tags codebase.)
653 .. note::
654     From Geany 1.22 GLib's GRegex engine is used instead of POSIX
655     regex, unlike CTags. It should be close enough to POSIX to work
656     OK.
657     We no longer support regex parsers with the "b" regex flag
658     option set and Geany will print debug warnings if it's used.
659     CTags supports it but doesn't currently (2011) include any
660     parsers that use it. It should be easy to convert to extended
661     regex syntax anyway.
663 Method
664 ``````
665 * Add foo.c to SRCS in Makefile.am.
666 * Add Foo to parsers.h
667 * Add TM_PARSER_FOO to src/tagmanager/tm_parser.h.  The list here must follow
668   exactly the order in parsers.h.
670 In src/tagmanager/tm_parser.c:
671 Add a map_FOO TMParserMapEntry mapping each kind's letter from foo.c's
672 FooKinds to the appropriate TMTagType, and add the corresponding
673 MAP_ENTRY(FOO) to parser_map.
674 (You may want to make the symbols.c change before doing this).
676 In src/tagmanager/tm_parser.c:
677 Update tm_parser_context_separator() and tm_parser_has_full_context() to
678 handle the new parser if applicable, by adding a TM_PARSER_FOO case entry.
680 In filetypes.c, init_builtin_filetypes():
681 Set the 2nd argument of the FT_INIT() macro for this filetype to FOO.
683 In symbols.c:
684 Unless your parser uses C-like tag type kinds, update
685 add_top_level_items() for foo, calling tag_list_add_groups(). See
686 get_tag_type_iter() for which tv_iters fields to use.
688 Tests
689 `````
690 The tag parser tests checks if the proper tags are emitted
691 for a given source. Tests for tag parsers consist of two files: the
692 source to parse, and the expected output. Tests are run using ``make
693 check``.
695 The source to parse should be in the file ``tests/ctags/mytest.ext``,
696 where ``mytest`` is the name you choose for your test, and ``ext`` is an
697 extension recognized by Geany as the language the test file is for.
698 This file should contain a snippet of the language to test for.
699 It can be either long or short, depending on what it tests.
701 The expected output should be in the file ``tests/ctags/mytest.ext.tags``
702 (which is the same name as the source, but with ``.tags`` appended), and
703 should be in the format generated by ``geany -g``. This file contains
704 the tag information expected to be generated from the corresponding
705 source file.
707 When you have these two files, you have to list your new test along the
708 other ones in the ``test_source`` variable in ``tests/ctags/Makefile.am``.
709 Please keep this list sorted alphabetically.
711 Upgrading Scintilla
712 -------------------
714 To upgrade the local Scintilla copy, use the ``scripts/update-scintilla.sh``
715 script.
717 To use it, you need to first obtain a copy of the Scintilla sources you want
718 to update to.  This will generally mean checking out a release tag from the
719 Scintilla Mercurial repository, or extracting a tarball.
721 Then, just run the script from Geany's to source directory passing the path
722 to the Scintilla source directory as first argument, and follow the
723 instructions, if any::
725     ./scripts/update-scintilla.sh /path/to/scintilla/
730 Stop on warnings
731 ^^^^^^^^^^^^^^^^
732 When a GLib or GTK warning is printed, often you want to get a
733 backtrace to find out what code caused them. You can do that with the
734 ``--g-fatal-warnings`` argument, which will abort Geany on the first
735 warning it receives.
737 But for ordinary testing, you don't always want your editor to abort
738 just because of a warning - use::
740     (gdb) b handler_log if level <= G_LOG_LEVEL_WARNING
743 Running with batch commands
744 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
745 Use::
747     $ gdb src/geany -x gdb-commands
749 Where ``gdb-commands`` is a file with the following lines::
751     set pagination off
752     b handler_log if level <= G_LOG_LEVEL_WARNING
753     r -v
756 Loading a plugin
757 ^^^^^^^^^^^^^^^^
758 This is useful so you can load plugins without installing them first.
759 Alternatively you can use a symlink in ~/.config/geany/plugins or
760 $prefix/lib/geany (where $prefix is /usr/local by default).
762 The gdb session below was run from the toplevel Geany source directory.
763 Start normally with e.g. "gdb src/geany".
764 Type 'r' to run.
765 Press Ctrl-C from the gdb window to interrupt program execution.
767 Example::
769     Program received signal SIGINT, Interrupt.
770     0x00d16402 in __kernel_vsyscall ()
771     (gdb) call plugin_new("./plugins/.libs/demoplugin.so")
772     ** INFO: Loaded:   ./plugins/.libs/demoplugin.so (Demo)
773     $1 = (Plugin *) 0x905a890
774     (gdb) c
775     Continuing.
777     Program received signal SIGINT, Interrupt.
778     0x00d16402 in __kernel_vsyscall ()
779     (gdb) call plugin_free(0x905a890)
780     ** INFO: Unloaded: ./plugins/.libs/demoplugin.so
781     (gdb) c
782     Continuing.
784 Building Plugins
785 ^^^^^^^^^^^^^^^^
787 The geany-plugins autotools script automatically detects the
788 installed system Geany and builds the plugins against that.
790 Plugins will build with either GTK2 or GTK3, whichever the detected
791 Geany was built with.
793 To use plugins with a development version of Geany built with
794 a different prefix, the plugins will need to be compiled against
795 that version if the ABI has changed.
797 To do this you need to specify both --prefix and --with-geany-libdir
798 to the plugin configure.  Normally the plugin prefix is the
799 same as the Geany prefix to keep plugins with the version of Geany
800 that they are compiled against, and with-geany-libdir is the Geany
801 prefix/lib.
803 Whilst it is possible for the plugin prefix to be different to
804 the prefix of the libdir (which is why there are two settings),
805 it is probably better to keep the version of Geany and its plugins
806 together.