docs/faq/developing.xml

   1 <sect1 id="chapter-developing">
   2   <title id="title-developing">Developing applications with GStreamer</title>
   3   <qandaset defaultlabel="qanda">
   4
   5     <qandaentry>
   6       <question id="developing-compile-programs">
   7         <para>How do I compile programs that use GStreamer ?</para>
   8       </question>
   9
  10       <answer>
  11         <para>
  12 GStreamer uses pkg-config to assist applications with compilation and
  13 linking flags.
  14 pkg-config is already used by GTK+, GNOME, SDL, and others; so if you are
  15 familiar with using it for any of those, you're set.
  16         </para>
  17         <para>
  18 If you're not familiar with pkg-config to compile and link a small
  19 one-file program, pass the --cflags and --libs arguments to pkg-config.
  20 For example:
  21 <programlisting>
  22 $ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-&GST_MAJORMINOR;` -o myprog myprog.c
  23 </programlisting>
  24 would be sufficient for a gstreamer-only program.
  25 If (for example) your app also used GTK+ 2.0, you could use
  26 <programlisting>
  27 $ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-&GST_MAJORMINOR; gtk+-2.0` -o myprog myprog.c
  28 </programlisting>
  29 Those are back-ticks (on the same key with the tilde on US keyboards),
  30 not single quotes.
  31         </para>
  32         <para>
  33 For bigger projects, you should integrate pkg-config use in your Makefile,
  34 or integrate with autoconf using the pkg.m4 macro (providing PKG_CONFIG_CHECK).
  35         </para>
  36       </answer>
  37     </qandaentry>
  38
  39     <qandaentry>
  40       <question id="developing-uninstalled-gstreamer">
  41         <para>How do I develop against an uninstalled GStreamer copy ?</para>
  42       </question>
  43
  44       <answer>
  45         <para>
  46 It is possible to develop and compile against an uninstalled copy of
  47 gstreamer and gst-plugins-* (for example, against gits checkouts).
  48 The easiest way to do this is to use a bash script like this (also:
  49 <ulink url="http://cgit.freedesktop.org/gstreamer/gstreamer/tree/docs/faq/gst-uninstalled">lastest version of gst-uninstalled</ulink>):
  50
  51 <programlisting>
  52 &gst-uninstalled;
  53 </programlisting>
  54 If you put this script in your path, and symlink it to gst-git (if you want
  55 to develop against git master) or to gst-released (if you want to develop
  56 against the lastest release of each module), it will automatically use the
  57 uninstalled version from that directory (ie. gst-git will look for a directory
  58 called 'git', and gst-released will expect the uninstalled modules to be in
  59 the 'released' directory; you are free to use any name or identifier you like
  60 here).
  61         </para>
  62         <para>
  63 This requires you to have put your checkouts of gstreamer and gst-plugins
  64 under ~/gst/git (for the master version).  The program is easily modifiable
  65 if this isn't the case.
  66         </para>
  67         <para>
  68 After running this script, you'll be in an environment where the uninstalled
  69 tools and plugins will be used by default.  Also, pkg-config will detect the
  70 uninstalled copies before (and prefer them to) any installed copies.
  71         </para>
  72       </answer>
  73     </qandaentry>
  74
  75     <qandaentry>
  76       <question id="developing-gconf">
  77         <para>How can I use GConf to get the system-wide defaults ?</para>
  78       </question>
  79
  80       <answer>
  81         <para>
  82 For GNOME applications it's a good idea to use GConf to find the default ways
  83 of outputting audio and video.  You can do this by using the 'gconfaudiosink'
  84 and 'gconfvideosink' elements for audio and video output. They will take
  85 care of everything GConf-related for you and automatically use the outputs
  86 that the user configured. If you are using gconfaudiosink, your application
  87 should set the 'profile' property.
  88         </para>
  89       </answer>
  90     </qandaentry>
  91
  92     <qandaentry>
  93       <question id="developing-libtool-scripts">
  94         <para>
  95 How do I debug these funny shell scripts that libtool makes ?
  96         </para>
  97       </question>
  98
  99       <answer>
 100         <para>
 101 When you link a program against uninstalled GStreamer using libtool,
 102 funny shell scripts are made to modify your shared object search path
 103 and then run your program. For instance, to debug gst-launch, try
 104 <programlisting>
 105 libtool --mode=execute gdb /path/to/gst-launch
 106 </programlisting>.
 107 If this does not work, you're probably using a broken version of libtool.
 108         </para>
 109       </answer>
 110     </qandaentry>
 111
 112     <qandaentry>
 113       <question id="developing-mail-gstreamer-devel">
 114         <para>Why is mail traffic so low on gstreamer-devel ?</para>
 115       </question>
 116
 117       <answer>
 118         <para>
 119 Our main arena for coordination and discussion is IRC, not email.
 120 Join us in <ulink url="irc://irc.freenode.net/#gstreamer">#gstreamer on irc.freenode.net</ulink>
 121 For larger picture questions or getting more input from more persons,
 122 a mail to gstreamer-devel is never a bad idea.
 123         </para>
 124       </answer>
 125     </qandaentry>
 126
 127     <qandaentry>
 128       <question id="developing-versioning">
 129         <para>What kind of versioning scheme does GStreamer use ?</para>
 130       </question>
 131
 132       <answer>
 133         <para>
 134 For public releases, GStreamer uses a standard MAJOR.MINOR.MICRO version
 135 scheme.  If the release consists of mostly bug fixes or incremental changes,
 136 the MICRO version is incremented.
 137 If the release contains big changes, the MINOR version is incremented.
 138 If we're particularly giddy, we might even increase the MAJOR number.
 139 Don't hold your breath for that though.
 140         </para>
 141         <para>
 142 During the development cycle, GStreamer also uses a fourth or NANO number.
 143 If this number is 1, then it's a git development version.
 144 Any tarball or package that has a nano number of 1 is made from git and thus
 145 not supported.  Additionally, if you didn't get this package or tarball from
 146 the GStreamer team, don't have high hopes on it doing whatever you want it
 147 to do.
 148         </para>
 149         <para>
 150 If the number is 2 or higher, it's an official pre-release in preparation
 151 of an actual complete release.  Your help in testing these tarballs and
 152 packages is very much appreciated.
 153         </para>
 154       </answer>
 155     </qandaentry>
 156
 157     <qandaentry>
 158       <question id="developing-coding-style">
 159         <para>What is the coding style for GStreamer code?</para>
 160       </question>
 161
 162       <answer>
 163         <para>
 164 The core and almost all plugin modules are basically coded in K&amp;R with
 165 2-space indenting. Just follow what's already there and you'll be fine.
 166         </para>
 167         <para>
 168 Individual plugins in gst-plugins-* or plugins that you want considered for
 169 addition to one of the gst-plugins-* modules should be coded in the same style.
 170 It's easier if everything is consistent. Consistency is, of course, the goal.
 171         </para>
 172         <para>
 173 Simply run your code (only the *.c files, not the header files) through
 174 <programlisting>
 175 indent \
 176   --braces-on-if-line \
 177   --case-brace-indentation0 \
 178   --case-indentation2 \
 179   --braces-after-struct-decl-line \
 180   --line-length80 \
 181   --no-tabs \
 182   --cuddle-else \
 183   --dont-line-up-parentheses \
 184   --continuation-indentation4 \
 185   --honour-newlines \
 186   --tab-size8 \
 187   --indent-level2
 188 </programlisting>
 189 before submitting a patch. (This is using GNU indent.) There is also a
 190 gst-indent script in the GStreamer core source tree in the tools directory
 191 which wraps this and contains the latest option. The easiest way to get the
 192 indenting right is probably to develop against a git checkout. The local
 193 git commit hook will ensure correct indentation. We only require code files to
 194 be indented, header files may be indented manually for better readability
 195 (however, please use spaces for indenting, not tabs, even in header files).
 196         </para>
 197         <para>
 198 As for the code itself, the
 199 <ulink url="http://developer.gnome.org/doc/guides/programming-guidelines/book1.html">GNOME coding guidelines</ulink> is a good read.
 200 Where possible, we try to adhere to the spirit of GObject and use similar
 201 coding idioms.
 202         </para>
 203         <para>
 204 Patches should be made against git master or the latest release and should be
 205 in 'unified context' format (use diff -u -p). They should be attached to
 206 a bug report (or feature request) in
 207 <ulink url="http://bugzilla.gnome.org">bugzilla</ulink> rather than
 208 sent to the mailing list. Also see
 209 <ulink url="http://gstreamer.freedesktop.org/wiki/SubmittingPatches">SubmittingPatches</ulink>
 210 in the GStreamer wiki.
 211         </para>
 212       </answer>
 213     </qandaentry>
 214     <qandaentry>
 215     <question id="developing-translations">
 216     <para>I have translated one of the module .po files into a new language. How do I get it included?</para>
 217     </question>
 218     <answer>
 219     <para>GStreamer translations are uniformly managed through the Translation Project (http://translationproject.org). There are some instructions on how to join the Translation Project team and submit new translations at http://translationproject.org/html/translators.html.</para>
 220     <para>New translations submitted via the Translation Project are merged periodically into git by the maintainers by running 'make download-po' in the various modules.</para>
 221     </answer>
 222     </qandaentry>
 223   </qandaset>
 224 </sect1>