fix READMEs, code style, etc.

11 files changed, 78 insertions, 63 deletions

diff --git a/README.md b/README.md
index 1585cbf..a3473ca 100644
--- a/README.md
+++ b/README.md
@@ -30,8 +30,8 @@ It's used in a bunch of projects of mine, namely in
 
 and a few others.
 
-[Boost]: boost/build/README.md
-[CMake project]: cmake/build/README.md
+[Boost]: project/boost/README.md
+[CMake project]: project/cmake/README.md
 
 [aes-tools]: https://github.com/egor-tensin/aes-tools
 [math-server]: https://github.com/egor-tensin/math-server
diff --git a/project/boost/README.md b/project/boost/README.md
index c1f903e..5c8240c 100644
--- a/project/boost/README.md
+++ b/project/boost/README.md
@@ -2,12 +2,11 @@ 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:
+A simple usage example to download and build Boost 1.72.0:
 
-    $ python3 build.py download 1.71.0
+    $ python3 -m project.boost.download 1.72.0
     ...
 
-    $ python3 build.py build -- boost_1_71_0/ --with-filesystem --with-program_options
+    $ python3 -m project.boost.build -- boost_1_72_0/ --with-filesystem --with-program_options
     ...
diff --git a/project/boost/archive.py b/project/boost/archive.py
index 55d05f2..e4c85e0 100644
--- a/project/boost/archive.py
+++ b/project/boost/archive.py
@@ -75,8 +75,10 @@ class TemporaryStorage(ArchiveStorage):
 
     @contextmanager
     def write_archive(self, version, contents):
-        with tempfile.NamedTemporaryFile(prefix=f'boost_{version}_', suffix=version.archive_ext,
-                                         dir=self._dir, delete=False) as dest:
+        temp = tempfile.NamedTemporaryFile(prefix=f'boost_{version}_',
+                                           suffix=version.archive_ext,
+                                           dir=self._dir, delete=False)
+        with temp as dest:
             path = dest.name
             logging.info('Writing Boost archive: %s', path)
             dest.write(contents)
diff --git a/project/boost/build.py b/project/boost/build.py
index e17af32..82180a5 100644
--- a/project/boost/build.py
+++ b/project/boost/build.py
@@ -8,10 +8,9 @@ R'''Build Boost.
 This script builds the Boost libraries.  It's main utility is setting the
 correct --stagedir parameter value to avoid name clashes.
 
-Usage examples:
+Usage example:
 
-
-    $ %(prog)s -- boost_1_71_0/ --with-filesystem --with-program_options
+    $ python -m project.boost.build -- boost_1_71_0/ --with-filesystem --with-program_options
     ...
 '''
 
@@ -37,8 +36,9 @@ DEFAULT_B2_ARGS = ['-d0']
 
 
 class BuildParameters:
-    def __init__(self, boost_dir, build_dir=None, platforms=None, configurations=None, link=None,
-                 runtime_link=None, b2_args=None):
+    def __init__(self, boost_dir, build_dir=None, platforms=None,
+                 configurations=None, link=None, runtime_link=None,
+                 b2_args=None):
 
         boost_dir = project.utils.normalize_path(boost_dir)
         if build_dir is not None:
@@ -70,7 +70,9 @@ class BuildParameters:
             for platform in self.platforms:
                 for configuration in self.configurations:
                     for link, runtime_link in self._linkage_options():
-                        yield self._build_params(build_dir, platform, configuration, link, runtime_link)
+                        yield self._build_params(build_dir, platform,
+                                                 configuration, link,
+                                                 runtime_link)
 
     def _linkage_options(self):
         for link in self.link:
@@ -116,14 +118,12 @@ class BuildParameters:
 
     def _stagedir(self, platform, configuration):
         # Having different --stagedir values for every configuration/platform
-        # combination is unnecessary on Windows.
-        # Even for older Boost versions (when the binaries weren't tagged with
-        # their target platform) only a single --stagedir for every platform
-        # would suffice.
-        # For newer versions, just a single --stagedir would do, as the
-        # binaries are tagged with the target platform, as well as their
-        # configuration (a.k.a. "variant" in Boost's terminology).
-        # Still, uniformity helps.
+        # combination is unnecessary on Windows.  Even for older Boost versions
+        # (when the binaries weren't tagged with their target platform) only a
+        # single --stagedir for every platform would suffice.  For newer
+        # versions, just a single --stagedir would do, as the binaries are
+        # tagged with the target platform, as well as their configuration
+        # (a.k.a. "variant" in Boost's terminology).  Still, uniformity helps.
         platform = str(platform)
         configuration = str(configuration)
         return f'--stagedir={os.path.join(self.stage_dir, platform, configuration)}'
@@ -159,28 +159,29 @@ def _parse_args(argv=None):
         description=__doc__,
         formatter_class=argparse.RawDescriptionHelpFormatter)
 
