diff --git a/doc/src/Build_cmake.rst b/doc/src/Build_cmake.rst index 70a9767f23..82ba093220 100644 --- a/doc/src/Build_cmake.rst +++ b/doc/src/Build_cmake.rst @@ -86,12 +86,20 @@ options and settings will be printed at the end. The ``cmake --build ultimately produce a library ``liblammps.a`` and the LAMMPS executable ``lmp`` inside the ``build`` folder. -If your machine has multiple CPU cores (most do these days), you can -speed this up by compiling sources in parallel with ``make -j N`` (with -N being the maximum number of concurrently executed tasks). Also -installation of the `ccache `_ (= Compiler Cache) -software may speed up repeated compilation significantly, e.g. during code -development. +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), you can speed this up by compiling sources in parallel with +``make -j N`` (with N being the maximum number of concurrently executed +tasks). Also installation of the `ccache `_ (= +Compiler Cache) software may speed up repeated compilation even more, +e.g. during code development. + +After the initial build, whenever you edit LAMMPS source files, add +or remove packages, change compiler flags or build options, +you must re-compile and relink the LAMMPS executable with ``cmake --build .``. +If the compilation fails for some reason, try running ``cmake .`` and +then compile again. The included dependency tracking of should insure +that only the necessary subset of files are re-compiled. After compilation, you may optionally install the LAMMPS executable into your system with: diff --git a/doc/src/Build_make.rst b/doc/src/Build_make.rst index 0379a8379a..bc294175e0 100644 --- a/doc/src/Build_make.rst +++ b/doc/src/Build_make.rst @@ -2,10 +2,14 @@ Build LAMMPS with make ====================== Building LAMMPS with traditional makefiles requires that you have a -Makefile."machine" file appropriate for your system in the src/MAKE, -src/MAKE/MACHINES, src/MAKE/OPTIONS, or src/MAKE/MINE directory (see -below). It can include various options for customizing your LAMMPS -build with a number of global compilation options and features. +``Makefile.`` file appropriate for your system in either the +``src/MAKE``, ``src/MAKE/MACHINES``, ``src/MAKE/OPTIONS``, or +``src/MAKE/MINE`` directory (see below). It can include various options +for customizing your LAMMPS build with a number of global compilation +options and features. + +Requirements +^^^^^^^^^^^^ Those makefiles are written for and tested with GNU make and may not be compatible with other make programs. In most cases, if the "make" @@ -16,44 +20,52 @@ with :doc:`CMake `. The makefiles of the traditional make based build process and the scripts they are calling expect a few additional tools to be available and functioning. - * a Bourne shell compatible "Unix" shell program (often this is bash) - * a few shell utilities: ls, mv, ln, rm, grep, sed, tr, cat, touch, diff, dirname - * python (optional, required for "make lib-XXX" in the src folder) + * a working C/C++ compiler toolchain; on Linux these are often the GNU compilers + * a Bourne shell compatible "Unix" shell program (often this is ``bash``) + * a few shell utilities: ``ls``, ``mv``, ``ln``, ``rm``, ``grep``, ``sed``, ``tr``, ``cat``, ``touch``, ``diff``, ``dirname`` + * python (optional, required for ``make lib-`` in the src folder). + python scripts are currently tested with python 2.7 and 3.6. The procedure + for :doc:`building the documentation ` requires python 3. -To include LAMMPS packages (i.e. optional commands and styles) you -must enable them first, as discussed on the :doc:`Build package -` doc page. If a packages requires (provided or +Getting started +^^^^^^^^^^^^^^^ + +To include LAMMPS packages (i.e. optional commands and styles) you must +enable (or "install") them first, as discussed on the :doc:`Build +package ` doc page. If a packages requires (provided or external) libraries, you must configure and build those libraries **before** building LAMMPS itself and especially **before** enabling -such a package with "make yes-". Building :doc:`LAMMPS -with CMake ` can automate much of this for many types of +such a package with ``make yes-``. Building :doc:`LAMMPS with +CMake ` can automate much of this for many types of machines, especially workstations, desktops, and laptops, so we suggest you try it first when building LAMMPS in those cases. The commands below perform a default LAMMPS build, producing the LAMMPS -executable lmp_serial and lmp_mpi in lammps/src: +executable ``lmp_serial`` and ``lmp_mpi`` in ``lammps/src``: .. code-block:: bash - cd lammps/src - make serial # build a serial LAMMPS executable + cd lammps/src # change to main LAMMPS source folder + make serial # build a serial LAMMPS executable using GNU g++ make mpi # build a parallel LAMMPS executable with MPI make # see a variety of make options -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 = -the number of available CPU cores) can be much faster. If you plan to -do development on LAMMPS or need to re-compile LAMMPS repeatedly, the -installation of the ccache (= Compiler Cache) software may speed up -compilation even more. +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), you can speed this up by compiling sources in parallel with +``make -j N`` (with N being the maximum number of concurrently executed +tasks). Also installation of the `ccache `_ (= +Compiler Cache) software may speed up repeated compilation even more, +e.g. during code development. 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 re-compile and relink the LAMMPS -executable with the same "make" command. This makefiles dependencies -should insure that only the subset of files that need to be are -re-compiled. +executable with the same ``make `` command. The makefile's +dependency tracking should insure that only the necessary subset of +files are re-compiled. If you change settings in the makefile, you have +to recompile *everything*. To delete all objects you can use ``make +clean-``. .. note:: @@ -65,13 +77,15 @@ re-compiled. correctly detect which parts need to be recompiled after changes were made to the sources. ----------- +Customized builds and alternate makefiles +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The lammps/src/MAKE tree contains 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, respectively. Other makefiles -are in these directories: +The ``src/MAKE`` directory tree contains the ``Makefile.`` +files included in the LAMMPS distribution. Typing ``make example`` uses +``Makefile.example`` from one of those folders, if available. Thus the +``make serial`` and ``make mpi`` lines above use +``src/MAKE/Makefile.serial`` and ``src/MAKE/Makefile.mpi``, +respectively. Other makefiles are in these directories: .. code-block:: bash @@ -79,11 +93,16 @@ are in these directories: MACHINES # Makefiles for specific machines MINE # customized Makefiles you create (you may need to create this folder) -Typing "make" lists all the available Makefile.machine files. A file -with the same name can appear in multiple folders (not a good idea). -The order the directories are searched is as follows: src/MAKE/MINE, -src/MAKE, src/MAKE/OPTIONS, src/MAKE/MACHINES. This gives preference -to a customized file you put in src/MAKE/MINE. +Simply typing ``make`` lists all the available ``Makefile.`` +files with a single line description toward the end of the output. A +file with the same name can appear in multiple folders (not a good +idea). The order the directories are searched is as follows: +``src/MAKE/MINE``, ``src/MAKE``, ``src/MAKE/OPTIONS``, +``src/MAKE/MACHINES``. This gives preference to a customized file you +put in ``src/MAKE/MINE``. If you create your own custom makefile under +a new name, please edit the first line with the description and machine +name, so you will not confuse yourself, when looking at the machine +summary. Makefiles you may wish to try include these (some require a package first be installed). Many of these include specific compiler flags