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

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).