docs/random/moving-plugins

   1 Moving around plug-ins between source modules
   2 ---------------------------------------------
   3
   4 Last updated: 2005-11-18
   5
   6 How to get your plug-in out of -bad and into -good or -ugly
   7 -----------------------------------------------------------
   8
   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:
  12
  13 - People involved:
  14   - There should be a person who is actively going to maintain this element;
  15     presumably this is the person writing the plug-in in the first place
  16   - There should be a GStreamer hacker who is willing to sponsor the element;
  17     this would be someone who is going to help out getting all the conditions
  18     met
  19   - There should be a core developer who verifies the merge
  20
  21   The three roles can be filled by two people, but not just one.
  22
  23 - The plug-in's code:
  24   - should descend from an applicable base class if possible
  25   - make use of GST_BOILERPLATE macros
  26   - conform to the GStreamer coding style
  27   - use a custom debug category
  28   - use GST_(DEBUG/*)_OBJECT
  29   - use dashes in object property names to separate words
  30   - use correct value, name, nick for enums
  31
  32 - The compiled plug-in:
  33   - should show up correct in gst-inspect output; no warnings, no unknown
  34     types, ...
  35
  36 - The plug-in should be put in the correct location inside the module:
  37   sys/: plug-ins that include system headers/link to system libraries;
  38     usually platform-dependent as well
  39   gst/: plug-ins with no external dependencies, only GLib/GStreamer/liboil
  40   ext/: plug-ins with external dependencies
  41
  42 - The plug-in is documented:
  43   - the compiled-in descriptions should be correct
  44   - every element in the plug-in should have gtk-doc documentation:
  45     - longer description of element
  46     - why you would use this element
  47     - example launch line OR example source code
  48       (for example, see
  49        http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/gst-plugins-base-plugins-audiotestsrc.html
  50        for the first and
  51        http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-level.html
  52        for the second)
  53     - if the element has custom messages, they should be documented
  54     - signals and properties should be documented
  55
  56 - The plug-in should come with tests:
  57   - preferably, a unit test should be written, testing things like:
  58     - setup and teardown
  59     - push in buffers in all supported formats and verify they are handled
  60       properly
  61     - push in buffers that trigger error cases, and verify errors are
  62       correctly thrown
  63
  64     for example, see gst-plugins-base/check/elements/audioconvert
  65
  66     The unit test should be put in check/elements/(nameofelement)
  67     and be added to check_PROGRAMS and Makefile.am
  68
  69   - if a unit test is not appropriate (for example, device elements),
  70     a test application should be written that can be run manually
  71
  72 - The tests should be leak-free, tested with valgrind
  73   - the unit tests in check/ dirs are valgrinded by default
  74   - the manual tests should have a valgrind target
  75   - leaks in the supporting library (and verified to be in the supporting
  76     library !) can be added to suppressions files
  77
  78 - The elements should not segfault under any circumstance.  This includes:
  79   - wrong pipelines
  80   - bad data
  81
  82 - The plugins need to be marked correctly for translations.
  83 - All error conditions should be correctly handled using GST_ELEMENT_ERROR
  84   and following practice outlined in
  85   http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstGError.html
  86
  87 - Decision should be made if it should go into good (LGPL license,
  88   LGPL dependencies, no patent issues) or ugly