provide cmbuild wrapper script for cmake. document it and add some improvements to CMake build docs

doc/src/Build_cmake.rst

@@ -22,27 +22,31 @@ Makefile(s). Example:
    cd lammps                        # change to the LAMMPS distribution directory
    mkdir build; cd build            # create a new directory (folder) for build
    cmake [options ...] ../cmake     # configuration with (command-line) cmake
-   make                             # compilation
+   make                             # compilation (or use "cmbuild" from "tools/cmake")
 
-The cmake command will detect available features, enable selected
+The ``cmake`` command will detect available features, enable selected
 packages and options, and will generate the build environment.  By default
 this build environment will be created for "Unix Makefiles" on most
 platforms and particularly on Linux.  However, alternate build tools
 (e.g. Ninja) and project files for Integrated Development Environments
 (IDEs) like Eclipse, CodeBlocks, or Kate can be generated, too. This is
-selected via the "-G" command line flag. For the rest of the documentation
+selected via the ``-G`` command line flag. For the rest of the documentation
 we will assume that the build environment is generated for makefiles
-and thus the make command will be used to compile and link LAMMPS as
+and thus the ``make`` command will be used to compile and link LAMMPS as
-indicated above, producing (by default) an executable called "lmp" and
+indicated above, producing (by default) an executable called ``lmp`` and
-a library called "liblammps.a" in the "build" folder.  When generating
+a library called ``liblammps.a`` in the ``build`` folder.  When generating
 a build environment for the "Ninja" build tool, the build command would
-be "ninja" instead of "make".
+be ``ninja`` instead of ``make``.  Or you may copy the ``cmbuild`` script
+from the :ref:`tools/cmake folder <cmake>` somewhere in your path and use that,
+as it will indirectly call CMake with the configured tool.  This is
+particularly, if you configured the build folder with a build tool
+in a non-standard location or name using ``-D CMAKE_MAKE_PROGRAM=<name>``.
 
 If your machine has multiple CPU cores (most do these days), using a