+    platform_options = '/'.join(map(str, Platform.all()))
+    configuration_options = '/'.join(map(str, Configuration.all()))
     # These are used to put the built libraries into proper stage/
     # subdirectories (to avoid name clashes).
-    parser.add_argument('--platform', metavar='PLATFORM',
-                        nargs='*', dest='platforms', default=[],
-                        type=Platform.parse,
-                        help=f'target platform ({"/".join(map(str, Platform))})')
-    parser.add_argument('--configuration', metavar='CONFIGURATION',
-                        nargs='*', dest='configurations', default=[],
-                        type=Configuration.parse,
-                        help=f'target configuration ({"/".join(map(str, Configuration))})')
+    parser.add_argument('--platform', metavar='PLATFORM', dest='platforms',
+                        nargs='*', type=Platform.parse, default=[],
+                        help=f'target platform ({platform_options})')
+    parser.add_argument('--configuration', metavar='CONFIGURATION', dest='configurations',
+                        nargs='*', type=Configuration.parse, default=[],
+                        help=f'target configuration ({configuration_options})')
+
+    linkage_options = '/'.join(map(str, Linkage.all()))
     # 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.
     parser.add_argument('--link', metavar='LINKAGE',
-                        nargs='*', default=[],
-                        type=Linkage.parse,
-                        help=f'how the libraries are linked ({"/".join(map(str, Linkage))})')
+                        nargs='*', type=Linkage.parse, default=[],
+                        help=f'how the libraries are linked ({linkage_options})')
     # 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.
     parser.add_argument('--runtime-link', metavar='LINKAGE',
                         type=Linkage.parse, default=DEFAULT_RUNTIME_LINK,
-                        help=f'how the libraries link to the runtime ({"/".join(map(str, Linkage))})')
+                        help=f'how the libraries link to the runtime ({linkage_options})')
 
     parser.add_argument('--build', metavar='DIR', dest='build_dir',
                         type=project.utils.normalize_path,
@@ -189,7 +190,8 @@ def _parse_args(argv=None):
                         type=project.utils.normalize_path,
                         help='root Boost directory')
 
