FAQ: update for git and miscellaneous small fixes and additions

Replace all mentions of CVS with git. Add link to gst-uninstalled script in cgit and to SubmittingPatches page in wiki. Fix some typos. Update indenting rules to what we actually use (#571646).
This commit is contained in:
Tim-Philipp Müller 2009-02-14 13:35:48 +00:00
parent 66a47b2103
commit 1c716ae407
8 changed files with 89 additions and 56 deletions

View file

@ -9,7 +9,7 @@
<answer>
<para>
GStreamer uses pkg-config to assist applications with compilationa and
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.
@ -31,7 +31,7 @@ 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.
or integrate with autoconf using the pkg.m4 macro (providing PKG_CONFIG_CHECK).
</para>
</answer>
</qandaentry>
@ -44,27 +44,30 @@ or integrate with autoconf using the pkg.m4 macro.
<answer>
<para>
It is possible to develop and compile against an uninstalled copy of
gstreamer and gst-plugins (for example, against CVS copies).
The easiest way to do this is to use a script like this (for bash):
gstreamer and gst-plugins-* (for example, against gits checkouts).
The easiest way to do this is to use a bash script like this (also:
<ulink url="http://cgit.freedesktop.org/gstreamer/gstreamer/tree/docs/faq/gst-uninstalled">lastest version of gst-uninstalled</ulink>):
<programlisting>
&gst-uninstalled;
</programlisting>
If you put this script in your path, and symlink it to gst-cvs (if you want
to develop against cvs HEAD) or to gst-0.8 (if you want to develop against the
0.8 branch), it will automatically use the uninstalled version from that
directory.
If you put this script in your path, and symlink it to gst-git (if you want
to develop against git master) or to gst-released (if you want to develop
against the lastest release of each module), it will automatically use the
uninstalled version from that directory (ie. gst-git will look for a directory
called 'git', and gst-released will expect the uninstalled modules to be in
the 'released' directory; you are free to use any name or identifier you like
here).
</para>
<para>
This requires you to have put your checkouts of gstreamer and gst-plugins
under ~/gst/cvs (for the HEAD version). The program is easily modifiable
under ~/gst/git (for the master version). The program is easily modifiable
if this isn't the case.
</para>
<para>
After running this script, you'll be in an environment where you can
use the uninstalled tools, and where gst-register registers the uninstalled
plugins by default. Also, pkg-config wil detect the uninstalled copies
before any installed copies.
After 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>
</answer>
</qandaentry>
@ -80,7 +83,8 @@ 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.
that the user configured. If you are using gconfaudiosink, your application
should set the 'profile' property.
</para>
</answer>
</qandaentry>
@ -136,8 +140,8 @@ 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 CVS version.
Any tarball or package that has a nano number of 1 is made from CVS and thus
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.
@ -162,8 +166,8 @@ Just follow what's already there and you'll be fine.
The core could use a code cleanup though at this point.
</para>
<para>
Individual plugins in gst-plugins or plugins that you want considered for
addition to the gst-plugins module should be coded in the same style.
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>
@ -181,11 +185,29 @@ If you use emacs, try these lines:
</programlisting>
</para>
<para>
Or, run your code through
Or, run your code (only the *.c files, not the header files) through
<programlisting>
indent -br -bad -cbi0 -cli2 -bls -l100 -ut -ce
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 (FIXME: check if these are indeed the proper options).
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>
As for the code itself, the
@ -194,21 +216,23 @@ Where possible, we try to adhere to the spirit of GObject and use similar
coding idioms.
</para>
<para>
Patches should be made against CVS or the latest release and should be
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.
sent to the mailing list. Also see
<ulink url="http://gstreamer.freedesktop.org/wiki/SubmittingPatches">SubmittingPatches</ulink>
in the GStreamer wiki.
</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 into CVS?</para>
<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 CVS by the maintainers by running 'make download-po' in the various modules.</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>

View file

@ -17,7 +17,7 @@
<!ENTITY USING SYSTEM "using.xml">
<!ENTITY TROUBLESHOOTING SYSTEM "troubleshooting.xml">
<!ENTITY CVS SYSTEM "cvs.xml">
<!ENTITY GIT SYSTEM "git.xml">
<!ENTITY DEVELOPING SYSTEM "developing.xml">
<!ENTITY LEGAL SYSTEM "legal.xml">
@ -69,7 +69,7 @@
&USING;
&TROUBLESHOOTING;
&CVS;
&GIT;
&DEVELOPING;
&LEGAL;

View file

@ -16,7 +16,7 @@ distribution-specific packages</link></para></listitem>
<listitem><para><link linkend="getting-gstreamer-source">
source tarballs</link></para></listitem>
<listitem><para><link linkend="getting-gstreamer-packages">
CVS</link></para></listitem>
git</link></para></listitem>
</itemizedlist>
</para>
</answer>
@ -155,13 +155,13 @@ neither can or want to know enough, about how your unique system is configured,
</qandaentry>
<qandaentry>
<question id="getting-gstreamer-cvs">
<para>How do I get GStreamer through CVS ?</para>
<question id="getting-gstreamer-git">
<para>How do I get GStreamer through git ?</para>
</question>
<answer>
<para>
see this page : <ulink url="http://gstreamer.freedesktop.org/dev/">http://gstreamer.freedesktop.org/dev/</ulink> for CVS access. (anonymous and developer)
see this page : <ulink url="http://gstreamer.freedesktop.org/dev/">http://gstreamer.freedesktop.org/dev/</ulink> for git access. (anonymous and developer)
</para>
</answer>
</qandaentry>

View file

@ -1,11 +1,11 @@
<sect1 id="chapter-cvs">
<title id="title-cvs">Building GStreamer from CVS</title>
<sect1 id="chapter-git">
<title id="title-git">Building GStreamer from git</title>
<qandaset defaultlabel="qanda">
<qandaentry>
<question id="cvs-anon">
<question id="git-anon">
<para>
How do I check out GStreamer from CVS ?
How do I check out GStreamer from git ?
</para>
</question>
@ -13,16 +13,23 @@ How do I check out GStreamer from CVS ?
<para>
GStreamer is hosted on Freedesktop.org. GStreamer consists of various parts.
In the beginning, you will be interested in the "gstreamer" module, containing
the core, and "gst-plugins", containing the basic set of plugins.
the core, and "gst-plugins-base" and "gst-plugins-good", containing the basic
set of plugins. Finally, you may also be interested in "gst-plugins-ugly",
"gst-plugins-bad" and "gst-ffmpeg" for more comprehensive media format support.
</para>
<para>
To check out the HEAD version of the core, use
To check out the latest git version of the core and the basic modules, use
<programlisting>
cvs -d:pserver:anoncvs@anoncvs.freedesktop.org:/cvs/gstreamer co gstreamer
for module in gstreamer gst-plugins-base gst-plugins-good; do
git clone git://anongit.freedesktop.org:/git/gstreamer/$module ;
done
</programlisting>
This will create a directory "gstreamer" in your current directory.
If you want to get another module, replace the last "gstreamer" with the
name of the module.
This will create three directories in your current directory: "gstreamer",
"gst-plugins-base", and "gst-plugins-good". If you want to get another module,
use the above git clone command line and replace $module with the name of the
module. Once you have checked out these modules, you will need to change into
each directory and run ./autogen.sh, which will among other things checkout
the common module underneath each module checkout.
</para>
<para>
The <ulink url="http://gstreamer.freedesktop.org/modules/">modules page</ulink>
@ -32,18 +39,20 @@ has a list of active ones together with a short description.
</qandaentry>
<qandaentry>
<question id="cvs-developer">
<question id="git-developer">
<para>
How do I get developer access to GStreamer CVS ?
How do I get developer access to GStreamer git ?
</para>
</question>
<answer>
<para>
If you want to gain developer access to GStreamer CVS, you should ask for
it on the development lists, or ask one of the maintainers directly.
If you are not already a registered developer with a user account on
Freedesktop.org, You will then have to provide them with:
If you want to gain developer access to GStreamer git, you should ask for
it on the development lists, or ask one of the maintainers directly. We will
usually only consider requests by developers who have been active and
competent GStreamer contributors for some time already. If you are not
already a registered developer with a user account on Freedesktop.org,
you will then have to provide them with:
<orderedlist>
<listitem><para>your desired unix username</para></listitem>
<listitem><para>your full name</para></listitem>
@ -122,7 +131,7 @@ chasing a bug for days that the compiler was giving you hints about.
</para>
<para>
"-Werror" is turned off for actual releases. It's turned on by default for
CVS and prereleases so that people actually notice and fix problems found by
git and prereleases so that people actually notice and fix problems found by
"-Wall". We want people to actively hit and report or fix them.
</para>
<para>

View file

@ -1,9 +1,9 @@
#!/bin/bash -i
#
# this script is in CVS as gstreamer/docs/faq/gst-uninstalled
# this script is in git as gstreamer/docs/faq/gst-uninstalled
#
# It will set up the environment to use and develop gstreamer and projects
# that use gstreamer with an uninstalled CVS checkout of gstreamer and the
# that use gstreamer with an uninstalled git checkout of gstreamer and the
# plugin modules.
#
# It will set up LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, PKG_CONFIG_PATH,
@ -27,7 +27,7 @@
# This script is run -i so that PS1 doesn't get cleared
# Change this variable to the location of your gstreamer CVS checkouts
# Change this variable to the location of your gstreamer git checkouts
MYGST=$HOME/gst
#

View file

@ -18,8 +18,8 @@ If you'd rather learn by trying it out, start with
</listitem>
<listitem>
<para>
If you want to live on the bleeding edge and develop and use CVS, see
<xref linkend="title-cvs" endterm="title-cvs"/>
If you want to live on the bleeding edge and develop and use git, see
<xref linkend="title-git" endterm="title-git"/>
</para>
</listitem>
</itemizedlist>

View file

@ -39,7 +39,7 @@ Make sure to remember to re-run configure after installing the supporting
library !
</para></listitem>
<listitem><para>
if you run GStreamer from CVS, the same logic applies as for a source install.
if you run GStreamer from git, the same logic applies as for a source install.
Go over the reasons why the plug-in didn't get configured for build.
Check output of config.log for a clue as to why it doesn't get built if
you're sure you have the library needed installed in a sane place.
@ -63,7 +63,7 @@ What's wrong ?
<answer>
<para>
If you run GStreamer CVS uninstalled, it means that something changed in
If you run GStreamer from git uninstalled, it means that something changed in
the core that requires a recompilation in the plugins. Recompile the
plugins by doing "make clean &amp;&amp; make".
</para>

View file

@ -149,7 +149,7 @@ When doing a bug report, you should at least describe
<itemizedlist>
<listitem><para>your distribution</para></listitem>
<listitem><para>
how you installed GStreamer (from cvs, source, packages, which ?)</para></listitem>
how you installed GStreamer (from git, source, packages, which ?)</para></listitem>
<listitem><para>if you installed GStreamer before</para></listitem>
</itemizedlist>
</para>