Update, organize, and improve debian/README.source

debian/README.source

 FreeSWITCH for Debian
 =====================
 
+Introduction
+------------
+
 You may be reading this because you're wondering where all the files
 are in debian/, such as control.  You may also be here looking for the
 sound or music packages.  Read on.
@@ -11,6 +14,9 @@ mostly in the file debian/bootstrap.sh.  This bootstrap needs to run
 before any other step of the packaging, though we do try to
 autogenerate it when possible.
 
+The debian/control-modules file
+-------------------------------
+
 The build dependencies, runtime dependencies, and other details about
 modules can be configured in the debian/control-modules file.  Even
 though this file looks a bit like a debian control file and has a
@@ -36,6 +42,9 @@ control-modules file is properly formatted, this generated file should
 be identical.  This is a sanity check mechanism for our parsing, as
 well as a way to automatically reorganize the file.
 
+The debian/modules.conf file
+----------------------------
+
 If the file debian/modules.conf is present, we read that file and only
 build and package the files listed there.  Otherwise, we build every
 module except the ones that either should not be packaged, or for
@@ -46,12 +55,88 @@ The format of debian/modules.conf is:
     ## comments should start with two hash characters
     <category>/<module_name>
 
-To build this package, I recommend running the following from the root
-directory of your FS git working tree:
+Getting the FreeSWITCH sources
+------------------------------
+
+Everything that follows will assume that you're in the base directory
+of a FreeSWITCH git repository.  You can achieve this with:
+
+    aptitude update && aptitude install -y git
+    mkdir -p /usr/src/freeswitch
+    git clone git://git.freeswitch.org/freeswitch /usr/src/freeswitch/src
+    cd /usr/src/freeswitch/src
+
+Ensuring you have a clean build directory
+-----------------------------------------
+
+Every time you start over, you should make sure your build directory
+is perfectly clean and clear of untracked files.  You can accomplish
+this with:
+
+    git clean -fdx && git reset --hard origin/master
+
+Using the packaging to do a normal build
+----------------------------------------
+
+Let's say you don't want to build the Debian packages; you just want
+to build FS.  You'll need certain dependencies installed on your
+system to do this.  And you probably want to configure FS in the same
+way we do for the packaging.  You can let the packaging files do this
+work for you so you don't have to manually keep track of which
+dependencies are required to build FS.  Build as follows:
+
+    aptitude update && aptitude install -y devscripts equivs build-essential
+    my_release=$(awk '/deb .*\/debian/{print $3; exit}' /etc/apt/sources.list)
+    (cd debian && ./bootstrap.sh -c $my_release)
+    mk-build-deps -i
+    make -f debian/rules .stamp-configure && make
+
+Building the Debian packaging
+-----------------------------
+
+If you want actualy Debian binary or source packages to upload to your
+own repository, you'll need to build them as described here.  We have
+some fancy automatic tools to accomplish this.  The tools allow you to
+start from a very bare Debian image and generate working packages.
+Simply run:
+
+    ./debian/util.sh build-all -ibn -z9
+
+Building only some modules
+--------------------------
+
+If you don't need all the modules to build, create a modules.conf file
+outside of your source tree and pass the -f option to build-all.  e.g.:
+
+    echo "applications/mod_commands" > /tmp/modules.conf
+    ./debian/util.sh build-all -ibn -z9 -f /tmp/modules.conf
+
+Testing a particular module under packaging
+-------------------------------------------
+
+If you need to build a small set of modules for compile testing in the
+pbuilder environment, you can run:
+
+    ./debian/util.sh build-all -dni -z1 -a amd64 -c sid -l "applications/mod_commands"
+
+Getting help with debian/util.sh
+--------------------------------
+
+The debian/util.sh has many options.  You can see the documentation
+for these options by running:
+
+    ./debian/util.sh -h
+
+Building Debian packages without util.sh
+----------------------------------------
+
+Building the packages without util.sh is not recommended as util.sh
+takes care of many non-trivial details.  If needed, however, the
+packages can be built:
 
     distro=sid
     ver="$(cat build/next-release.txt | sed -e 's/-/~/g')~n$(date +%Y%m%dT%H%M%SZ)-1~${distro}+1"
-    git clean -fdx && git reset --hard HEAD
+    git clean -fdx && git reset --hard origin/master
     ./build/set-fs-version.sh "$ver"
     git add configure.in && git commit -m "bump to custom v$ver"
     (cd debian && ./bootstrap.sh -c $distro)
@@ -63,8 +148,6 @@ To build for a stable branch, do this:
 
     distro=sid # update as needed
     stable_ver="1.2.1" # update as needed
-    # if you only want to build some modules, put them one per line here, e.g.:
-    #echo "applications/mod_commands" >> debian/modules.conf
     ver="$(echo "$stable_ver" | sed -e 's/-/~/g')~n$(date +%Y%m%dT%H%M%SZ)-1~${distro}+1"
     git clean -fdx && git reset --hard refs/tags/v${stable_ver}
     ./build/set-fs-version.sh "$ver"
@@ -74,26 +157,8 @@ To build for a stable branch, do this:
     dpkg-buildpackage -b -us -uc -Zxz -z9
     git reset --hard origin/master
 
-Alternatively, you can build using our automated tools.  To build the
-source packages and all supported binary packages for sid, wheezy,
-squeeze on i386 and amd64, run the following as root from a clean
-Debian sid 'buildd' image:
-
-    aptitude update && aptitude upgrade
-    aptitude install -y git
-    mkdir /usr/src/freeswitch
-    git clone git://git.freeswitch.org/freeswitch /usr/src/freeswitch/src
-    cd /usr/src/freeswitch/src
-    # if you only want to build some modules, create a modules.conf
-    # outside the source tree and add -f ../path/to/modules.conf to the
-    # command below.  See ./debian/util.sh -h for further usage
-    # information.
-    ./debian/util.sh build-all -ibn -z9
-
-If you need to build a small set of modules for compile testing in the
-pbuilder environment, run something like:
-
-    ./debian/util.sh build-all -dni -z1 -a amd64 -c sid -l "applications/mod_commands"
+Building the freeswitch-sounds and freeswitch-music packages
+------------------------------------------------------------
 
 The source packages for sounds and music on hold are maintained in a
 separate repository.  Each set of sounds has a separate version number
@@ -107,4 +172,4 @@ freeswitch-music-*:
     git clone https://github.com/traviscross/freeswitch-sounds.git
     cd freeswitch-sounds && cat debian/README.source
 
- -- Travis Cross <tc@traviscross.com>, Sun, 23 Feb 2014 17:08:30 +0000
+ -- Travis Cross <tc@traviscross.com>, Sun, 23 Feb 2014 17:44:32 +0000