-command like "make -jN" (with N being the number of available local
+command like ``make -j N`` (with N being the number of available local
 CPU cores) can be much faster.  If you plan to do development on
 LAMMPS or need to re-compile LAMMPS repeatedly, installation of the
-ccache (= Compiler Cache) software may speed up repeated compilation
+``ccache`` (= Compiler Cache) software may speed up repeated compilation
 even more.
 
 After compilation, you may optionally install the LAMMPS executable into
@@ -60,9 +64,11 @@ to ${HOME}/.local
 
 ----------
 
+.. _cmake_build:
+
 There are 3 variants of the CMake command itself: a command-line version
-(*cmake* or *cmake3*), a text mode UI version (*ccmake* or *ccmake3*),
+(``cmake`` or ``cmake3``), a text mode UI version (``ccmake`` or ``ccmake3``),
-and a graphical GUI version (*cmake-gui*).  You can use any of them
+and a graphical GUI version (``cmake-gui``).  You can use any of them
 interchangeably to configure and create the LAMMPS build environment.
 On Linux all the versions produce a Makefile as their output by default.
 See more details on each below.
@@ -75,7 +81,7 @@ the :doc:`Build <Build>` doc page.
 You must perform the CMake build system generation and compilation in
 a new directory you create.  It can be anywhere on your local machine.
 In these Build pages we assume that you are building in a directory
-called "lammps/build".  You can perform separate builds independently
+called ``lammps/build``.  You can perform separate builds independently
 with different options, so long as you perform each of them in a
 separate directory you create.  All the auxiliary files created by one
 build process (executable, object files, log files, etc) are stored in
@@ -84,10 +90,10 @@ this directory or sub-directories within it that CMake creates.
 .. note::
 
    To perform a CMake build, no packages can be installed or a build
-   been previously attempted in the LAMMPS src directory by using "make"
+   been previously attempted in the LAMMPS src directory by using ``make``
    commands to :doc:`perform a conventional LAMMPS build <Build_make>`.
    CMake detects if this is the case and generates an error, telling you
-   to type "make no-all purge" in the src directory to un-install all
+   to type ``make no-all purge`` in the src directory to un-install all
    packages.  The purge removes all the \*.h files auto-generated by
    make.
 

doc/src/Tools.rst

@@ -40,33 +40,61 @@ own sub-directories with their own Makefiles and/or README files.
 Pre-processing tools
 ====================
 
-+-----------------------------+------------------------+----------------------+----------------------------------+----------------------------------+-----------------------------+
+.. table_from_list::
-| :ref:`amber2lmp <amber>`    | :ref:`ch2lmp <charmm>` | :ref:`chain <chain>` | :ref:`createatoms <createatoms>` | :ref:`drude <drude>`             | :ref:`eam database <eamdb>` |
+   :columns: 6
-+-----------------------------+------------------------+----------------------+----------------------------------+----------------------------------+-----------------------------+
+
-| :ref:`eam generate <eamgn>` | :ref:`eff <eff>`       | :ref:`ipp <ipp>`     | :ref:`micelle2d <micelle>`       | :ref:`moltemplate <moltemplate>` | :ref:`msi2lmp <msi>`        |
+   * :ref:`amber2lmp <amber>`
-+-----------------------------+------------------------+----------------------+----------------------------------+----------------------------------+-----------------------------+
+   * :ref:`ch2lmp <charmm>`
-| :ref:`polybond <polybond>`  |                        |                      |                                  |                                  |                             |
+   * :ref:`chain <chain>`
-+-----------------------------+------------------------+----------------------+----------------------------------+----------------------------------+-----------------------------+
+   * :ref:`createatoms <createatoms>`
+   * :ref:`drude <drude>`
+   * :ref:`eam database <eamdb>`
+   * :ref:`eam generate <eamgn>`
+   * :ref:`eff <eff>`
+   * :ref:`ipp <ipp>`
+   * :ref:`micelle2d <micelle>`
+   * :ref:`moltemplate <moltemplate>`
+   * :ref:`msi2lmp <msi>`
+   * :ref:`polybond <polybond>`
+
 
 Post-processing tools
 =====================
 
-+--------------------------+----------------------------+------------------------+--------------------------+-------------------------------+-----------------------------+
+.. table_from_list::
-| :ref:`amber2lmp <amber>` | :ref:`binary2txt <binary>` | :ref:`ch2lmp <charmm>` | :ref:`colvars <colvars>` | :ref:`eff <eff>`              | :ref:`fep <fep>`            |
+   :columns: 6
-+--------------------------+----------------------------+------------------------+--------------------------+-------------------------------+-----------------------------+
+
-| :ref:`lmp2arc <arc>`     | :ref:`lmp2cfg <cfg>`       | :ref:`matlab <matlab>` | :ref:`phonon <phonon>`   | :ref:`pymol_asphere <pymol>`  | :ref:`python <pythontools>` |
+   * :ref:`amber2lmp <amber>`
-+--------------------------+----------------------------+------------------------+--------------------------+-------------------------------+-----------------------------+
+   * :ref:`binary2txt <binary>`
-| :ref:`reax <reax_tool>`  | :ref:`replica <replica>`   | :ref:`smd <smd>`       | :ref:`spin <spin>`       | :ref:`xmgrace <xmgrace>`      |                             |
+   * :ref:`ch2lmp <charmm>`
-+--------------------------+----------------------------+------------------------+--------------------------+-------------------------------+-----------------------------+
+   * :ref:`colvars <colvars>`
+   * :ref:`eff <eff>`
+   * :ref:`fep <fep>`
+   * :ref:`lmp2arc <arc>`
+   * :ref:`lmp2cfg <cfg>`
+   * :ref:`matlab <matlab>`
+   * :ref:`phonon <phonon>`
+   * :ref:`pymol_asphere <pymol>`
+   * :ref:`python <pythontools>`
+   * :ref:`reax <reax_tool>`
+   * :ref:`replica <replica>`
+   * :ref:`smd <smd>`
+   * :ref:`spin <spin>`
+   * :ref:`xmgrace <xmgrace>`
 
 Miscellaneous tools
 ===================
 
-+--------------------------+----------------------+-------------------+--------------------+---------------------------------------+
+.. table_from_list::
-| :ref:`doxygen <doxygen>` | :ref:`emacs <emacs>` | :ref:`i-pi <ipi>` | :ref:`kate <kate>` | :ref:`singularity <singularity_tool>` |
+   :columns: 6
-+--------------------------+----------------------+-------------------+--------------------+---------------------------------------+
+
-| :ref:`vim <vim>`         |                      |                   |                    |                                       |
+   * :ref:`CMake <cmake>`
-+--------------------------+----------------------+-------------------+--------------------+---------------------------------------+
+   * :ref:`doxygen <doxygen>`
+   * :ref:`emacs <emacs>`
+   * :ref:`i-pi <ipi>`
+   * :ref:`kate <kate>`
+   * :ref:`singularity <singularity_tool>`
+   * :ref:`vim <vim>`
 
 ----------
 
@@ -157,6 +185,30 @@ See the def.chain or def.chain.ab files in the tools directory for
 examples of definition files.  This tool was used to create the system
 for the :doc:`chain benchmark <Speed_bench>`.
 
+----------
+
+.. _cmake:
+
+CMake tools
+-----------
+
+The ``cmbuild`` script is a wrapper around using ``cmake --build <dir>
+--target`` and allows compiling LAMMPS in a :ref:`CMake build folder
+<cmake_build>` with a make-like syntax regardless of the actual build
+tool and the specific name of the program used (e.g. ``ninja-v1.10`` or
+``gmake``) when using ``-D CMAKE_MAKE_PROGRAM=<name>``.
+
+.. parsed-literal::
+
+  Usage: cmbuild [-v] [-h] [-C <dir>] [-j <num>] [<target1> [<target2>] ...]
+
+  Options:
+    -h                print this message
+    -j <NUM>          allow processing of NUM concurrent tasks
+    -C DIRECTORY      execute build in folder DIRECTORY
+    -v                produce verbose output
+
+
 ----------
 
 .. _colvars:

tools/README

@@ -12,36 +12,37 @@ at.
 
 These are the included tools:
 
-amber2lmp	       python scripts for using AMBER to setup LAMMPS input
+amber2lmp              python scripts for using AMBER to setup LAMMPS input
-binary2txt	       convert a LAMMPS dump file from binary to ASCII text
+binary2txt             convert a LAMMPS dump file from binary to ASCII text
-ch2lmp		       convert CHARMM files to LAMMPS input
+ch2lmp                 convert CHARMM files to LAMMPS input
-chain		       create a data file of bead-spring chains
+chain                  create a data file of bead-spring chains
-colvars		       post-process output of the fix colvars command        
+cmake                  tools and scripts for use with CMake
-createatoms	       generate lattices of atoms within a geometry
+colvars                post-process output of the fix colvars command
+createatoms            generate lattices of atoms within a geometry
 drude                  create Drude core/electron atom pairs in a data file
-eam_database	       one tool to generate EAM alloy potential files
+eam_database           one tool to generate EAM alloy potential files
-eam_generate	       2nd tool to generate EAM alloy potential files
+eam_generate           2nd tool to generate EAM alloy potential files
-eff		       scripts for working with the eFF (electron force field)
+eff                    scripts for working with the eFF (electron force field)
-emacs		       add-ons to EMACS editor for editing LAMMPS input scripts
+emacs                  add-ons to EMACS editor for editing LAMMPS input scripts
-fep		       scripts for free-energy perturbation with USER-FEP pkg
+fep                    scripts for free-energy perturbation with USER-FEP pkg
 i-pi                   Python wrapper for performing path-integral MD (PIMD)
-ipp		       input pre-processor Perl tool for creating input scripts
+ipp                    input pre-processor Perl tool for creating input scripts
 kate                   add-ons to Kate editor for editing LAMMPS input scripts
-lmp2arc		       convert LAMMPS output to Accelrys Insight format
+lmp2arc                convert LAMMPS output to Accelrys Insight format
-lmp2cfg		       convert LAMMPS output to CFG files for AtomEye viz
+lmp2cfg                convert LAMMPS output to CFG files for AtomEye viz
-matlab		       MatLab scripts for post-processing LAMMPS output
+matlab                 MatLab scripts for post-processing LAMMPS output
-micelle2d	       create a data file of small lipid chains in solvent
+micelle2d              create a data file of small lipid chains in solvent
 moltemplate            Instructions for installing the Moltemplate builder program
-msi2lmp		       use Accelrys Insight code to setup LAMMPS input
+msi2lmp                use Accelrys Insight code to setup LAMMPS input
 phonon                 post-process output of the fix phonon command
 polybond               Python tool for programmable polymer bonding
-pymol_asphere	       convert LAMMPS output of ellipsoids to PyMol format
+pymol_asphere          convert LAMMPS output of ellipsoids to PyMol format
-python		       Python scripts for post-processing LAMMPS output
+python                 Python scripts for post-processing LAMMPS output
-reax	       	       Tools for analyzing output of ReaxFF simulations
+reax                   Tools for analyzing output of ReaxFF simulations
-replica        tool to reorder LAMMPS replica trajectories according to temperature
+replica                tool to reorder LAMMPS replica trajectories according to temperature
 smd                    convert Smooth Mach Dynamics triangles to VTK
 spin                   perform a cubic polynomial interpolation of a GNEB MEP
-vim		       add-ons to VIM editor for editing LAMMPS input scripts
+vim                    add-ons to VIM editor for editing LAMMPS input scripts
 xmgrace                a collection of scripts to generate xmgrace plots
 
 For tools that are single C, C++, or Fortran files, a Makefile for

tools/cmake/cmbuild

@@ -0,0 +1,69 @@
+#!/bin/bash
+# make like wrapper around "cmake --build"
+# (c) 2020 Axel Kohlmeyer <akohlmey@temple.edu>
+# This file is in the public domain
+
+WORKDIR="${PWD}"
+PARAMS=""
+MYARGS=""
+
+usage()
+{
+   echo "Usage: cmbuild [-v] [-h] [-C <dir>] [-j <num>] [<target1> [<target2>] ...]" >&2
+}
+
+help()
+{
+   usage
+   cat >&2 <<EOF
+
+Options:
+  -h                print this message
+  -j <NUM>          allow processing of NUM concurrent tasks
+  -C DIRECTORY      execute build in folder DIRECTORY
+  -v                produce verbose output
+EOF
+}
+
+while (( "$#" )); do
+    case "$1" in
+      -C)
+        WORKDIR="$2"
+        shift 2
+        ;;
+      -v)
+        MYARGS="${MYARGS} -v"
+        shift
+        ;;
+      -h)
+        help
+        exit 2
+        ;;
+      -j)
+        MYARGS="${MYARGS} -j $2"
+        shift 2
+        ;;
+      --)
+        shift
+        break
+        ;;
+      -*)
+        echo "Error: Unsupported flag $1" >&2
+        echo
+        usage
+        exit 1
+        ;;
+      *)
+        PARAMS="${PARAMS} $1"
+        shift
+        ;;
+    esac
+done
+
+if [ ! -f "${WORKDIR}/CMakeCache.txt" ] ; then
+   echo "Must execute in a CMake build directory or use -C flag to select one" >&2
+   exit 3
+fi
+
+eval set -- "${PARAMS} $@"
+exec cmake --build "${WORKDIR}" ${MYARGS} --target "$@"