better usage messages & READMEs

11 files changed, 156 insertions, 42 deletions

diff --git a/README.md b/README.md
index 701db7d..d6c0415 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,19 @@ guide] to help you through.
 
 [an excellent guide]: https://medium.com/@porteneuve/mastering-git-submodules-34c65e940407
 
+Usage
+-----
+
+Using the scripts in this project, you can build
+
+* [Boost],
+* a [CMake project].
+
+All in a relatively cross-platform way.
+
+[Boost]: boost/build/README.md
+[CMake project]: cmake/build/README.md
+
 License
 -------
 
diff --git a/boost/build/README.md b/boost/build/README.md
new file mode 100644
index 0000000..c1f903e
--- /dev/null
+++ b/boost/build/README.md
@@ -0,0 +1,13 @@
+Boost
+=====
+
+Download & build the Boost libraries in a cross-platform way.
+Consult the output of `build.py --help` for details.
+
+A simple usage example to download and build Boost 1.71.0:
+
+    $ python3 build.py download 1.71.0
+    ...
+
+    $ python3 build.py build -- boost_1_71_0/ --with-filesystem --with-program_options
+    ...
diff --git a/boost/build/build.py b/boost/build/build.py
index bfb204b..4957e85 100755
--- a/boost/build/build.py
+++ b/boost/build/build.py
@@ -5,10 +5,24 @@
 # For details, see https://github.com/egor-tensin/cmake-common.
 # Distributed under the MIT License.
 
-# This script downloads and builds the Boost libraries.
-# It's main utility is being able to download & unpack the Boost distribution
-# archive in a cross-platform way + setting the correct --stagedir parameter
-# value to avoid name clashes.
+'''Download & build Boost.
+
+This script downloads and builds the Boost libraries.  It's main purpose is to:
+1) provide a cross-platform way to download & unpack the Boost distribution
+archive,
+2) set the correct --stagedir parameter value to avoid name clashes.
+
+Please pick a command below.  You can execute `%(prog)s COMMAND --help` to view
+its usage message.
+
+A simple usage example:
+
+    $ %(prog)s download 1.71.0
+    ...
+
+    $ %(prog)s build -- boost_1_71_0/ --with-filesystem --with-program_options
+    ...
+'''
 
 import abc
 import argparse
@@ -123,13 +137,13 @@ def _parse_linkage(s):
         raise argparse.ArgumentTypeError(f'invalid linkage: {s}')
 
 
-Version = namedtuple('Version', ['major', 'minor', 'patch'])
+_Version = namedtuple('_Version', ['major', 'minor', 'patch'])
 
 
 @total_ordering
 class BoostVersion:
     def __init__(self, major, minor, patch):
-        self._impl = Version(major, minor, patch)
+        self._impl = _Version(major, minor, patch)
 
     @property
     def major(self):
@@ -178,7 +192,7 @@ class BoostVersion:
         return f'{self.dir_name}{self.archive_ext}'
 
     def get_download_url(self):
-        if self._impl < Version(1, 63, 0):
+        if self._impl < _Version(1, 63, 0):
             return f'https://sourceforge.net/projects/boost/files/boost/{self}/{self.archive_name}/download'
         return f'https://dl.bintray.com/boostorg/release/{self}/source/{self.archive_name}'
 
@@ -425,7 +439,10 @@ def _parse_args(argv=None):
         argv = sys.argv[1:]
     logging.info('Command line arguments: %s', argv)
 
-    parser = argparse.ArgumentParser()
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+
     subparsers = parser.add_subparsers(dest='command')
 
     download = subparsers.add_parser('download', help='download & bootstrap Boost')
@@ -435,35 +452,35 @@ def _parse_args(argv=None):
                           help='download directory (temporary file unless specified)')
     download.add_argument('--unpack', metavar='DIR', dest='unpack_dir',
                           type=_parse_dir, default='.',
-                          help='directory to unpack Boost to')
+                          help='directory to unpack the archive to')
     download.add_argument('boost_version', metavar='VERSION',
                           type=BoostVersion.from_string,
                           help='Boost version (in the MAJOR.MINOR.PATCH format)')
 