-    parser.add_argument('b2_args', nargs='*', metavar='B2_ARG', default=[],
+    parser.add_argument('b2_args', metavar='B2_ARG',
+                        nargs='*', default=[],
                         help='additional b2 arguments, to be passed verbatim')
 
     return parser.parse_args(argv)
diff --git a/project/boost/download.py b/project/boost/download.py
index 954ec1f..d135eb3 100644
--- a/project/boost/download.py
+++ b/project/boost/download.py
@@ -10,10 +10,10 @@ is that it's supposed to be cross-platform.
 
 Usage examples:
 
-    $ %(prog)s 1.71.0
+    $ python -m project.boost.download 1.71.0
     ...
 
-    $ %(prog)s --unpack ~/workspace/third-party/ 1.65.0
+    $ python -m project.boost.download --unpack ~/workspace/third-party/ 1.65.0
     ...
 '''
 
@@ -98,8 +98,10 @@ def _parse_args(argv=None):
     parser.add_argument('--cache', metavar='DIR', dest='cache_dir',
                         type=project.utils.normalize_path,
                         help='download directory (temporary file unless specified)')
-    parser.add_argument('version', metavar='VERSION', type=Version.from_string,
+    parser.add_argument('version', metavar='VERSION',
+                        type=Version.from_string,
                         help='Boost version (in the MAJOR.MINOR.PATCH format)')
+
     return parser.parse_args(argv)
 
 
diff --git a/project/ci/appveyor/boost.py b/project/ci/appveyor/boost.py
index 0a15b7b..875d681 100644
--- a/project/ci/appveyor/boost.py
+++ b/project/ci/appveyor/boost.py
@@ -5,10 +5,10 @@
 
 R'''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.
+This is similar to running both project.boost.download & project.boost.build,
+but auto-fills some parameters 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:\projects\boost.
 '''
@@ -67,12 +67,17 @@ def _parse_args(argv=None):
     parser = argparse.ArgumentParser(
         description=__doc__,
         formatter_class=argparse.RawDescriptionHelpFormatter)
-    parser.add_argument('--link', metavar='LINKAGE', nargs='*', type=Linkage.parse,
-                        help='how the libraries are linked (i.e. static/shared)')
-    parser.add_argument('--runtime-link', metavar='LINKAGE', type=Linkage.parse,
+
+    parser.add_argument('--link', metavar='LINKAGE',
+                        nargs='*', type=Linkage.parse,
+                        help='how the libraries are linked')
+    parser.add_argument('--runtime-link', metavar='LINKAGE',
+                        type=Linkage.parse,
                         help='how the libraries link to the runtime')
-    parser.add_argument('b2_args', nargs='*', metavar='B2_ARG', default=[],
+    parser.add_argument('b2_args', metavar='B2_ARG',
+                        nargs='*', default=[],
                         help='additional b2 arguments, to be passed verbatim')
+
     return parser.parse_args(argv)
 
 
diff --git a/project/ci/travis/boost.py b/project/ci/travis/boost.py
index b8e843f..0830544 100644
--- a/project/ci/travis/boost.py
+++ b/project/ci/travis/boost.py
@@ -5,8 +5,8 @@
 
 R'''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.
+This is similar to running both project.boost.download & project.boost.build,
+but auto-fills some parameters from the Travis-defined environment variables.
 
 Boost is built in $HOME/boost.
 '''
@@ -65,12 +65,17 @@ def _parse_args(argv=None):
     parser = argparse.ArgumentParser(
         description=__doc__,
         formatter_class=argparse.RawDescriptionHelpFormatter)
-    parser.add_argument('--link', metavar='LINKAGE', nargs='*', type=Linkage.parse,
+
+    parser.add_argument('--link', metavar='LINKAGE',
+                        nargs='*', type=Linkage.parse,
                         help='how the libraries are linked')
-    parser.add_argument('--runtime-link', metavar='LINKAGE', type=Linkage.parse,
+    parser.add_argument('--runtime-link', metavar='LINKAGE',
+                        type=Linkage.parse,
                         help='how the libraries link to the runtime')
-    parser.add_argument('b2_args', nargs='*', metavar='B2_ARG', default=[],
+    parser.add_argument('b2_args', metavar='B2_ARG',
+                        nargs='*', default=[],
                         help='additional b2 arguments, to be passed verbatim')
+
     return parser.parse_args(argv)
 
 
diff --git a/project/cmake/README.md b/project/cmake/README.md
index b63564d..7a488d9 100644
--- a/project/cmake/README.md
+++ b/project/cmake/README.md
@@ -2,12 +2,11 @@ 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
+    $ python3 -m project.cmake.build --configuration Release --install path/to/somewhere -- examples/simple
     ...
 
-    > ./path/to/somewhere/bin/foo
+    $ ./path/to/somewhere/bin/foo
     foo
diff --git a/project/cmake/build.py b/project/cmake/build.py
index 77242ec..b15badd 100644
--- a/project/cmake/build.py
+++ b/project/cmake/build.py
@@ -14,7 +14,7 @@ but written in bash and PowerShell, respectively).
 
 A simple usage example:
 
-    $ %(prog)s --configuration Release --install path/to/somewhere -- ../examples/simple
+    $ python -m project.cmake.build --configuration Release --install path/to/somewhere -- examples/simple
     ...
 
     $ ./path/to/somewhere/bin/foo
@@ -23,13 +23,13 @@ A simple usage example:
 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
+    > python -m project.cmake.build --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).
+toolchains/cmake in this repository for examples).
 
-    $ %(prog)s --install path/to/somewhere -- ../examples/simple -D CMAKE_TOOLCHAIN_FILE="$( pwd )/../toolchains/mingw-x86.cmake"
+    $ python -m project.cmake.build --install path/to/somewhere -- examples/simple -D CMAKE_TOOLCHAIN_FILE="$( pwd )/toolchains/mingw-x86.cmake"
     ...
 '''
 
@@ -157,10 +157,11 @@ def _parse_args(argv=None):
     parser.add_argument('src_dir', metavar='DIR',
                         type=project.utils.normalize_path,
                         help='source directory')
-    parser.add_argument('cmake_args', nargs='*', metavar='CMAKE_ARG',
+    parser.add_argument('cmake_args', metavar='CMAKE_ARG',
+                        nargs='*', default=[],
                         help='additional CMake arguments, to be passed verbatim')
-    args = parser.parse_args(argv)
-    return args
+
+    return parser.parse_args(argv)
 
 
 def main(argv=None):
diff --git a/toolchains/boost/README.md b/toolchains/boost/README.md
index 8c6870a..a0e7c16 100644
--- a/toolchains/boost/README.md
+++ b/toolchains/boost/README.md
@@ -1,2 +1,2 @@
 Use the toolchain files by passing something like
-`--user-config=PATH/TO/cmake-common/boost/toolchains/TOOLCHAIN.jam` to `b2`.
+`--user-config=PATH/TO/cmake-common/toolchains/boost/TOOLCHAIN.jam` to `b2`.
diff --git a/toolchains/cmake/README.md b/toolchains/cmake/README.md
index 9c58eb6..bd04031 100644
--- a/toolchains/cmake/README.md
+++ b/toolchains/cmake/README.md
@@ -1,3 +1,3 @@
 Use the toolchain files by passing something like
-`-D CMAKE_TOOLCHAIN_FILE=PATH/TO/cmake-common/cmake/toolchains/TOOLCHAIN.cmake`
+`-D CMAKE_TOOLCHAIN_FILE=PATH/TO/cmake-common/toolchains/cmake/TOOLCHAIN.cmake`
 to `cmake`.