aboutsummaryrefslogtreecommitdiffstatshomepage
diff options
context:
space:
mode:
authorEgor Tensin <Egor.Tensin@gmail.com>2020-01-09 02:27:57 +0300
committerEgor Tensin <Egor.Tensin@gmail.com>2020-01-09 02:27:57 +0300
commit1c91b96f8740daad93991d50c086fbaf1f08770d (patch)
treee4d62d7f1d22d23eed1bebf00c80cb175bc58ce6
parentcommon.cmake: more precise platform detection (diff)
downloadcmake-common-1c91b96f8740daad93991d50c086fbaf1f08770d.tar.gz
cmake-common-1c91b96f8740daad93991d50c086fbaf1f08770d.zip
better usage messages & READMEs
Diffstat (limited to '')
-rw-r--r--README.md13
-rw-r--r--boost/build/README.md13
-rwxr-xr-xboost/build/build.py50
-rw-r--r--boost/build/ci/appveyor.py18
-rwxr-xr-xboost/build/ci/travis.py16
-rw-r--r--boost/toolchains/README.md2
-rw-r--r--cmake/build/README.md13
-rwxr-xr-xcmake/build/build.py38
-rwxr-xr-xcmake/build/ci/appveyor.py16
-rwxr-xr-xcmake/build/ci/travis.py15
-rw-r--r--cmake/toolchains/README.md4
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`.