Clean up options to build scripts.

1. Remove options that are already deprecated:
   --chromefromsource --chromebuild --chromebase
   --crosbug12352_arm_kernel_signing
2. Remove the --retries option and associated function eretry.
3. Move seldomly used options out of --help to avoid confusing
   developers. Developers who need these options can read the
   source.
4. Alphabetize all options.
5. Add description of each script to --help.

BUG=chromium-os:27364
TEST=Run --help with each script. Full canary trybot run.

Change-Id: I95675b069781f7e950d75d32dbad744adce6b830
Reviewed-on: https://gerrit.chromium.org/gerrit/18194
Reviewed-by: David James <davidjames@chromium.org>
Tested-by: David James <davidjames@chromium.org>
Commit-Ready: David James <davidjames@chromium.org>

build_image

@@ -13,52 +13,28 @@ SCRIPT_ROOT=$(dirname "$0")
 . "${SCRIPT_ROOT}/build_library/build_common.sh" || exit 1
 
 
+# Developer-visible flags.
 DEFINE_string board "${DEFAULT_BOARD}" \
   "The board to build an image for."
-DEFINE_string build_root "/build" \
+DEFINE_string boot_args "noinitrd" \
-  "The root location for board sysroots."
+  "Additional boot arguments to pass to the commandline"
-DEFINE_integer build_attempt 1 \
+DEFINE_boolean enable_rootfs_verification ${FLAGS_TRUE} \
-  "The build attempt for this image build."
+  "Default all bootloaders to use kernel-based root fs integrity checking."
 DEFINE_string output_root "${DEFAULT_BUILD_ROOT}/images" \
   "Directory in which to place image result directories (named by version)"
-DEFINE_boolean replace ${FLAGS_FALSE} \
+DEFINE_integer rootfs_hash_pad 8 \
-  "Overwrite existing output, if any."
+  "MiBs reserved at the end of the rootfs image. \
-DEFINE_integer jobs -1 \
+ ceil(0.01 * rootfs_size) is a good minimum."
-  "How many packages to build in parallel at maximum."
 DEFINE_integer rootfs_partition_size 1024 \
   "rootfs partition size in MiBs."
 DEFINE_integer rootfs_size 850 \
   "rootfs filesystem size in MiBs."
-# ceil(0.1 * rootfs_size) is a good minimum.
-DEFINE_integer rootfs_hash_pad 8 \
-  "MiBs reserved at the end of the rootfs image."
-DEFINE_integer statefulfs_size 1024 \
-  "stateful filesystem size in MiBs."
-DEFINE_string boot_args "noinitrd" \
-  "Additional boot arguments to pass to the commandline"
-
-DEFINE_string usb_disk /dev/sdb3 \
-  "Path syslinux should use to do a usb boot. Default: /dev/sdb3"
-
-DEFINE_boolean enable_rootfs_verification ${FLAGS_TRUE} \
-  "Default all bootloaders to use kernel-based root fs integrity checking."
-DEFINE_integer verity_error_behavior 3 \
-  "Kernel verified boot error behavior (0: I/O errors, 1: panic, 2: nothing, \
-3: cros) Default: 3"
-DEFINE_integer verity_max_ios -1 \
-  "Number of outstanding I/O operations dm-verity caps at. Default: -1"
-DEFINE_string verity_algorithm "sha1" \
-  "Cryptographic hash algorithm used for kernel vboot. Default : sha1"
-DEFINE_string verity_salt "" \
-  "Root filesystem salt. Default: randomly generated."
 DEFINE_boolean standard_backdoor ${FLAGS_TRUE} \
   "Install standard backdoor credentials for testing"
-DEFINE_string symlink "latest" \
+DEFINE_integer statefulfs_size 1024 \
-  "Symlink name to use for this image."
+  "stateful filesystem size in MiBs."
-
+DEFINE_string usb_disk /dev/sdb3 \
-# TODO(clchiou): Remove this flag after buildbot is fixed
+  "Path syslinux should use to do a usb boot. Default: /dev/sdb3"
-DEFINE_boolean crosbug12352_arm_kernel_signing ${FLAGS_TRUE} \
-  "A dummy this flag for preventing buildbot fail"
 
 FLAGS_HELP="USAGE: build_image [flags] [list of images to build].
 This script is used to build a Chromium OS image. Chromium OS comes in many
@@ -73,12 +49,36 @@ factory_test - Like test but with extra packages and modifications used to
 factory_install - Install shim for bootstrapping the factory test process.
   Cannot be built along with any other image.
 
-Examples
+Examples:
 
 build_image --board=<board> dev test - builds developer and test images.
 build_image --board=<board> factory_install - builds a factory install shim.
 ...
 "
