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