Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 390 lines (288 sloc) 13.462 kB
8b2f4c6 @b4n Add a HACKING with a few information for plugin developers
b4n authored
1 ========================
2 Hacking on Geany-Plugins
3 ========================
4 .. contents::
5
6 General
7 =======
8
9 About this file
10 ---------------
11 This file contains some useful information for any plugin developer, and
4335e4d @frlan Some further smaller changes on HACKING and fix indention of l10n-bul…
frlan authored
12 especially for new plugin developers. A lot of information inside
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
13 `Geany's HACKING file <http://geany.org/manual/hacking.html>` is useful
14 as well, so it's recommended you give it a read.
8b2f4c6 @b4n Add a HACKING with a few information for plugin developers
b4n authored
15
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
16
8b2f4c6 @b4n Add a HACKING with a few information for plugin developers
b4n authored
17 Building your plugin
18 --------------------
19 You should first read either `README` or `README.waf` depending on whether
20 you want to use Autotools or Waf to build the plugins.
21
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
22
8b2f4c6 @b4n Add a HACKING with a few information for plugin developers
b4n authored
23 Autotools Build System
24 ^^^^^^^^^^^^^^^^^^^^^^
25 The Autotools build system automatically enables some code checking
26 utilities, meant to ease tracking of common programming mistakes, or simply
27 to help making everyone's plugin code better.
28 They currently are:
29
30 * C compiler warnings (can be disabled with the ``--disable-extra-c-warnings``
31 configuration flag) -- this test is (obviouly) run during build;
32 * Static code analysis using ``cppcheck`` (can be disabled with the
33 ``--disable-cppcheck`` configuration flag) -- this test is run during
34 ``make check``.
35
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
36 These features are only here to help you writing better code: they
37 are not necessarily and always right -- though they try. However
38 it's highly recommended to make usage of them and fix maybe occuring
39 issues before submitting a patch. If you think they reports wrong
40 problems, please file a report on the appropriate place (either the
41 mailing lists or the geany-plugins bug tracker).
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
42
43
44 Documentation
45 -------------
46
47 README
48 ^^^^^^
4335e4d @frlan Some further smaller changes on HACKING and fix indention of l10n-bul…
frlan authored
49
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
50 Each plugin folder should contain at least a `README` file for
51 documentation.
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
52
53
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
54 Markup language
55 ###############
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
56
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
57 The `README` is intended to be written in `Restructured Text
58 <http://sphinx.pocoo.org/rest.html>`_ (as this document is) and
59 therefore should work with ``rst2html`` or similar tools. The reason
60 for this is that this information is used to generate the content of
4335e4d @frlan Some further smaller changes on HACKING and fix indention of l10n-bul…
frlan authored
61 the `Plugins Website <http://plugins.geany.org>`.
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
62
63
64 Recommended contents
65 ####################
66
67 The documentation should include a detailed description on features
68 offered by the plugins and usage of those features. It should also
69 include some basic information to make it easier for users to get in
70 touch with the developer(s) or to find further help in case of any
71 issues. You can use some of the other `README` files to get a
72 general idea of what should be in the file, but generally it should
73 contain:
74
75 * author(s) of plugin and their mail addresses
76 * external web site (if any)
77 * known issues
78 * bug tracker
79 * dependencies
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
80
81
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
82 Committing
83 ----------
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
84
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
85 General
86 ^^^^^^^
87
88 * Commit one thing at a time, do small commits. Commits should be
89 meaningful and not too big when possible; multiple small commits are
90 good if there is no good reason to group them.
91 * Use meaningful name and email in the Author and Committer fields.
92 This helps knowing who did what and allows to contact the author if
93 there is a good reason to do so (unlikely, but can happen). Using
94 the email address associated with your GitHub account will allows
95 for better integration with the website's hyperlinking to accounts
96 features.
97 * When working on a new feature, create a new branch for it. When
98 merging it, use the --no-ff option to make sure a merge commit will
99 be created to better track what happened. However, if the feature
100 only took one commit you might merge it fast-forward since there is
101 not history to keep together.
102
8eb9827 @frlan Hacking: Added a few comments.
frlan authored
103 Writing
104 ^^^^^^^
105 * Please use "Geany" as it is not just a noun, but a name.
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
106
107 Commit messages
108 ^^^^^^^^^^^^^^^
b12c8aa @frlan Adding a short note about l10n/I18n into HACKING
frlan authored
109
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
110 Follow the standard Git formatting:
111
112 * No line should use more than about 80 characters (around 72 is best).
113 * The first line is the commit's summary and is followed by an empty
114 line. This summary should be one line and one line only, thus less
115 than 80 characters. This summary should not include any punctuation
116 unless really needed. See it as the subject of an email: keep it
117 concise and as precise as you can, but not tool long.
118 * If you're working on a specific plugin, prefix the summary line
119 with the lower case name of the plugin (same as the directory name)
120 to make it easier to know which commit affected which plugin without
121 having to thoroughly examine the commit diff itself. No prefix is
122 needed if the commit is non-plugin specific or affects only files
123 outside of the plugins' directories.
124 * Following lines are optional detailed commit information, with
125 paragraphs separated by blank lines. This part should be as long as
126 needed to describe the commit in depth, should use proper
127 punctuation and should include any useful information, like the
128 motivation for the patch and/or any valuable details the diff itself
129 doesn't provide or make clear. Make it as complete as you think
130 it makes sense, but don't include an information that is better
131 explained by the commit's diff.
132
133 It is OK to use ASCII formatting like bullet list using "*" or "-",
134 etc. if useful, but emphasis (bold, italic, underline) should be
135 avoided.
136
137 Example::
138
6031d0b @b4n Fix redundancy and typos in HACKING
b4n authored
139 myfancyplugin: Ask the user if spawn fails in utils_open_browser()
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
140
141 Ask the user to configure a valid browser command if spawning it
142 fails rather than falling back to some arbitrary hardcoded defaults.
143
6031d0b @b4n Fix redundancy and typos in HACKING
b4n authored
144 This avoids spawning an unexpected browser when the configured one
145 is wrong, and gives the user a chance to fix the preference.
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
146
3ea5639 @frlan HACKING: Added info about MAINTAINERS and po/POTFILES.in
frlan authored
147
b12c8aa @frlan Adding a short note about l10n/I18n into HACKING
frlan authored
148 Coding and Plugin structure
149 ===========================
150
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
151 Structure of a plugin
152 ---------------------
153
154 Your plugin shall be structured like this:
155
156 - yourplugin
157 - src/
158 - data/
159 - doc/
160
161 Where you put all your source code inside the src-folder, all
162 additional data like scripts should be put into a seperate
163 data-folder and content for plugin documentation fit into the folder
164 doc.
165
166 Adding a new plugin to autotools build system
167 ---------------------------------------------
168
169 configure.ac
170 ^^^^^^^^^^^^
171
172 Add an entry into configure.ac for your plugin. The entry should look like
5a4bf67 @b4n Extend a bit the docs on how to add a plugin the the build system
b4n authored
173 ``GP_CHECK_YOURFANCYPLUGINNAME``. This is a custom macro that will be
174 discussed in the `build sub-folder`_ section below.
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
175
5a4bf67 @b4n Extend a bit the docs on how to add a plugin the the build system
b4n authored
176 Root Makefile.am
177 ^^^^^^^^^^^^^^^^
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
178
5a4bf67 @b4n Extend a bit the docs on how to add a plugin the the build system
b4n authored
179 Add an entry into the root Makefile.am where to find the sources of your
180 plugin. This entry shall look like this::
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
181
182 if ENABLE_YOURFANCYPLUGINNAME
183 SUBDIRS += yourfancyplugin
184 endif
185
186
5a4bf67 @b4n Extend a bit the docs on how to add a plugin the the build system
b4n authored
187 `build` sub-folder
188 ^^^^^^^^^^^^^^^^^^
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
189
5a4bf67 @b4n Extend a bit the docs on how to add a plugin the the build system
b4n authored
190 To build your plugin you will also need to add an M4 script inside
191 the ``build`` sub-folder of the geany-plugin sources. The file should
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
192 be called ``yourfancypluginname.m4`` and contain the definition of the M4
193 macro that checks for your plugin's dependencies and generates its
194 build files, which macro is called from configure.ac::
195
196 AC_DEFUN([GP_CHECK_YOURFANCYPLUGINNAME],
197 [
3432c92 @frlan Improve GP_ARG_DISABLE() default to auto inside HACKING
frlan authored
198 GP_ARG_DISABLE([yourfancypluginname], [auto])
0d11ade @b4n Fix and extend HACKING docs on writing build/someplugin.m4
b4n authored
199 GP_COMMIT_PLUGIN_STATUS([yourfancypluginname])
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
200 AC_CONFIG_FILES([
201 yourplugin/Makefile
202 yourplugin/src/Makefile
203 ])
204 ])
205
0d11ade @b4n Fix and extend HACKING docs on writing build/someplugin.m4
b4n authored
206 You may add checks for dependencies of your plugin between the
207 ``GP_ARG_DISABLE`` and ``GP_COMMIT_PLUGIN_STATUS`` calls. Note that you
208 must respect the ``$enable_yourfancypluginname`` (lowercase) variable
209 and try to avoid performing checks if it is set to ``no``, and never
210 abort unless it is set to ``yes``. If a required dependency is not met
211 and ``$enable_yourfancypluginname`` is not set to ``yes``, you should
212 update ``enable_yourfancypluginname`` and set it to ``no`` to disable
213 building of your plugin.
214
215 To ease checking for modules using *pkg-config*, the
216 ``GP_CHECK_PLUGIN_DEPS`` macro is provided, which wraps
217 ``PKG_CHECK_MODULES`` and follows the above rules about plugin
218 enabling/disabling.
219
220 While we recommend plugins to work with both GTK 2 and 3, you can use
221 the ``GP_CHECK_PLUGIN_GTK2_ONLY`` or ``GP_CHECK_PLUGIN_GTK3_ONLY``
222 macros if your plugin only works with one version.
223
224 You may also check which GTK version is used for the build using either
225 the ``$GP_GTK_VERSION`` or ``$GP_GTK_PACKAGE`` variables, or the
226 ``GP_CHECK_GTK3`` macro. For example, if your plugin works with both
227 GTK 2 and 3 but you want to check for a minimal GTK2 version, you may
228 use ``$GP_GTK_PACKAGE >= 2.XX`` in a ``GP_CHECK_PLUGIN_DEPS`` call.
229
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
230
5a4bf67 @b4n Extend a bit the docs on how to add a plugin the the build system
b4n authored
231 Makefiles inside your plugin folder
232 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
233
5a4bf67 @b4n Extend a bit the docs on how to add a plugin the the build system
b4n authored
234 The Makefiles inside your plugin folder can be separated at least
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
235 into two parts: The first part is located inside the root folder of
5a4bf67 @b4n Extend a bit the docs on how to add a plugin the the build system
b4n authored
236 your plugin, whereas the second one is located inside ``src/`` of your
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
237 plugin.
238
239
5a4bf67 @b4n Extend a bit the docs on how to add a plugin the the build system
b4n authored
240 Plugin root
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
241 ###########
242
243 The file should be called ``Makefile.am`` and contains the entry
244 point for really building your plugin. The easiest version could look
245 similar to this::
246
247 include $(top_srcdir)/build/vars.auxfiles.mk
248 SUBDIRS = src
249 plugin = yourfancypluginname
250
251
5a4bf67 @b4n Extend a bit the docs on how to add a plugin the the build system
b4n authored
252 `src` folder
253 ############
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
254
5a4bf67 @b4n Extend a bit the docs on how to add a plugin the the build system
b4n authored
255 The ``Makefile.am`` inside the ``src`` folder declares how to build the
256 sources. An example could look like::
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
257
258 include $(top_srcdir)/build/vars.build.mk
259
260 yourfancypluginname_LTLIBRARIES = yourfancypluginname.la
261
262 yourfancypluginname_la_SOURCES = yourfancypluginname.c
263 yourfancypluginname_la_LIBADD = $(COMMONLIBS)
264
265 include $(top_srcdir)/build/cppcheck.mk
266
5a4bf67 @b4n Extend a bit the docs on how to add a plugin the the build system
b4n authored
267 If you checked for additional dependencies in ``yourfancypluginname.m4``
268 (besides Geany, GLib and GTK, which are included in ``$(COMMONLIBS)``),
269 you will need to use the various flags they might require.
270
271 For a library checked with ``GP_CHECK_PLUGIN_DEPS`` you will have to add
272 ``$(PREFIX_CFLAGS)`` to ``yourfancypluginname_la_CFLAGS`` and
273 ``$(PREFIX_LIBS)`` to ``yourfancypluginname_la_LIBADD`` (where
274 ``PREFIX`` is the name you chose to store the results in the
275 ``GP_CHECK_PLUGIN_DEPS`` call). Note that if you set
276 ``yourfancypluginname_la_CFLAGS`` you will need to explicitly mention
277 ``$(AM_CFLAGS)`` in it.
278
279 For example, if you checked for the hypothetical library ``foo`` and
280 used the ``FOO`` prefix to store the results, you should alter the
281 Makefile.am to references them::
282
283 yourfancypluginname_la_CFLAGS = $(AM_CFLAGS) $(FOO_CFLAGS)
284 yourfancypluginname_la_LIBADD = $(COMMONLIBS) $(FOO_LIBS)
285
286
07a32b8 @b4n Add docs on how to add a plugin to the Waf build system
b4n authored
287 Adding a new plugin to Waf build system
288 ---------------------------------------
289
290 Configuration checks
291 ^^^^^^^^^^^^^^^^^^^^
292
293 Add a ``wscript_configure`` file in your plugin's root folder.
294 This file contains checks for dependencies, like libraries your plugin
295 requires. If your plugin does not have any additional dependencies
296 besides Geany, GLib and GTK, you can leave this file empty (but you need
297 to create it nonetheless).
298
299 Generally checks are performed with ``check_cfg_cached``. An example
300 to check for library ``foo`` at version 2.0 or newer might look like
301 this::
302
303 from build.wafutils import check_cfg_cached
304
305 check_cfg_cached(conf,
306 package='foo',
307 atleast_version='2.0',
308 uselib_store='FOO',
309 mandatory=True,
310 args='--cflags --libs')
311
312
313 Build rules
314 ^^^^^^^^^^^
315
316 Add a ``wscript_build`` file inside your plugin's root folder.
317 This files defines how the plugin is built, and has to at least call
318 ``build_plugin()``. An example could look like this::
319
320 from build.wafutils import build_plugin
321
322 name = 'YourFancyPluginName'
323 sources = ['src/yourfancypluginname.c']
324
325 build_plugin(bld, name, sources=sources)
326
327 If you checked for additional dependencies in ``wscript_configure``
328 in addition to the standard Geany, GLib or GTK, you might need to make
329 use of some results of these checks. Given the configuration example
330 above, you would need to add the ``libraries=['FOO']`` argument to
331 the ``build_plugin()`` call::
332
333 build_plugin(bld, name, sources=sources, libraries=['FOO'])
334
335
3ea5639 @frlan HACKING: Added info about MAINTAINERS and po/POTFILES.in
frlan authored
336 Additional things to do for a new plugin
337 ----------------------------------------
338
339 Adding yourself to MAINTAINERS
340 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
341
8eb9827 @frlan Hacking: Added a few comments.
frlan authored
342 As you might want to keep on maintaining your newly added plugin, we
343 recommend to put your contact data to file MAINTAINERS which is
344 located inside geany-plugins root folder. The entry should contain
345 your plugin name as well as some of the important data. An example
3ea5639 @frlan HACKING: Added info about MAINTAINERS and po/POTFILES.in
frlan authored
346 could look like::
347
348 myfancyplugin
349 P: Jon Doe <jon@example.org>
350 M: Jon Doe <jon@example.org>
8eb9827 @frlan Hacking: Added a few comments.
frlan authored
351 W: http://example.org/myfancyplugin
3ea5639 @frlan HACKING: Added info about MAINTAINERS and po/POTFILES.in
frlan authored
352 S: Maintained
353
8eb9827 @frlan Hacking: Added a few comments.
frlan authored
354 The flags can be compiled like this:
3ea5639 @frlan HACKING: Added info about MAINTAINERS and po/POTFILES.in
frlan authored
355
356 * P: Person
357 * M: Mail patches to: FullName <address@domain>
358 * W: Web-page with status/info
359 * S: Status of plugin
360
8eb9827 @frlan Hacking: Added a few comments.
frlan authored
361 Once you have a look onto MAINTAINERS you will see a lot of examples
3ea5639 @frlan HACKING: Added info about MAINTAINERS and po/POTFILES.in
frlan authored
362 as well as some more detailed information.
363
364
365 Adding your plugin-files to po/POTFILES.in
366 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
367
8eb9827 @frlan Hacking: Added a few comments.
frlan authored
368 If you want to have your plugin translated into different languages
369 you will have to add your plugin to file po/POTFILES.in. This
370 contains a list of all translateable files for each plugin. An
3ea5639 @frlan HACKING: Added info about MAINTAINERS and po/POTFILES.in
frlan authored
371 example could look like::
8eb9827 @frlan Hacking: Added a few comments.
frlan authored
372
3ea5639 @frlan HACKING: Added info about MAINTAINERS and po/POTFILES.in
frlan authored
373 #myfancyplugin
374 yourfancypluginname/src/yourfancypluginname.c
8eb9827 @frlan Hacking: Added a few comments.
frlan authored
375
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
376
b12c8aa @frlan Adding a short note about l10n/I18n into HACKING
frlan authored
377 I18n/l10n
378 ---------
379
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
380 Geany-Plugins is supporting localisation of your plugin. To make
b12c8aa @frlan Adding a short note about l10n/I18n into HACKING
frlan authored
381 usage of it, there needs to be done:
382
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
383 * Mark each string which should be translatable with the gettext macro
384 ``_()`` or ``N_()`` for static strings. As an example the string
4335e4d @frlan Some further smaller changes on HACKING and fix indention of l10n-bul…
frlan authored
385 ``"Hello World"`` might become ``_("Hello World")``.
a2db1cc @frlan Extending HACKING-file with some information about e.g. build system …
frlan authored
386 * Add files with translateable strings into ``po/POTFILES.in``. You
387 should group them for your plugin as done for the other. Each files
388 needs to be put into one line with complete relative path from
4335e4d @frlan Some further smaller changes on HACKING and fix indention of l10n-bul…
frlan authored
389 plugin root directory. E.g. ``myplugin/src/myplugin.c``
Something went wrong with that request. Please try again.