+show_help_if_requested "$@"
+
+# The following options are advanced options, only available to those willing
+# to read the source code. They are not shown in help output, since they are
+# not needed for the typical developer workflow.
+DEFINE_string build_root "/build" \
+  "The root location for board sysroots."
+DEFINE_integer build_attempt 1 \
+  "The build attempt for this image build."
+DEFINE_integer jobs -1 \
+  "How many packages to build in parallel at maximum."
+DEFINE_boolean replace ${FLAGS_FALSE} \
+  "Overwrite existing output, if any."
+DEFINE_string symlink "latest" \
+  "Symlink name to use for this image."
+DEFINE_integer verity_error_behavior 3 \
+  "Kernel verified boot error behavior (0: I/O errors, 1: panic, 2: nothing, \
+3: cros) Default: 3"
+DEFINE_integer verity_max_ios -1 \
+  "Number of outstanding I/O operations dm-verity caps at. Default: -1"
+DEFINE_string verity_algorithm "sha1" \
+  "Cryptographic hash algorithm used for kernel vboot. Default : sha1"
+DEFINE_string verity_salt "" \
+  "Root filesystem salt. Default: randomly generated."
 
 # Parse command line.
 FLAGS "$@" || exit 1

build_packages

@@ -4,11 +4,6 @@
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
-# Script to build the set of binary packages needed by Chrome OS. It will
-# cross compile all of the packages into the given targets root and build
-# binary packages as a side-effect. The output packages will be picked up
-# by the build_image script to put together a bootable Chrome OS image.
-
 . "$(dirname "$0")/common.sh" || exit 1
 
 # Script must run inside the chroot
@@ -16,46 +11,52 @@ restart_in_chroot_if_needed "$@"
 
 get_default_board
 
-# Flags
+# Developer-visible flags.
 DEFINE_string board "${DEFAULT_BOARD}" \
   "The board to build packages for."
-# Deprecate chrome* options below once we have cbuild not passing these options
-DEFINE_boolean chromefromsource "${FLAGS_FALSE}" \
-  "Deprecated"
-DEFINE_string chromebuild "" \
-  "Deprecated"
-DEFINE_string chromebase "" \
-  "Deprecated"
 DEFINE_boolean usepkg "${FLAGS_TRUE}" \
   "Use binary packages to bootstrap when possible."
-DEFINE_boolean withdev "${FLAGS_TRUE}" \
-  "Build useful developer friendly utilities."
-DEFINE_boolean withautotest "${FLAGS_TRUE}" \
-  "Build autotest client code."
-DEFINE_integer jobs -1 \
-  "How many packages to build in parallel at maximum."
-DEFINE_integer retries -1 \
-  "On build failure, the number of times to retry."
-DEFINE_boolean withtest "${FLAGS_TRUE}" \
-  "Build packages required for testing."
-DEFINE_boolean withfactory "${FLAGS_TRUE}" \
-  "Build factory installer."
-DEFINE_boolean fast "${DEFAULT_FAST}" \
-  "Call many emerges in parallel."
-DEFINE_boolean norebuild "${FLAGS_FALSE}" \
-  "Don't automatically rebuild dependencies."
-DEFINE_boolean showoutput "${FLAGS_FALSE}" \
-  "Show all output from parallel_emerge."
 DEFINE_boolean noworkon "${FLAGS_FALSE}" \
   "Don't force-build workon packages."
-DEFINE_boolean withdebug "${FLAGS_TRUE}" \
+DEFINE_boolean showoutput "${FLAGS_FALSE}" \
-  "Build debug versions of Chromium-OS-specific packages."
+  "Show all output from parallel_emerge."
+DEFINE_boolean withautotest "${FLAGS_TRUE}" \
+  "Build autotest client code."
+
+FLAGS_HELP="usage: $(basename $0) [flags]
+
+build_packages updates the set of binary packages needed by Chrome OS. It will
+cross compile all packages that have been updated into the given target's root
+and build binary packages as a side-effect. The output packages will be picked
+up by the build_image script to put together a bootable Chrome OS image.
+
+For the fastest builds, use --nowithautotest --noworkon.
+"
+show_help_if_requested "$@"
+
+# The following options are advanced options, only available to those willing
+# to read the source code. They are not shown in help output, since they are
+# not needed for the typical developer workflow.
+DEFINE_boolean fast "${DEFAULT_FAST}" \
+  "Call many emerges in parallel."
+DEFINE_integer jobs -1 \
+  "How many packages to build in parallel at maximum."
+DEFINE_boolean norebuild "${FLAGS_FALSE}" \
+  "Don't automatically rebuild dependencies."
 DEFINE_boolean oldchromebinary "${FLAGS_FALSE}" \
   "Use the last prebuilt binary for Chrome produced by the buildbot."
