Reformat HACKING as true reStructuredText.
Add 'make hacking-doc' target to generate hacking.html. git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@3029 ea778897-0a13-0410-b9d1-a72fbfd435f5
This commit is contained in:
Nick Treleaven
parent
9bbf07f195
commit
6d4068f7b3
@ -1,3 +1,10 @@
|
||||
2008-10-01 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>
|
||||
|
||||
* HACKING, doc/Makefile.am:
|
||||
Reformat HACKING as true reStructuredText.
|
||||
Add 'make hacking-doc' target to generate hacking.html.
|
||||
|
||||
|
||||
2008-09-30 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
|
||||
|
||||
* src/project.c:
|
||||
|
||||
209
HACKING
209
HACKING
@ -1,23 +1,33 @@
|
||||
=============
|
||||
Hacking Geany
|
||||
=============
|
||||
.. contents::
|
||||
|
||||
General
|
||||
=======
|
||||
|
||||
About this file
|
||||
---------------
|
||||
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 pseudo-reStructuredText.
|
||||
the README file or the documentation. It is reStructuredText; the
|
||||
source file is HACKING. You can generate hacking.html by running ``make
|
||||
hacking-doc`` from the doc/ subdirectory.
|
||||
|
||||
Writing plugins
|
||||
---------------
|
||||
You should generate and read the plugin API documentation, see below.
|
||||
* src/plugindata.h contains the plugin API data types.
|
||||
* See plugins/demoplugin.c for a very basic example plugin.
|
||||
* src/plugins.c loads and unloads plugins (you shouldn't need to read
|
||||
this really).
|
||||
|
||||
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 (you shouldn't need to read
|
||||
this really).
|
||||
You should generate and read the plugin API documentation, see below.
|
||||
|
||||
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.
|
||||
tool. Run ``make api-doc`` in the doc subdirectory. The documentation
|
||||
will be output to doc/reference/index.html.
|
||||
|
||||
Patches
|
||||
-------
|
||||
@ -26,11 +36,13 @@ 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
|
||||
against other releases::
|
||||
|
||||
If you're not using SVN, you can use the diff command:
|
||||
$ diff -u originalpath modifiedpath > new-feature.patch
|
||||
$ 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
|
||||
|
||||
Please make sure patches follow the style of existing code - In
|
||||
particular, use tabs for indentation. See `Style`_ and `Coding`_.
|
||||
@ -44,30 +56,33 @@ File organization
|
||||
-----------------
|
||||
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.
|
||||
See the top of each ``src/*.c`` file for a brief description of what
|
||||
it's for.
|
||||
|
||||
Keeping the plugin ABI stable
|
||||
-----------------------------
|
||||
Please be aware that anything with a doc-comment (a comment with an
|
||||
extra asterix: '/**') 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.
|
||||
extra asterix: ``/**``) 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.
|
||||
|
||||
Note: Some structs like KeyBindingGroup and 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.
|
||||
.. warning::
|
||||
|
||||
Some structs like GeanyKeyGroup and 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.
|
||||
|
||||
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
|
||||
not load and they must be rebuilt. An API change means that some plugins
|
||||
might not build correctly.
|
||||
|
||||
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.
|
||||
This is not needed if you're just appending fields to structs. The
|
||||
api_version value should be incremented for any changes to the plugin API,
|
||||
including appending elements.
|
||||
When reordering or changing existing elements of structs that are
|
||||
used as part of the plugin API, you should 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.
|
||||
|
||||
@ -99,36 +114,38 @@ against GTK 2.6.
|
||||
|
||||
Coding
|
||||
------
|
||||
Don't write long functions with a lot of variables and/or scopes - break
|
||||
them down into smaller static functions where possible. This makes code
|
||||
much easier to read and maintain.
|
||||
Use GLib types and functions - e.g. g_free instead of free.
|
||||
Your code should build against GLib 2.6 and GTK 2.6. At least for the
|
||||
moment, we want to keep the minimum requirement for GTK at 2.6 (of
|
||||
course, you can use the GTK_CHECK_VERSION macro to protect code using
|
||||
later versions).
|
||||
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.
|
||||
You should also 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 can use
|
||||
-ansi in your CFLAGS to help check this.
|
||||
* Don't write long functions with a lot of variables and/or scopes - break
|
||||
them down into smaller static functions where possible. This makes code
|
||||
much easier to read and maintain.
|
||||
* Use GLib types and functions - e.g. g_free instead of free.
|
||||
* Your code should build against GLib 2.6 and GTK 2.6. At least for the
|
||||
moment, we want to keep the minimum requirement for GTK at 2.6 (of
|
||||
course, you can use the GTK_CHECK_VERSION macro to protect code using
|
||||
later versions).
|
||||
* 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.
|
||||
* You should also 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 can use -ansi in your CFLAGS to help check this.
|
||||
|
||||
Style
|
||||
-----
|
||||
We use a tab width of 4 and indent completely with tabs not spaces.
|
||||
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.
|
||||
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 ;-)
|
||||
* We use a tab width of 4 and indent completely with tabs not spaces.
|
||||
* 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.
|
||||
* 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 don't put 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
|
||||
---------
|
||||
@ -142,10 +159,10 @@ before Geany was started. It's source code parsing is mostly taken from
|
||||
Exuberant CTags (see http://ctags.sf.net).
|
||||
|
||||
|
||||
NOTES
|
||||
Notes
|
||||
=====
|
||||
Some of these notes below are brief (or maybe incomplete) - please
|
||||
contact the mailing list for more information.
|
||||
contact the geany-devel mailing list for more information.
|
||||
|
||||
Using pre-defined autotools values
|
||||
----------------------------------
|
||||
@ -159,21 +176,22 @@ printf("Prefix: %s", GEANY_PREFIX);
|
||||
|
||||
Adding a source 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).
|
||||
* 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
|
||||
-----------------
|
||||
You can add a filetype without syntax highlighting or tag parsing, but
|
||||
check to see if those features have been written in other projects first.
|
||||
|
||||
Add GEANY_FILETYPES_FOO to filetypes.h.
|
||||
Initialize GEANY_FILETYPES_FOO in init_builtin_filetypes() of
|
||||
filetypes.c.
|
||||
Rebuild Geany.
|
||||
From your geany/ directory, run:
|
||||
src/geany --generate-data-files
|
||||
* Add GEANY_FILETYPES_FOO to filetypes.h.
|
||||
* Initialize GEANY_FILETYPES_FOO in init_builtin_filetypes() of
|
||||
filetypes.c.
|
||||
* Rebuild Geany.
|
||||
* From your geany/ directory, run::
|
||||
|
||||
src/geany --generate-data-files
|
||||
|
||||
(The src/ prefix may be different, depending on where the binary is
|
||||
generated.)
|
||||
@ -188,9 +206,10 @@ All languages need a data/filetypes.foo configuration file. See
|
||||
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.
|
||||
|
||||
* [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 styleset_foo() in highlighting.c -
|
||||
@ -202,23 +221,23 @@ 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 Scintilla project first. When adding a lexer, update:
|
||||
|
||||
* scintilla/Makefile.am
|
||||
* scintilla/makefile.win32
|
||||
* scintilla/KeyWords.cxx - add a LINK_LEXER command *manually*
|
||||
* scintilla/Makefile.am
|
||||
* scintilla/makefile.win32
|
||||
* scintilla/KeyWords.cxx - add a LINK_LEXER command *manually*
|
||||
|
||||
For syntax highlighting, you will need to edit highlighting.c and add
|
||||
the following things:
|
||||
|
||||
1. Write styleset_foo_init() to setup default styles and load style
|
||||
settings from the filetypes.foo configuration file. You should probably
|
||||
start by copying and adapting another filetype's initialization, such
|
||||
as styleset_asm_init().
|
||||
settings from the filetypes.foo configuration file. You should probably
|
||||
start by copying and adapting another filetype's initialization, such
|
||||
as styleset_asm_init().
|
||||
2. Write styleset_foo() to apply styles when a new scintilla widget
|
||||
is created. Again you could copy and adapt a function like styleset_asm().
|
||||
3. Add this in highlighting_init_styles():
|
||||
init_styleset_case(GEANY_FILETYPES_FOO, foo);
|
||||
4. Add this in highlighting_set_styles():
|
||||
styleset_case(GEANY_FILETYPES_FOO, foo);
|
||||
is created. Again you could copy and adapt a function like styleset_asm().
|
||||
3. In highlighting_init_styles(), add
|
||||
``init_styleset_case(GEANY_FILETYPES_FOO, foo);``.
|
||||
4. In highlighting_set_styles(), add
|
||||
``styleset_case(GEANY_FILETYPES_FOO, foo);``.
|
||||
|
||||
Please try to make your styles fit in with the other filetypes' default
|
||||
colors.
|
||||
@ -256,9 +275,9 @@ 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.
|
||||
* 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.
|
||||
@ -282,17 +301,19 @@ 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.
|
||||
Example::
|
||||
|
||||
Program received signal SIGINT, Interrupt.
|
||||
0x00d16402 in __kernel_vsyscall ()
|
||||
(gdb) call plugin_free(0x905a890)
|
||||
** INFO: Unloaded: ./plugins/.libs/demoplugin.so
|
||||
(gdb) c
|
||||
Continuing.
|
||||
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.
|
||||
|
||||
@ -13,6 +13,9 @@ pdf: geany.txt
|
||||
api-doc: Doxyfile
|
||||
doxygen
|
||||
|
||||
hacking-doc: ../HACKING
|
||||
rst2html -stg --stylesheet=geany.css $^ hacking.html
|
||||
|
||||
# when generating documentation, first try rst2html.py as it is the upstream default
|
||||
doc: geany.txt
|
||||
rst2html.py -stg --stylesheet=geany.css $(srcdir)/geany.txt geany.html || \
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user