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:
 107
 108 ```
 109 meson test -C build/ --suite gstreamer gst/gstbuffer
 110 ```
 111
 112 ## Add information about GStreamer development environment in your prompt line
 113
 114 ### Bash prompt
 115
 116 We automatically handle `bash` and set `$PS1` accordingly
 117
 118 ### Zsh prompt
 119
 120 In your `.zshrc`, you should add something like:
 121
 122 ```
 123 export PROMPT="$GST_ENV-$PROMPT"
 124 ```
 125
 126 ### Fish prompt
 127
 128 In your `~/.config/fish/functions/fish_prompt.fish`, you should add something like this at the end of the fish_prompt function body:
 129
 130 ```
 131 if set -q GST_ENV
 132   echo -n -s (set_color -b blue white) "(" (basename "$GST_ENV") ")" (set_color normal) " "
 133 end
 134 ```
 135
 136 ### Using powerline
 137
 138 In your powerline theme configuration file (by default in
 139 `{POWERLINE INSTALLATION DIR}/config_files/themes/shell/default.json`)
 140 you should add a new environment segment as follow:
 141
 142 ```
 143 {
 144   "function": "powerline.segments.common.env.environment",
 145   "args": { "variable": "GST_ENV" },
 146   "priority": 50
 147 },
 148 ```