1 Moving around plug-ins between source modules
2 ---------------------------------------------
4 Last updated: 2006-09-01
6 How to get your plug-in out of -bad and into -good or -ugly
7 -----------------------------------------------------------
9 Since GStreamer 0.9.x, we have four plugin modules: -base, -good, -ugly,
10 and -bad. Plug-ins are by default added to -bad. They can only move
11 to -good or -ugly if a number of conditions are met:
16 - There should be a person who is actively going to maintain this element;
17 presumably this is the person writing the plug-in in the first place
18 and opening the move request
19 - There should be a GStreamer hacker who is willing to sponsor the element;
20 this would be someone who is going to help out getting all the conditions
21 met, act as a mentor if necessary,...
22 - There should be a core developer who verifies that the checklist is
25 The three roles can be filled by two people, but not just one.
27 In addition, an admin needs to perform the actual move, which involves
32 - bug in bugzilla gets filed by someone requesting a move from bad
34 This is "requesting" the move.
35 - a second person reviews the request and code, and verifies that the
36 plugin meets the checklist items below, by commenting on the bug
37 and giving a rundown of what still needs to be done
38 This is "sponsoring" the move.
39 - when the checklist is met, a third person can approve the move.
40 This is "approving" the move.
41 - an admin performs the move.
42 This is "performing" the move. (Are you laughing yet ?)
47 - should descend from an applicable base class if possible
48 - make use of GST_BOILERPLATE macros
49 - conform to the GStreamer coding style
50 - use a custom debug category
51 - use GST_(DEBUG/*)_OBJECT
52 - use dashes in object property names to separate words
53 - use correct value, name, nick for enums
54 - use underscores in macros/function names/structs
55 e.g.: GST_BASE_SINK, GstBaseSink, gst_base_sink_
56 - use g_assert(), g_return_if_fail(), g_return_val_if_fail() for pre/post
59 - The plug-in's build:
60 - should be correctly integrated with configure.ac
61 - files implementing elements should be named according to their class name,
62 e.g GstBaseSink -> gstbasesink.c
63 - should list libs and cflags in stack order, with lowest in the stack first
64 (so one can link against highest in the stack somewhere else without
65 picking up everything from the somewhere else)
66 e.g. $(GST_PLUGINS_BASE_CFLAGS) \
68 $(GST_CFLAGS) $(CAIRO_CFLAGS)
70 - The compiled plug-in:
71 - should show up correct in gst-inspect output; no warnings, no unknown
74 - The plug-in should be put in the correct location inside the module:
75 sys/: plug-ins that include system headers/link to system libraries;
76 usually platform-dependent as well
77 name after whatever system "thing" they use (oss, v4l, ...)
78 gst/: plug-ins with no external dependencies, only GLib/GStreamer/liboil
79 ext/: plug-ins with external dependencies
81 - The plug-in is documented:
82 - the compiled-in descriptions (element details) should be correct
83 - every element in the plug-in should have gtk-doc documentation:
84 - longer description of element
85 - why you would use this element
86 - example launch line OR example source code
88 http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/gst-plugins-base-plugins-audiotestsrc.html
90 http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-level.html
92 - if the element has custom messages, they should be documented
93 - signals and properties should be documented
95 - The plug-in should come with tests:
96 - preferably, a unit test should be written, testing things like:
98 - push in buffers in all supported formats and verify they are handled
100 - push in buffers that trigger error cases, and verify errors are
103 for example, see gst-plugins-base/check/elements/audioconvert
105 The unit test should be put in check/elements/(nameofelement)
106 and be added to check_PROGRAMS and Makefile.am
108 - if a unit test is not appropriate (for example, device elements),
109 a test application should be written that can be run manually
111 - The tests should be leak-free, tested with valgrind
112 - the unit tests in check/ dirs are valgrinded by default
113 - the manual tests should have a valgrind target
114 - leaks in the supporting library (and verified to be in the supporting
115 library !) can be added to suppression files
117 - The elements should not segfault under any circumstance. This includes:
121 - The plugins need to be marked correctly for translations.
122 - All error conditions should be correctly handled using GST_ELEMENT_ERROR
123 and following practice outlined in
124 http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstGError.html
126 - message strings need to be marked for translation
127 - should be short, well-written, clear
128 - in particular, should *not* contain debug info, strerror, errno, ...
129 No, really ! NO STRERROR, NO ERRNO. If you are too lazy to provide
130 the user of your library with a nice experience, put your crap in
133 - Decision should be made if it should go into good (LGPL license,
134 LGPL dependencies, no patent issues) or ugly
136 - plugin documentation needs to be added:
137 - see gstreamer/docs/README; section on adding plugins and elements
138 - "make update" in docs/plugins and commit the new file
139 - edit -docs.sgml and add an include for the file