From 1c91b96f8740daad93991d50c086fbaf1f08770d Mon Sep 17 00:00:00 2001 From: Egor Tensin Date: Thu, 9 Jan 2020 02:27:57 +0300 Subject: better usage messages & READMEs --- cmake/build/README.md | 13 +++++++++++++ cmake/build/build.py | 38 ++++++++++++++++++++++++++++++++------ cmake/build/ci/appveyor.py | 16 ++++++++++++---- cmake/build/ci/travis.py | 15 +++++++++++---- 4 files changed, 68 insertions(+), 14 deletions(-) create mode 100644 cmake/build/README.md (limited to 'cmake/build') 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=[], -- cgit v1.2.3