Add more callbacks for fork() event, doc progress

* Add fork.prepare(), fork.parent() and fork.child() to match with
  pthread_atfork(), which makes more sense
* Code documentation progress

1 files changed, 24 insertions, 0 deletions

diff --git a/scripts/build-arch.sh b/scripts/build-arch.sh
index 9fc2ed0..3127850 100755
--- a/scripts/build-arch.sh
+++ b/scripts/build-arch.sh
@@ -1,17 +1,38 @@
 #!/bin/bash
+## \file
+# \brief Build one target. Usually, this script is run by build-all.sh although
+#	it can be run standalone by setting all the required environment variables
+#	by hand.
 set -e
 
+# Miscellaneous executables
 MISC_BIN="
 	proone-stress
 	proone-resolv
 	proone-test_proto
 	proone-test_util
 "
+# Proone executable output path
 BIN_PATH="$PROONE_EXEC_PREFIX.$PROONE_BIN_OS.$PROONE_BIN_ARCH"
+# Unstripped Proone executable output path
 ENTIRE_BIN_PATH="$PROONE_ENTIRE_PREFIX.$PROONE_BIN_OS.$PROONE_BIN_ARCH"
+# Path to readelf output of unstripped executable
 READELF_PATH="$PROONE_READELF_PREFIX.$PROONE_BIN_OS.$PROONE_BIN_ARCH"
+# Disassembler output path (unused)
 ASM_PATH="$PROONE_ASM_PREFIX.$PROONE_BIN_OS.$PROONE_BIN_ARCH"
 
+##
+# \brief Separate debug symbols from an executable
+# \param[in] 1 the input executable
+# \param[out] 2 the stripped executable for release build
+# \param[out] 3 the debug symbols
+# \param[out] 4 (optional)a copy of \p 1
+# \note This is a convenience function for creating various binary files from
+#	the compiler executable output. The two types of files, the stripped
+#	executable and the debug symbol, should be kept for each release in order to
+#	analyse core dumps.
+# \note When \p 4 is used, the function copies \p 1 to \p 4 and
+#	dumps the output of readelf to \c $READELF_PATH.
 separate_debug() {
 	cp -a "$1" "$2"
 	if [ ! -z "$4" ]; then
@@ -37,11 +58,13 @@ separate_debug() {
 	"$PROONE_HOST-objcopy" --add-gnu-debuglink="$3" "$2"
 }
 
+# do build
 ./configure --host="$PROONE_HOST" --enable-static $PROONE_AM_CONF
 cd src
 make -j$(nproc) proone.bin $MISC_BIN
 cd ..
 
+# extract output
 separate_debug\
 	src/proone.bin\
 	"$BIN_PATH"\
@@ -54,4 +77,5 @@ for b in $MISC_BIN; do
 		"$PROONE_DEBUG_SYM_PREFIX""$b.sym.$PROONE_BIN_OS.$PROONE_BIN_ARCH"
 done
 
+# clean up for the next arch build
 make distclean