SF.net SVN: geany: [2347] trunk

ntrel at users.sourceforge.net ntrel at xxxxx
Fri Mar 14 17:44:58 UTC 2008


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.



More information about the Commits mailing list