tb: Update Documentation

2 files changed, 66 insertions, 36 deletions

diff --git a/tb/tb b/tb/tb
index 1946808..b44df7c 100755
--- a/tb/tb
+++ b/tb/tb
@@ -5,6 +5,12 @@
 #    License: GPLv3
 #
 
+#
+# ATTENTION Developers: see tb_internal.sh for information
+# about design, naming conventions etc...
+#
+
+# run debug=1 tb ... to debug
 if [ -n "$debug" ] ; then
     set -x
 fi
@@ -108,6 +114,9 @@ In other words: B prevail over P, which prevail over G.
 
 The following variables can be specified in tb's configuration files.
 
+CCACHE_DIR=<path> This is to override the normal ccache environment variable.
+                  This allow to have a per profile, or even better, a per branche
+                  cache.
 TB_BIBISECT_DIR=<path> Location of a git bibisect repository
                        This is a tb-mode only paramter. This is ingored in gerrit mode
                        This is a tb-mode only paramter. This is ingored in gerrit mode
@@ -135,6 +144,9 @@ TB_BRANCH_REMOTE_REFSPEC=<ref> Name of the branch on the remote repo.
                                This is a tb-mode only paramter. This is ingored in gerrit mode
 TB_BUILD_DIR=<path> Directory to use a a build directory. If specified, it must exist.
                     Default to TB_GIT_DIR.
+TB_CCACHE_SIZE=<size> When CCACHE is specified at a profile or branche level
+                      if TB_CCACHE_SIZE as a value it is used to run
+                      ccache -M <size> to insure that the cache has the appropriate size
 TB_DEFAULT_MODE=[gerrit|gerrit-tb|tb-gerrit|tb] Default mode of operation.
                                                 This is a G or P level parameter
                                                 The command line --mode= override both level.
@@ -146,6 +158,13 @@ TB_GIT_DIR=<path> Location of the libreoffice core git repo to use for a build.
                   This parameter is mandatory.
 TB_ID=<integer> Id of the tinderbox. see http://wiki/documentfoundation.org/Development/Tinderbox
                 for information on how to acquire such an ID.
+TB_INCREMENTAL=[0|1] Indicate that one want to do incremental build, iow skip the clean phase
+                     This apply only to tb build, as tb build are normally progressive
+                     in time, whereas gerrit build can be all over the place...
+                     This only make sens if each branch that is meant to be built incrementally
+                     has it's own build directory (which for now also mean its own git repo
+                     at least until gbuildification is complete and the source tree is finaly
+                     treated as a read-only zone.
 TB_LOGFILE=<path> File where tb will log message about it's operation.
                   The file does not have to exist, but the path containing the file must.
                   This is only for message issued by tb itself.. this does no relate to build
diff --git a/tb/tb_internals.sh b/tb/tb_internals.sh
index fa5b220..b3225d9 100644
--- a/tb/tb_internals.sh
+++ b/tb/tb_internals.sh
@@ -4,8 +4,8 @@
 #    Copyright (C) 2011-2013 Norbert Thiebaud
 #    License: GPLv3
 #
-
-# Naming convention
+#
+# Naming convention/Namespace
 #
 # lowercase variable: local variable. must be declared as 'local'
 #
@@ -17,11 +17,47 @@
 #
 # Exception: P : project name
 #            B : current branch name. gerrit_* are reserved branch names for gerrit works
-#            R : build result indicator
-#            V : verbose messages
+#            R : build result indicator ( 0=OK 1=KO 2=False positive )
+#            V : verbose messages (V=1 => verbose message V= => no verbose message, iow: [ $V ] && msgs_log ....
 #         MAKE : environement variable is use if set to point to a gnu-make
 #                otherwise overriden to a gne-make found in the PATH
 #
+# profile_* reserved for functions specific to .../<profile_name>/phases.sh
+# branches_* reserved for functions specific to .../<branch_name>/phases.sh
+# canonical_* reserverved for phase implementation in tb_phases.sh
+# canonical_[pre|do|post]_<phase> is garanteed to exist, even if it is a no-op function.
+#
+# The rational for these namespace is to allow lower-level overload to still call
+# the implementation at higher level.
+#
+# for instance if a branche phase.sh want derefine the TMPDIR and clean it up
+# in the pre-clean phase, but still want to do what-ever the tb_phase.sh normally do
+# it can implement
+# pre_clean()
+# {
+#    do what I need to do
+#    canonical_pre_clean() to invoke the defautl impelmentation
+# }
+#
+# similarely at the profile level one can override pre-clean in this fashion:
+#
+# profile_pre_clean()
+# {
+#     profile override implementation fo pre-clean()
+# }
+#
+# pre_clean()
+# {
+#     profile_pre_clean()
+# }
+#
+# that way a branch's phase.sh can invoke profile_pre_clean in it's own implemenation of pre_clean()
+#
+# ATTENTION: do not abuse this scheme by having defferent level invoking different phase
+# at higher level... so a branch's pre_clean() for instance shall not invoke canonical_do_clean()
+# or any other phase than *_pre_clean()
+# Obviously profile level phase.sh shall not invoke any branche_* functions.
+#
 # Configuration files layout
 #
 #  ~/.tb/config
@@ -44,40 +80,8 @@
 # Note: config are accumulated from high to low.
 #       autogen are 'lowest level prime'.
 
-
 # XRef :
 #
-# TB_BIBISECT_DIR :
-# TB_BIBISECT_GC :
-# TB_BIBISECT_PUSH :
-# TB_BIBISECT :
-# TB_BRANCHES :
-# TB_BRANCH_LOCAL_REFSPEC :
-# TB_BRANCH_REMOTE_REFSPEC :
-# TB_BUILD_DIR :
-# TB_CONFIG_DIR :
-# TB_DEFAULT_MODE:-tb :
-# TB_DO_TESTS :
-# TB_GERRIT_BRANCH :
-# TB_GERRIT_HOST :
-# TB_GIT_DIR :
-# TB_ID :
-# TB_LOGFILE :
-# TB_MATADATA_DIR :
-# TB_METADATA_DIR :
-# TB_NAME :
-# TB_NICE_CPU :
-# TB_NICE_IO :
-# TB_OWNER :
-# TB_POLL_DELAY :
-# TB_PROFILE_DIR :
-# TB_PROFILE :
-# TB_SMTP_HOST :
-# TB_SMTP_PASSWORD :
-# TB_SMTP_USER :
-# TB_TINDERBOX_BRANCH :
-# TB_WATCHDOG :
-
 # tb_BIN_DIR :
 # tb_BRANCHES :
 # tb_BRANCH_AUTHOR :
@@ -1490,6 +1494,13 @@ local rc
 
 }
 
+# Do we have timeout? If yes, guard git pull with that - which has a
+# tendency to hang forever, when connection is flaky
+if which timeout > /dev/null 2>&1 ; then
+	# std coreutils - timeout is two hours
+	tb_TIMEOUT="$(which timeout) 2h"
+fi
+
 ################
 # ATTENTION:
 # Nothing below this point can be overriden at the platform-level