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