geany/HACKING

About this file
---------------
This file contains information for anyone wanting to work on the Geany codebase.
You should be aware of the licenses used - see the README file or the documentation.

Patches
-------
We are happy to receive patches, but it's best to check with us by email or mailing list whether a
new feature is appropriate, and whether someone is already working on similar code.

In general it's best to work from the current SVN, but we accept patches against other releases.
$ svn diff > fix-some-bug.patch

If you're not using SVN, you can use the diff command:
$ diff -u originalpath modifiedpath > new-feature.patch

For Windows:
Subversion (SVN): http://subversion.tigris.org/
diff, grep, etc: http://mingw.org/ or http://unxutils.sourceforge.net/.
See also the 'Building on Windows' document on the website.

File organization
-----------------
We aim to use callbacks.c only for Glade callbacks.
Avoid adding code to geany.h if it will fit better elsewhere.
See the src/*.c files for descriptions.

Glade
-----
Use the code generation features of Glade instead of editing interface.c or support.c.
Glade 2.10 is recommended as long as we support GTK+ 2.6, because later versions of Glade are not
100% compatible with GTK+ 2.6 (e.g. they may use functions added in GTK+ 2.8).

Coding
------
Use static functions where possible.
Try to use GLib types and functions - e.g. g_free instead of free and try to use only GLib 2.6 and
GTK 2.6 functions. At least for the moment, we want to keep the minimum requirement for GTK at 2.6.
We currently try to support the old GCC 2.9.x compiler, so we always declare variables before
statements. You can use -Wdeclaration-after-statement in your ./configure CFLAGS to warn about
this.

Style
-----
We use a tab width of 4 and indent completely with tabs not spaces.
To comment small blocks of code we use the C++ // comments and for functions descriptions or longer
explanations of code, the multiline comment /* */ should be used. In any case, the more comments
are in your code the better.
Lines should not be longer than about 100 characters and after 100 characters the lines should be
wrapped and more indented than the first line to highlight that the line is continued.
We avoid putting spaces between function names and the opening brace for argument lists.
Try to fit in with the existing code brace indenting style, comments, operator spacing etc. It's
not required but it makes our lives easier ;-)

Libraries
---------
We prefer to use an unmodified version of Scintilla - any changes should be passed on to the
maintainers at http://scintilla.org.
Tagmanager was originally taken from Anjuta 1.2.2, and parts of it (notably c.c) have been merged
from later versions of Anjuta. The independent Tagmanager library itself ceased development before
Geany was started. It's source code parsing is mostly taken from Exuberant Ctags (see
http://ctags.sf.net).


NOTES
=====
Some of these notes below are brief (or maybe incomplete) - please contact
the mailing list for more information.

Modifying data types
--------------------
When reordering or changing existing elements of structs that are used as part of the
plugin API, you should increment abi_version in plugindata.h (and api_version if changing
elements). This is not needed if you're just appending fields to structs.

Adding a file foo.[hc] in src/ or plugins/
------------------------------------------
Add foo.c, foo.h to SRCS in path/Makefile.am.
Add foo.o to OBJS in path/makefile.win32.
Add path/foo.c to po/POTFILES.in (for string translation).

Adding a filetype
-----------------
For syntax highlighting, you will need to find (or write) a Scintilla lexer, LexFoo.cxx.
For tag parsing (e.g. for the symbol list), see 'Adding a TagManager parser' below.
Add GEANY_FILETYPES_FOO and initialize it in filetypes.[hc].

Adding a TagManager parser
--------------------------
This assumes the Geany filetype 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.)

Add foo.c to SRCS in Makefile.am.
Add foo.o to OBJS in makefile.win32.
Add Foo to parsers.h & fill in comment with parser number for foo.

In foo.c:
Edit FooKinds 3rd column to match a s_tag_type_names string in tm_tag.c.

In filetypes.c, filetypes_init_types():
Set filetypes[GEANY_FILETYPES_FOO].lang = foo's parser number.

In symbols.c:
Update init_tag_list() for foo, listing the tm_tag_* types corresponding
to the s_tag_type_names strings used in foo.c for FooKinds.


PLUGINS
=======

src/plugindata.h contains the plugin API data types and some notes.
See plugins/demoplugin.c for a very basic example plugin.
src/plugins.c loads and unloads plugins.

Loading a plugin from GDB
-------------------------
This is useful so you can load plugins without installing them first.
Alternatively you can use a symlink to $prefix/lib/geany/myplugin.so, (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.

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.