Tim-Philipp Müller | e5ea6c4 | 2013-04-22 23:52:20 +0100 | [diff] [blame] | 1 | ================================= |
| 2 | GStreamer Static Linking README |
| 3 | ================================= |
| 4 | |
| 5 | DRAFT, April 2013 |
| 6 | |
| 7 | |
| 8 | I. INTRODUCTION |
| 9 | |
| 10 | It is possible to link GStreamer libraries, plugins and applications |
| 11 | statically, both in case of free/libre/open-source software applications |
| 12 | and proprietary applications. On some platforms static linking may even |
| 13 | be required. |
| 14 | |
| 15 | However, distributing statically linked binaries using GStreamer usually |
| 16 | requires additional effort to stay compliant with the GNU LGPL v2.1 license. |
| 17 | |
| 18 | The purpose of this document is to draw attention to this fact, and to |
| 19 | summarise in layman's terms what we believe is required from anyone |
| 20 | distributing statically linked GStreamer binaries. Most of this also |
| 21 | applies to dynamically linked GStreamer binaries. |
| 22 | |
| 23 | |
| 24 | II. DISCLAIMER |
| 25 | |
| 26 | This document is not legal advice, nor is it comprehensive. It may use |
| 27 | words in ways that do not match the definition or use in the license |
| 28 | text. It may even be outright wrong. Read the license text for all the |
| 29 | details, it is the only legally binding document in this respect. |
| 30 | |
| 31 | This document is primarily concerned with the implications for the |
| 32 | distribution of binaries based on LGPL-licensed software as imposed by |
| 33 | the LGPL license, but there may be other restrictions to the distribution |
| 34 | of such binaries, such as terms and conditions of distribution channels |
| 35 | (e.g. "app stores"). |
| 36 | |
| 37 | |
| 38 | III. THE SPIRIT OF THE LGPL LICENSE |
| 39 | |
| 40 | The GNU LGPL v2.1 license allows use of such-licensed software by |
| 41 | proprietary applications, but still aims to ensure that at least the |
| 42 | LGPL-licensed software parts remain free under all circumstances. This |
| 43 | means any changes to LGPL-licensed source code must be documented and |
| 44 | be made available on request to those who received binaries of the |
| 45 | software. It also means that it must be possible to make changes to the |
| 46 | LGPL-licensed software parts and make the application use those, as far |
| 47 | as that is possible. And that recipients of an application using |
| 48 | LGPL-licensed software are made aware of their rights according to the |
| 49 | LGPL license. |
| 50 | |
| 51 | In an environment where GStreamer libraries and plugins are used as |
| 52 | dynamically-loaded shared objects (DLL/.so/.dyn files), this is usually |
| 53 | not a big problem, because it is fairly easy to compile a modified version |
| 54 | of the GStreamer libraries or LGPL plugins, and the application will/should |
| 55 | just pick up and use the modified version automatically. All that is needed |
| 56 | is for the original, LGPL-licensed source code and source code modifications |
| 57 | to be made available, and for a way to build the libraries or plugins for |
| 58 | the platform required (usually that will be using the build system scripts |
| 59 | that come with GStreamer, and using the typical build environment on the |
| 60 | system in question, but where that is not the case the needed build scripts |
| 61 | and/or tools would need to be provided as well). |
| 62 | |
| 63 | |
| 64 | IV. THINGS YOU NEED TO DO |
| 65 | |
| 66 | * You must tell users of your application that you are using LGPL-licensed |
| 67 | software, which LGPL-licensed software exactly, and you must provide them |
| 68 | with a copy of the license so they know their rights under the LGPL. |
| 69 | |
| 70 | * You must provide (on request) all the source code and all the changes |
| 71 | or additions you have made to the LGPL-licensed software you are using. |
| 72 | |
| 73 | For GStreamer code we would recommend that the changes be provided either |
| 74 | in form of a branch in a git repository, or as a set of "git format-patch"- |
| 75 | style patches against a GStreamer release or a snapshot of a GStreamer git |
| 76 | repository. The patches should ideally say what was changed and why it |
| 77 | was changed, and there should ideally be separate patches for independent |
| 78 | changes. |
| 79 | |
| 80 | * You must provide a way for users of your application to make changes to |
| 81 | the LGPL-licensed parts of the code, and re-create a full application |
| 82 | binary with the changes (using the standard toolchain and tools of the |
| 83 | target platform; if you are using a custom toolchain or custom tools |
| 84 | you must provide these and document how to use them to create a new |
| 85 | application binary). |
| 86 | |
| 87 | Note that this of course does not mean that the user is allowed to |
| 88 | re-distribute the changed application. Nor does it mean that you have |
| 89 | to provide your proprietary source code - it is sufficient to provide a |
| 90 | ready-made compiled object file that can be relinked into an application |
| 91 | binary with the re-compiled LGPL components. |
| 92 | |
| 93 | |
| 94 | V. THINGS TO LOOK OUT FOR |
| 95 | |
| 96 | While most GStreamer plugins and the libraries they depend on are licensed |
| 97 | under the LGPL or even more permissive licenses, that is not the case for |
| 98 | all plugins and libraries used, esp. those in the gst-plugins-ugly or |
| 99 | some of those in the gst-plugins-bad set of plugins. |
| 100 | |
| 101 | When statically linking proprietary code, care must be taken not to |
| 102 | statically link plugins or libraries that are licensed under less permissive |
| 103 | terms than the LGPL, such as e.g. GPL-licensed libraries. |
| 104 | |
| 105 | |
| 106 | VI. SPECIAL CONSIDERATIONS FOR SPECIFIC USE-CASES |
| 107 | |
| 108 | |
| 109 | 1. Proprietary GStreamer/GLib-based Application On iOS |
| 110 | |
| 111 | Let's assume an individual or a company wants to distribute a proprietary |
| 112 | iOS application that is built on top of GStreamer and GLib through |
| 113 | Apple's App Store. At the time of writing the Apple iPhone developer |
| 114 | agreement didn’t allow the bundling of shared libraries, so distributing |
| 115 | a proprietary iOS application with shared libraries is only possible using |
| 116 | distribution mechanisms outside of the App Store and/or only to jailbroken |
| 117 | devices, a prospect that may not appeal to our individual or company. So the |
| 118 | only alternative then is to link everything statically, which means the |
| 119 | obligations mentioned above come into play. |
| 120 | |
| 121 | |
| 122 | 2. Example: Jabber on iOS |
| 123 | |
| 124 | Tandberg (now Cisco) created a Jabber application for iOS, based on GStreamer. |
| 125 | On request they provided an LGPL compliance bundle in form of a zip file, with |
| 126 | roughly the following contents: |
| 127 | |
| 128 | buildapp.sh |
| 129 | readme.txt |
| 130 | Jabber/Jabber-Info.plist |
| 131 | Jabber/libip.a [236MB binary with proprietary code] |
| 132 | Jabber/main.mm |
| 133 | Jabber/xcconfig/Application.xcconfig |
| 134 | Jabber/xcconfig/Debug.xcconfig |
| 135 | Jabber/xcconfig/Release.xcconfig |
| 136 | Jabber/xcconfig/Shared.xcconfig |
| 137 | Jabber/Resources/*.lproj/Localizable.strings |
| 138 | Jabber/Resources/{Images,Audio,Sounds,IB,Message Styles,Emoticons,Fonts}/* |
| 139 | Jabber/Resources/* |
| 140 | Jabber.xcodeproj/project.pbxproj |
| 141 | Jabber.xcodeproj/project.xcworkspace/contents.xcworkspacedata |
| 142 | opensource/build/config.site |
| 143 | opensource/build/m4/movi.m4 |
| 144 | opensource/build/scripts/clean-deps.sh |
| 145 | opensource/build/scripts/fixup-makefile.sh |
| 146 | opensource/build/scripts/MoviMaker.py |
| 147 | opensource/build.sh |
| 148 | opensource/env.sh |
| 149 | opensource/Makefile |
| 150 | opensource/external/glib/* |
| 151 | opensource/external/gstreamer/{gstreamer,gst-plugins-*}/* |
| 152 | opensource/external/openssl/* |
| 153 | opensource/external/proxy-libintl/* |
| 154 | opensource/toolchain/darwin-x86/bin/{misc autotoools,m4,glib-mkenums,glib-genmarshal,libtool,pkg-config,etc.} |
| 155 | opensource/toolchain/darwin-x86/share/{aclocal,aclocal-1.11,autoconf,automake-1.11,libtool}/* |
| 156 | opensource/toolchain/darwin-x86/share/Config.pm |
| 157 | opensource/toolchain/darwin-x86/share/Config.pm.movi.in |
| 158 | patches/glib/glib.patch |
| 159 | patches/gst-plugins-bad/gst-plugins-bad.patch |
| 160 | patches/gst-plugins-base/gst-plugins-base.patch |
| 161 | patches/gst-plugins-good/gst-plugins-good.patch |
| 162 | patches/gstreamer/gstreamer.patch |
| 163 | patches/openssl/openssl.patch |
| 164 | |
| 165 | readme.txt starts with "This Readme file describes how to build the Cisco |
| 166 | Jabber for iPad application. You need to install Xcode, but the final package |
| 167 | is built by running buildapp.sh." and describes how to build project, |
| 168 | prerequisites, the procedure in detail, and a "How to Include Provisioning |
| 169 | Profile Manually / Alternate Code Signing Instructions" section. |
| 170 | |
| 171 | |
| 172 | 3. Random Links Which May Be Of Interest |
| 173 | |
| 174 | [0] http://multinc.com/2009/08/24/compatibility-between-the-iphone-app-store-and-the-lgpl/ |