-DEFINE_boolean skip_toolchain_update "${FLAGS_FALSE}" \
-  "Don't update toolchain automatically."
 DEFINE_boolean skip_chroot_upgrade "${FLAGS_FALSE}" \
   "Don't run the chroot upgrade automatically; use with care."
+DEFINE_boolean skip_toolchain_update "${FLAGS_FALSE}" \
+  "Don't update toolchain automatically."
+DEFINE_boolean withdev "${FLAGS_TRUE}" \
+  "Build useful developer friendly utilities."
+DEFINE_boolean withdebug "${FLAGS_TRUE}" \
+  "Build debug versions of Chromium-OS-specific packages."
+DEFINE_boolean withfactory "${FLAGS_TRUE}" \
+  "Build factory installer."
+DEFINE_boolean withtest "${FLAGS_TRUE}" \
+  "Build packages required for testing."
 
 # The --reuse_pkgs_from_local_boards flag tells Portage to share binary
 # packages between boards that are built locally, so that the total time
@@ -66,7 +67,6 @@ DEFINE_boolean reuse_pkgs_from_local_boards $FLAGS_FALSE \
   "Bootstrap from local packages instead of remote packages."
 
 # Parse command line
-FLAGS_HELP="usage: $0 [flags]"
 FLAGS "$@" || exit 1
 eval set -- "${FLAGS_ARGV}"
 check_flags_only_and_allow_null_arg "$@" && set --
