Add Folding section link to filetypes.common custom settings.
[geany-mirror.git] / HACKING
blob07c17b789606866c2ce401368abcb7d3c78bae7a
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. You can generate hacking.html by running ``make
15 hacking-doc`` from the doc/ subdirectory.
17 Writing plugins
18 ---------------
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
22   this really).
23 * The API documentation contains a few basic guidelines and hints to
24   write plugins.
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/.
36 Patches
37 -------
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
51 .. note::
52     Please make sure patches follow the style of existing code - In
53     particular, use tabs for indentation. See `Coding`_.
55 Windows tools
56 -------------
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.
62 File organization
63 -----------------
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
67 it's for.
69 Plugin API code
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.
76 .. warning::
78     Some structs like GeanyCallback cannot be appended to without
79     breaking the ABI because they are used to declare structs by
80     plugins, not just for accessing struct members through a pointer.
81     Normally structs should never be allocated by plugins.
83 Keeping the plugin ABI stable
84 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
85 Before the 1.0 release series, the ABI can change when necessary, and
86 even the API can change. An ABI change just means that all plugins will
87 not load and they must be rebuilt. An API change means that some plugins
88 might not build correctly.
90 If you're reordering or changing existing elements of structs that are
91 used as part of the plugin API, you must increment GEANY_ABI_VERSION
92 in plugindata.h. This is usually not needed if you're just appending
93 fields to structs. The GEANY_API_VERSION value should be incremented
94 for any changes to the plugin API, including appending elements.
96 If you're in any doubt when making changes to plugin API code, just ask us.
98 Plugin API/ABI design
99 ^^^^^^^^^^^^^^^^^^^^^
100 You should not make plugins rely on the size of a struct. This means:
102 * Don't let plugins allocate any structs (stack or heap).
103 * Don't let plugins index any arrays of structs.
104 * Don't add any array fields to structs in case we want to change the
105   array size later.
107 Doc-comments
108 ^^^^^^^^^^^^
109 * The @file tag can go in the source .c file, but use the .h header name so
110   it appears normally in the generated documentation. See ui_utils.c for an
111   example.
112 * Function doc-comments should always go in the source file, not the
113   header, so they can be updated if/when the implementation changes.
115 Glade
116 -----
117 Use the code generation features of Glade instead of editing interface.c
118 or support.c. Glade 2.12 is recommended as long as we support GTK+ 2.8,
119 because later versions of Glade are not 100% compatible with GTK+ 2.8
120 (e.g. they may use functions added in GTK+ 2.10).
122 You can build Glade 2.12 and run the binary in place, without installing
123 it - this should work fine even if you have another version of Glade
124 installed on the system.
126 GTK API documentation
127 ---------------------
128 The official GTK 2.8 API documentation is not available online anymore,
129 so we put them on http://www.geany.org/manual/gtk/.
130 There is also a tarball with all available files for download and use
131 with devhelp.
133 Using the 2.8 API documentation of the GTK libs (including GLib, GDK and
134 Pango) has the advantages that you don't get confused by any newer API
135 additions and you don't have to take care about whether you can use
136 them or not.
137 This is because Geany depends on GTK 2.8. API symbols from newer
138 GTK/GLib versions should be avoided to keep the source code building
139 against GTK 2.8.
141 Coding
142 ------
143 * Don't write long functions with a lot of variables and/or scopes - break
144   them down into smaller static functions where possible. This makes code
145   much easier to read and maintain.
146 * Use GLib types and functions - gint not int, g_free() not free().
147 * Your code should build against GLib 2.8 and GTK 2.8. At least for the
148   moment, we want to keep the minimum requirement for GTK at 2.8 (of
149   course, you can use the GTK_CHECK_VERSION macro to protect code using
150   later versions).
151 * Variables should be declared before statements. You can use
152   gcc's -Wdeclaration-after-statement to warn about this.
153 * Don't let variable names shadow outer variables - use gcc's -Wshadow
154   option.
156 Compiler options & warnings
157 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
158 Use ``CFLAGS='-Wfoo' ./configure`` or ``CFLAGS='-Wfoo' ./autogen.sh``
159 to set warning options (as well as anything else e.g. -g -O2).
161 * Enable warnings - for gcc use '-Wall -W' (and optionally
162   -Wno-unused-parameter to avoid unused parameter warnings in Glade
163   callbacks).
164 * You should try to write ISO C90 code for portability, so always
165   use C ``/* */`` comments and function_name(void) instead of
166   function_name(). This is for compatibility with various Unix-like
167   compilers. You should use -ansi to help check this.
169 .. tip::
170     Remember for gcc you need to enable optimization to get certain
171     warnings like uninitialized variables, but for debugging it's
172     better to have no optimization on.
174 Style
175 ^^^^^
176 * We use a tab width of 4 and indent completely with tabs not spaces.
177   Note the documentation files use (4) spaces instead, so you may want
178   to use the 'Detect from file' indent pref.
179 * Use the multiline comment ``/* */`` to comment small blocks of code,
180   functions descriptions or longer explanations of code, etc. C++ single
181   line comments will cause portability issues. The more comments are in
182   your code the better. (See also ``scripts/fix-cxx-comments.pl`` in SVN).
183 * Lines should not be longer than about 100 characters and after 100
184   characters the lines should be wrapped and indented once more to
185   show that the line is continued.
186 * We don't put spaces between function names and the opening brace for
187   argument lists.
188 * Variable declarations come first after an opening brace, then one
189   newline to separate declarations and code.
190 * 2-operand operators should have a space each side.
191 * Function bodies should have 2 blank newlines after them.
192 * Align braces together on separate lines.
193 * Don't put assignments in 'if/while/etc' expressions.
194 * if statements without brace bodies should have the code on a separate
195   line, then a blank line afterwards.
196 * Use braces after if/while statements if the body uses another
197   if/while statement.
198 * Try to fit in with the existing code style.
200 .. note::
201     A few of the above can be done with the SVN
202     ``scripts/fix-alignment.pl``, but it is quite dumb and it's much better
203     to write it correctly in the first place.
205 .. below tabs should be used, but spaces are required for reST.
207 Example::
209     gint some_func(void);
212     gint function_long_name(gchar arg1, <too many args to fit on this line>,
213             gchar argN)
214     {
215         /* variable declarations go before code in each scope */
216         gint foo, bar;  /* variables can go on the same line */
217         gchar *ptr;     /* pointer symbol must go next to variable name, not type */
218         gchar *another; /* pointers should normally go on separate lines */
220         /* Some long comment block
221          * taking several different
222          * lines to explain */
223         if (foo)
224         {
225             gint dir = -1;    /* -1 to search backwards */
227             bar = foo;
228             if ((bar & (guint)dir) != 7)
229                 some_code(arg1, <too many args to fit on this line>,
230                     argN - 1, argN);
232             some_func();
233         }
234     }
237     gint another_function(void)
238     {
239         ...
242 Testing
243 -------
244 * Run with ``-v`` to print any debug messages.
245 * You can use a second instance (``geany -i``).
246 * To check first-run behaviour, use an alternate config directory by
247   passing ``-c some_dir`` (but make sure the directory is clean first).
248 * For debugging tips, see `GDB`_.
250 Libraries
251 ---------
252 We try to use an unmodified version of Scintilla - any new lexers or
253 other changes should be passed on to the maintainers at
254 http://scintilla.org. We normally update to a new Scintilla release
255 shortly after one is made.
257 Tagmanager was originally taken from Anjuta 1.2.2, and parts of it
258 (notably c.c) have been merged from later versions of Anjuta and
259 CTags. The independent Tagmanager library itself ceased development
260 before Geany was started. It's source code parsing is mostly taken from
261 Exuberant CTags (see http://ctags.sf.net). If appropriate it's good to
262 pass language parser changes back to the CTags project.
265 Notes
266 =====
267 Some of these notes below are brief (or maybe incomplete) - please
268 contact the geany-devel mailing list for more information.
270 Using pre-defined autotools values
271 ----------------------------------
272 When you are use macros supplied by the autotools like GEANY_PREFIX,
273 GEANY_LIBDIR, GEANY_DATADIR and GEANY_LOCALEDIR be aware that these
274 might not be static strings when Geany is configured with
275 --enable-binreloc. Then these macros will be replaced by function calls
276 (in src/prefix.h). So, don't use anything like
277 printf("Prefix: " GEANY_PREFIX); but instead use
278 printf("Prefix: %s", GEANY_PREFIX);
280 Adding a source file foo.[hc] in src/ or plugins/
281 -------------------------------------------------
282 * Add foo.c, foo.h to SRCS in path/Makefile.am.
283 * Add foo.o to OBJS in path/makefile.win32.
284 * Add path/foo.c to geany_sources in wscript.
285 * Add path/foo.c to po/POTFILES.in (for string translation).
287 Adding a filetype
288 -----------------
289 You can add a filetype without syntax highlighting or tag parsing, but
290 check to see if those features have been written in other projects first.
292 * Add GEANY_FILETYPES_FOO to filetypes.h.
293 * Initialize GEANY_FILETYPES_FOO in init_builtin_filetypes() of
294   filetypes.c. You should use filetype_make_title() to avoid a
295   translation whenever possible.
296 * Update data/filetype_extensions.conf.
298 filetypes.* configuration file
299 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
300 All languages need a data/filetypes.foo configuration file. See
301 the "Filetype definition files" section in the manual and/or
302 data/filetypes.c for an example.
304 Programming languages should have:
306 * [keywords] if the lexer supports it.
307 * [settings] mostly for comment settings.
308 * [build_settings] for commands to run.
310 For languages with a Scintilla lexer, there should be a [styling] section,
311 to correspond to the styles used in styleset_foo() in highlighting.c -
312 see below.
314 Syntax highlighting
315 ^^^^^^^^^^^^^^^^^^^
316 It may be possible to use an existing Scintilla lexer in the scintilla/
317 subdirectory - if not, you will need to find (or write) one,
318 LexFoo.cxx. Try the official Scintilla project first.
320 .. warning::
321     We won't accept adding a lexer that conflicts with one in
322     Scintilla. All new lexers should be submitted back to the Scintilla
323     project to save duplication of work.
325 When adding a lexer, update:
327 * scintilla/Makefile.am
328 * scintilla/makefile.win32
329 * wscript
330 * scintilla/KeyWords.cxx - add a LINK_LEXER command *manually*
332 For syntax highlighting, you will need to edit highlighting.c and add
333 the following things:
335 1. Write styleset_foo_init() to setup lexer styles and load style
336    settings from the filetypes.foo configuration file. You should probably
337    start by copying and adapting another filetype's initialization, such
338    as styleset_tcl_init(). You may want to use load_style_entries().
339 2. Write styleset_foo() to apply styles when a new scintilla widget
340    is created. Again you could copy and adapt a function like
341    styleset_tcl(). You may want to use apply_style_entries().
342 3. In highlighting_init_styles(), add
343    ``init_styleset_case(GEANY_FILETYPES_FOO, styleset_foo_init);``.
344 4. In highlighting_set_styles(), add
345    ``styleset_case(GEANY_FILETYPES_FOO, styleset_foo);``.
346 5. Write data/filetypes.foo configuration file [styling] section. See
347    the manual and see data/filetypes.d for a named style example.
349 .. note::
350     Please try to make your styles fit in with the other filetypes'
351     default colors, and to use named styles where possible (e.g.
352     "commentline=comment"). Filetypes that share a lexer should have
353     the same colors. If not using named styles, leave the background color
354     empty to match the default color.
356 Error message parsing
357 ^^^^^^^^^^^^^^^^^^^^^
358 New-style error message parsing is done with an extended GNU-style regex
359 stored in the filetypes.foo file - see the [build_settings] information
360 in the manual for details.
362 Old-style error message parsing is done in
363 msgwin_parse_compiler_error_line() of msgwindow.c - see the ParseData
364 typedef for more information.
366 Other features
367 ^^^^^^^^^^^^^^
368 For brace indentation, update lexer_has_braces() in editor.c;
369 indentation after ':' is done from on_new_line_added().
371 If the lexer has comment styles, you should add them in is_comment_style()
372 in editor.c. You should also update is_string_style() for string/character
373 styles. For now, this prevents calltips and autocompletion when typing
374 in a comment (but it can still be forced by the user).
376 If the Scintilla lexer supports user type keyword highlighting (e.g.
377 SCLEX_CPP), update editor_lexer_get_type_keyword_idx() in editor.c.
379 Adding a TagManager parser
380 ^^^^^^^^^^^^^^^^^^^^^^^^^^
381 This assumes the filetype for Geany already exists.
383 First write or find a CTags compatible parser, foo.c. Note that there
384 are some language patches for CTags at:
385 http://sf.net/projects/ctags - see the tracker.
387 (You can also try the Anjuta project's tagmanager codebase.)
389 * Add foo.c to SRCS in Makefile.am.
390 * Add foo.o to OBJS in makefile.win32.
391 * Add path/foo.c to geany_sources in wscript.
392 * Add Foo to parsers.h & fill in comment with parser number for foo.
394 In foo.c:
395 Edit FooKinds 3rd column to match a s_tag_type_names string in tm_tag.c.
396 (You may want to make the symbols.c change before doing this).
398 In filetypes.c, init_builtin_filetypes():
399 Set filetypes[GEANY_FILETYPES_FOO].lang = foo's parser number.
401 In symbols.c:
402 Unless your parser uses C-like tag type kinds, update
403 add_top_level_items() for foo, calling tag_list_add_groups(). See
404 get_tag_type_iter() for which tv_iters fields to use.
410 Stop on warnings
411 ^^^^^^^^^^^^^^^^
412 When a GLib or GTK warning is printed, often you want to get a
413 backtrace to find out what code caused them. You can do that with the
414 ``--g-fatal-warnings`` argument, which will abort Geany on the first
415 warning it receives.
417 But for ordinary testing, you don't always want your editor to abort
418 just because of a warning - use::
420     (gdb) b handler_log if level <= G_LOG_LEVEL_WARNING
423 Running with batch commands
424 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
425 Use::
427     $ gdb src/geany -x gdb-commands
429 Where ``gdb-commands`` is a file with the following lines::
431     set pagination off
432     b handler_log if level <= G_LOG_LEVEL_WARNING
433     r -v
436 Loading a plugin
437 ^^^^^^^^^^^^^^^^
438 This is useful so you can load plugins without installing them first.
439 Alternatively you can use a symlink in ~/.config/geany/plugins or
440 $prefix/lib/geany (where $prefix is /usr/local by default).
442 The gdb session below was run from the toplevel Geany source directory.
443 Start normally with e.g. "gdb src/geany".
444 Type 'r' to run.
445 Press Ctrl-C from the gdb window to interrupt program execution.
447 Example::
449     Program received signal SIGINT, Interrupt.
450     0x00d16402 in __kernel_vsyscall ()
451     (gdb) call plugin_new("./plugins/.libs/demoplugin.so")
452     ** INFO: Loaded:   ./plugins/.libs/demoplugin.so (Demo)
453     $1 = (Plugin *) 0x905a890
454     (gdb) c
455     Continuing.
457     Program received signal SIGINT, Interrupt.
458     0x00d16402 in __kernel_vsyscall ()
459     (gdb) call plugin_free(0x905a890)
460     ** INFO: Unloaded: ./plugins/.libs/demoplugin.so
461     (gdb) c
462     Continuing.