[geany/geany-plugins] da466b: Merge pull request #215 from b4n/hacking

Wed May 27 21:17:23 UTC 2015

Branch:      refs/heads/master
Author:      Colomban Wendling <ban at herbesfolles.org>
Committer:   Colomban Wendling <ban at herbesfolles.org>
Date:        Wed, 27 May 2015 21:17:23 UTC
Commit:      da466b327d959208b5a8205e1018a03962c3a5ec
             https://github.com/geany/geany-plugins/commit/da466b327d959208b5a8205e1018a03962c3a5ec

Log Message:
-----------
Merge pull request #215 from b4n/hacking

Extend docs on adding a plugin to the build systems


Modified Paths:
--------------
    HACKING

Modified: HACKING
106 lines changed, 88 insertions(+), 18 deletions(-)
===================================================================
@@ -170,24 +170,25 @@ configure.ac
 ^^^^^^^^^^^^
 
 Add an entry into configure.ac for your plugin. The entry should look like
-``GP_CHECK_YOURFANCYPLUGINNAME``
+``GP_CHECK_YOURFANCYPLUGINNAME``.  This is a custom macro that will be
+discussed in the `build sub-folder`_ section below.
 
-Makefile.am
-^^^^^^^^^^^
+Root Makefile.am
+^^^^^^^^^^^^^^^^
 
-Add an entry into Makefile.am where to find the sources of your plugin.
-This entry shall look like this::
+Add an entry into the root Makefile.am where to find the sources of your
+plugin.  This entry shall look like this::
 
  if ENABLE_YOURFANCYPLUGINNAME
  SUBDIRS += yourfancyplugin
  endif
 
 
-build-subfolder
-^^^^^^^^^^^^^^^
+`build` sub-folder
+^^^^^^^^^^^^^^^^^^
 
-To build your plugin you will also need to add an m4-script inside
-the ``build`` subfolder of the geany-plugin sources. The file should
+To build your plugin you will also need to add an M4 script inside
+the ``build`` sub-folder of the geany-plugin sources. The file should
 be called ``yourfancypluginname.m4`` and contain the definition of the M4
 macro that checks for your plugin's dependencies and generates its
 build files, which macro is called from configure.ac::
@@ -227,16 +228,16 @@ GTK 2 and 3 but you want to check for a minimal GTK2 version, you may
 use ``$GP_GTK_PACKAGE >= 2.XX`` in a ``GP_CHECK_PLUGIN_DEPS`` call.
 
 
-Makefile inside your plugin folder
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Makefiles inside your plugin folder
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The Makefile inside your plugin folder can be seperated at least
+The Makefiles inside your plugin folder can be separated at least
 into two parts: The first part is located inside the root folder of
-your plugin, whereas the second one is located inside src/ of your
+your plugin, whereas the second one is located inside ``src/`` of your
 plugin.
 
 
-Plugin-root
+Plugin root
 ###########
 
 The file should be called ``Makefile.am`` and contains the entry
@@ -248,11 +249,11 @@ similar to this::
     plugin = yourfancypluginname
 
 
-src-folder
-###########
+`src` folder
+############
 
-The ``Makefile.am`` inside the src-Folder is containing the
-informationen how to build the sources. An example could look like::
+The ``Makefile.am`` inside the ``src`` folder declares how to build the
+sources. An example could look like::
 
     include $(top_srcdir)/build/vars.build.mk
 
@@ -263,6 +264,75 @@ informationen how to build the sources. An example could look like::
 
     include $(top_srcdir)/build/cppcheck.mk
 
+If you checked for additional dependencies in ``yourfancypluginname.m4``
+(besides Geany, GLib and GTK, which are included in ``$(COMMONLIBS)``),
+you will need to use the various flags they might require.
+
+For a library checked with ``GP_CHECK_PLUGIN_DEPS`` you will have to add
+``$(PREFIX_CFLAGS)`` to ``yourfancypluginname_la_CFLAGS`` and
+``$(PREFIX_LIBS)`` to ``yourfancypluginname_la_LIBADD`` (where
+``PREFIX`` is the name you chose to store the results in the
+``GP_CHECK_PLUGIN_DEPS`` call).  Note that if you set
+``yourfancypluginname_la_CFLAGS`` you will need to explicitly mention
+``$(AM_CFLAGS)`` in it.
+
+For example, if you checked for the hypothetical library ``foo`` and
+used the ``FOO`` prefix to store the results, you should alter the
+Makefile.am to references them::
+
+    yourfancypluginname_la_CFLAGS = $(AM_CFLAGS) $(FOO_CFLAGS)
+    yourfancypluginname_la_LIBADD = $(COMMONLIBS) $(FOO_LIBS)
+
+
+Adding a new plugin to Waf build system
+---------------------------------------
+
+Configuration checks
+^^^^^^^^^^^^^^^^^^^^
+
+Add a ``wscript_configure`` file in your plugin's root folder.
+This file contains checks for dependencies, like libraries your plugin
+requires.  If your plugin does not have any additional dependencies
+besides Geany, GLib and GTK, you can leave this file empty (but you need
+to create it nonetheless).
+
+Generally checks are performed with ``check_cfg_cached``.  An example
+to check for library ``foo`` at version 2.0 or newer might look like
+this::
+
+    from build.wafutils import check_cfg_cached
+
+    check_cfg_cached(conf,
+                     package='foo',
+                     atleast_version='2.0',
+                     uselib_store='FOO',
+                     mandatory=True,
+                     args='--cflags --libs')
+
+
+Build rules
+^^^^^^^^^^^
+
+Add a ``wscript_build`` file inside your plugin's root folder.
+This files defines how the plugin is built, and has to at least call
+``build_plugin()``.  An example could look like this::
+
+    from build.wafutils import build_plugin
+
+    name = 'YourFancyPluginName'
+    sources = ['src/yourfancypluginname.c']
+
+    build_plugin(bld, name, sources=sources)
+
+If you checked for additional dependencies in ``wscript_configure``
+in addition to the standard Geany, GLib or GTK, you might need to make
+use of some results of these checks.  Given the configuration example
+above, you would need to add the ``libraries=['FOO']`` argument to
+the ``build_plugin()`` call::
+
+    build_plugin(bld, name, sources=sources, libraries=['FOO'])
+
+
 Additional things to do for a new plugin
 ----------------------------------------
 



--------------
This E-Mail was brought to you by github_commit_mail.py (Source: https://github.com/geany/infrastructure).
