From 0b523cb48e2fcb884a273b3d76474d2c19ae5c33 Mon Sep 17 00:00:00 2001
From: Axel Kohlmeyer <akohlmey@gmail.com>
Date: Fri, 10 Aug 2018 11:38:59 +0200
Subject: [PATCH] some rewording and updates for the traditional and cmake
 documentation

---
 doc/src/Build.txt        |   8 ++-
 doc/src/Build_basics.txt |   2 +-
 doc/src/Build_cmake.txt  | 146 +++++++++++++++++++++++----------------
 doc/src/Build_make.txt   |  48 ++++++++-----
 doc/src/Run_basics.txt   |  24 ++++---
 5 files changed, 138 insertions(+), 90 deletions(-)

diff --git a/doc/src/Build.txt b/doc/src/Build.txt
index 287e151c31..76aa95de55 100644
--- a/doc/src/Build.txt
+++ b/doc/src/Build.txt
@@ -10,9 +10,11 @@ Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Run.html :c
 Build LAMMPS :h2
 
 LAMMPS can be built as an executable or library from source code via
-either CMake or traditional make.  As an alternative you can download
-a pre-built executable file as described on the "Install"_Install.html
-doc page.
+either traditional makefiles (which may require manual editing)
+for use with GNU make or gmake, or a build environment generated by CMake
+(Unix Makefiles, Xcode, Visual Studio, KDevelop or more).  As an
+alternative you can download a package with pre-built executables
+as described on the "Install"_Install.html doc page.
 
 <!-- RST
 
diff --git a/doc/src/Build_basics.txt b/doc/src/Build_basics.txt
index 454e5fbe35..ccfb2b444c 100644
--- a/doc/src/Build_basics.txt
+++ b/doc/src/Build_basics.txt
@@ -301,7 +301,7 @@ want to copy files to is protected.
 
 [CMake variable]:
 
-cmake -D CMAKE_INSTALL_PREFIX=path \[options ...\] ~/lammps/cmake
+cmake -D CMAKE_INSTALL_PREFIX=path \[options ...\] ../cmake
 make                        # perform make after CMake command
 make install                # perform the installation into prefix :pre
 
diff --git a/doc/src/Build_cmake.txt b/doc/src/Build_cmake.txt
index b4f160f371..903c92f584 100644
--- a/doc/src/Build_cmake.txt
+++ b/doc/src/Build_cmake.txt
@@ -18,32 +18,42 @@ for how to use CMake to build LAMMPS.  If you are new to CMake it is a
 good place to start:
 
 "Bulding LAMMPS using
-CMake"_https://github.com/rbberger/lammps/tree/cmake_documentation/cmake
+CMake"_https://github.com/lammps/lammps/blob/master/cmake/README.md
+:line
+
+Building LAMMPS with CMake is a two-step process.  First you use CMake
+to create a build environment in a new folder.  On Linux systems, this
+will be based on makefiles for use with make.  Then you use the make
+command to build LAMMPS, which uses the created Makefile(s). Example:
+
+cd lammps                        # change to the folder with the LAMMPS sources
+mkdir build; cd build            # create a new dir for build          
+cmake ../cmake \[options ...\]   # configuration with (command-line) cmake
+make                             # compilation :pre
+
+The cmake command will detect available features, enable selected
+packages and options, and will generate the build environment.  The make
+command will then compile and link LAMMPS, producing (by default) an
+executable called "lmp" and a library called "liblammps.a" in the
+"build" folder.
+
+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 CPU
+cores) can be much faster.  If you plan to do development on LAMMPS or
+may need to recompile LAMMPS repeatedly, the installation of the ccache
+(= Compiler Cache) software may speed up compilation even more.
+
+After compilation, you optionally, can copy the LAMMPS executable and
+library into your system folders (by default under /usr/local) with:
+
+make install    # optional, copy LAMMPS executable & library elsewhere :pre
 
 :line
 
