Made a script to build docker images easier to use.

[ilya-biryukov]

Summary

• Removed double indirection via command-line args (i.e. two -- options of build_docker_image.sh).
• Added a comment on how to build 2-stage clang install into the build_docker_image.sh, it used to be only in the docs/Docker.rst.

[klimek]

lg

docs/Docker.rst

95 ↗

(On Diff #105397)

'a' build

[ilya-biryukov]

Fixed docs.

llvm/trunk/docs/Docker.rst

 Here's a very simple example of getting a docker image with clang binary,
 compiled by the system compiler in the debian8 image:
 
 .. code-block:: bash
 
     ./llvm/utils/docker/build_docker_image.sh \
   --source debian8 \
   --docker-repository clang-debian8 --docker-tag "staging" \
-  -- \
   -p clang -i install-clang -i install-clang-headers \
   -- \
   -DCMAKE_BUILD_TYPE=Release
 
-Note there are two levels of ``--`` indirection. First one separates
-``build_docker_image.sh`` arguments from ``llvm/utils/build_install_llvm.sh``
-arguments. Second one separates CMake arguments from ``build_install_llvm.sh``
-arguments. Note that build like that doesn't use a 2-stage build process that
+Note that a build like that doesn't use a 2-stage build process that
 you probably want for clang. Running a 2-stage build is a little more intricate,
 this command will do that:
 
 .. code-block:: bash
 
     # Run a 2-stage build.
     #   LLVM_TARGETS_TO_BUILD=Native is to reduce stage1 compile time.
     #   Options, starting with BOOTSTRAP_* are passed to stage2 cmake invocation.
     ./build_docker_image.sh \
   --source debian8 \
   --docker-repository clang-debian8 --docker-tag "staging" \
-  -- \
   -p clang -i stage2-install-clang -i stage2-install-clang-headers \
   -- \
   -DLLVM_TARGETS_TO_BUILD=Native -DCMAKE_BUILD_TYPE=Release \
   -DBOOTSTRAP_CMAKE_BUILD_TYPE=Release \
   -DCLANG_ENABLE_BOOTSTRAP=ON -DCLANG_BOOTSTRAP_TARGETS="install-clang;install-clang-headers"
   
 This will produce two images, a release image ``clang-debian8:staging`` and a
 build image ``clang-debian8-build:staging`` from the latest upstream revision.

 If you want a somewhat recent and somewhat stable build, use the
 ``branches/google/stable`` branch, i.e. the following command will produce a
 debian8-based image using the latest ``google/stable`` sources for you:
 
 .. code-block:: bash
 
     ./llvm/utils/docker/build_docker_image.sh \
   -s debian8 --d clang-debian8 -t "staging" \
-  -- \
   --branch branches/google/stable \
   -p clang -i install-clang -i install-clang-headers \
   -- \
   -DCMAKE_BUILD_TYPE=Release
 
 
 Minimizing docker image size
 ============================

llvm/trunk/utils/docker/build_docker_image.sh

 
 IMAGE_SOURCE=""
 DOCKER_REPOSITORY=""
 DOCKER_TAG=""
 BUILDSCRIPT_ARGS=""
 
 function show_usage() {
   usage=$(cat << EOF
-Usage: build_docker_image.sh [options] [-- [buildscript_args]...]
+Usage: build_docker_image.sh [options] [-- [cmake_args]...]
 
 Available options:
+  General:
+    -h|--help               show this help message
+  Docker-specific:
     -s|--source             image source dir (i.e. debian8, nvidia-cuda, etc)
     -d|--docker-repository  docker repository for the image
     -t|--docker-tag         docker tag for the image
-Required options: --source and --docker-repository.
+  LLVM-specific:
+    -b|--branch         svn branch to checkout, i.e. 'trunk',
+                        'branches/release_40'
+                        (default: 'trunk')
+    -r|--revision       svn revision to checkout
+    -p|--llvm-project   name of an svn project to checkout. Will also add the
+                        project to a list LLVM_ENABLE_PROJECTS, passed to CMake.
+                        For clang, please use 'clang', not 'cfe'.
+                        Project 'llvm' is always included and ignored, if
+                        specified.
+                        Can be specified multiple times.
+    -i|--install-target name of a cmake install target to build and include in
+                        the resulting archive. Can be specified multiple times.
 
-All options after '--' are passed to buildscript (see
-scripts/build_install_llvm.sh).
+Required options: --source and --docker-repository, at least one
+  --install-target.
+
+All options after '--' are passed to CMake invocation.
 
 For example, running:
 $ build_docker_image.sh -s debian8 -d mydocker/debian8-clang -t latest \ 
-  -- -p clang -i install-clang -i install-clang-headers
+  -p clang -i install-clang -i install-clang-headers
 will produce two docker images:
     mydocker/debian8-clang-build:latest - an intermediate image used to compile
       clang.
     mydocker/clang-debian8:latest       - a small image with preinstalled clang.
 Please note that this example produces a not very useful installation, since it
 doesn't override CMake defaults, which produces a Debug and non-boostrapped
 version of clang.
 
-For an example of a somewhat more useful build, search for 2-stage build
-instructions in llvm/docs/Docker.rst.
+To get a 2-stage clang build, you could use this command:
+$ ./build_docker_image.sh -s debian8 -d mydocker/clang-debian8 -t "latest" \ 
+    -p clang -i stage2-install-clang -i stage2-install-clang-headers \ 
+    -- \ 
+    -DLLVM_TARGETS_TO_BUILD=Native -DCMAKE_BUILD_TYPE=Release \ 
+    -DBOOTSTRAP_CMAKE_BUILD_TYPE=Release \ 
+    -DCLANG_ENABLE_BOOTSTRAP=ON \ 
+    -DCLANG_BOOTSTRAP_TARGETS="install-clang;install-clang-headers"
 EOF
 )
   echo "$usage"
 }
 
+SEEN_INSTALL_TARGET=0
 while [[ $# -gt 0 ]]; do
   case "$1" in
     -h|--help)
       show_usage
       exit 0
       ;;
     -s|--source)
       shift
       IMAGE_SOURCE="$1"
       shift
       ;;
     -d|--docker-repository)
       shift
       DOCKER_REPOSITORY="$1"
       shift
       ;;
     -t|--docker-tag)
       shift
       DOCKER_TAG="$1"
       shift
       ;;
+    -i|--install-target|-r|--revision|-b|--branch|-p|--llvm-project)
+      if [ "$1" == "-i" ] || [ "$1" == "--install-target" ]; then
+        SEEN_INSTALL_TARGET=1
+      fi
+      BUILDSCRIPT_ARGS="$BUILDSCRIPT_ARGS $1 $2"
+      shift 2
+      ;;
     --)
       shift
-      BUILDSCRIPT_ARGS="$*"
+      BUILDSCRIPT_ARGS="$BUILDSCRIPT_ARGS -- $*"
       shift $#
       ;;
     *)
       echo "Unknown argument $1"
       exit 1
       ;;
   esac
 done
if [ "$IMAGE_SOURCE" == "" ]; then
   exit 1
 fi
 
 if [ "$DOCKER_REPOSITORY" == "" ]; then
   echo "Required argument missing: --docker-repository"
   exit 1
 fi
 
+if [ $SEEN_INSTALL_TARGET -eq 0 ]; then
+  echo "Please provide at least one --install-target"
+  exit 1
+fi
+
 cd $(dirname $0)
 if [ ! -d $IMAGE_SOURCE ]; then
   echo "No sources for '$IMAGE_SOURCE' were found in $PWD"
   exit 1
 fi
 
 echo "Building from $IMAGE_SOURCE"