From 6a15b2b0c5e38e31cbd1b6a7f8bf921ca0507385 Mon Sep 17 00:00:00 2001
From: Stefan Kost <ensonic@users.sf.net>
Date: Wed, 25 Mar 2009 11:03:22 +0200
Subject: [PATCH] docs: add a page about building gstreamer and apps

---
 docs/gst/Makefile.am         |   2 +-
 docs/gst/building.xml        | 100 +++++++++++++++++++++++++++++++++++
 docs/gst/gstreamer-docs.sgml |   1 +
 3 files changed, 102 insertions(+), 1 deletion(-)
 create mode 100644 docs/gst/building.xml

diff --git a/docs/gst/Makefile.am b/docs/gst/Makefile.am
index d3b89d8702..24270ccc00 100644
--- a/docs/gst/Makefile.am
+++ b/docs/gst/Makefile.am
@@ -78,7 +78,7 @@ IGNORE_HFILES= \
 HTML_IMAGES =
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
-content_files = running.xml
+content_files = building.xml running.xml
 
 # Other files to distribute.
 extra_files =
diff --git a/docs/gst/building.xml b/docs/gst/building.xml
new file mode 100644
index 0000000000..da1f15f16f
--- /dev/null
+++ b/docs/gst/building.xml
@@ -0,0 +1,100 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!ENTITY % version-entities SYSTEM "version.entities">
+%version-entities;
+<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+<refentry id="gst-buidling" revision="25 mar 2009">
+<refmeta>
+<refentrytitle>Building GStreamer and GStreamer Applications</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GStreamer Core</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Building GStreamer and GStreamer Applications</refname>
+<refpurpose>
+How to build the GStreamer framework and applications using it.
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Building GStreamer on UNIX</title>
+
+  <!-- this has been borrowed from the glib docs -->
+  <para>
+    On UNIX, GStreamer uses the standard GNU build system,
+    using <application>autoconf</application> for package
+    configuration and resolving portability issues,
+    <application>automake</application> for building makefiles
+    that comply with the GNU Coding Standards, and
+    <application>libtool</application> for building shared
+    libraries on multiple platforms.  The normal sequence for
+    compiling and installing the GStreamer library is thus:
+
+    <literallayout>
+      <userinput>./configure</userinput>
+      <userinput>make</userinput>
+      <userinput>make install</userinput>
+    </literallayout>
+  </para>
+
+  <para>
+    The standard options provided by <application>GNU
+    autoconf</application> may be passed to the
+    <command>configure</command> script.  Please see the
+    <application>autoconf</application> documentation or run
+    <command>./configure --help</command> for information about
+    the standard options.
+  </para>
+
+  <para>
+    In addition there are several option to activate or deactivate features.
+    E.g. passing <option>--disable-gst-debug</option> to <command>configure</command>
+    will turn the debugging subsystem into non-functional stub and remove all
+    macro based invokations from within the library (and anything compiled
+    against the library afterwards)
+  </para>
+  <para>
+    If library size matters and one builds in a controlled environment, its also
+    possible to totaly remove sybsystem code. This is intetionally not offered
+    as a configure option as it causes an ABI break. Code build against a
+    version of GStreamer without these modifications needs to be recompiled.
+
+    <literallayout>
+      <userinput>make CFLAGS="-DGST_REMOVE_DEPRECATED -DGST_REMOVE_DISABLED"</userinput>
+    </literallayout>
+    
+    <itemizedlist>
+      <listitem>
+        <para>
+          <symbol>GST_REMOVE_DEPRECATED</symbol> - Omit deprecated functions
+          from the library.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <symbol>GST_REMOVE_DISABLED</symbol> - Omit stubs for disabled
+          subsytems from the library.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </para>
+
+</refsect1>
+
+<refsect1>
+<title>Building GStreamer Applications</title>
+
+<para>
+Applications and libraries can use <command>pkg-config</command> to get all the
+needed compiler and linker flags building against GStreamer. Please note that
+GStreamer is split into several libraries itself. 
+<command>pkg-config --list-all | grep gstreamer</command> will list the
+available libraries.
+</para>
+
+</refsect1>
+
+</refentry>
diff --git a/docs/gst/gstreamer-docs.sgml b/docs/gst/gstreamer-docs.sgml
index b7ae9f7271..76e937857b 100644
--- a/docs/gst/gstreamer-docs.sgml
+++ b/docs/gst/gstreamer-docs.sgml
@@ -33,6 +33,7 @@ Windows.  It is released under the GNU Library General Public License
 (GNU LGPL).
     </para>
 
+    <xi:include href="building.xml" />
     <xi:include href="running.xml" />
   </chapter>