SF.net SVN: geany:[4565] branches/geany-0.18.1

[eht16 at users.sourceforge.net]

Revision: 4565
          http://geany.svn.sourceforge.net/geany/?rev=4565&view=rev
Author:   eht16
Date:     2010-01-25 21:16:46 +0000 (Mon, 25 Jan 2010)

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

Modified Paths:
--------------
    branches/geany-0.18.1/ChangeLog
    branches/geany-0.18.1/HACKING

Modified: branches/geany-0.18.1/ChangeLog
===================================================================
--- branches/geany-0.18.1/ChangeLog	2010-01-25 21:16:38 UTC (rev 4564)
+++ branches/geany-0.18.1/ChangeLog	2010-01-25 21:16:46 UTC (rev 4565)
@@ -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: branches/geany-0.18.1/HACKING
===================================================================
--- branches/geany-0.18.1/HACKING	2010-01-25 21:16:38 UTC (rev 4564)
+++ branches/geany-0.18.1/HACKING	2010-01-25 21:16:46 UTC (rev 4565)
@@ -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.