Revision: 3029 http://geany.svn.sourceforge.net/geany/?rev=3029&view=rev Author: ntrel Date: 2008-10-01 16:47:25 +0000 (Wed, 01 Oct 2008)

Log Message: ----------- Reformat HACKING as true reStructuredText. Add 'make hacking-doc' target to generate hacking.html.

Modified Paths: -------------- trunk/ChangeLog trunk/HACKING trunk/doc/Makefile.am

Modified: trunk/ChangeLog =================================================================== --- trunk/ChangeLog 2008-10-01 12:43:17 UTC (rev 3028) +++ trunk/ChangeLog 2008-10-01 16:47:25 UTC (rev 3029) @@ -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:

Modified: trunk/HACKING =================================================================== --- trunk/HACKING 2008-10-01 12:43:17 UTC (rev 3028) +++ trunk/HACKING 2008-10-01 16:47:25 UTC (rev 3029) @@ -1,3 +1,11 @@ +============= +Hacking Geany +============= +.. contents:: + +General +======= + About this file --------------- This file contains information for anyone wanting to work on the Geany @@ -2,18 +10,20 @@ 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 --------------- +* 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). + You should generate and read the plugin API documentation, see below.

-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). - 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.

@@ -26,12 +36,14 @@ 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 @@ ----------------- 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 @@

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 @@ 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,22 +176,23 @@

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.) This will update data/filetype_extensions.conf. Note that @@ -188,10 +206,11 @@ 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 - see below. @@ -202,23 +221,23 @@ 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 @@

(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 @@ 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.

Modified: trunk/doc/Makefile.am =================================================================== --- trunk/doc/Makefile.am 2008-10-01 12:43:17 UTC (rev 3028) +++ trunk/doc/Makefile.am 2008-10-01 16:47:25 UTC (rev 3029) @@ -13,6 +13,9 @@ 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 || \

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.