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 ## Uninstalled environment
  42
  43 gst-build also contains a special `uninstalled` target that lets you enter an
  44 uninstalled development environment where you will be able to work on GStreamer
  45 easily. You can get into that environment running:
  46
  47 ```
  48 ninja -C build/ uninstalled
  49 ```
  50
  51 If your operating system handles symlinks, built modules source code will be
  52 available at the root of `gst-build/` for example GStreamer core will be in
  53 `gstreamer/`. Otherwise they will be present in `subprojects/`. You can simply
  54 hack in there and to rebuild you just need to rerun `ninja -C build/`.
  55
  56 NOTE: In the uninstalled environment, a fully usable prefix is also configured
  57 in `gst-build/prefix` where you can install any extra dependency/project.
  58
  59 ## Update git subprojects
  60
  61 We added a special `update` target to update subprojects (it uses `git pull
  62 --rebase` meaning you should always make sure the branches you work on are
  63 following the right upstream branch, you can set it with `git branch
  64 --set-upstream-to origin/master` if you are working on `gst-build` master
  65 branch).
  66
  67 Update all GStreamer modules and rebuild:
  68
  69 ```
  70 ninja -C build/ update
  71 ```
  72
  73 Update all GStreamer modules without rebuilding:
  74
  75 ```
  76 ninja -C build/ git-update
  77 ```
  78
  79 ## Custom subprojects
  80
  81 We also added a meson option, 'custom_subprojects', that allows the user
  82 to provide a comma-separated list of subprojects that should be built
  83 alongside the default ones.
  84
  85 To use it:
  86
  87 ```
  88 cd subprojects
  89 git clone my_subproject
  90 cd ../build
  91 rm -rf * && meson .. -Dcustom_subprojects=my_subproject
  92 ninja
  93 ```
  94
  95
  96 ## Run tests
  97
  98 You can easily run the test of all the components:
  99
 100 ```
 101 meson test -C build
 102 ```
 103
 104 To list all available tests:
 105
 106 ```
 107 meson test -C build --list
 108 ```
 109
 110 To run all the tests of a specific component:
 111
 112 ```
 113 meson test -C build --suite gst-plugins-base
 114 ```
 115
 116 Or to run a specific test file:
 117
 118 ```
 119 meson test -C build/ --suite gstreamer gst_gstbuffer
 120 ```
 121
 122 Run a specific test from a specific test file:
 123
 124 ```
 125 GST_CHECKS=test_subbuffer meson test -C build/ --suite gstreamer gst_gstbuffer
 126 ```
 127
 128 ## Checkout another branch using worktrees
 129
 130 If you need to have several versions of GStreamer coexisting (eg. `master` and `1.14`),
 131 you can use the `checkout-branch-worktree` script provided by `gst-build`. It allows you
 132 to create a new `gst-build` environment with new checkout of all the GStreamer modules as
 133 [git worktrees](https://git-scm.com/docs/git-worktree).
 134
 135 For example to get a fresh checkout of `gst-1.14` from a `gst-build` in master already
 136 built in a `build` directory you can simply run:
 137
 138 ```
 139 ./checkout-branch-worktree ../gst-1.14 1.14 -C build/
 140 ```
 141
 142 ## Add information about GStreamer development environment in your prompt line
 143
 144 ### Bash prompt
 145
 146 We automatically handle `bash` and set `$PS1` accordingly.
 147
 148 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:
 149
 150 ```bash
 151 ...
 152 if [[ -n "${GST_ENV-}" ]];
 153 then
 154   PS1+="[ ${GST_ENV} ]"
 155 fi
 156 ...
 157
 158 ```
 159
 160 ### Zsh prompt
 161
 162 In your `.zshrc`, you should add something like:
 163
 164 ```
 165 export PROMPT="$GST_ENV-$PROMPT"
 166 ```
 167
 168 ### Fish prompt
 169
 170 In your `~/.config/fish/functions/fish_prompt.fish`, you should add something like this at the end of the fish_prompt function body:
 171
 172 ```
 173 if set -q GST_ENV
 174   echo -n -s (set_color -b blue white) "(" (basename "$GST_ENV") ")" (set_color normal) " "
 175 end
 176 ```
 177
 178 ### Using powerline
 179
 180 In your powerline theme configuration file (by default in
 181 `{POWERLINE INSTALLATION DIR}/config_files/themes/shell/default.json`)
 182 you should add a new environment segment as follow:
 183
 184 ```
 185 {
 186   "function": "powerline.segments.common.env.environment",
 187   "args": { "variable": "GST_ENV" },
 188   "priority": 50
 189 },
 190 ```