Improving documentation for bundling.

Added some copyright headers, enhanced the README, added notes
about the sources and their usage in the source headers.

5 files changed, 163 insertions, 54 deletions

diff --git a/build/linux/AppRun b/build/linux/AppRun
index 237f4647..9e29e57c 100755
--- a/build/linux/AppRun
+++ b/build/linux/AppRun
@@ -1,4 +1,24 @@
 #!/bin/sh
+#
+# Copyright (C) Tristan Van Berkom <tristan@upstairslabs.com>
+#
+# This library is free software; you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License as
+# published by the Free Software Foundation; either version 2.1 of
+# the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public 
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+# Authors:
+#   Tristan Van Berkom <tristan@upstairslabs.com>
+#
 
 # This needs to be set to /home/username/AppImages/Install
 INSTALL_PREFIX=/home/tristan/AppImages/Install
diff --git a/build/linux/LibcWrapGenerator.vala b/build/linux/LibcWrapGenerator.vala
index 6844e352..5a26638c 100644
--- a/build/linux/LibcWrapGenerator.vala
+++ b/build/linux/LibcWrapGenerator.vala
@@ -19,8 +19,35 @@
  * Authors:
  *   Jan Niklas Hasse <jhasse@gmail.com>
  *   Tristan Van Berkom <tristan@upstairslabs.com>
+ *
+ *
+ * This program is used to generate a header safely selecting the ABI
+ * glibc requirement.
+ *
+ * The resulting program can be run as such:
+ *
+ *      ./LibcWrapGenerator libcwrap.h 2.7 /path/to/libc/runtime/libraries
+ *
+ * This will generate a libcwrap.h which should be included by any
+ * C/C++ sources before anything else, redirecting any references
+ * to glibc symbols > 2.7 to symbols from previous versions.
+ *
+ * For symbols which are found to be new after 2.7, those will be
+ * redirected to symbol@GLIBC_DONT_USE_THIS_SYMBOL_2.10 (or whichever
+ * version the said symbol was actually added in)
+ *
+ * This will generate a link error at compile time, it is possible
+ * however unlikely that these link errors will occur, if they do
+ * you must patch the sources in such a way that those glibc symbols
+ * which generated the link error are not accessed.
+ *
+ * Sources should also be compiled with -U_FORTIFY_SOURCE as some
+ * compilers build in _FORTIFY_SOURCE by default, enabling some
+ * glibc runtime checkers to be linked into your source code.
+ *
+ * We recommend disabling _FORTIFY_SOURCE since most of the runtime
+ * checkers are only available in relatively recent versions of glibc.
  */
