Moving around plug-ins between source modules --------------------------------------------- Last updated: 2005-11-18 How to get your plug-in out of -bad and into -good or -ugly ----------------------------------------------------------- Since GStreamer 0.9.x, we have four plugin modules: -base, -good, -ugly, and -bad. Plug-ins are by default added to -bad. They can only move to -good or -ugly if a number of conditions are met: - People involved: - There should be a person who is actively going to maintain this element; presumably this is the person writing the plug-in in the first place - There should be a GStreamer hacker who is willing to sponsor the element; this would be someone who is going to help out getting all the conditions met - There should be a core developer who verifies the merge The three roles can be filled by two people, but not just one. - The plug-in's code: - should descend from an applicable base class if possible - make use of GST_BOILERPLATE macros - conform to the GStreamer coding style - use a custom debug category - use GST_(DEBUG/*)_OBJECT - use dashes in object property names to separate words - use correct value, name, nick for enums - The compiled plug-in: - should show up correct in gst-inspect output; no warnings, no unknown types, ... - The plug-in should be put in the correct location inside the module: sys/: plug-ins that include system headers/link to system libraries; usually platform-dependent as well gst/: plug-ins with no external dependencies, only GLib/GStreamer/liboil ext/: plug-ins with external dependencies - The plug-in is documented: - the compiled-in descriptions should be correct - every element in the plug-in should have gtk-doc documentation: - longer description of element - why you would use this element - example launch line OR example source code (for example, see http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/gst-plugins-base-plugins-audiotestsrc.html for the first and http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-level.html for the second) - if the element has custom messages, they should be documented - signals and properties should be documented - The plug-in should come with tests: - preferably, a unit test should be written, testing things like: - setup and teardown - push in buffers in all supported formats and verify they are handled properly - push in buffers that trigger error cases, and verify errors are correctly thrown for example, see gst-plugins-base/check/elements/audioconvert The unit test should be put in check/elements/(nameofelement) and be added to check_PROGRAMS and Makefile.am - if a unit test is not appropriate (for example, device elements), a test application should be written that can be run manually - The tests should be leak-free, tested with valgrind - the unit tests in check/ dirs are valgrinded by default - the manual tests should have a valgrind target - leaks in the supporting library (and verified to be in the supporting library !) can be added to suppressions files - The elements should not segfault under any circumstance. This includes: - wrong pipelines - bad data - The plugins need to be marked correctly for translations. - All error conditions should be correctly handled using GST_ELEMENT_ERROR and following practice outlined in http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstGError.html - Decision should be made if it should go into good (LGPL license, LGPL dependencies, no patent issues) or ugly - plugin documentation needs to be added: - "make update" in docs/plugins and commit the new file - edit -docs.sgml and add an include for the file