better README

Original commit message from CVS:
better README

diff --git a/README b/README
index fb003a9..f60e0d7 100644 (file)
--- a/README
+++ b/README
@@ -1,18 +1,101 @@
-gst-plugins : plug-ins for GStreamer
+WHAT IT IS
+----------
+This is gst-plugins, a set of plug-ins for GStreamer.
 
-* to develop against uninstalled GStreamer core :
-  add path to gstreamer-uninstalled.pc to PKG_CONFIG_PATH
-  or run configure --with-pkg-config-path=(path to gstreamer uninstalled)
+COMPILING FROM SOURCE
+---------------------
+- make sure you compiled and at least did a test-run of GStreamer (core)
+- check output of ./configure --help to see if any options apply to you
+- configure the source tree:
+  - if you installed GStreamer, then do:
+      ./configure
+    If configure complains about missing GStreamer, you should try
+      ./configure --with-pkg-config-path=prefix/lib/pkgconfig
+    where prefix should be replaced by the prefix you used to configure
+    GStreamer.  (Be mindful NOT to ADD a trailing / to that option !)
+    If this doesn't fix it, you have other issues ;)
 
-* to register plug-ins in source tree
-  run gst-register --gst-plugin-path=.
+  - if you didn't install GStreamer, you can still compile the plug-ins.
+    Add the path to gstreamer-uninstalled.pc (which lives in the gstreamer
+    source tree) to PKG_CONFIG_PATH
+    or run configure --with-pkg-config-path=(path to gstreamer uninstalled)
+  
+  - the output of configure will give you a list of plug-ins with external
+    dependencies (ie, depending on other libs, see below).  By no means
+    should you try to get them all built on your first run.  This is hard
+    enough as it is ;)  Resist the urge to get the most features for now.
+    It doesn't list all of the non-depending plug-ins, which get built
+    regardless (unless you explicitly asked it not to).
 
-* if a certain plug-in doesn't build, then redo configure with
-  --disable-(plug-in)
-  to disable it from the build
+- build the tree:
+  make
+  If any plug-in causes a problem at this stage, you should re-configure
+  with --disable-(dependency)
+  and doublecheck if configure reports this plug-in as being disabled.
+  Then re-run make.
 
-* Additional documentation :
+- install:
+  - if you installed GStreamer, and want to install the plug-ins as well, run
+      make install
+    and, as root, run
+      gst-register
+  - if you installed GStreamer, but don't want to install the plug-ins, run
+      gst-register --gst-plugin-path=.
+  - if you didn't install GStreamer, then do
+      path/to/gstreamer/tools/gst-register --gst-plugin-path=.
+      (Replace path/to/gstreamer obviously)
 
+- test:
+  - run 
+     gst-launch sinesrc ! fakesink
+   and prefix gst-launch with the path to gstreamer/tools if you didn't install
+   GStreamer.
+   If this doesn't give any errors, you can abort it.  
+
+  - try replacing fakesink with your choice of 
+    osssink/esdsink/artsdsink/alsasink/jacksink (depending on what output
+    method you have available) and see if you hear a C tone.
+
+- After this, you should look into installing an application, like
+  gst-player, gst-editor or monkey-media with rhythmbox.
+
+COMPILING FROM CVS
+------------------
+When building from CVS sources, you will need to run autogen.sh to generate
+the build system files.
+
+GStreamer is cutting-edge stuff.  To be a CVS developer, you need
+what used to be considered cutting-edge tools.
+
+ATM, most of us have at least these versions :
+
+* autoconf      2.52    (NOT 2.52d)
+* automake      1.5     
+* libtool       1.4     (NOT Gentoo's genetic failure 1.4.2)
+* pkg-config    0.8.0
+
+autogen.sh will check for these versions and complain if you don't have 
+them.  You can also specify specific versions of automake and autoconf with
+--with-automake and --with-autoconf
+
+Check autogen.sh options by running autogen.sh --help
+
+autogen.sh can pass on arguments to configure - you just need to separate them
+from autogen.sh with -- between the two.
+prefix has been added to autogen.sh but will be passed on to configure because
+some build scripts like that.
+You will probably have to pass at least --with-pkg-config-path to autogen.sh
+to point to the CVS version of GStreamer.
+
+When you have done this once, you can use autoregen.sh to re-autogen with
+the last passed options as a handy shortcut.  Use it.
+
+After the autogen.sh stage, you can follow the directions listed in
+"COMPILING FROM SOURCE"
+
+
+PLUG-IN DEPENDENCIES AND LICENSES
+---------------------------------
 GStreamer is developed under the terms of the LGPL (see LICENSE file for 
 details). Some of our plug-ins however rely on libraries which are available 
 under other licenses. This means that if you are using an application which