-    build = subparsers.add_parser('build', help='build Boost libraries')
+    build = subparsers.add_parser('build', help='build the libraries')
 
     # These are used to put the built libraries into proper stage/
     # subdirectories (to avoid name clashes).
     build.add_argument('--platform', metavar='PLATFORM',
                        nargs='*', dest='platforms', default=[],
                        type=_parse_platform,
-                       help='target platform (e.g. x86/x64)')
+                       help=f'target platform ({"/".join(map(str, Platform))})')
     build.add_argument('--configuration', metavar='CONFIGURATION',
                        nargs='*', dest='configurations', default=[],
                        type=_parse_configuration,
-                       help='target configuration (e.g. Debug/Release)')
+                       help=f'target configuration ({"/".join(map(str, Configuration))})')
     # This is needed because the default behaviour on Linux and Windows is
     # different: static & dynamic libs are built on Linux, but only static libs
     # are built on Windows by default.
     build.add_argument('--link', metavar='LINKAGE',
                        nargs='*', default=[],
                        type=_parse_linkage,
-                       help='how the libraries are linked (i.e. static/shared)')
+                       help=f'how the libraries are linked ({"/".join(map(str, Linkage))})')
     # This is used to omit runtime-link=static I'd have to otherwise use a lot,
     # plus the script validates the link= and runtime-link= combinations.
     build.add_argument('--runtime-link', metavar='LINKAGE',
                        type=_parse_linkage, default=Linkage.STATIC,
-                       help='how the libraries link to the runtime')
+                       help=f'how the libraries link to the runtime ({"/".join(map(str, Linkage))})')
 
     build.add_argument('--build', metavar='DIR', dest='build_dir',
                        type=_parse_dir,
@@ -475,7 +492,10 @@ def _parse_args(argv=None):
     build.add_argument('b2_args', nargs='*', metavar='B2_ARG', default=[],
                        help='additional b2 arguments, to be passed verbatim')
 
-    return parser.parse_args(argv)
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.error("please specify a command")
+    return args
 
 
 def build(args):
diff --git a/boost/build/ci/appveyor.py b/boost/build/ci/appveyor.py
index 86488aa..7bc009a 100644
--- a/boost/build/ci/appveyor.py
+++ b/boost/build/ci/appveyor.py
@@ -5,11 +5,15 @@
 # For details, see https://github.com/egor-tensin/cmake-common.
 # Distributed under the MIT License.
 
-# This is similar to build.py, but auto-fills some parameters for build.py from
-# the AppVeyor-defined environment variables.
-# This script is rarely usefull, since AppVeyor images come with lots of
-# pre-built Boost distributions, but still.
-# Boost is built in C:\.
+'''Download & build Boost on AppVeyor.
+
+This is similar to build.py, but auto-fills some parameters for build.py from
+the AppVeyor-defined environment variables.  This script is rarely usefull,
+since AppVeyor images come with lots of pre-built Boost distributions, but
+still.
+
+Boost is built in C:\.
+'''
 
 import argparse
 import logging
@@ -55,7 +59,9 @@ def _parse_args(argv=None):
         argv = sys.argv[1:]
     logging.info('Command line arguments: %s', argv)
 
-    parser = argparse.ArgumentParser()
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
     parser.add_argument('--link', metavar='LINKAGE', nargs='*',
                         help='how the libraries are linked (i.e. static/shared)')
     parser.add_argument('--runtime-link', metavar='LINKAGE',
diff --git a/boost/build/ci/travis.py b/boost/build/ci/travis.py
index 4b06281..f088c48 100755
--- a/boost/build/ci/travis.py
+++ b/boost/build/ci/travis.py
@@ -5,9 +5,13 @@
 # For details, see https://github.com/egor-tensin/cmake-common.
 # Distributed under the MIT License.
 
-# This is similar to build.py, but auto-fills some parameters for build.py from
-# the Travis-defined environment variables.
-# Boost is built in $HOME.
+'''Download & build Boost on Travis.
+
+This is similar to build.py, but auto-fills some parameters for build.py from
+the Travis-defined environment variables.
+
+Boost is built in $HOME.
+'''
 
 import argparse
 import logging
@@ -53,9 +57,11 @@ def _parse_args(argv=None):
         argv = sys.argv[1:]
     logging.info('Command line arguments: %s', argv)
 
-    parser = argparse.ArgumentParser()
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
     parser.add_argument('--link', metavar='LINKAGE', nargs='*',
-                        help='how the libraries are linked (i.e. static/shared)')
+                        help='how the libraries are linked')
     parser.add_argument('--runtime-link', metavar='LINKAGE',
                         help='how the libraries link to the runtime')
     parser.add_argument('b2_args', nargs='*', metavar='B2_ARG', default=[],
diff --git a/boost/toolchains/README.md b/boost/toolchains/README.md
new file mode 100644
index 0000000..8c6870a
--- /dev/null
+++ b/boost/toolchains/README.md
@@ -0,0 +1,2 @@
+Use the toolchain files by passing something like
+`--user-config=PATH/TO/cmake-common/boost/toolchains/TOOLCHAIN.jam` to `b2`.
diff --git a/cmake/build/README.md b/cmake/build/README.md
new file mode 100644
index 0000000..b63564d
--- /dev/null
+++ b/cmake/build/README.md
@@ -0,0 +1,13 @@
+CMake
+=====
+
+Build a CMake project.
+Consult the output of `build.py --help` for details.
+
+A simple usage example:
+
+    > python3 build.py --configuration Release --install path/to/somewhere -- ../examples/simple
+    ...
+
+    > ./path/to/somewhere/bin/foo
+    foo
diff --git a/cmake/build/build.py b/cmake/build/build.py
index c4af4ea..e256b72 100755
--- a/cmake/build/build.py
+++ b/cmake/build/build.py
@@ -5,10 +5,33 @@
 # For details, see https://github.com/egor-tensin/cmake-common.
 # Distributed under the MIT License.
 
-# This script is used basically to invoke the CMake executable in a
-# cross-platform way (provided the platform has Python 3, of course).
-# The motivation was to merge my Travis and AppVeyor build scripts (largely
-# similar, but written in bash and PowerShell, respectively).
+R'''Build a CMake project.
+
+This script is used basically to invoke the CMake executable in a
+cross-platform way (provided the platform has Python 3, of course).  The
+motivation was to merge my Travis and AppVeyor build scripts (largely similar,
+but written in bash and PowerShell, respectively).
+
+A simple usage example:
+
+    $ %(prog)s --configuration Release --install path/to/somewhere -- ../examples/simple
+    ...
+
+    $ ./path/to/somewhere/bin/foo
+    foo
+
+Picking the target platform is build system-specific.  On Visual Studio, pass
+the target platform using the `-A` flag like this:
+
+    > %(prog)s --install path\to\somewhere -- ..\examples\simple -A Win32
+    ...
+
+Using GCC-like compilers, the best way is to use CMake toolchain files (see
+cmake/toolchains in this repository for examples).
+
+    $ %(prog)s --install path/to/somewhere -- ../examples/simple -D CMAKE_TOOLCHAIN_FILE="$( pwd )/../toolchains/mingw-x86.cmake"
+    ...
+'''
 
 import argparse
 from contextlib import contextmanager
@@ -115,7 +138,10 @@ def _parse_args(argv=None):
         argv = sys.argv[1:]
     logging.info('Command line arguments: %s', argv)
 
-    parser = argparse.ArgumentParser(description='Build a CMake project')
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+
     parser.add_argument('--build', metavar='DIR', dest='build_dir',
                         type=_parse_dir,
                         help='build directory (temporary directory unless specified)')
@@ -124,7 +150,7 @@ def _parse_args(argv=None):
                         help='install directory')
     parser.add_argument('--configuration', metavar='CONFIG',
                         type=_parse_configuration, default=Configuration.DEBUG,
-                        help='build configuration (i.e. Debug/Release)')
+                        help=f'build configuration ({"/".join(map(str, Configuration))})')
     parser.add_argument('src_dir', metavar='DIR',
                         type=_parse_dir,
                         help='source directory')