-
 using GLib;
 
 /***************************************************************
diff --git a/build/linux/PrepareAppDir.sh b/build/linux/PrepareAppDir.sh
index 0f009860..3419cd38 100755
--- a/build/linux/PrepareAppDir.sh
+++ b/build/linux/PrepareAppDir.sh
@@ -1,5 +1,5 @@
 #!/bin/sh
-
+#
 # Used to prepare the AppDir bundle directory. -*- mode: sh -*-
 #
 # Written by Tristan Van Berkom <tristan@upstairslabs.com>
@@ -21,21 +21,24 @@
 # Usage:
 #
 # ./PrepareAppDir.sh /path/to/AppImage/Install /path/to/glade
-#
 
 APP_DIR_ROOT=$1
 GLADE_DIR=$2
 
-echo -n "Removing static archives and libtool cruft... "
+if test -z ${APP_DIR_ROOT} || test -z ${GLADE_DIR}; then
+    echo "Usage ./PrepareAppDir.sh /path/to/AppImage/Install /path/to/glade"
+    exit 0;
+fi
+
+echo -n "Removing various unwanted files from the image... "
+# Remove static libraries and libtool archives
 rm -f `find ${APP_DIR_ROOT} -name "*.a"`
 rm -f `find ${APP_DIR_ROOT} -name "*.la"`
-echo "Done."
 
-echo -n "Removing includes... "
+# Remove include directory
 rm -rf ${APP_DIR_ROOT}/include
-echo "Done."
 
-echo -n "Removing uwanted shared data... "
+# Remove various stuff in /share
 rm -rf ${APP_DIR_ROOT}/share/man
 rm -rf ${APP_DIR_ROOT}/share/info
 rm -rf ${APP_DIR_ROOT}/share/help
@@ -53,15 +56,17 @@ rm -rf ${APP_DIR_ROOT}/share/dbus-1
 rm -rf ${APP_DIR_ROOT}/share/glib-2.0/codegen
 rm -rf ${APP_DIR_ROOT}/share/glib-2.0/gdb
 rm -rf ${APP_DIR_ROOT}/share/glib-2.0/gettext
-echo "Done."
 
-echo -n "Removing unwanted binaries... "
+# Remove the binaries we dont need
 mv ${APP_DIR_ROOT}/bin/glade ${APP_DIR_ROOT}/glade
 mv ${APP_DIR_ROOT}/bin/glade-previewer ${APP_DIR_ROOT}/glade-previewer
 rm -f ${APP_DIR_ROOT}/bin/*
 mv ${APP_DIR_ROOT}/glade ${APP_DIR_ROOT}/bin
 mv ${APP_DIR_ROOT}/glade-previewer ${APP_DIR_ROOT}/bin
 rm -f ${APP_DIR_ROOT}/libexec/*
+
+# jhbuild meta directory
+rm -rf ${APP_DIR_ROOT}/_jhbuild
 echo "Done."
 
 echo -n "Removing encoded rpath from all binaries... "
@@ -92,7 +97,7 @@ echo "Done."
 
 echo -n "Installing desktop file and runner script... "
 cp ${APP_DIR_ROOT}/share/applications/glade.desktop ${APP_DIR_ROOT}
-cp ${GLADE_DIR}/build/linux64/AppRun ${APP_DIR_ROOT}
+cp ${GLADE_DIR}/build/linux/AppRun ${APP_DIR_ROOT}
 echo "Done."
 
 echo -n "Fixing pixbuf loaders to have bundle relative paths... "
diff --git a/build/linux/README b/build/linux/README
index 4c1bc7a4..eb4e6915 100644
--- a/build/linux/README
+++ b/build/linux/README
@@ -1,12 +1,11 @@
 Instructions on how to build a bundle for 64bit linux systems.
 
-
 System requirements
 ~~~~~~~~~~~~~~~~~~~
 
   o A 64bit linux system
 
-  o AppImageKit (https://github.com/tristanvb/AppImageKit/)
+  o AppImageKit (https://github.com/probonopd/AppImageKit)
 
     To build AppImageKit, you will require:
       - A functional cross compiler to generate 32bit binaries as well as 64bit binaries
@@ -27,6 +26,8 @@ System requirements
     This will be required after your build root is complete, we use it to strip out the -rpaths which
     libtool loves to embed into binaries.
 
+  o Vala compiler, we'll be using valac --pkg gee-0.8 --pkg posix --pkg glib-2.0 --pkg gio-2.0
+
 
 Build Instructions
 ~~~~~~~~~~~~~~~~~~
@@ -36,57 +37,94 @@ We will refer to your Glade checkout or tarball directory as ${GLADE_CHECKOUT},
 this to be a "/full/path/to/the/checkout/of/glade"
 
 
-Building AppImageKit
-~~~~~~~~~~~~~~~~~~~~
-Fetch AppImageKit form https://github.com/tristanvb/AppImageKit/
+  Build the LibcWrapGenerator
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  To update the libcwrap.h for your system's version of glibc, first you must build
+  the LibcWrapGenerator like so:
 
-To build follow these steps:
+    cd ${GLADE_CHECKOUT}/build/linux
+    valac  --pkg gee-0.8 --pkg posix --pkg glib-2.0 --pkg gio-2.0 LibcWrapGenerator.vala
 
-  cd AppImageKit
-  export CC='gcc -U_FORTIFY_SOURCE -include ${GLADE_CHECKOUT}/build/linux64/libcwrap.h'
-  cmake .
-  make
-  unset CC
+  Note that the environment in which you choose to build and run the generator is of
+  absolutely no consequence, I had to build & run this from an existing jhbuild environment
+  because I lacked the gee-0.8, this is absolutely not a problem.
 
-This trick with overriding CC should build your AppImageKit in such a way that
-it depends only on the glibc 2.7 ABI.
 
+  Updating libcwrap.h
+  ~~~~~~~~~~~~~~~~~~~
+  The libcwrap.h header file is the magick which ensures that you target a specific
+  version of the glibc ABI.
 
-Building the AppDir
-~~~~~~~~~~~~~~~~~~~
-The AppDir is what AppImageKit refers to as the root filesystem inside the
-bundle.
+  To generate the libcwrap.h file, run the generator like so:
 
-The provided jhbuild scripts will create a directory in your ${HOME} named
-'AppImages', if you already have a jhbuild environment there is no need to worry,
-our scripts do not interfere with your existing jhbuild environment.
+    cd ${GLADE_CHECKOUT}/build/linux
+    ./LibcWrapGenerator libcwrap.h 2.7 /path/to/libc/runtime/libraries
 
-To build the whole stack up to Glade, including Glade, issue this command:
+  We recommend using 2.7 as a stable base glibc requirement, the patches
+  for this bundle (which are only a few) allow usage of glibc 2.7 and later.
 
-    GLADE_DIR=${GLADE_CHECKOUT} jhbuild -f ${GLADE_CHECKOUT}/build/linux64/jhbuildrc build glade
+  The path to your libc runtime should be a directory containing libc.so.6
+  and other libc runtime libraries, some systems keep this in different
+  directories (i.e. /lib/x86_64-linux-gnu, /lib, /lib64 are good bets).
 
-Some post processing is needed on the AppDir, we intentionally keep this separate from
-the jhbuild setup. To perform the needed post processing, issue this command:
+  For a more detailed explanation of what libcwrap.h does, look into the
+  file header of LibcWrapGenerator.vala.
 
-    ${GLADE_CHECKOUT}/build/linux64/PrepareAppDir.sh ${HOME}/AppImages/Install ${GLADE_CHECKOUT}
 
-The script takes the path to the AppDir, which is hard coded to be in your ${HOME},
-as well as the path to your glade checkout.
+  Building AppImageKit
+  ~~~~~~~~~~~~~~~~~~~~
+  Fetch AppImageKit form https://github.com/probonopd/AppImageKit/
 
-Finally, you need to add the AppRun program to your AppDir:
+  To build follow these steps:
 
-    cp /path/to/AppImageKit/AppRun ${HOME}/AppImages/Install
+    cd AppImageKit
+    export CC='gcc -U_FORTIFY_SOURCE -include ${GLADE_CHECKOUT}/build/linux/libcwrap.h'
+    cmake .
+    make
+    unset CC
 
-This should give you a fully functional image in ${HOME}/AppImages/Install
 
+  Building the stack
+  ~~~~~~~~~~~~~~~~~~
+  The AppDir is what AppImageKit refers to as the root filesystem inside the
+  bundle.
 
-Bundling the AppDir
-~~~~~~~~~~~~~~~~~~~
+  The provided jhbuild scripts will create a directory in your ${HOME} named
+  'AppImages', all of our building & bundling will take place inside this directory.
+
+  Note, if you already have a jhbuild environment there is no need to worry,
+  our scripts do not interfere with your existing jhbuild environment.
+
+  To build the whole stack up to Glade, including Glade, issue this command:
+
+    GLADE_DIR=${GLADE_CHECKOUT} jhbuild -f ${GLADE_CHECKOUT}/build/linux/jhbuildrc build glade
+
+  I've found the build to break sometimes at 'shared-mime-info', in this case I just rerun
+  the above command and it passes on the second try... nothing to see here... carry on...
+
+
+  Post processing the image directory
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  Some post processing is needed on the AppDir, we intentionally keep this separate from
+  the jhbuild setup. To perform the needed post processing, issue this command:
+
+    ${GLADE_CHECKOUT}/build/linux/PrepareAppDir.sh ${HOME}/AppImages/Install ${GLADE_CHECKOUT}
+
+  WARNING: The above script will modify the ${HOME}/AppImages/Install directory in such
+  a way that it cannot be rebuilt (development headers and unneeded cruft is removed
+  from the installation directory). This is why we use a script as a separate stage from
+  building.
+
+  At this point, you should have a fully functional image in ${HOME}/AppImages/Install
+
+
+Bundling
+~~~~~~~~
 Build the bundle with one simple command:
 
-    /path/to/AppImageKit/AppImageAssistant ${HOME}/AppImages/Install glade
+    /path/to/AppImageKit/AppImageAssistant ${HOME}/AppImages/Install /path/to/generated/glade
 
-This will create a huge binary named 'glade'
+This will create a huge binary named 'glade' at the location of your choosing.
 
 
 Running and Debugging the bundle
@@ -110,13 +148,17 @@ and which are properly pulled from the bundle. We've intentionally
 left out X11 libraries, fontconfig and freetype, so these should
 be pulled from somewhere in your system directories.
 
-    LD_DEBUG=bindings ./bin/glade > ${HOME}/bindings.log 2>&1
+    LD_DEBUG=all ./bin/glade > ${HOME}/bindings.log 2>&1
 
 This will create a log of all the symbol bindings, you may want
-to check here if anything symbol originating in the bundle is bound
+to check here if any symbol originating in the bundle is bound
 to GLIBC > 2.7, the intention with this configuration is to aim
 for a low glibc dependency, if libraries inside your bundle require
 a higher libc version than 2.7 then the libcwrap.h file probably
 needs to be regenerated (the committed version should work for
 glibc ABI versions up to 2.15).
 
+Note that as we rely on the system's Xlib libraries, fontconfig
+and freetype libraries, there will be references to GLIBC > 2.7
+from those system libraries, this is not a problem at all as they
+will be resolved differently on hosts with older glibc.
diff --git a/build/linux/jhbuildrc b/build/linux/jhbuildrc
index 52dd7fb2..57dcb834 100644
--- a/build/linux/jhbuildrc
+++ b/build/linux/jhbuildrc
@@ -1,6 +1,25 @@
 # -*- mode: python -*-
 # -*- coding: utf-8 -*-
-
+#
+# Copyright (C) Tristan Van Berkom <tristan@upstairslabs.com>
+#
+# This library is free software; you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License as
+# published by the Free Software Foundation; either version 2.1 of
+# the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public 
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+# Authors:
+#   Tristan Van Berkom <tristan@upstairslabs.com>
+#
 use_local_modulesets = True
 modulesets_dir = os.getenv('GLADE_DIR') + '/build/linux/modulesets'
 moduleset = 'bundle.modules'
@@ -8,12 +27,9 @@ moduleset = 'bundle.modules'
 # Unset autogenargs (screws with some modules like freetype)
 autogenargs = ''
 
+# This causes jhbuild to fire some sort of warning, but no problem...
 build_cflags = ''
 
-# For 32bit builds, build for 32bit arches
-if os.environ.get('BUILD_32BIT') is not None:
-    build_cflags = ' -m32'
-
 # _FORTIFY_SOURCE can be defined by default in some compilers
 # we want to unset this because glibc's runtime checkers are only
 # available in recent versions of glibc
@@ -31,7 +47,6 @@ build_cflags += ' -include ' + os.getenv('GLADE_DIR') + '/build/linux/libcwrap.h
 # ensures that they come before any flags that any buildscripts might add
 os.environ['CC']  = 'gcc ' + build_cflags
 os.environ['CXX'] = 'g++ ' + build_cflags
-build_cflags = None
 
 # Enable our custom triggers
 os.environ['JHBUILD_TRIGGERS'] = os.getenv('GLADE_DIR') + '/build/linux/triggers'
@@ -53,5 +68,5 @@ prefix = '~/AppImages/Install'
 use_lib64 = False
 
 # Uncomment this for verbose builds
-makeargs = "V=1"
+# makeargs = "V=1"