SF.net SVN: geany:[4127] trunk

[ntrel at users.sourceforge.net]

Revision: 4127
          http://geany.svn.sourceforge.net/geany/?rev=4127&view=rev
Author:   ntrel
Date:     2009-08-26 14:46:45 +0000 (Wed, 26 Aug 2009)

Log Message:
-----------
Add section 'Plugin API/ABI design'.

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

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog	2009-08-26 14:42:25 UTC (rev 4126)
+++ trunk/ChangeLog	2009-08-26 14:46:45 UTC (rev 4127)
@@ -3,6 +3,8 @@
  * doc/plugins.dox:
    Add warning about not using undocumented features.
    Add reference to HACKING for plugin API development.
+ * HACKING:
+   Add section 'Plugin API/ABI design'.
 
 
 2009-08-25  Enrico Tröger  <enrico(dot)troeger(at)uvena(dot)de>

Modified: trunk/HACKING
===================================================================
--- trunk/HACKING	2009-08-26 14:42:25 UTC (rev 4126)
+++ trunk/HACKING	2009-08-26 14:46:45 UTC (rev 4127)
@@ -72,7 +72,7 @@
 
 .. warning::
 
-	Some structs like GeanyKeyGroup and GeanyCallback cannot be
+	Some structs like GeanyKeyGroupInfo 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.
@@ -82,7 +82,7 @@
 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
+If you're 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
@@ -90,6 +90,15 @@
 
 If you're in any doubt when making changes to plugin API code, just ask us.
 
+Plugin API/ABI design
+---------------------
+You should not make plugins rely on the size of a struct. This means:
+
+* Don't let plugins allocate any structs (stack or heap).
+* Don't let plugins index any arrays of structs.
+* Don't add any array fields to structs in case we want to change the
+  array size later.
+
 Glade
 -----
 Use the code generation features of Glade instead of editing interface.c


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