Files
lammps/doc/html/Build_cmake.html
2025-01-13 14:55:48 +00:00

353 lines
26 KiB
HTML

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>3.1. Build LAMMPS with CMake &mdash; LAMMPS documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinx-design.min.css" type="text/css" />
<link rel="stylesheet" href="_static/css/lammps.css" type="text/css" />
<link rel="shortcut icon" href="_static/lammps.ico"/>
<link rel="canonical" href="https://docs.lammps.org/Build_cmake.html" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=5929fcd5"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/design-tabs.js?v=f930bc37"></script>
<script async="async" src="_static/mathjax/es5/tex-mml-chtml.js?v=cadf963e"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="3.2. Build LAMMPS with make" href="Build_make.html" />
<link rel="prev" title="3. Build LAMMPS" href="Build.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="Manual.html">
<img src="_static/lammps-logo.png" class="logo" alt="Logo"/>
</a>
<div class="lammps_version">Version: <b>19 Nov 2024</b></div>
<div class="lammps_release">git info: </div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">User Guide</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="Intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Install.html">2. Install LAMMPS</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="Build.html">3. Build LAMMPS</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">3.1. Build LAMMPS with CMake</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#advantages-of-using-cmake">3.1.1. Advantages of using CMake</a></li>
<li class="toctree-l3"><a class="reference internal" href="#getting-started">3.1.2. Getting started</a></li>
<li class="toctree-l3"><a class="reference internal" href="#configuration-and-build-options">3.1.3. Configuration and build options</a></li>
<li class="toctree-l3"><a class="reference internal" href="#multi-configuration-build-systems">3.1.4. Multi-configuration build systems</a></li>
<li class="toctree-l3"><a class="reference internal" href="#installing-cmake">3.1.5. Installing CMake</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="Build_make.html">3.2. Build LAMMPS with make</a></li>
<li class="toctree-l2"><a class="reference internal" href="Build_link.html">3.3. Link LAMMPS as a library to another code</a></li>
<li class="toctree-l2"><a class="reference internal" href="Build_basics.html">3.4. Basic build options</a></li>
<li class="toctree-l2"><a class="reference internal" href="Build_settings.html">3.5. Optional build settings</a></li>
<li class="toctree-l2"><a class="reference internal" href="Build_package.html">3.6. Include packages in build</a></li>
<li class="toctree-l2"><a class="reference internal" href="Build_extras.html">3.7. Packages with extra build options</a></li>
<li class="toctree-l2"><a class="reference internal" href="Build_manual.html">3.8. Build the LAMMPS documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="Build_windows.html">3.9. Notes for building LAMMPS on Windows</a></li>
<li class="toctree-l2"><a class="reference internal" href="Build_diskspace.html">3.10. Notes for saving disk space when building LAMMPS from source</a></li>
<li class="toctree-l2"><a class="reference internal" href="Build_development.html">3.11. Development build options</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Run_head.html">4. Run LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Commands.html">5. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Packages.html">6. Optional packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Speed.html">7. Accelerate performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Howto.html">8. Howto discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Examples.html">9. Example scripts</a></li>
<li class="toctree-l1"><a class="reference internal" href="Tools.html">10. Auxiliary tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Errors.html">11. Errors</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Programmer Guide</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="Library.html">1. LAMMPS Library Interfaces</a></li>
<li class="toctree-l1"><a class="reference internal" href="Python_head.html">2. Use Python with LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Modify.html">3. Modifying &amp; extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Developer.html">4. Information for Developers</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Command Reference</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="commands_list.html">Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="fixes.html">Fix Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="computes.html">Compute Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="pairs.html">Pair Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="bonds.html">Bond Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="angles.html">Angle Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="dihedrals.html">Dihedral Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="impropers.html">Improper Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="dumps.html">Dump Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="fix_modify_atc_commands.html">fix_modify AtC commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Bibliography.html">Bibliography</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="Manual.html">LAMMPS</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content style-external-links">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="Build.html"><span class="section-number">3. </span>Build LAMMPS</a></li>
<li class="breadcrumb-item active"><span class="section-number">3.1. </span>Build LAMMPS with CMake</li>
<li class="wy-breadcrumbs-aside">
<a href="https://www.lammps.org"><img src="_static/lammps-logo.png" width="64" height="16" alt="LAMMPS Homepage"></a> | <a href="Commands_all.html">Commands</a>
</li>
</ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation">
<a href="Build.html" class="btn btn-neutral float-left" title="3. Build LAMMPS" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="Build_make.html" class="btn btn-neutral float-right" title="3.2. Build LAMMPS with make" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<p><span class="math notranslate nohighlight">\(\renewcommand{\AA}{\text{Å}}\)</span></p>
<section id="build-lammps-with-cmake">
<h1><span class="section-number">3.1. </span>Build LAMMPS with CMake<a class="headerlink" href="#build-lammps-with-cmake" title="Link to this heading"></a></h1>
<p>This page describes how to use <a class="reference external" href="https://cmake.org">CMake</a> in general
to build LAMMPS. Details for specific compile time settings and options
to enable and configure add-on packages are discussed with those
packages. Links to those pages on the <a class="reference internal" href="Build.html"><span class="doc">Build overview</span></a>
page.</p>
<p>The following text assumes some familiarity with CMake and focuses on
using the command-line tool <code class="docutils literal notranslate"><span class="pre">cmake</span></code> and what settings are supported
for building LAMMPS. A more detailed tutorial on how to use CMake
itself, the text mode or graphical user interface, to change the
generated output files for different build tools and development
environments is on a <a class="reference internal" href="Howto_cmake.html"><span class="doc">separate page</span></a>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>LAMMPS currently requires that CMake version 3.16 or later is available.</p>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>You must not mix the <a class="reference internal" href="Build_make.html"><span class="doc">traditional make based</span></a>
LAMMPS build procedure with using CMake. No packages may be
installed or a build been previously attempted in the LAMMPS source
directory by using <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">&lt;machine&gt;</span></code>. CMake will detect if this is
the case and generate an error. To remove conflicting files from the
<code class="docutils literal notranslate"><span class="pre">src</span></code> you can use the command <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">no-all</span> <span class="pre">purge</span></code> which will
uninstall all packages and delete all auto-generated files.</p>
</div>
<section id="advantages-of-using-cmake">
<h2><span class="section-number">3.1.1. </span>Advantages of using CMake<a class="headerlink" href="#advantages-of-using-cmake" title="Link to this heading"></a></h2>
<p>CMake is an alternative to compiling LAMMPS in the traditional way
through <a class="reference internal" href="Build_make.html"><span class="doc">(manually customized) makefiles</span></a>. Using
CMake has multiple advantages that are specifically helpful for
people with limited experience in compiling software or for people
that want to modify or extend LAMMPS.</p>
<ul class="simple">
<li><p>CMake can detect available hardware, tools, features, and libraries
and adapt the LAMMPS default build configuration accordingly.</p></li>
<li><p>CMake can generate files for different build tools and integrated
development environments (IDE).</p></li>
<li><p>CMake supports customization of settings with a command-line, text
mode, or graphical user interface. No manual editing of files,
knowledge of file formats or complex command-line syntax is required.</p></li>
<li><p>All enabled components are compiled in a single build operation.</p></li>
<li><p>Automated dependency tracking for all files and configuration options.</p></li>
<li><p>Support for true out-of-source compilation. Multiple configurations
and settings with different choices of LAMMPS packages, settings, or
compilers can be configured and built concurrently from the same
source tree.</p></li>
<li><p>Simplified packaging of LAMMPS for Linux distributions, environment
modules, or automated build tools like <a class="reference external" href="https://brew.sh/">Homebrew</a>.</p></li>
<li><p>Integration of automated unit and regression testing (the LAMMPS side
of this is still under active development).</p></li>
</ul>
</section>
<section id="getting-started">
<span id="cmake-build"></span><h2><span class="section-number">3.1.2. </span>Getting started<a class="headerlink" href="#getting-started" title="Link to this heading"></a></h2>
<p>Building LAMMPS with CMake is a two-step process. In the first step,
you use CMake to generate a build environment in a new directory. For
that purpose you can use either the command-line utility <code class="docutils literal notranslate"><span class="pre">cmake</span></code> (or
<code class="docutils literal notranslate"><span class="pre">cmake3</span></code>), the text-mode UI utility <code class="docutils literal notranslate"><span class="pre">ccmake</span></code> (or <code class="docutils literal notranslate"><span class="pre">ccmake3</span></code>) or the
graphical utility <code class="docutils literal notranslate"><span class="pre">cmake-gui</span></code>, or use them interchangeably. The
second step is then the compilation and linking of all objects,
libraries, and executables using the selected build tool. Here is a
minimal example using the command-line version of CMake to build LAMMPS
with no add-on packages enabled and no customization:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>lammps<span class="w"> </span><span class="c1"># change to the LAMMPS distribution directory</span>
mkdir<span class="w"> </span>build<span class="p">;</span><span class="w"> </span><span class="nb">cd</span><span class="w"> </span>build<span class="w"> </span><span class="c1"># create and use a build directory</span>
cmake<span class="w"> </span>../cmake<span class="w"> </span><span class="c1"># configuration reading CMake scripts from ../cmake</span>
cmake<span class="w"> </span>--build<span class="w"> </span>.<span class="w"> </span><span class="c1"># compilation (or type &quot;make&quot;)</span>
</pre></div>
</div>
<p>This will create and change into a folder called <code class="docutils literal notranslate"><span class="pre">build</span></code>, then run the
configuration step to generate build files for the default build command
and then launch that build command to compile LAMMPS. During the
configuration step CMake will try to detect whether support for MPI,
OpenMP, FFTW, gzip, JPEG, PNG, and ffmpeg are available and enable the
corresponding configuration settings. The progress of this
configuration can be followed on the screen and a summary of selected
options and settings will be printed at the end. The <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--build</span>
<span class="pre">.</span></code> command will launch the compilation, which, if successful, will
ultimately produce a library <code class="docutils literal notranslate"><span class="pre">liblammps.a</span></code> and the LAMMPS executable
<code class="docutils literal notranslate"><span class="pre">lmp</span></code> inside the <code class="docutils literal notranslate"><span class="pre">build</span></code> folder.</p>
<p>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
<code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">-j</span> <span class="pre">N</span></code> (with N being the maximum number of concurrently executed
tasks). Installation of the <a class="reference external" href="https://ccache.dev/">ccache</a> (= Compiler
Cache) software may speed up repeated compilation even more, e.g. during
code development, especially when repeatedly switching between branches.</p>
<p>After the initial build, whenever you edit LAMMPS source files, enable
or disable packages, change compiler flags or build options, you must
re-compile and relink the LAMMPS executable with <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--build</span> <span class="pre">.</span></code> (or
<code class="docutils literal notranslate"><span class="pre">make</span></code>). If the compilation fails for some reason, try running
<code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">.</span></code> and then compile again. The included dependency tracking
should make certain that only the necessary subset of files is
re-compiled. You can also delete compiled objects, libraries, and
executables with <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--build</span> <span class="pre">.</span> <span class="pre">--target</span> <span class="pre">clean</span></code> (or <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">clean</span></code>).</p>
<p>After compilation, you may optionally install the LAMMPS executable into
your system with:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>install<span class="w"> </span><span class="c1"># optional, copy compiled files into installation location</span>
</pre></div>
</div>
<p>This will install the LAMMPS executable and library, some tools (if
configured) and additional files like LAMMPS API headers, manpages,
potential and force field files. The location of the installation tree
defaults to <code class="docutils literal notranslate"><span class="pre">${HOME}/.local</span></code>.</p>
</section>
<section id="configuration-and-build-options">
<span id="cmake-options"></span><h2><span class="section-number">3.1.3. </span>Configuration and build options<a class="headerlink" href="#configuration-and-build-options" title="Link to this heading"></a></h2>
<p>The CMake commands have one mandatory argument: a folder containing a
file called <code class="docutils literal notranslate"><span class="pre">CMakeLists.txt</span></code> (for LAMMPS it is located in the
<code class="docutils literal notranslate"><span class="pre">cmake</span></code> folder) or a build folder containing a file called
<code class="docutils literal notranslate"><span class="pre">CMakeCache.txt</span></code>, which is generated at the end of the CMake
configuration step. The cache file contains all current CMake settings.</p>
<p>To modify settings, enable or disable features, you need to set
<em>variables</em> with either the <code class="docutils literal notranslate"><span class="pre">-D</span></code> command-line flag (<code class="docutils literal notranslate"><span class="pre">-D</span>
<span class="pre">VARIABLE1_NAME=value</span></code>) or change them in the text mode of the graphical
user interface. The <code class="docutils literal notranslate"><span class="pre">-D</span></code> flag can be used several times in one command.</p>
<p>For your convenience, we provide <a class="reference internal" href="Build_package.html#cmake-presets"><span class="std std-ref">CMake presets</span></a>
that combine multiple settings to enable optional LAMMPS packages or use
a different compiler tool chain. Those are loaded with the <code class="docutils literal notranslate"><span class="pre">-C</span></code> flag
(<code class="docutils literal notranslate"><span class="pre">-C</span> <span class="pre">../cmake/presets/basic.cmake</span></code>). This step would only be needed
once, as the settings from the preset files are stored in the
<code class="docutils literal notranslate"><span class="pre">CMakeCache.txt</span></code> file. It is also possible to customize the build
by adding one or more <code class="docutils literal notranslate"><span class="pre">-D</span></code> flags to the CMake command.</p>
<p>Generating files for alternate build tools (e.g. Ninja) and project files
for IDEs like Eclipse, CodeBlocks, or Kate can be selected using the <code class="docutils literal notranslate"><span class="pre">-G</span></code>
command-line flag. A list of available generator settings for your
specific CMake version is given when running <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--help</span></code>.</p>
</section>
<section id="multi-configuration-build-systems">
<span id="cmake-multiconfig"></span><h2><span class="section-number">3.1.4. </span>Multi-configuration build systems<a class="headerlink" href="#multi-configuration-build-systems" title="Link to this heading"></a></h2>
<p>Throughout this manual, it is mostly assumed that LAMMPS is being built
on a Unix-like operating system with “make” as the underlying “builder”,
since this is the most common case. In this case the build
“configuration” is chose using <code class="docutils literal notranslate"><span class="pre">-D</span> <span class="pre">CMAKE_BUILD_TYPE=&lt;configuration&gt;</span></code>
with <code class="docutils literal notranslate"><span class="pre">&lt;configuration&gt;</span></code> being one of “Release”, “Debug”,
“RelWithDebInfo”, or “MinSizeRel”. Some build tools, however, can also
use or even require having a so-called multi-configuration build system
setup. For a multi-configuration build, the built type (or
configuration) is selected at compile time using the same build
files. E.g. with:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>cmake<span class="w"> </span>--build<span class="w"> </span>build-multi<span class="w"> </span>--config<span class="w"> </span>Release
</pre></div>
</div>
<p>In that case the resulting binaries are not in the build folder directly
but in subdirectories corresponding to the build type (i.e. Release in
the example from above). Similarly, for running unit tests the
configuration is selected with the <code class="docutils literal notranslate"><span class="pre">-C</span></code> flag:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>ctest<span class="w"> </span>-C<span class="w"> </span>Debug
</pre></div>
</div>
<p>The CMake scripts in LAMMPS have basic support for being compiled using
a multi-config build system, but not all of it has been ported. This is
in particular applicable to compiling packages that require additional
libraries that would be downloaded and compiled by CMake. The
<code class="docutils literal notranslate"><span class="pre">windows.cmake</span></code> preset file tries to keep track of which packages can
be compiled natively with the MSVC compilers out-of-the box. Not all of
the external libraries are portable to Windows, either.</p>
</section>
<section id="installing-cmake">
<h2><span class="section-number">3.1.5. </span>Installing CMake<a class="headerlink" href="#installing-cmake" title="Link to this heading"></a></h2>
<p>Check if your machine already has CMake installed:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>which<span class="w"> </span>cmake<span class="w"> </span><span class="c1"># do you have it?</span>
which<span class="w"> </span>cmake3<span class="w"> </span><span class="c1"># version 3 may have this name</span>
cmake<span class="w"> </span>--version<span class="w"> </span><span class="c1"># what specific version you have</span>
</pre></div>
</div>
<p>On clusters or supercomputers which use environment modules to manage
software packages, do this:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>module<span class="w"> </span>list<span class="w"> </span><span class="c1"># is a module for cmake already loaded?</span>
module<span class="w"> </span>avail<span class="w"> </span><span class="c1"># is a module for cmake available?</span>
module<span class="w"> </span>load<span class="w"> </span>cmake<span class="w"> </span><span class="c1"># load cmake module with appropriate name</span>
</pre></div>
</div>
<p>Most Linux distributions offer pre-compiled cmake packages through their
package management system. If you do not have CMake or a recent enough
version (Note: for CentOS 7.x you need to enable the EPEL repository),
you can download the latest version from <a class="reference external" href="https://cmake.org/download/">https://cmake.org/download/</a>. Instructions on how to install it on
various platforms can be found <a class="reference external" href="https://cmake.org/install/">on this page</a>.</p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="Build.html" class="btn btn-neutral float-left" title="3. Build LAMMPS" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="Build_make.html" class="btn btn-neutral float-right" title="3.2. Build LAMMPS with make" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2003-2025 Sandia Corporation.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(false);
});
</script>
</body>
</html>