-Building LAMMPS with CMake is a two-step process.  First use CMake to
-create a Makefile.  Then use the standard make command to build
-LAMMPS, which uses the created Makefile.
-
-mkdir mydir; cd mydir                  # create a new dir for build          
-cmake ~/lammps/cmake \[options ...\]   # command-line version
-ccmake ~/lammps/cmake                  # curses version (terminal-style menu)
-cmake-gui ~/lammps/cmake               # GUI version
-make                                   # traditional make command
-make install                           # optional, copy LAMMPS executable & library elsewhere :pre
-
-The make command will compile and link LAMMPS, producing the
-executable lmp and the library liblammps.a in mydir.
-
-If your machine has multiple cores (most do), using a command like
-"make -j" will be much faster.
-
-:line
-
-There are 3 variants of CMake: a command-line verison, a curses
-version (teminal-style menu), and a GUI version.  You can use any of
-them to build LAMMPS.  All the versions produce a Makefile as their
+There are 3 variants of CMake: a command-line verison (cmake), a text mode
+UI version (ccmake), 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.  See more details on each below.
 
 You can specify a variety of options with any of the 3 versions, which
@@ -51,39 +61,41 @@ affect how the build is performed and what is included in the LAMMPS
 executable.  Links to pages explaining all the options are listed on
 the "Build"_Build.html doc page.
 
-Perform the build in a new directory you create.  It can be a sub-dir
-within lammps/cmake or anywhere you wish.  You can perform separate
-builds, with different options, in as many directories as you like.
-All the auxiliary files created by the build (executable, object
-files, log files, etc) are stored in that directory or sub-directories
-within it that CMake creates.
+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 the following, we will assume, that you are building in the folder
+"lammps/build".  You can perform separate builds independently at the
+same time and with different options, for as long as you put each of
+them into a separate directory. There can be as many build directories
+as you like. All the auxiliary files created by the build (executable,
+object files, log files, etc) are stored in that directory or
+sub-directories within it that CMake creates.
 
-NOTE: To perform a CMake build, no packages can be installed in the
-LAMMPS src dir.  Likewise no style*.h or a lmpinstalledpkgs.h file can
-exist, which are auto-generated by "building LAMMPS via traditional
-make"_Build_make.html.  CMake detects if this is not the case and
+NOTE: To perform a CMake build, no packages may be installed or a build
+attempted in the LAMMPS src folder using the "conventional build
+procedure"_Build_make.html.  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 packages.  The purge removes all the
 auto-generated *.h files.
 
-You must have CMake version 2.8 or later on your system to build
-LAMMPS.  If you include the GPU package, version 3.2 or later is
+You must have CMake version 2.8 or later on your system to build LAMMPS.
+If you include the GPU or KOKKOS packages, CMake version 3.2 or later is
 required.  Installation instructions for CMake are below.
 
 After the initial build, if you edit LAMMPS source files, or add your
 own new files to the source directory, you can just re-type make from
 your build directory and it will re-compile only the files that have
-changed.  If you want to change CMake options, you can remove the
-cache file CMakeCache.txt in the build directory and start over.  Or
-you can run cmake again from the same build directory and alter
-various options; see details below.
+changed.  If you want to change CMake options you can run cmake (or
+ccmake or cmake-gui) again from the same build directory and alter
+various options; see details below.  Or you can remove the entire build
+folder, recreate the directory and start over.
 
 :line
 
 [Command-line version of CMake]:
 
-cmake \[options ...\] ~/lammps/cmake      # build from any dir
-cmake \[options ...\] ..                  # build from lammps/cmake/newdir :pre
+cmake \[options ...\] /path/to/lammps/cmake  # build from any dir
+cmake \[options ...\] ../cmake               # build from lammps/build :pre
 
 The cmake command takes one required argument, which is the LAMMPS
 cmake directory which contains the CMakeLists.txt file.
@@ -103,20 +115,23 @@ All of these variable names are upper-case and their values are
 lower-case, e.g. -D LAMMPS_SIZES=smallbig.  For boolean values, any of
 these forms can be used: yes/no, on/off, 1/0.
 
-On Unix/Linux CMake generates a Makefile by default to perform the LAMMPS build.
-Alternate forms of build info can be generated via the -G switch,
-e.g. Visual Studio on a Windows machine.  Type "cmake --help" to see
-the "Generator" styles of output your system supports.
+On Unix/Linux CMake generates a Makefile by default to perform the
+LAMMPS build.  Alternate forms of build info can be generated via the 
+-G switch, e.g. Visual Studio on a Windows machine, Xcode on MacOS or
+KDevelop on Linux.  Type "cmake --help" to see the "Generator" styles
+of output your system supports.
 
 NOTE: When CMake runs, it prints configuration info to the screen.
-You should scan this to verify all the features you requested were
-enabled, including packages.  You can also see what compiler and
+You should review this to verify all the features you requested were
+enabled, including packages.  You can also see what compilers and
 compile options will be used for the build.  Any errors will also be
 flagged, e.g. mis-typed variable names or variable values.
 
 CMake creates a CMakeCache.txt file when it runs.  This stores all the
