docs/faq/developing.xml - mtk-gstreamer-debian - Git at Google

 <sect1 id="chapter-developing">
   <title id="title-developing">Developing applications with GStreamer</title>
   <qandaset defaultlabel="qanda">

     <qandaentry>
       <question id="developing-compile-programs">
         <para>How do I compile programs that use GStreamer ?</para>
       </question>

       <answer>
         <para>
 GStreamer uses pkg-config to assist applications with compilation and
 linking flags.
 pkg-config is already used by GTK+, GNOME, SDL, and others; so if you are
 familiar with using it for any of those, you're set.
         </para>
         <para>
 If you're not familiar with pkg-config to compile and link a small
 one-file program, pass the --cflags and --libs arguments to pkg-config.
 For example:
 <programlisting>
 $ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-&GST_API_VERSION;` -o myprog myprog.c
 </programlisting>
 would be sufficient for a gstreamer-only program.
 If (for example) your app also used GTK+ 2.0, you could use
 <programlisting>
 $ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-&GST_API_VERSION; gtk+-2.0` -o myprog myprog.c
 </programlisting>
 Those are back-ticks (on the same key with the tilde on US keyboards),
 not single quotes.
         </para>
         <para>
 For bigger projects, you should integrate pkg-config use in your Makefile,
 or integrate with autoconf using the pkg.m4 macro (providing PKG_CONFIG_CHECK).
         </para>
       </answer>
     </qandaentry>

     <qandaentry>
       <question id="developing-uninstalled-gstreamer">
         <para>How do I develop against an uninstalled GStreamer copy ?</para>
       </question>

       <answer>
         <para>
 It is possible to develop and compile against an uninstalled copy of
 gstreamer and gst-plugins-* (for example, against git checkouts). This
 allows you to develop against and test the latest GStreamer version
 without having to install it and without interfering with your system-wide
 GStreamer setup.
         </para>
         <para>
 The easiest way too create such a setup is the
 <ulink url="http://cgit.freedesktop.org/gstreamer/gstreamer/tree/scripts/create-uninstalled-setup.sh">latest version of create-uninstalled-setup.sh</ulink>
         </para>
         <para>
 This setup makes use of the
 <ulink url="http://cgit.freedesktop.org/gstreamer/gstreamer/tree/scripts/gst-uninstalled">latest version of gst-uninstalled</ulink>.
 Running this script, you'll be in an environment where the uninstalled
 tools and plugins will be used by default.  Also, pkg-config will detect the
 uninstalled copies before (and prefer them to) any installed copies.
         </para>
         <para>
 Multiple uninstalled setups can be used in parallel. Have a look at
 <ulink url="http://cgit.freedesktop.org/gstreamer/gstreamer/tree/scripts/gst-uninstalled">gst-uninstalled</ulink>
 to see how it determines which environment is used.
         </para>
       </answer>
     </qandaentry>

     <qandaentry>
       <question id="developing-gconf">
         <para>How can I use GConf to get the system-wide defaults ?</para>
       </question>

       <answer>
         <para>
 For GNOME applications it's a good idea to use GConf to find the default ways
 of outputting audio and video.  You can do this by using the 'gconfaudiosink'
 and 'gconfvideosink' elements for audio and video output. They will take
 care of everything GConf-related for you and automatically use the outputs
 that the user configured. If you are using gconfaudiosink, your application
 should set the 'profile' property.
         </para>
       </answer>
     </qandaentry>

     <qandaentry>
       <question id="developing-libtool-scripts">
         <para>
 How do I debug these funny shell scripts that libtool makes ?
         </para>
       </question>

       <answer>
         <para>
 When you link a program against uninstalled GStreamer using libtool,
 funny shell scripts are made to modify your shared object search path
 and then run your program. For instance, to debug gst-launch, try
 <programlisting>
 libtool --mode=execute gdb /path/to/gst-launch
 </programlisting>.
 If this does not work, you're probably using a broken version of libtool.
         </para>
       </answer>
     </qandaentry>

     <qandaentry>
       <question id="developing-mail-gstreamer-devel">
         <para>Why is mail traffic so low on gstreamer-devel ?</para>
       </question>

       <answer>
         <para>
 Our main arena for coordination and discussion is IRC, not email.
 Join us in <ulink url="irc://irc.freenode.net/#gstreamer">#gstreamer on irc.freenode.net</ulink>
 For larger picture questions or getting more input from more persons,
 a mail to gstreamer-devel is never a bad idea.
         </para>
       </answer>
     </qandaentry>

     <qandaentry>
       <question id="developing-versioning">
         <para>What kind of versioning scheme does GStreamer use ?</para>
       </question>

       <answer>
         <para>
 For public releases, GStreamer uses a standard MAJOR.MINOR.MICRO version
 scheme.  If the release consists of mostly bug fixes or incremental changes,
 the MICRO version is incremented.
 If the release contains big changes, the MINOR version is incremented.
 If we're particularly giddy, we might even increase the MAJOR number.
 Don't hold your breath for that though.
         </para>
         <para>
 During the development cycle, GStreamer also uses a fourth or NANO number.
 If this number is 1, then it's a git development version.
 Any tarball or package that has a nano number of 1 is made from git and thus
 not supported.  Additionally, if you didn't get this package or tarball from
 the GStreamer team, don't have high hopes on it doing whatever you want it
 to do.
         </para>
         <para>
 If the number is 2 or higher, it's an official pre-release in preparation
 of an actual complete release.  Your help in testing these tarballs and
 packages is very much appreciated.
         </para>
       </answer>
     </qandaentry>

     <qandaentry>
       <question id="developing-coding-style">
         <para>What is the coding style for GStreamer code?</para>
       </question>

       <answer>
         <para>
 The core and almost all plugin modules are basically coded in K&amp;R with
 2-space indenting. Just follow what's already there and you'll be fine.
         </para>
         <para>
 Individual plugins in gst-plugins-* or plugins that you want considered for
 addition to one of the gst-plugins-* modules should be coded in the same style.
 It's easier if everything is consistent. Consistency is, of course, the goal.
         </para>
         <para>
 Simply run your code (only the *.c files, not the header files) through
 <programlisting>
 indent \
   --braces-on-if-line \
   --case-brace-indentation0 \
   --case-indentation2 \
   --braces-after-struct-decl-line \
   --line-length80 \
   --no-tabs \
   --cuddle-else \
   --dont-line-up-parentheses \
   --continuation-indentation4 \
   --honour-newlines \
   --tab-size8 \
   --indent-level2
 </programlisting>
 before submitting a patch. (This is using GNU indent.) There is also a
 gst-indent script in the GStreamer core source tree in the tools directory
 which wraps this and contains the latest option. The easiest way to get the
 indenting right is probably to develop against a git checkout. The local
 git commit hook will ensure correct indentation. We only require code files to
 be indented, header files may be indented manually for better readability
 (however, please use spaces for indenting, not tabs, even in header files).
         </para>
         <para>
 <!-- TODO(ensonic): link is dead, pending question on desktop-devel
 As for the code itself, the
 <ulink url="http://developer.gnome.org/doc/guides/programming-guidelines/book1.html">GNOME
 coding guidelines</ulink> is a good read.
 -->
 Where possible, we try to adhere to the spirit of GObject and use similar
 coding idioms.
         </para>
         <para>
 Patches should be made against git master or the latest release and should be
 in 'unified context' format (use diff -u -p). They should be attached to
 a bug report (or feature request) in
 <ulink url="http://bugzilla.gnome.org">bugzilla</ulink> rather than
 sent to the mailing list.
         </para>
       </answer>
     </qandaentry>
     <qandaentry>
     <question id="developing-translations">
     <para>I have translated one of the module .po files into a new language. How do I get it included?</para>
     </question>
     <answer>
     <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>
     <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>
     </answer>
     </qandaentry>
   </qandaset>
 </sect1>
	<sect1 id="chapter-developing">
	<title id="title-developing">Developing applications with GStreamer</title>
	<qandaset defaultlabel="qanda">

	<qandaentry>
	<question id="developing-compile-programs">
	<para>How do I compile programs that use GStreamer ?</para>
	</question>

	<answer>
	<para>
	GStreamer uses pkg-config to assist applications with compilation and
	linking flags.
	pkg-config is already used by GTK+, GNOME, SDL, and others; so if you are
	familiar with using it for any of those, you're set.
	</para>
	<para>
	If you're not familiar with pkg-config to compile and link a small
	one-file program, pass the --cflags and --libs arguments to pkg-config.
	For example:
	<programlisting>
	$ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-&GST_API_VERSION;` -o myprog myprog.c
	</programlisting>
	would be sufficient for a gstreamer-only program.
	If (for example) your app also used GTK+ 2.0, you could use
	<programlisting>
	$ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-&GST_API_VERSION; gtk+-2.0` -o myprog myprog.c
	</programlisting>
	Those are back-ticks (on the same key with the tilde on US keyboards),
	not single quotes.
	</para>
	<para>
	For bigger projects, you should integrate pkg-config use in your Makefile,
	or integrate with autoconf using the pkg.m4 macro (providing PKG_CONFIG_CHECK).
	</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="developing-uninstalled-gstreamer">
	<para>How do I develop against an uninstalled GStreamer copy ?</para>
	</question>

	<answer>
	<para>
	It is possible to develop and compile against an uninstalled copy of
	gstreamer and gst-plugins-* (for example, against git checkouts). This
	allows you to develop against and test the latest GStreamer version
	without having to install it and without interfering with your system-wide
	GStreamer setup.
	</para>
	<para>
	The easiest way too create such a setup is the
	<ulink url="http://cgit.freedesktop.org/gstreamer/gstreamer/tree/scripts/create-uninstalled-setup.sh">latest version of create-uninstalled-setup.sh</ulink>
	</para>
	<para>
	This setup makes use of the
	<ulink url="http://cgit.freedesktop.org/gstreamer/gstreamer/tree/scripts/gst-uninstalled">latest version of gst-uninstalled</ulink>.
	Running this script, you'll be in an environment where the uninstalled
	tools and plugins will be used by default. Also, pkg-config will detect the
	uninstalled copies before (and prefer them to) any installed copies.
	</para>
	<para>
	Multiple uninstalled setups can be used in parallel. Have a look at
	<ulink url="http://cgit.freedesktop.org/gstreamer/gstreamer/tree/scripts/gst-uninstalled">gst-uninstalled</ulink>
	to see how it determines which environment is used.
	</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="developing-gconf">
	<para>How can I use GConf to get the system-wide defaults ?</para>
	</question>

	<answer>
	<para>
	For GNOME applications it's a good idea to use GConf to find the default ways
	of outputting audio and video. You can do this by using the 'gconfaudiosink'
	and 'gconfvideosink' elements for audio and video output. They will take
	care of everything GConf-related for you and automatically use the outputs
	that the user configured. If you are using gconfaudiosink, your application
	should set the 'profile' property.
	</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="developing-libtool-scripts">
	<para>
	How do I debug these funny shell scripts that libtool makes ?
	</para>
	</question>

	<answer>
	<para>
	When you link a program against uninstalled GStreamer using libtool,
	funny shell scripts are made to modify your shared object search path
	and then run your program. For instance, to debug gst-launch, try
	<programlisting>
	libtool --mode=execute gdb /path/to/gst-launch
	</programlisting>.
	If this does not work, you're probably using a broken version of libtool.
	</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="developing-mail-gstreamer-devel">
	<para>Why is mail traffic so low on gstreamer-devel ?</para>
	</question>

	<answer>
	<para>
	Our main arena for coordination and discussion is IRC, not email.
	Join us in <ulink url="irc://irc.freenode.net/#gstreamer">#gstreamer on irc.freenode.net</ulink>
	For larger picture questions or getting more input from more persons,
	a mail to gstreamer-devel is never a bad idea.
	</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="developing-versioning">
	<para>What kind of versioning scheme does GStreamer use ?</para>
	</question>

	<answer>
	<para>
	For public releases, GStreamer uses a standard MAJOR.MINOR.MICRO version
	scheme. If the release consists of mostly bug fixes or incremental changes,
	the MICRO version is incremented.
	If the release contains big changes, the MINOR version is incremented.
	If we're particularly giddy, we might even increase the MAJOR number.
	Don't hold your breath for that though.
	</para>
	<para>
	During the development cycle, GStreamer also uses a fourth or NANO number.
	If this number is 1, then it's a git development version.
	Any tarball or package that has a nano number of 1 is made from git and thus
	not supported. Additionally, if you didn't get this package or tarball from
	the GStreamer team, don't have high hopes on it doing whatever you want it
	to do.
	</para>
	<para>
	If the number is 2 or higher, it's an official pre-release in preparation
	of an actual complete release. Your help in testing these tarballs and
	packages is very much appreciated.
	</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="developing-coding-style">
	<para>What is the coding style for GStreamer code?</para>
	</question>

	<answer>
	<para>
	The core and almost all plugin modules are basically coded in K&R with
	2-space indenting. Just follow what's already there and you'll be fine.
	</para>
	<para>
	Individual plugins in gst-plugins-* or plugins that you want considered for
	addition to one of the gst-plugins-* modules should be coded in the same style.
	It's easier if everything is consistent. Consistency is, of course, the goal.
	</para>
	<para>
	Simply run your code (only the *.c files, not the header files) through
	<programlisting>
	indent \
	--braces-on-if-line \
	--case-brace-indentation0 \
	--case-indentation2 \
	--braces-after-struct-decl-line \
	--line-length80 \
	--no-tabs \
	--cuddle-else \
	--dont-line-up-parentheses \
	--continuation-indentation4 \
	--honour-newlines \
	--tab-size8 \
	--indent-level2
	</programlisting>
	before submitting a patch. (This is using GNU indent.) There is also a
	gst-indent script in the GStreamer core source tree in the tools directory
	which wraps this and contains the latest option. The easiest way to get the
	indenting right is probably to develop against a git checkout. The local
	git commit hook will ensure correct indentation. We only require code files to
	be indented, header files may be indented manually for better readability
	(however, please use spaces for indenting, not tabs, even in header files).
	</para>
	<para>
	<!-- TODO(ensonic): link is dead, pending question on desktop-devel
	As for the code itself, the
	<ulink url="http://developer.gnome.org/doc/guides/programming-guidelines/book1.html">GNOME
	coding guidelines</ulink> is a good read.
	-->
	Where possible, we try to adhere to the spirit of GObject and use similar
	coding idioms.
	</para>
	<para>
	Patches should be made against git master or the latest release and should be
	in 'unified context' format (use diff -u -p). They should be attached to
	a bug report (or feature request) in
	<ulink url="http://bugzilla.gnome.org">bugzilla</ulink> rather than
	sent to the mailing list.
	</para>
	</answer>
	</qandaentry>
	<qandaentry>
	<question id="developing-translations">
	<para>I have translated one of the module .po files into a new language. How do I get it included?</para>
	</question>
	<answer>
	<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>
	<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>
	</answer>
	</qandaentry>
	</qandaset>
	</sect1>