diff --git a/cmake/build/ci/appveyor.py b/cmake/build/ci/appveyor.py
index bb4d31d..ed656b3 100755
--- a/cmake/build/ci/appveyor.py
+++ b/cmake/build/ci/appveyor.py
@@ -5,9 +5,14 @@
 # For details, see https://github.com/egor-tensin/cmake-common.
 # Distributed under the MIT License.
 
-# This is similar to build.py, but auto-fills some parameters for build.py from
-# the AppVeyor-defined environment variables.
-# The project is built in C:\Projects\build.
+'''Build a CMake project on AppVeyor.
+
+This is similar to build.py, but auto-fills some parameters for build.py from
+the AppVeyor-defined environment variables.
+
+
+The project is built in C:\Projects\build.
+'''
 
 import argparse
 from enum import Enum
@@ -113,7 +118,10 @@ def _parse_args(argv=None):
         argv = sys.argv[1:]
     logging.info('Command line arguments: %s', argv)
 
-    parser = argparse.ArgumentParser(description='Build a CMake project on AppVeyor')
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+
     parser.add_argument('--install', metavar='DIR', dest='install_dir',
                         help='install directory')
     parser.add_argument('cmake_args', nargs='*', metavar='CMAKE_ARG', default=[],
diff --git a/cmake/build/ci/travis.py b/cmake/build/ci/travis.py
index 3712bf9..ab93711 100755
--- a/cmake/build/ci/travis.py
+++ b/cmake/build/ci/travis.py
@@ -5,9 +5,13 @@
 # For details, see https://github.com/egor-tensin/cmake-common.
 # Distributed under the MIT License.
 
-# This is similar to build.py, but auto-fills some parameters for build.py from
-# the Travis-defined environment variables.
-# The project is built in $HOME/build.
+'''Build a CMake project on Travis.
+
+This is similar to build.py, but auto-fills some parameters for build.py from
+the Travis-defined environment variables.
+
+The project is built in $HOME/build.
+'''
 
 import argparse
 import logging
@@ -50,7 +54,10 @@ def _parse_args(argv=None):
         argv = sys.argv[1:]
     logging.info('Command line arguments: %s', argv)
 
-    parser = argparse.ArgumentParser(description='Build a CMake project on Travis')
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+
     parser.add_argument('--install', metavar='DIR', dest='install_dir',
                         help='install directory')
     parser.add_argument('cmake_args', nargs='*', metavar='CMAKE_ARG', default=[],
diff --git a/cmake/toolchains/README.md b/cmake/toolchains/README.md
index 0e46391..9c58eb6 100644
--- a/cmake/toolchains/README.md
+++ b/cmake/toolchains/README.md
@@ -1,3 +1,3 @@
 Use the toolchain files by passing something like
-`-DCMAKE_TOOLCHAIN_FILE=path/to/cmake-common/toolchains/toolchain.cmake` to
-`cmake`.
+`-D CMAKE_TOOLCHAIN_FILE=PATH/TO/cmake-common/cmake/toolchains/TOOLCHAIN.cmake`
+to `cmake`.