[build_script.py] Add "test" subcommand

This "FIXME" describes a problem with the swift-corelibs-xctest build
script when invoked in the context of the greater Swift build script:
https://github.com/apple/swift/blob/6ccf5da2dfc8a74c84b2fd99c32dcdf2255699d7/utils/build-script-impl#L2070-L2072

The problem is that there is currently no way to test an *already
built* XCTest.so. Instead, the XCTest build script re-builds the entire
project, then tests the newly build XCTest.so.

Add a "test" subcommand to build_script.py, which allows users to test
an already built XCTest.so:

```
$ ./build_script.py test --swiftc `which swiftc` /path/to/build/dir
```

Users may still choose to build *and* test, by using the old
build_script.py invocation:

```
$ ./build_script.py --swiftc `which swiftc` --test
```

Author: modocache

build_script.py

@@ -12,6 +12,7 @@
 import argparse
 import os
 import subprocess
+import sys
 import tempfile
 
 SOURCE_DIR = os.path.dirname(os.path.abspath(__file__))
@@ -23,50 +24,12 @@ def run(command):
     note(command)
     subprocess.check_call(command, shell=True)
 
-def main():
-    parser = argparse.ArgumentParser(
-        description="Builds XCTest using a Swift compiler.")
-    parser.add_argument("--swiftc",
-                        help="path to the swift compiler",
-                        metavar="PATH",
-                        required=True)
-    parser.add_argument("--build-dir",
-                        help="path to the output build directory. If not "
-                             "specified, a temporary directory is used",
-                        metavar="PATH",
-                        default=tempfile.mkdtemp())
-    parser.add_argument("--swift-build-dir", help="deprecated, do not use")
-    parser.add_argument("--arch", help="deprecated, do not use")
-    parser.add_argument("--module-install-path",
-                        help="location to install module files",
-                        metavar="PATH",
-                        dest="module_path")
-    parser.add_argument("--library-install-path",
-                        help="location to install shared library files",
-                        metavar="PATH",
-                        dest="lib_path")
-    parser.add_argument("--release",
-                        help="builds for release",
-                        action="store_const",
-                        dest="build_style",
-                        const="release",
-                        default="debug")
-    parser.add_argument("--debug",
-                        help="builds for debug (the default)",
-                        action="store_const",
-                        dest="build_style",
-                        const="debug",
-                        default="debug")
-    parser.add_argument("--test",
-                        help="Whether to run tests after building. "
-                             "Note that you must have cloned "
-                             "https://github.com/apple/swift-llvm "
-                             "at {} in order to run this command. ".format(
-                                 os.path.join(
-                                     os.path.dirname(SOURCE_DIR), 'llvm')),
-                        action="store_true")
-    args = parser.parse_args()
 
+def _build(args):
+    """
+    Build XCTest and place the built products in the given 'build_dir'.
+    If 'test' is specified, also executes the 'test' subcommand.
+    """
     swiftc = os.path.abspath(args.swiftc)
     build_dir = os.path.abspath(args.build_dir)
 
@@ -84,7 +47,6 @@ def main():
     for file in sourceFiles:
         sourcePaths.append("{0}/Sources/XCTest/{1}".format(SOURCE_DIR, file))
 
-
     if args.build_style == "debug":
         style_options = "-g"
     else:
@@ -120,20 +82,132 @@ def main():
         subprocess.check_call(cmd)
 
     if args.test:
-        lit_path = os.path.join(
-            os.path.dirname(SOURCE_DIR), 'llvm', 'utils', 'lit', 'lit.py')
-        lit_flags = '-sv --no-progress-bar'
-        tests_path = os.path.join(SOURCE_DIR, 'Tests', 'Functional')
-        run('SWIFT_EXEC={swiftc} '
-            'BUILT_PRODUCTS_DIR={built_products_dir} '
-            '{lit_path} {lit_flags} '
-            '{tests_path}'.format(swiftc=swiftc,
-                                  built_products_dir=build_dir,
-                                  lit_path=lit_path,
-                                  lit_flags=lit_flags,
-                                  tests_path=tests_path))
+        # Execute main() using the arguments necessary to run the tests.
+        main(args=["test", "--swiftc", swiftc, build_dir])
 
     note('Done.')
 
