gstreamer/docs/random/moving-plugins
Thomas Vander Stichele 505dced8dc releasing 0.9.6
Original commit message from CVS:
releasing 0.9.6
2005-11-23 19:55:09 +00:00

92 lines
3.9 KiB
Text

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