-settings, so that running CMake again from the same directory will
-inherit those settings.
+settings, so that when running CMake again you can use the current
+folder '.' instead of the path to the LAMMPS cmake folder as the
+required argument to the CMake command. Either way the existing
+settings will be inherited unless the CMakeCache.txt file is removed.
 
 If you later want to change a setting you can rerun cmake in the build
 directory with different setting. Please note that some automatically
@@ -125,15 +140,28 @@ usually better to start with a fresh build directory.
 
 [Curses version (terminal-style menu) of CMake]:
 
-ccmake ~/lammps/cmake :pre
+ccmake ../cmake :pre
 
-Please see the "ccmake manual"_https://cmake.org/cmake/help/latest/manual/ccmake.1.html for more information.
+You initiate the configuration and build environment generation steps
+separately. For the first you have to type [c], for the second you have
+to type [g]. You may need to type [c] multiple times, and may be
+required to edit some of the entries of CMake configuration variables in
+between.  Please see the "ccmake
+manual"_https://cmake.org/cmake/help/latest/manual/ccmake.1.html for
+more information.
 
 [GUI version of CMake]:
 
-cmake-gui ~/lammps/cmake :pre
+cmake-gui ../cmake :pre
 
-Please see the "cmake-gui manual"_https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html for more information.
+You initiate the configuration and build environment generation steps
+separately. For the first you have to click on the [Configure] button,
+for the second you have to click on the [Generate] button.  You may need
+to click on [Configure] multiple times, and may be required to edit some
+of the entries of CMake configuration variables in between.  Please see
+the "cmake-gui
+manual"_https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html for
+more information.
 
 :line
 
@@ -145,14 +173,16 @@ which cmake             # do you have it?
 which cmake3            # version 3 may have this name
 cmake --version         # what specific version you have :pre
 
-On clusters or supercomputers which use modules to manage software
-packages, do this:
+On clusters or supercomputers which use environment modules to manage
+software packages, do this:
 
 module list            # is a cmake module is already loaded
 module avail           # is a cmake module available?
 module load cmake3     # load cmake module with appropriate name :pre
 
-If you do not have CMake or a new enough version, you can download the latest
-version at "https://cmake.org/download/"_https://cmake.org/download/.
-Instructions on how to install it on various platforms can be found
+Most Linux distributions offer precompiled cmake packages through their
+package management system. If you do not have CMake or a new enough
+version, you can download the latest version at
+"https://cmake.org/download/"_https://cmake.org/download/.  Instructions
+on how to install it on various platforms can be found
 "here"_https://cmake.org/install/.
diff --git a/doc/src/Build_make.txt b/doc/src/Build_make.txt
index 4603a986a3..e8926df6ad 100644
--- a/doc/src/Build_make.txt
+++ b/doc/src/Build_make.txt
@@ -9,15 +9,18 @@ Documentation"_ld - "LAMMPS Commands"_lc :c
 
 Build LAMMPS with make :h3
 
-Building LAMMPS with traditional make requires you have a
-Makefile.machine file in the src/MAKE directory appropriate for your
-system (see below).  It can list various options for what to
-include/exclude in a LAMMPS build.  To include LAMMPS packages you
-must install them first, as discussed on the "Build
-package"_Build_package.html doc page.  If the packages use provided or
-external libraries, you must build those libraries before building
-LAMMPS.  Building "LAMMPS with CMake"_Build_cmake.html can automate
-all of this, so we suggest you try it first.
+Building LAMMPS with traditional makefiles requires, that you have a
+Makefile."machine" file in the src/MAKE, src/MAKE/MACHINES,
+src/MAKE/OPTIONS, or src/MAKE/MINE directory, which is appropriate
+for your system (see below).  It can list various options for
+customizing your LAMMPS build with a number of global compilation
+options and features.  To include LAMMPS packages (i.e. optional
+commands and styles) you must install them first, as discussed on
+the "Build package"_Build_package.html doc page.  If the packages
+use provided or external libraries, you must build those libraries
+before building LAMMPS.  Building "LAMMPS with CMake"_Build_cmake.html
+can automate all of this for many types of machines, especially
+workstations, desktops and laptops, so we suggest you try it first.
 
 These commands perform a default LAMMPS build, producing the LAMMPS
 executable lmp_serial or lmp_mpi in lammps/src:
