sdk-building-from-source-using-cerbero.md

   1 # Building from source using Cerbero
   2
   3 > ![Warning] This section is intended for advanced users.
   4
   5 ## Build requirements
   6
   7 The GStreamer build system provides bootstrapping facilities for all
   8 platforms, but it still needs a minimum base to bootstrap:
   9
  10 -   python > 2.6 and python's `argparse` module, which is already
  11     included in python2.7.
  12 -   git
  13
  14 ### Windows users
  15
  16 Cerbero can be used on Windows using the Msys/MinGW shell (a Unix-like
  17 shell for Windows). There is a bit of setup that you need to do before
  18 Cerbero can take control.
  19
  20 You need to install the following programs:
  21
  22 -   [Python 2.7]
  23 -   [Git] (Select the install option "Checkout as-is, Commit as-is" and
  24     install it in a path without spaces, eg: c:\Git)
  25 -   [Msys/MinGW] (Install it with all the options enabled)
  26 -   [CMake] (Select the option "Add CMake in system path for the
  27     current user")
  28 -   [Yasm] (Download the win32 or win64 version for your platform, name
  29     it `yasm.exe`, and place it in your MinGW `bin` directory,
  30     typically, `C:\MinGW\bin`)
  31 -   [WiX 3.5]
  32 -   [Microsoft SDK 7.1] (Install the SDK samples and the Visual C++
  33     Compilers, required to build the DirectShow base classes. Might need
  34     installing the .NET 4 Framework first if the SDK installer doesn't
  35     find it)
  36 -   [Windows Driver Kit 7.1.0]
  37
  38 Your user ID can't have spaces (eg: John Smith). Paths with spaces are
  39 not correctly handled in the build system and msys uses the user ID for
  40 the home folder.
  41
  42 Cerbero must be run in the MinGW shell, which is accessible from the
  43 main menu once MinGW is installed.
  44
  45 The last step is making `python` and `git` available from the shell, for
  46 which you will need to create a `.profile` file. Issue this command from
  47 within the MinGW shell:
  48
  49 `echo "export PATH=\"\$PATH:/c/Python27:/c/Git/bin\"" >> ~/.profile`
  50
  51 Using the appropriate paths to where you installed `python` and `git`
  52
  53 (Note that inside the shell, / is mapped to c:\Mingw\msys\1.0 )
  54
  55 ### OS X users
  56
  57 To use cerbero on OS X you need to install the "Command Line Tools" from
  58 XCode. They are available from the "Preferences" dialog under
  59 "Downloads".
  60
  61 ### iOS developers
  62
  63 If you want to build GStreamer for iOS, you also need the iOS
  64 SDK. The minimum required iOS SDK version is 6.0 and is included in
  65 [XCode] since version 4.
  66
  67 ## Download the sources
  68
  69 To build GStreamer, you first need to download **Cerbero**.
  70 Cerbero is a multi-platform build system for Open Source projects that
  71 builds and creates native packages for different platforms,
  72 architectures and distributions.
  73
  74 Get a copy of Cerbero by cloning the git repository:
  75
  76     git clone git://anongit.freedesktop.org/gstreamer/cerbero
  77
  78 Cerbero can be run uninstalled and for convenience you can create an
  79 alias in your `.bashrc` file*. *If you prefer to skip this step,
  80 remember that you need to replace the calls to `cerbero` with
  81 `./cerbero-uninstalled` in the next steps.
  82
  83     echo "alias cerbero='~/git/cerbero/cerbero-uninstalled'" >> ~/.bashrc
  84
  85 ## Setup environment
  86
  87 After Cerbero and the base requirements are in place, you need to setup
  88 the build environment.
  89
  90 Cerbero reads the configuration file `$HOME/.cerbero/cerbero.cbc` to
  91 determine the build options. This file is a python code which allows
  92 overriding/defining some options.
  93
  94 If the file does not exist, Cerbero will try to determine the distro you
  95 are running and will use default build options such as the default build
  96 directory. The default options should work fine on the supported
  97 distributions.
  98
  99 An example configuration file with detailed comments can be found [here]
 100
 101 To fire up the bootstrapping process, go to the directory where you
 102 cloned/unpacked Cerbero and type:
 103
 104     cerbero bootstrap
 105
 106 Enter the superuser/root password when prompted.
 107
 108 The bootstrap process will then install all packages required to build
 109 GStreamer.
 110
 111 ## Build GSTreamer
 112
 113 To generate GStreamer binaries, use the following command:
 114
 115     cerbero package gstreamer-1.0
 116
 117 This should build all required GStreamer components and create packages for
 118 your distribution at the Cerbero source directory.
 119
 120 A list of supported packages to build can be retrieved using:
 121
 122     cerbero list-packages
 123
 124 Packages are composed of 0 (in case of a meta package) or more
 125 components that can be built separately if desired. The components are
 126 defined as individual recipes and can be listed with:
 127
 128     cerbero list
 129
 130 To build an individual recipe and its dependencies, do the following:
 131
 132     cerbero build <recipe_name>
 133
 134 Or to build or force a rebuild of a recipe without building its
 135 dependencies use:
 136
 137     cerbero buildone <recipe_name>
 138
 139 To wipe everything and start from scratch:
 140
 141     cerbero wipe
 142
 143 Once built, the output of the recipes will be installed at the prefix
 144 defined in the Cerbero configuration file `$HOME/.cerbero/cerbero.cbc`
 145 or at `$HOME/cerbero/dist` if no prefix is defined.
 146
 147 ### Build a single project with GStreamer
 148
 149 Rebuilding the whole GStreamer is relatively fast on Linux and OS X, but it
 150 can be very slow on Windows, so if you only need to rebuild a single
 151 project (eg: gst-plugins-good to patch qtdemux) there is a much faster
 152 way of doing it. You will need to follow the steps detailed in this
 153 page, but skipping the step "**Build GStreamer**", and installing the
 154 GStreamer's development files as explained in [Installing GStreamer].
 155
 156 By default, Cerbero uses as prefix a folder in the user directory with
 157 the following schema \~/cerbero/dist/$platform\_$arch, but for GStreamer
 158 we must change this prefix to use its installation directory. This can
 159 be done with a custom configuration file named *custom.cbc*:
 160
 161     # For Windows x86
 162     prefix='/c/gstreamer/1.0/x86/'
 163
 164     # For Windows x86_64
 165     #prefix='/c/gstreamer/1.0/x86_64'
 166
 167     # For Linux
 168     #prefix='/opt/gstreamer'
 169
 170     # For OS X
 171     #prefix='/Library/Frameworks/GStreamer.framework/Versions/1.0'
 172
 173 The prefix path might not be writable by your current user. Make sure
 174 you fix it before, for instance with:
 175
 176     $ sudo chown -R <username> /Library/Frameworks/GStreamer.framework/
 177
 178 Cerbero has a shell command that starts a new shell with all the
 179 environment set up to target GStreamer. You can start a new shell using
 180 the installation prefix defined in *custom.cbc *with the following
 181 command:
 182
 183     $ cerbero -c custom.cbc shell
 184
 185 Once you are in Cerbero's shell you can compile new projects targeting
 186 GStreamer using the regular build process:
 187
 188     $ git clone git://anongit.freedesktop.org/gstreamer/gst-plugins-good; cd gst-plugins-good
 189     $ sh autogen.sh --disable-gtk-doc --prefix=<prefix>
 190     $ make -C gst/isomp4
 191
 192 ### Cross-compilation of GStreamer
 193
 194 Cerbero can be used to cross-compile GStreamer to other platforms like
 195 Android or Windows. You only need to use a configuration file that sets
 196 the target platform, but we also provide a set of of pre-defined
 197 configuration files for the supported platforms (you will find them in
 198 the `config` folder with the `.cbc` extension
 199
 200 #### Android
 201
 202 You can cross-compile GStreamer for Android from a Linux host using the
 203 configuration file `config/cross-android.cbc`. Replace all the previous
 204 commands with:
 205
 206     cerbero -c config/cross-android.cbc <command>
 207
 208 #### Windows
 209
 210 GStreamer can also be cross-compiled to Windows from Linux, but you should
 211 only use it for testing purpose. The DirectShow plugins cannot be
 212 cross-compiled yet and WiX can't be used with Wine yet, so packages can
 213 only be created from Windows.
 214
 215 Replace all the above commands for Windows 32bits with:
 216
 217     cerbero -c config/cross-win32.cbc <command>
 218
 219 Or with using the following for Windows 64bits:
 220
 221     cerbero -c config/cross-win64.cbc <command>
 222
 223 #### iOS
 224
 225 To cross compile for iOS from OS X, use the configuration file
 226 `config/cross-ios-universal.cbc`. Replace all previous commands with:
 227
 228     cerbero -c config/cross-ios-universal.cbc <command>
 229
 230   [Warning]: images/icons/emoticons/warning.png
 231   [Python 2.7]: http://www.python.org/getit/releases/2.7/
 232   [Git]: http://code.google.com/p/msysgit/downloads/list?q=full+installer+official+git
 233   [Msys/MinGW]: https://sourceforge.net/projects/mingw/files/Installer/mingw-get-inst/
 234   [CMake]: http://www.cmake.org/cmake/resources/software.htm
 235   [Yasm]: http://yasm.tortall.net/Download.html
 236   [WiX 3.5]: http://wix.codeplex.com/releases/view/60102
 237   [Microsoft SDK 7.1]: http://www.microsoft.com/en-us/download/details.aspx?id=8279
 238   [Windows Driver Kit 7.1.0]: http://msdn.microsoft.com/en-us/windows/hardware/hh852365
 239   [XCode]: https://developer.apple.com/devcenter/ios/index.action#downloads
 240   [here]: http://www.freedesktop.org/software/gstreamer-sdk/cerbero.cbc.template
 241   [Installing GStreamer]: sdk-installing.md