Revision: 2347 http://geany.svn.sourceforge.net/geany/?rev=2347&view=rev Author: ntrel Date: 2008-03-14 10:44:43 -0700 (Fri, 14 Mar 2008)

Log Message: ----------- Replace Plugins chapter with 'Writing plugins' section. Add generating plugin API documentation section. Replace 'Modifying data types' with 'Keeping the plugin ABI stable' section. Add note about using -ansi.

Modified Paths: -------------- trunk/ChangeLog trunk/HACKING

Modified: trunk/ChangeLog =================================================================== --- trunk/ChangeLog 2008-03-14 17:28:37 UTC (rev 2346) +++ trunk/ChangeLog 2008-03-14 17:44:43 UTC (rev 2347) @@ -7,6 +7,12 @@ Make KeyBinding name and label fields non-const strings so they can be freed by any plugins that need to use malloc'd strings. Document KeyCallback typedef. + * HACKING: + Replace Plugins chapter with 'Writing plugins' section. + Add generating plugin API documentation section. + Replace 'Modifying data types' with 'Keeping the plugin ABI stable' + section. + Add note about using -ansi.

2008-03-14 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>

Modified: trunk/HACKING =================================================================== --- trunk/HACKING 2008-03-14 17:28:37 UTC (rev 2346) +++ trunk/HACKING 2008-03-14 17:44:43 UTC (rev 2347) @@ -4,6 +4,23 @@ codebase. You should be aware of the open source licenses used - see the README file or the documentation.

+Writing plugins +--------------- +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. + +See the Related Pages section for a link to the plugin howto. + Patches ------- We are happy to receive patches, but it's best to check with us by email @@ -28,6 +45,26 @@ 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.

+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 still be appended to, ensuring that all the existing +elements stay in place - this will keep the ABI stable. + +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 +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. + +If you're in any doubt when making changes to plugin API code, just ask us. + Glade ----- Use the code generation features of Glade instead of editing interface.c @@ -55,7 +92,8 @@ 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. +This is for compatibility with various Unix-like compilers. You can use +-ansi in your CFLAGS to help check this.

Style ----- @@ -88,13 +126,6 @@ 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. - Using pre-defined autotools values ---------------------------------- When you are use macros supplied by the autotools like GEANY_PREFIX, @@ -199,13 +230,6 @@ 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.

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