@@ -27,23 +30,31 @@ make serial     # build a serial LAMMPS executable
 make mpi        # build a parallel LAMMPS executable with MPI
 make            # see a variety of make options :pre
 
-If your machine has multiple cores (most do), using a command like
-"make -j mpi" will be much faster.
+This initial compilation can take a long time, since LAMMPS is a large
+project with many features. If your machine has multiple CPU cores (most
+do these days), using a command like "make -jN mpi" (with N being to the
+number of available local CPU cores) can be much faster. If you plan to
+do development on LAMMPS or may need to recompile LAMMPS repeatedly, the
+installation of the ccache (= Compiler Cache) software may speed up
+compilation even more.
 
-After the initial build, if you edit LAMMPS source files, or add new
-files to the source directory, you can re-type make and it will only
-re-compile the files that have changed.
+After the initial build, whenever you edit LAMMPS source files, or 
+add or remove new files to the source directory (e.g. by installing or
+uninstalling packages), you must recompile and relink the LAMMPS executable
+with the same command line, but the makefiles will make certain, that
+only files that need to be recompiled will be compiled (because they
+were changed or depend on files, that were changed). 
 
 :line
 
-The lammps/src/MAKE directory contains all the Makefile.machine files
+The lammps/src/MAKE tree contains all the Makefile.machine files
 included in the LAMMPS distribution.  Typing "make machine" uses
 Makefile.machine.  Thus the "make serial" or "make mpi" lines above
 use Makefile.serial and Makefile.mpi.  Others are in these dirs:
 
 OPTIONS      # Makefiles which enable specific options
 MACHINES     # Makefiles for specific machines
-MINE         # customized Makefiles you create :pre
+MINE         # customized Makefiles you create (you may need to create this folder) :pre
 
 Typing "make" lists all the available Makefile.machine files.  A file
 with the same name can appear in multiple dirs (not a good idea).  The
@@ -53,7 +64,10 @@ customized file you put in src/MAKE/MINE.
 
 Makefiles you may wish to try include these (some require a package
 first be installed).  Many of these include specific compiler flags
-for optimized performance:
+for optimized performance.  Please note, however, that most of these
+customized machine Makefile are contributed and since both, compilers
+and also OS configs, as well as LAMMPS itself keep changing all the
+time, some of these settings and recommendations may be outdated:
 
 make mac             # build serial LAMMPS on a Mac
 make mac_mpi         # build parallel LAMMPS on a Mac
diff --git a/doc/src/Run_basics.txt b/doc/src/Run_basics.txt
index 1d4b570f21..c83d17d6a9 100644
--- a/doc/src/Run_basics.txt
+++ b/doc/src/Run_basics.txt
@@ -9,23 +9,25 @@ Documentation"_ld - "LAMMPS Commands"_lc :c
 
 Basics of running LAMMPS :h3
 
-LAMMPS is run from the command line, reading commands from standard
-input, which are typically listed in an input script:
+LAMMPS is run from the command line, reading commands from a
+file via the -in command line flag, or from standard input.
+Using the "-in in.file" variant is recommended:
 
 lmp_serial < in.file
 lmp_serial -in in.file
-~/lammps/src/lmp_serial < in.file
+/path/to/lammps/src/lmp_serial < in.file
 mpirun -np 4 lmp_mpi -in in.file
-mpirun -np 8 ~/lammps/src/lmp_mpi -in in.file
-mpirun -np 6 /usr/local/bin/lmp_mpi -in in.file :pre
+mpirun -np 8 /path/to//lammps/src/lmp_mpi -in in.file
+mpirun -np 6 /usr/local/bin/lmp -in in.file :pre
 
-You normally run from the directory your input script is in.  That is
-also where output files are produced, unless you specify otherwise in
-your input script.  As in some of the examples above, the LAMMPS
-executable can be elsewhere.
+You normally run the LAMMPS command in the directory where your
+input script is located.  That is also where output files are
+produced by default, unless you provide specific other paths in
+your input script or on the command line.  As in some of the
+examples above, the LAMMPS executable itself can be placed elsewhere.
 
-NOTE: The redirection operator "<" can often be used with mpirun, but
-some systems require the -in form.
+NOTE: The redirection operator "<" will not always work when running
+in parallel with mpirun; for those systems the -in form is required.
 
 As LAMMPS runs it prints info to the screen and a logfile named
 log.lammps.  More info about output is given on the "Run