diff --git a/doc/src/Build_cmake.rst b/doc/src/Build_cmake.rst index c41136c0a5..206fd05253 100644 --- a/doc/src/Build_cmake.rst +++ b/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 -indicated above, producing (by default) an executable called "lmp" and -a library called "liblammps.a" in the "build" folder. When generating +and thus the ``make`` command will be used to compile and link LAMMPS as +indicated above, producing (by default) an executable called ``lmp`` and +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 ` 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=``. 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*), -and a graphical GUI version (*cmake-gui*). You can use any of them +(``cmake`` or ``cmake3``), a text mode UI version (``ccmake`` or ``ccmake3``), +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 ` 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 `. 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. diff --git a/doc/src/Tools.rst b/doc/src/Tools.rst index 6137b1aa6f..080b87b310 100644 --- a/doc/src/Tools.rst +++ b/doc/src/Tools.rst @@ -40,33 +40,61 @@ own sub-directories with their own Makefiles and/or README files. Pre-processing tools ==================== -+-----------------------------+------------------------+----------------------+----------------------------------+----------------------------------+-----------------------------+ -| :ref:`amber2lmp ` | :ref:`ch2lmp ` | :ref:`chain ` | :ref:`createatoms ` | :ref:`drude ` | :ref:`eam database ` | -+-----------------------------+------------------------+----------------------+----------------------------------+----------------------------------+-----------------------------+ -| :ref:`eam generate ` | :ref:`eff ` | :ref:`ipp ` | :ref:`micelle2d ` | :ref:`moltemplate ` | :ref:`msi2lmp ` | -+-----------------------------+------------------------+----------------------+----------------------------------+----------------------------------+-----------------------------+ -| :ref:`polybond ` | | | | | | -+-----------------------------+------------------------+----------------------+----------------------------------+----------------------------------+-----------------------------+ +.. table_from_list:: + :columns: 6 + + * :ref:`amber2lmp ` + * :ref:`ch2lmp ` + * :ref:`chain ` + * :ref:`createatoms ` + * :ref:`drude ` + * :ref:`eam database ` + * :ref:`eam generate ` + * :ref:`eff ` + * :ref:`ipp ` + * :ref:`micelle2d ` + * :ref:`moltemplate ` + * :ref:`msi2lmp ` + * :ref:`polybond ` + Post-processing tools ===================== -+--------------------------+----------------------------+------------------------+--------------------------+-------------------------------+-----------------------------+ -| :ref:`amber2lmp ` | :ref:`binary2txt ` | :ref:`ch2lmp ` | :ref:`colvars ` | :ref:`eff ` | :ref:`fep ` | -+--------------------------+----------------------------+------------------------+--------------------------+-------------------------------+-----------------------------+ -| :ref:`lmp2arc ` | :ref:`lmp2cfg ` | :ref:`matlab ` | :ref:`phonon ` | :ref:`pymol_asphere ` | :ref:`python ` | -+--------------------------+----------------------------+------------------------+--------------------------+-------------------------------+-----------------------------+ -| :ref:`reax ` | :ref:`replica ` | :ref:`smd ` | :ref:`spin ` | :ref:`xmgrace ` | | -+--------------------------+----------------------------+------------------------+--------------------------+-------------------------------+-----------------------------+ +.. table_from_list:: + :columns: 6 + + * :ref:`amber2lmp ` + * :ref:`binary2txt ` + * :ref:`ch2lmp ` + * :ref:`colvars ` + * :ref:`eff ` + * :ref:`fep ` + * :ref:`lmp2arc ` + * :ref:`lmp2cfg ` + * :ref:`matlab ` + * :ref:`phonon ` + * :ref:`pymol_asphere ` + * :ref:`python ` + * :ref:`reax ` + * :ref:`replica ` + * :ref:`smd ` + * :ref:`spin ` + * :ref:`xmgrace ` Miscellaneous tools =================== -+--------------------------+----------------------+-------------------+--------------------+---------------------------------------+ -| :ref:`doxygen ` | :ref:`emacs ` | :ref:`i-pi ` | :ref:`kate ` | :ref:`singularity ` | -+--------------------------+----------------------+-------------------+--------------------+---------------------------------------+ -| :ref:`vim ` | | | | | -+--------------------------+----------------------+-------------------+--------------------+---------------------------------------+ +.. table_from_list:: + :columns: 6 + + * :ref:`CMake ` + * :ref:`doxygen ` + * :ref:`emacs ` + * :ref:`i-pi ` + * :ref:`kate ` + * :ref:`singularity ` + * :ref:`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 `. +---------- + +.. _cmake: + +CMake tools +----------- + +The ``cmbuild`` script is a wrapper around using ``cmake --build +--target`` and allows compiling LAMMPS in a :ref:`CMake build folder +` 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=``. + +.. parsed-literal:: + + Usage: cmbuild [-v] [-h] [-C ] [-j ] [ [] ...] + + Options: + -h print this message + -j allow processing of NUM concurrent tasks + -C DIRECTORY execute build in folder DIRECTORY + -v produce verbose output + + ---------- .. _colvars: diff --git a/tools/README b/tools/README index b20e82c53e..2a6f28caf0 100644 --- a/tools/README +++ b/tools/README @@ -12,36 +12,37 @@ at. These are the included tools: -amber2lmp python scripts for using AMBER to setup LAMMPS input -binary2txt convert a LAMMPS dump file from binary to ASCII text -ch2lmp convert CHARMM files to LAMMPS input -chain create a data file of bead-spring chains -colvars post-process output of the fix colvars command -createatoms generate lattices of atoms within a geometry +amber2lmp python scripts for using AMBER to setup LAMMPS input +binary2txt convert a LAMMPS dump file from binary to ASCII text +ch2lmp convert CHARMM files to LAMMPS input +chain create a data file of bead-spring chains +cmake tools and scripts for use with CMake +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_generate 2nd tool to generate EAM alloy potential files -eff scripts for working with the eFF (electron force field) -emacs add-ons to EMACS editor for editing LAMMPS input scripts -fep scripts for free-energy perturbation with USER-FEP pkg +eam_database one 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) +emacs add-ons to EMACS editor for editing LAMMPS input scripts +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 -lmp2cfg convert LAMMPS output to CFG files for AtomEye viz -matlab MatLab scripts for post-processing LAMMPS output -micelle2d create a data file of small lipid chains in solvent +lmp2arc convert LAMMPS output to Accelrys Insight format +lmp2cfg convert LAMMPS output to CFG files for AtomEye viz +matlab MatLab scripts for post-processing LAMMPS output +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 -python Python scripts for post-processing LAMMPS output -reax Tools for analyzing output of ReaxFF simulations -replica tool to reorder LAMMPS replica trajectories according to temperature +pymol_asphere convert LAMMPS output of ellipsoids to PyMol format +python Python scripts for post-processing LAMMPS output +reax Tools for analyzing output of ReaxFF simulations +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 diff --git a/tools/cmake/cmbuild b/tools/cmake/cmbuild new file mode 100755 index 0000000000..f9c5223048 --- /dev/null +++ b/tools/cmake/cmbuild @@ -0,0 +1,69 @@ +#!/bin/bash +# make like wrapper around "cmake --build" +# (c) 2020 Axel Kohlmeyer +# This file is in the public domain + +WORKDIR="${PWD}" +PARAMS="" +MYARGS="" + +usage() +{ + echo "Usage: cmbuild [-v] [-h] [-C ] [-j ] [ [] ...]" >&2 +} + +help() +{ + usage + cat >&2 < 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 "$@"