1 # Multiplatform deployment using Cerbero
3 Cerbero is the build and packaging system used to construct
4 GStreamer. It uses “recipe” files that indicate how to build
5 particular projects, and on what other projects they depend.
6 Moreover, the built projects can be combined into packages for
7 distribution. These packages are, depending on the target platform,
8 Windows or OS X installers or Linux packages.
10 To use Cerbero to build and package your application, you just need to
11 add a recipe explaining how to build you application and make it depend
12 on the `gstreamer-sdk` project. Then Cerbero can take care of building
13 your application and its dependencies and package them all together.
15 Read [](installing/building-from-source-using-cerbero.md) to learn how
16 to install and use Cerbero.
18 At this point, after reading the Build from source section in
19 [](installing/building-from-source-using-cerbero.md), you should be able to
20 build GStreamer from source and are ready to create recipe and package
21 files for your application.
23 In the Cerbero installation directory you will find the
24 `cerbero-uninstalled` script. Execute it without parameters to see the
25 list of commands it accepts:
31 ## Adding a recipe for your application
33 The first step is to create an empty recipe that you can then tailor to
37 ./cerbero-uninstalled add-recipe my-app 1.0
40 This will create an initial recipe file in `recipes/my-app.recipe`,
41 which contains the smallest necessary recipe. This file is a Python
42 script; set the following attributes to describe your application:
44 | Attribute Name | Description | Required | Example |
45 |----------------|-------------|----------|---------|
46 | `name` | The recipe name. | Yes | *name = 'my-app'* |
47 | `version` | The software version. | Yes | *version = '1.0'* |
48 | `licenses` | A list of licenses of the software (see `cerbero/enums.py:License` for allowed licenses). | Yes | *licenses = \[License.LGPLv2Plus\]* |
49 | `deps` | A list of build dependencies of the software as recipe names. | No | *deps = \['other', 'recipe', 'names'\]* |
50 | `platform_deps` | Platform specific build dependencies (see `cerbero/enums.py:Platform` for allowed platforms). | No | *platform\_deps = {Platform.LINUX: \['some-recipe'\], Platform.WINDOWS: \['another-recipe'\]}* |
51 | `remotes` | A dictionary specifying the git remote urls where sources are pulled from. | No | *remotes = {'origin': '<git://somewhere>'}* |
52 | `commit` | The git commit, tag or branch to use, defaulting to "sdk-*`version`*"*.* | No | *commit = 'my-app-branch'* |
53 | `config_sh` | Used to select the configuration script. | No | *config\_sh = 'autoreconf -fiv && sh ./configure'* |
54 | `configure_options` | Additional options that should be passed to the `configure` script. | No | *configure\_options = '--enable-something'* |
55 | `use_system_libs` | Whether to use system provided libs. | No | *use\_system\_libs = True* |
56 | `btype` | The build type (see `cerbero/build/build.py:BuildType` for allowed build types). | No | *btype = BuildType.CUSTOM* |
57 | `stype` | The source type (see `cerbero/build/source.py:SourceType` for allowed source types). | No | *stype = SourceType.CUSTOM* |
58 | `files_category` | A list of files that should be shipped with packages including this recipe *category*. See below for more details. Cerbero comes with some predefined categories that should be used if the files being installed match a category criteria. The predefined categories are: `libs` (for libraries), `bins` (for binaries), `devel` (for development files - header, pkgconfig files, etc), `python` (for python files) and `lang` (for language files). *Note that for the `bins` and `libs` categories there is no need to specify the files extensions as Cerbero will do it for you.* | Yes\* | *files\_bins = \['some-binary'\]* *files\_libs = \['libsomelib'\]* *files\_devel = \['include/something'\] files\_python = \['site-packages/some/pythonfile%(pext)s'\]* *files\_lang = \['foo'\]* |
59 | `platform_files_category` | Same as *`files_category`* but for platform specific files. | No | *platform\_files\_some\_category = {Platform.LINUX: \['/some/file'\]}* |
61 > ![warning] At least one “files” category should be set.
63 Apart from the attributes listed above, it is also possible to override
64 some Recipe methods. For example the `prepare` method can be overridden
65 to do anything before the software is built, or the `install` and
66 `post_install` methods for overriding what should be done during or
67 after installation. Take a look at the existing recipes in
68 `cerbero/recipes` for example.
70 Alternatively, you can pass some options to cerbero-uninstalled so some
71 of these attributes are already set for you. For
75 ./cerbero-uninstalled add-recipe --licenses "LGPL" --deps "glib" --origin "git://git.my-app.com" --commit "git-commit-to-use" my-app 1.0
78 See `./cerbero-uninstalled add-recipe -h` for help.
80 As an example, this is the recipe used to build the Pitivi video editor:
83 class Recipe(recipe.Recipe):
86 licenses = [License.GPLv2Plus]
87 remotes = {'origin': 'git://git.gnome.org/pitivi'}
88 config_sh = 'sh ./autogen.sh --noconfigure && ./configure'
89 configure_options = "--disable-help"
90 commit = 'origin/master'
91 deps = ['gst-editing-services-1.0',
94 'gst-plugins-bad-1.0',
95 'gst-plugins-ugly-1.0',
100 'gnome-icon-theme-symbolic',
101 'shared-mime-info'] # brings in gtk+
103 files_libs = ['libpitivi-1.0']
107 use_system_libs = True
108 files_bins = ['pitivi']
109 files_lang = ['pitivi']
110 files_pitivi = ['lib/pitivi/python/pitivi',
112 'share/applications/pitivi.desktop']
115 Cerbero gets the software sources to build from a GIT repository, which
116 is specified via the `git_root` configuration variable from the Cerbero
117 configuration file (see the "Build from software" section in [Installing
118 on Linux](installing/on-linux.md)) and can be overridden by the
119 `remotes` attribute inside the recipes (if setting the `origin` remote).
120 In this case where no “commit” attribute is specified, Cerbero will use
121 the commit named “sdk-0.2+git” from the GIT repository when building
124 Once the recipe is ready, instruct Cerbero to build it:
127 ./cerbero-uninstalled build my-app
130 ## Adding a package for you software
132 To distribute your software with GStreamer it is necessary to put it into
133 a package or installer, depending on the target platform. This is done
134 by selecting the files that should be included. To add a package you
135 have to create a package file in `cerbero/packages`. The package files
136 are Python scripts too and there are already many examples of package
137 files in `cerbero/packages`.
139 Now, to create an empty package, do:
142 ./cerbero-uninstalled add-package my-app 1.0
145 This will create an initial package file in `packages/my-app.package`.
147 The following Package attributes are used to describe your package:
149 | Attribute Name | Description | Required | Example |
150 |----------------|-------------|----------|---------|
151 | `name` | The package name. | Yes | *name = 'my-app'* |
152 | `shortdesc` | A short description of the package. | No | *shortdesc = 'some-short-desc'* |
153 | `longdesc` | A long description of the package. | No | *longdesc = 'Some Longer Description'* |
154 | `codename` | The release codename. | No | *codename = 'MyAppReleaseName'* |
155 | `vendor` | Vendor for this package.| No | *vendor = 'MyCompany'* |
156 | `url` | The package url | No | *url = 'http://www.my-app.com'* |
157 | `version` | The package version. | Yes | *version = '1.0'* |
158 | `license` | The package license (see `cerbero/enums.py:License` for allowed licenses). | Yes | *license = License.LGPLv2Plus* |
159 | `uuid` | The package unique id | Yes | *uuid = '6cd161c2-4535-411f-8287-e8f6a892f853'* |
160 | `deps` | A list of package dependencies as package names. | No | *deps = \['other', 'package', 'names'\]* |
161 | `sys_deps` | The system dependencies for this package. | No | *sys\_deps= {Distro.DEBIAN: \['python'\]}* |
162 | `files` | A list of files included in the **runtime** package in the form *“recipe\_name:category1:category2:...”* *If the recipe category is omitted, all categories are included.* | Yes\* | *files = \['my-app'\]* *files = \['my-app:category1'\]* |
163 | `files_devel` | A list of files included in the **devel** package in the form *“recipe\_name:category1:category2:...”* | Yes\* | *files\_devel = \['my-app:category\_devel'\]* |
164 | `platform_files` | Same as *files* but allowing to specify different files for different platforms. | Yes\* | *platform\_files = {Platform.WINDOWS: \['my-app:windows\_only\_category'\]}* |
165 | `platform_files_devel` | Same as *files\_devel* but allowing to specify different files for different platforms. | Yes\* | *platform\_files\_devel = {Platform.WINDOWS: \['my-app:windows\_only\_category\_devel'\]}* |
167 > ![warning] At least one of the “files” attributes should be set.
169 Alternatively you can also pass some options to `cerbero-uninstalled`,
174 ./cerbero-uninstalled add-package my-app 1.0 --license "LGPL" --codename MyApp --vendor MyAppVendor --url "http://www.my-app.com" --files=my-app:bins:libs --files-devel=my-app:devel --platform-files=linux:my-app:linux_specific --platform-files-devel=linux:my-app:linux_specific_devel,windows:my-app:windows_specific_devel --deps base-system --includes gstreamer-core
177 See `./cerbero-uninstalled add-package -h` for help.
179 As an example, this is the package file that is used for packaging the
180 `gstreamer-core` package:
183 class Package(package.Package):
185 name = 'gstreamer-1.0-codecs'
186 shortdesc = 'GStreamer 1.0 codecs'
187 longdesc = 'GStreamer 1.0 codecs'
189 url = "http://gstreamer.freedesktop.org"
190 license = License.LGPL
191 vendor = 'GStreamer Project'
192 org = 'org.freedesktop.gstreamer'
193 uuid = 'a2e545d5-7819-4636-9e86-3660542f08e5'
194 deps = ['gstreamer-1.0-core', 'base-crypto']
196 files = ['flac:libs', 'libkate:libs', 'libdv:libs',
197 'libogg:libs', 'schroedinger:libs', 'speex:libs',
198 'libtheora:libs', 'wavpack:libs', 'libvpx:libs',
199 'taglib:libs', 'opus:libs', 'libvorbis:libs',
200 'openjpeg:libs', 'openh264:libs', 'spandsp:libs',
201 'gst-plugins-base-1.0:plugins_codecs', 'gst-plugins-good-1.0:plugins_codecs',
202 'gst-plugins-bad-1.0:plugins_codecs', 'gst-plugins-ugly-1.0:plugins_codecs',
204 files_devel = ['gst-plugins-base-1.0-static:plugins_codecs_devel',
205 'gst-plugins-good-1.0-static:plugins_codecs_devel',
206 'gst-plugins-bad-1.0-static:plugins_codecs_devel',
207 'gst-plugins-ugly-1.0-static:plugins_codecs_devel',
208 'gst-plugins-bad-1.0-static:codecs_devel']
210 Platform.ANDROID: ['tremor:libs'],
211 Platform.IOS: ['tremor:libs']
215 At this point you have two main options: you could either have a single
216 package that contains everything your software needs, or depend on a
217 shared version of GStreamer.
219 ### Having a private version of GStreamer
221 To have a private version of GStreamer included in a single package you
222 don't have to add the `deps` variable to the package file but instead
223 list all files you need in the `files` variables. If you decide to go
224 this road you must make sure that you use a different prefix than
225 GStreamer in the Cerbero configuration file, otherwise your package
226 will have file conflicts with GStreamer.
228 ### Having a shared version of GStreamer
230 If you decide to use a shared version of GStreamer you can create a
231 package file like the other package files in GStreamer. Just
232 list all packages you need in the `deps` variable and put the files your
233 software needs inside the `files` variables. When building a package
234 this way you must make sure that you use the same prefix and
235 packages\_prefix as the ones in your Cerbero configuration file.
237 Finally, build your package by using:
240 ./cerbero-uninstalled package your-package
243 Where `your-package` is the name of the `.package` file that you created
244 in the `packages` directory. This command will build your software and
245 all its dependencies, and then make individual packages for them (both
246 the dependencies and your software). The resulting files will be in the
247 current working directory.
250 [warning]: images/icons/emoticons/warning.png