README.md

   1 # gst-build
   2
   3 GStreamer [meson](http://mesonbuild.com/) based repositories aggregrator
   4
   5 You can build GStreamer and all its modules at once using
   6 meson and its [subproject](https://github.com/mesonbuild/meson/wiki/Subprojects) feature.
   7
   8 ## Getting started
   9
  10 ### Install meson and ninja
  11
  12 Meson 0.48 or newer is required.
  13
  14 You should get meson through your package manager or using:
  15
  16   $ pip3 install --user meson
  17
  18 This will install meson into ~/.local/bin which may or may not be included
  19 automatically in your PATH by default.
  20
  21 If you are building on Windows, do not use the Meson MSI installer since it is
  22 experimental and will likely not work.
  23
  24 You can also run meson directly from a meson git checkout if you like.
  25
  26 You should get `ninja` using your package manager or download the [official
  27 release](https://github.com/ninja-build/ninja/releases) and put it in your PATH.
  28
  29 ### Build GStreamer and its modules
  30
  31 You can get all GStreamer built running:
  32
  33 ```
  34 mkdir build/ && meson build && ninja -C build/
  35 ```
  36
  37 NOTE: on fedora (and maybe other distributions) replace `ninja` with `ninja-build`
  38
  39 # Development environment
  40
  41 ## Building the Qt5 QML plugin
  42
  43 If `qmake` is not in `PATH` and pkgconfig files are not available, you can
  44 point the `QMAKE` env var to the Qt5 installation of your choosing before
  45 running `meson` as shown above.
  46
  47 The plugin will be automatically enabled if possible, but you can ensure that
  48 it is built by passing `-Dgst-plugins-good:qt5=enabled` to `meson`. This will
  49 cause Meson to error out if the plugin could not be enabled. This also works
  50 for all plugins in all GStreamer repositories.
  51
  52 ## Uninstalled environment
  53
  54 gst-build also contains a special `uninstalled` target that lets you enter an
  55 uninstalled development environment where you will be able to work on GStreamer
  56 easily. You can get into that environment running:
  57
  58 ```
  59 ninja -C build/ uninstalled
  60 ```
  61
  62 If your operating system handles symlinks, built modules source code will be
  63 available at the root of `gst-build/` for example GStreamer core will be in
  64 `gstreamer/`. Otherwise they will be present in `subprojects/`. You can simply
  65 hack in there and to rebuild you just need to rerun `ninja -C build/`.
  66
  67 NOTE: In the uninstalled environment, a fully usable prefix is also configured
  68 in `gst-build/prefix` where you can install any extra dependency/project.
  69
  70 ## Update git subprojects
  71
  72 We added a special `update` target to update subprojects (it uses `git pull
  73 --rebase` meaning you should always make sure the branches you work on are
  74 following the right upstream branch, you can set it with `git branch
  75 --set-upstream-to origin/master` if you are working on `gst-build` master
  76 branch).
  77
  78 Update all GStreamer modules and rebuild:
  79
  80 ```
  81 ninja -C build/ update
  82 ```
  83
  84 Update all GStreamer modules without rebuilding:
  85
  86 ```
  87 ninja -C build/ git-update
  88 ```
  89
  90 ## Custom subprojects
  91
  92 We also added a meson option, 'custom_subprojects', that allows the user
  93 to provide a comma-separated list of subprojects that should be built
  94 alongside the default ones.
  95
  96 To use it:
  97
  98 ```
  99 cd subprojects
 100 git clone my_subproject
 101 cd ../build
 102 rm -rf * && meson .. -Dcustom_subprojects=my_subproject
 103 ninja
 104 ```
 105
 106
 107 ## Run tests
 108
 109 You can easily run the test of all the components:
 110
 111 ```
 112 meson test -C build
 113 ```
 114
 115 To list all available tests:
 116
 117 ```
 118 meson test -C build --list
 119 ```
 120
 121 To run all the tests of a specific component:
 122
 123 ```
 124 meson test -C build --suite gst-plugins-base
 125 ```
 126
 127 Or to run a specific test file:
 128
 129 ```
 130 meson test -C build/ --suite gstreamer gst_gstbuffer
 131 ```
 132
 133 Run a specific test from a specific test file:
 134
 135 ```
 136 GST_CHECKS=test_subbuffer meson test -C build/ --suite gstreamer gst_gstbuffer
 137 ```
 138
 139 ## Checkout another branch using worktrees
 140
 141 If you need to have several versions of GStreamer coexisting (eg. `master` and `1.14`),
 142 you can use the `checkout-branch-worktree` script provided by `gst-build`. It allows you
 143 to create a new `gst-build` environment with new checkout of all the GStreamer modules as
 144 [git worktrees](https://git-scm.com/docs/git-worktree).
 145
 146 For example to get a fresh checkout of `gst-1.14` from a `gst-build` in master already
 147 built in a `build` directory you can simply run:
 148
 149 ```
 150 ./checkout-branch-worktree ../gst-1.14 1.14 -C build/
 151 ```
 152
 153 ## Add information about GStreamer development environment in your prompt line
 154
 155 ### Bash prompt
 156
 157 We automatically handle `bash` and set `$PS1` accordingly.
 158
 159 If the automatic `$PS1` override is not desired (maybe you have a fancy custom prompt), set the `$GST_BUILD_DISABLE_PS1_OVERRIDE` environment variable to `TRUE` and use `$GST_ENV` when setting the custom prompt, for example with a snippet like the following:
 160
 161 ```bash
 162 ...
 163 if [[ -n "${GST_ENV-}" ]];
 164 then
 165   PS1+="[ ${GST_ENV} ]"
 166 fi
 167 ...
 168
 169 ```
 170
 171 ### Zsh prompt
 172
 173 In your `.zshrc`, you should add something like:
 174
 175 ```
 176 export PROMPT="$GST_ENV-$PROMPT"
 177 ```
 178
 179 ### Fish prompt
 180
 181 In your `~/.config/fish/functions/fish_prompt.fish`, you should add something like this at the end of the fish_prompt function body:
 182
 183 ```
 184 if set -q GST_ENV
 185   echo -n -s (set_color -b blue white) "(" (basename "$GST_ENV") ")" (set_color normal) " "
 186 end
 187 ```
 188
 189 ### Using powerline
 190
 191 In your powerline theme configuration file (by default in
 192 `{POWERLINE INSTALLATION DIR}/config_files/themes/shell/default.json`)
 193 you should add a new environment segment as follow:
 194
 195 ```
 196 {
 197   "function": "powerline.segments.common.env.environment",
 198   "args": { "variable": "GST_ENV" },
 199   "priority": 50
 200 },
 201 ```