From 498964e1c7240f52de7b6b7e2609fc9e507e175d Mon Sep 17 00:00:00 2001 From: Nick Treleaven Date: Fri, 14 Mar 2008 17:44:43 +0000 Subject: [PATCH] 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. git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@2347 ea778897-0a13-0410-b9d1-a72fbfd435f5 --- ChangeLog | 6 ++++++ HACKING | 54 +++++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 45 insertions(+), 15 deletions(-) diff --git a/ChangeLog b/ChangeLog index 9c7045408..eee52a4ad 100644 --- a/ChangeLog +++ b/ChangeLog @@ -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 diff --git a/HACKING b/HACKING index dc76349f7..17c177cf8 100644 --- a/HACKING +++ b/HACKING @@ -4,6 +4,23 @@ 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. +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 @@ 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. +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 @@ so we always declare variables before statements. You can use 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 @@ 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. - Using pre-defined autotools values ---------------------------------- When you are use macros supplied by the autotools like GEANY_PREFIX, @@ -199,13 +230,6 @@ 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.