+
+def _test(args):
+    """
+    Test the built XCTest.so library at the given 'build_dir', using the
+    given 'swiftc' compiler.
+    """
+    # FIXME: Allow path to lit to be specified as an option, with this
+    #        path as a default.
+    lit_path = os.path.join(
+        os.path.dirname(SOURCE_DIR), "llvm", "utils", "lit", "lit.py")
+    # FIXME: Allow these to be specified by the Swift build script.
+    lit_flags = "-sv --no-progress-bar"
+    tests_path = os.path.join(SOURCE_DIR, "Tests", "Functional")
+    run("SWIFT_EXEC={swiftc} "
+        "BUILT_PRODUCTS_DIR={build_dir} "
+        "{lit_path} {lit_flags} "
+        "{tests_path}".format(swiftc=args.swiftc,
+                              build_dir=args.build_dir,
+                              lit_path=lit_path,
+                              lit_flags=lit_flags,
+                              tests_path=tests_path))
+
+
+def main(args=sys.argv[1:]):
+    """
+    The main entry point for this script. Based on the subcommand given,
+    delegates building or testing XCTest to a sub-parser and its corresponding
+    function.
+    """
+    parser = argparse.ArgumentParser(
+        description="Builds, tests, and installs XCTest.")
+    subparsers = parser.add_subparsers(
+        description="Use one of these to specify whether to build, test, "
+                    "or install XCTest. If you don't specify any of these, "
+                    "'build' is executed as a default. You may also use "
+                    "'build' to also test and install the built products. "
+                    "Pass the -h or --help option to any of the subcommands "
+                    "for more information.")
+
+    build_parser = subparsers.add_parser(
+        "build",
+        description="Build XCTest.so, XCTest.swiftmodule, and XCTest.swiftdoc "
+                    "using the given Swift compiler. This command may also "
+                    "test and install the built products.")
+    build_parser.set_defaults(func=_build)
+    build_parser.add_argument(
+        "--swiftc",
+        help="Path to the 'swiftc' compiler that will be used to build "
+             "XCTest.so, XCTest.swiftmodule, and XCTest.swiftdoc. This will "
+             "also be used to build the tests for those built products if the "
+             "--test option is specified.",
+        metavar="PATH",
+        required=True)
+    build_parser.add_argument(
+        "--build-dir",
+        help="Path to the output build directory. If not specified, a "
+             "temporary directory is used",
+        metavar="PATH",
+        default=tempfile.mkdtemp())
+    build_parser.add_argument("--swift-build-dir",
+                              help="deprecated, do not use")
+    build_parser.add_argument("--arch", help="deprecated, do not use")
+    build_parser.add_argument(
+        "--module-install-path",
+        help="Location at which to install XCTest.swiftmodule and "
+             "XCTest.swiftdoc. This directory will be created if it doesn't "
+             "already exist.",
+        dest="module_path")
+    build_parser.add_argument(
+        "--library-install-path",
+        help="Location at which to install XCTest.so. This directory will be "
+             "created if it doesn't already exist.",
+        dest="lib_path")
+    build_parser.add_argument(
+        "--release",
+        help="builds for release",
+        action="store_const",
+        dest="build_style",
+        const="release",
+        default="debug")
+    build_parser.add_argument(
+        "--debug",
+        help="builds for debug (the default)",
+        action="store_const",
+        dest="build_style",
+        const="debug",
+        default="debug")
+    build_parser.add_argument(
+        "--test",
+        help="Whether to run tests after building. Note that you must have "
+             "cloned https://github.com/apple/swift-llvm at {} in order to "
+             "run this command.".format(os.path.join(
+                 os.path.dirname(SOURCE_DIR), 'llvm')),
+        action="store_true")
+
+    test_parser = subparsers.add_parser(
+        "test",
+        description="Tests a built XCTest framework at the given path.")
+    test_parser.set_defaults(func=_test)
+    test_parser.add_argument(
+        "build_dir",
+        help="An absolute path to a directory containing the built XCTest.so "
+             "library.",
+        metavar="PATH")
+    test_parser.add_argument(
+        "--swiftc",
+        help="Path to the 'swiftc' compiler used to build and run the tests.",
+        required=True)
+
+    # Many versions of Python require a subcommand must be specified.
+    # We handle this here: if no known subcommand (or none of the help options)
+    # is included in the arguments, then insert the default subcommand
+    # argument.
+    if any([a in ["build", "test", "-h", "--help"] for a in args]):
+        parsed_args = parser.parse_args(args=args)
+    else:
+        parsed_args = parser.parse_args(args=["build"] + args)
+
+    # Execute the function for the subcommand we've been given.
+    parsed_args.func(parsed_args)
+
+
 if __name__ == '__main__':
     main()