faq: update developing

markdown/frequently-asked-questions/developing.md

@@ -2,30 +2,34 @@
 
 ## How do I compile programs that use GStreamer ?
 
-GStreamer uses pkg-config to assist applications with compilation
+<!-- FIXME: update for windows, macOS, and meson build, get rid of libtool things -->
-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.
 
-If you're not familiar with pkg-config to compile and link a small
+This depends all a bit on what your development environment and target
-one-file program, pass the --cflags and --libs arguments to pkg-config.
+operating systems is. The following is mostly aimed at Linux/unix setups.
+
+GStreamer uses the `pkg-config` utility to provide applications with the right
+compiler and linker flags. `pkg-config` is a standard build tool that is widely
+used unix systems to locate libraries and retrieve build settings, so if you're
+familiar with using it already then you're basically set.
+
+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:
 
-    $ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-GST_API_VERSION` -o myprog myprog.c
+    $ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-1.0` -o myprog myprog.c
 
 would be sufficient for a gstreamer-only program. If (for example) your
-app also used GTK+ 2.0, you could
+application also used GTK+ 3.0, you could use
-    use
 
-    $ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-GST_API_VERSION gtk+-2.0` -o myprog myprog.c
+    $ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-1.0 gtk+-3.0` -o myprog myprog.c
 
 Those are back-ticks (on the same key with the tilde on US keyboards),
 not single quotes.
 
 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).
+`PKG_CONFIG_CHECK`).
 
 ## How do I develop against an uninstalled GStreamer copy ?
 
@@ -35,18 +39,35 @@ 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.
 
-The easiest way too create such a setup is the [latest version of
+There are two ways to achieve such a setup:
-create-uninstalled-setup.sh](http://cgit.freedesktop.org/gstreamer/gstreamer/tree/scripts/create-uninstalled-setup.sh)
 
-This setup makes use of the [latest version of
+1. [`gst-build`][gst-build] is our new meta-build module based on the
-gst-uninstalled](http://cgit.freedesktop.org/gstreamer/gstreamer/tree/scripts/gst-uninstalled).
+   [Meson build system][meson]. This is the shiny new thing. It's fast and
-Running this script, you'll be in an environment where the uninstalled
+   simple to get started with, but you will need a recent version of Meson
-tools and plugins will be used by default. Also, pkg-config will detect
+   installed. Just check out the git repository and run the `setup.py` script.
-the uninstalled copies before (and prefer them to) any installed copies.
+   Once the initial meson configure stage has passed, you can enter an
+   uninstalled environment by running `ninja uninstalled` in the build
+   directory. This will make sure tools and plugin from the uninstalled build
+   tree will be used. Any problems, let us know.
 
-Multiple uninstalled setups can be used in parallel. Have a look at
+2. [`gst-uninstalled`][gst-uninstalled] is our traditional autotools-
-[gst-uninstalled](http://cgit.freedesktop.org/gstreamer/gstreamer/tree/scripts/gst-uninstalled)
+   and libtool-based build setup. The easiest way too create such a setup
-to see how it determines which environment is used.
+   is using the [latest version of the `create-uninstalled-setup.sh`
+   script][create-uninstalled]. This setup makes use of the [latest version of
+   the `gst-uninstalled` script][gst-uninstalled]. 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.
+
+Multiple uninstalled setups can be used in parallel, e.g. one for the
+latest stable branch and one for git master. Have a look at the
+[gst-uninstalled][gst-uninstalled] script to see how it determines which
+environment is used.
+
+[gst-build]: https://cgit.freedesktop.org/gstreamer/gst-build/
+[meson]: http://mesonbuild.com
+[gst-uninstalled]: http://cgit.freedesktop.org/gstreamer/gstreamer/tree/scripts/gst-uninstalled
+[create-uninstalled]: http://cgit.freedesktop.org/gstreamer/gstreamer/tree/scripts/create-uninstalled-setup.sh
 
 ## How can I use GConf to get the system-wide defaults ?
 
@@ -69,22 +90,37 @@ gst-launch, try
 . If this does not work, you're probably using a broken version of
 libtool.
 
+If you build GStreamer using the Meson build system, libtool will not
+be used and this is not a problem. You can run `gdb`, `valgrind` or any
+debugging tools directly on the binaries Meson creates in the build
+directory.
+
 ## Why is mail traffic so low on gstreamer-devel ?
 
-Our main arena for coordination and discussion is IRC, not email.
+Our main arena for coordination and discussion are IRC and bugzilla, not
-Join us in [\#gstreamer on
+mailing lists. Join us in [`#gstreamer`][irc-gstreamer] on irc.freenode.net.
-irc.freenode.net](irc://irc.freenode.net/#gstreamer) For larger picture
+There is also a [webchat interface][webchat-gstreamer]. For larger picture
-questions or getting more input from more persons, a mail to
+questions or getting more input from more people, a mail to the gstreamer-devel
-gstreamer-devel is never a bad idea.
+mailing list is never a bad idea, however.
+
+[irc-gstreamer]: irc://irc.freenode.net/#gstreamer
+[webchat-gstreamer]: https://webchat.freenode.net
 
 ## What kind of versioning scheme does GStreamer use ?
 
 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
+contains big changes, the MINOR version is incremented. A change in the
-particularly giddy, we might even increase the MAJOR number. Don't hold
+MAJOR version indicates incompatible API or ABI changes, which happens
-your breath for that though.
+very rarely (the last one dates back to 2012). This is also known as
+[semantic versioning](http://semver.org).
+
+Even MINOR numbers indicate *stable releases*: 1.0.x, 1.2.x, 1.4.x, 1.6.x,
+1.8.x, and 1.10.x are our stable release series. Odd MINOR numbers are used
+for *unstable development releases* and *prereleases* which should only be
+used temporarily for testing; your help in testing these tarballs and packages
+is very much appreciated!
 
 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
@@ -93,10 +129,6 @@ 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.
 
-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.
-
 ## What is the coding style for GStreamer code?
 
 The core and almost all plugin modules are basically coded in
@@ -125,7 +157,7 @@ Simply run your code (only the \*.c files, not the header files) through
       --indent-level2
 
 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
+`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
@@ -133,22 +165,26 @@ 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).
 
-Where possible, we try to adhere to the spirit of GObject and use
+Comments should be in `/* ANSI C comment style */` and code should generally
-similar coding idioms.
+be compatible with ANSI C89, so please declare all variables at the beginning
+of the block etc.
 
-Patches should be made against git master or the latest release and
+Patches should ideally be made against git master or a recent release and
-should be in 'unified context' format (use diff -u -p). They should be
+should be created using `git format-patch` format. They should then be
-attached to a bug report (or feature request) in
+attached individually to a bug report or feature request in
-[bugzilla](http://bugzilla.gnome.org) rather than sent to the mailing
+[bugzilla](http://bugzilla.gnome.org). Please don't send patches to the
-list.
+mailing list, they will likely get lost there.
 
 ## I have translated one of the module .po files into a new language. How do I get it included?
 
 GStreamer translations are uniformly managed through the
-Translation Project (http://translationproject.org). There are some
+[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.
 
 New translations submitted via the Translation Project are merged
-periodically into git by the maintainers by running 'make download-po'
+periodically into git by the maintainers by running `make download-po`
-in the various modules.
+in the various modules when preparing a new release.
+
+We won't merge new translations or translation fixes directly, everything
+must go via the Translation Project.