@@ -189,7 +189,7 @@ if [[ "${FLAGS_showoutput}" -eq "${FLAGS_TRUE}" && \
   EMERGE_FLAGS+=" --show-output"
 fi
 info "Merging board packages ${PACKAGES}"
-eretry sudo -E ${EMERGE_BOARD_CMD} -uDNv ${EMERGE_FLAGS} ${PACKAGES}
+sudo -E ${EMERGE_BOARD_CMD} -uDNv ${EMERGE_FLAGS} ${PACKAGES}
 
 echo "Builds complete"
 print_time_elapsed

common.sh

@@ -369,17 +369,6 @@ function check_flags_only_and_allow_null_arg {
   return $do_shift
 }
 
-# Retry an emerge command according to $FLAGS_retries
-function eretry () {
-  local i
-  for i in $(seq $FLAGS_retries); do
-    echo "Retrying $@"
-    "$@" && return 0
-  done
-  "$@" && return 0
-  return 1
-}
-
 # Removes single quotes around parameter
 # Arguments:
 #   $1 - string which optionally has surrounding quotes
@@ -855,3 +844,21 @@ function choose() {
     eval ${choose_reply}="${choose_invalid}"
   fi
 }
+
+# Display --help if requested. This is used to hide options from help
+# that are not intended for developer use.
+#
+# How to use:
+#  1) Declare the options that you want to appear in help.
+#  2) Call this function.
+#  3) Declare the options that you don't want to appear in help.
+#
+# See build_packages for example usage.
+function show_help_if_requested() {
+  for opt in "$@"; do
+    if [ "$opt" = "-h" ] || [ "$opt" = "--help" ]; then
+      flags_help
+      exit 0
+    fi
+  done
+}

setup_board

@@ -4,8 +4,6 @@
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
-# This script sets up a the sysroot for a particular target board.
-
 . "$(dirname "$0")/common.sh" || exit 1
 . "${SRC_ROOT}/platform/dev/toolchain_utils.sh"
 
@@ -14,45 +12,57 @@ restart_in_chroot_if_needed "$@"
 
 get_default_board
 
-# Flags
+# Developer-visible flags.
 DEFINE_string board "$DEFAULT_BOARD" \
   "The name of the board to set up."
+DEFINE_boolean default $FLAGS_FALSE \
+  "Set board to the default board in your chroot"
+DEFINE_boolean force $FLAGS_FALSE \
+  "Force re-creating board root."
+DEFINE_boolean usepkg $FLAGS_TRUE \
+  "Use binary packages to bootstrap."
+
+FLAGS_HELP="usage: $(basename $0) [flags]
+
+setup_board sets up the sysroot for a particular board. This script is called
+automatically when you run build_packages, so there is typically no need to
+call it directly, unless you want to blow away your board (using --force).
+"
+show_help_if_requested "$@"
+
+# The following options are advanced options, only available to those willing
+# to read the source code. They are not shown in help output, since they are
+# not needed for the typical developer workflow.
 DEFINE_string build_root "/build" \
   "The root location for board sysroots."
 DEFINE_string board_overlay "" \
   "Location of the board overlay."
-DEFINE_string variant "" \
-  "Board variant."
-DEFINE_string toolchain "" \
-  "Toolchain.  For example: i686-pc-linux-gnu, armv7a-softfloat-linux-gnueabi"
-DEFINE_boolean usepkg $FLAGS_TRUE \
-  "Use binary packages to bootstrap."
-DEFINE_boolean force $FLAGS_FALSE \
-  "Force re-creating board root."
 DEFINE_string binutils_version "2.21-r4" \
   "Version of binutils to use."
+DEFINE_boolean fast ${DEFAULT_FAST} "Call many emerges in parallel"
 DEFINE_string gcc_version "[stable]" \
   "Version of gcc to use."
-DEFINE_string libc_version "[stable]" \
+DEFINE_integer jobs -1 \
-  "Version of libc to use."
+  "How many packages to build in parallel at maximum."
 DEFINE_string kernel_version "[stable]" \
   "Version of kernel headers to use."
 DEFINE_boolean latest_toolchain $FLAGS_FALSE \
   "Use the latest ebuild for all toolchain packages (gcc, binutils, libc, \
 kernel). This overrides the other toolchain version options."
-DEFINE_boolean default $FLAGS_FALSE \
+DEFINE_string libc_version "[stable]" \
-  "Set board to the default board in your chroot"
+  "Version of libc to use."
-DEFINE_boolean fast ${DEFAULT_FAST} "Call many emerges in parallel"
 DEFINE_string profile "" \
   "The portage configuration profile to use. Profile must be located in overlay-board/profiles"
 DEFINE_boolean quiet $FLAGS_FALSE \
   "Don't print warnings when board already exists."
 DEFINE_boolean skip_toolchain_update $FLAGS_FALSE \
   "Don't update toolchain automatically."
-DEFINE_integer jobs -1 \
-  "How many packages to build in parallel at maximum."
 DEFINE_boolean skip_chroot_upgrade $FLAGS_FALSE \
   "Don't run the chroot upgrade automatically; use with care."
+DEFINE_string toolchain "" \
+  "Toolchain.  For example: i686-pc-linux-gnu, armv7a-softfloat-linux-gnueabi"
+DEFINE_string variant "" \
+  "Board variant."
 
 # The --reuse_pkgs_from_local_boards flag tells Portage to share binary
 # packages between boards that are built locally, so that the total time

update_chroot

@@ -4,7 +4,6 @@
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
-# Performs an update of the chroot.
 
 . "$(dirname "$0")/common.sh" || exit 1
 
@@ -14,12 +13,20 @@ assert_inside_chroot "$@"
 # Do not run as root
 assert_not_root_user
 
-# Flags
+# Developer-visible flags.
 DEFINE_boolean usepkg $FLAGS_TRUE \
   "Use binary packages to bootstrap."
+
+FLAGS_HELP="usage: $(basename $0) [flags]
+Performs an update of the chroot. This script is called as part of
+build_packages, so there is typically no need to call this script directly.
+"
+show_help_if_requested "$@"
+
+# The following options are advanced options, only available to those willing
+# to read the source code. They are not shown in help output, since they are
+# not needed for the typical developer workflow.
 DEFINE_boolean fast ${DEFAULT_FAST} "Call many emerges in parallel"
-DEFINE_integer retries -1 \
-  "On build failure, the number of times to retry."
 DEFINE_integer jobs -1 \
   "How many packages to build in parallel at maximum."
 
@@ -77,7 +84,7 @@ CHOST="$(portageq envvar CHOST)"
 LATEST="$(gcc-config -l | grep "${CHOST}" | awk '{ print $2 }' | \
           sort -V | tail -n 1 )"
 CURRENT="$(gcc-config -c)" || true # This fails if current profile is invalid.
-eretry sudo -E ${EMERGE_CMD} ${EMERGE_FLAGS} \
+sudo -E ${EMERGE_CMD} ${EMERGE_FLAGS} \
     sys-devel/gcc sys-devel/binutils sys-libs/glibc sys-apps/portage
 # If the latest toolchain wasn't already selected before we updated, do nothing,
 # otherwise autoselect the latest. Also fix if the current profile is invalid.
@@ -89,7 +96,7 @@ fi
 
 # Second pass, update everything else.
 EMERGE_FLAGS+=" --deep"
-eretry sudo -E ${EMERGE_CMD} ${EMERGE_FLAGS} \
+sudo -E ${EMERGE_CMD} ${EMERGE_FLAGS} \
     chromeos-base/hard-host-depends world
 
 # Automatically discard all CONFIG_PROTECT'ed files. Those that are