developing.md 6.8 KB
Newer Older
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
1
2
# Developing applications with GStreamer

3
## How do I compile programs that use GStreamer?
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
4

Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
5
<!-- FIXME: update for windows, macOS, and meson build, get rid of libtool things -->
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
6

Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
7
This depends all a bit on what your development environment and target
8
operating system is. The following is mostly aimed at Linux/unix setups.
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
9
10
11

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
12
13
used in unix systems to locate libraries and retrieve build settings. If
you're already familiar with it, then you're basically set.
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
14

15
If you're not familiar with `pkg-config`, to compile and link a small
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
16
one-file program, pass the `--cflags` and `--libs` arguments to `pkg-config`.
17
The following should be sufficient for a gstreamer-only program:
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
18

19
20
21
```
$ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-1.0` -o myprog myprog.c
```
22
23

If your application also used GTK+ 3.0, you could use
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
24

25
26
27
```
$ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-1.0 gtk+-3.0` -o myprog myprog.c
```
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
28
29
30
31

Those are back-ticks (on the same key with the tilde on US keyboards),
not single quotes.

32
33
For bigger projects, you should integrate `pkg-config` use in your
Makefile, or with autoconf using the pkg.m4 macro (providing
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
34
`PKG_CONFIG_CHECK`).
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
35

36
## How do I develop against an uninstalled GStreamer copy?
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
37

38
39
40
It is possible to develop and compile against an uninstalled copy of GStreamer
and its plugins, for example, against git checkouts. This enables you to test
the latest version of GStreamer without interfering with your system-wide
41
42
installation. See the [Building from source using
meson](installing/building-from-source-using-meson.md) documentation.
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
43
44


45
## How can I use GConf to get the system-wide defaults?
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
46

47
48
49
50
51
52
53
<!-- FIXME: Consider removing. GConf was deprecated half a decade ago -->

GStreamer used to have GConf-based elements but these were removed in 2011,
after `GConf` itself was deprecated in favor of `GSettings`.

If what you want is automatic audio/video sinks, consider using the
`autovideosink` and `autoaudiosink` elements.
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
54

55
## How do I debug these funny shell scripts that libtool makes?
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
56
57
58
59

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
60
`gst-launch`, try:
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
61

62
63
64
```
libtool --mode=execute gdb /path/to/gst-launch
```
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
65

66
If this does not work, you're probably using a broken version of
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
67
68
libtool.

Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
69
70
71
72
73
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.

74
## Why is mail traffic so low on gstreamer-devel?
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
75

Matthew Waters's avatar
Matthew Waters committed
76
Our main arenas for coordination and discussion are IRC and Gitlab, not
77
the mailing lists. Join us in [`#gstreamer`][irc-gstreamer] on irc.freenode.net.
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
78
79
80
81
82
83
There is also a [webchat interface][webchat-gstreamer]. For larger picture
questions or getting more input from more people, a mail to the gstreamer-devel
mailing list is never a bad idea, however.

[irc-gstreamer]: irc://irc.freenode.net/#gstreamer
[webchat-gstreamer]: https://webchat.freenode.net
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
84

85
## What kind of versioning scheme does GStreamer use?
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
86
87
88
89

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
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
90
91
92
93
94
95
96
97
98
99
contains big changes, the MINOR version is incremented. A change in the
MAJOR version indicates incompatible API or ABI changes, which happens
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!
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
100
101
102
103
104
105
106
107

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.

108
## What is the coding style for GStreamer code?
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
109

110
111
112
113
Basically, the core and almost all plugin modules use K\&R with 2-space
indenting. Just follow what's already there and you'll be fine. We only require
code files to be indented, header may be indented manually for better
readability. Please use spaces for indenting, not tabs, even in header files.
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
114
115

Individual plugins in gst-plugins-\* or plugins that you want considered
116
117
for addition to these modules should use the same style. It's easier if
everything is consistent. Consistency is, of course, the goal.
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
118

119
120
121
One way to make sure you are following our coding style is to run your code
(remember, only the `*.c` files, not the headers) through GNU Indent using the
following options:
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
122

123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
```
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
```
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
138

139
140
141
142
143
There is also a `gst-indent` script in the GStreamer core source tree in the
tools directory which wraps GNU Indent and uses the right options.

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.
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
144

Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
145
146
Comments should be in `/* ANSI C comment style */` and code should generally
be compatible with ANSI C89, so please declare all variables at the beginning
147
of the block, etc.
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
148

Matthew Waters's avatar
Matthew Waters committed
149
150
Merge requests should ideally be made against git master or a recent release.
Please don't send patches to the mailing list. They will likely get lost there.
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
151

152
153
154
155
See [How to submit patches][submit-patches] for more details.

[submit-patches]: contribute/index.md#how-to-submit-patches

156
157
158
## How do I get my translations included?

I have translated one of the module .po files into a new language. How do I get it included?
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
159
160

GStreamer translations are uniformly managed through the
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
161
[Translation Project](http://translationproject.org). There are some
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
162
163
164
165
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
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
166
167
168
periodically into git by the maintainers by running `make download-po`
in the various modules when preparing a new release.

169
We don't merge new translations or translation fixes directly, everything
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
170
must go via the Translation Project.