ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

rework documentation section on compiling on windows

Browse Source
This commit is contained in:
Axel Kohlmeyer
2022-02-21 17:04:31 -05:00
parent 78775a82f4
commit 0d68aa0c46
1 changed files with 58 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
doc/src/Build_windows.rst
View File

@ -16,48 +16,52 @@ General remarks
LAMMPS is developed and tested primarily on Linux machines. The vast
majority of HPC clusters and supercomputers today run on Linux as well.
While portability to other platforms is desired, it is not always achieved.
The LAMMPS developers are dependent on LAMMPS users giving feedback and
providing assistance in resolving portability issues. This is particularly
true for compiling LAMMPS on Windows, since this platform has significant
While portability to other platforms is desired, it is not always
achieved. That is sometimes due to non-portable code in LAMMPS itself,
but more often due to portability limitations of external libraries and
tools required to build a specific feature or package. The LAMMPS
developers are dependent on LAMMPS users giving feedback and providing
assistance in resolving portability issues. This is particularly true
for compiling LAMMPS on Windows, since this platform has significant
differences in some low-level functionality. As of LAMMPS version 14
December 2021, large parts of LAMMPS can be compiled natively with the
Microsoft Visual C++ Compilers. This is largely facilitated by using the
:doc:`Developer_platform` in the ``platform`` namespace.
Microsoft Visual C++ Compilers. This is largely facilitated by using
the :doc:`Developer_platform` in the ``platform`` namespace.
Before trying to build LAMMPS on Windows yourself, please consider the
`pre-compiled Windows installer packages <https://packages.lammps.org/windows.html>`_
and see if they are sufficient for your needs.
.. _linux:
Running Linux on Windows
^^^^^^^^^^^^^^^^^^^^^^^^
Before trying to build LAMMPS on Windows yourself, please consider if the
`pre-compiled Windows installer packages <https://packages.lammps.org/windows.html>`_
are sufficient for your needs. If it is necessary for you to compile
LAMMPS on a Windows machine (e.g. because it is your main desktop),
please also consider using a virtual machine software and compile and
run LAMMPS in a Linux virtual machine, or - if you have a sufficiently
up-to-date Windows 10 or Windows 11 installation - consider using the
Windows subsystem for Linux. This optional Windows feature allows you
to run the bash shell of a Linux system (Ubuntu by default) from within
Windows and from there on, you can pretty much use that shell like you
are running on a regular Ubuntu Linux machine (e.g. installing software
via apt-get and more). For more details on that, please see :doc:`this
tutorial <Howto_wsl>`.
If it is necessary for you to compile LAMMPS on a Windows machine
(e.g. because it is your main desktop), please also consider using a
virtual machine software and compile and run LAMMPS in a Linux virtual
machine, or - if you have a sufficiently up-to-date Windows 10 or
Windows 11 installation - consider using the Windows subsystem for
Linux. This optional Windows feature allows you to run the bash shell
of a Linux system (Ubuntu by default) from within Windows and from there
on, you can pretty much use that shell like you are running on a regular
Ubuntu Linux machine (e.g. installing software via apt-get and more).
For more details on that, please see :doc:`this tutorial <Howto_wsl>`.
.. _gnu:
Using a GNU GCC ported to Windows
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
One option for compiling LAMMPS on Windows natively, that has been known
to work in the past, is to install a bash shell, unix shell utilities,
perl, GNU make, and a GNU compiler ported to Windows. The Cygwin
package provides a unix/linux interface to low-level Windows functions,
so LAMMPS can be compiled on Windows. The necessary (minor)
modifications to LAMMPS are included, but may not always up-to-date for
recently added functionality and the corresponding new code. A machine
makefile for using cygwin for the old build system is provided. Using
CMake for this mode of compilation is untested and not likely to work.
One option for compiling LAMMPS on Windows natively is to install a Bash
shell, Unix shell utilities, Perl, Python, GNU make, and a GNU compiler
ported to Windows. The Cygwin package provides a unix/linux interface
to low-level Windows functions, so LAMMPS can be compiled on Windows.
The necessary (minor) modifications to LAMMPS are included, but may not
always up-to-date for recently added functionality and the corresponding
new code. A machine makefile for using cygwin for the old build system
is provided. Using CMake for this mode of compilation is untested and
not likely to work.
When compiling for Windows do **not** set the ``-DLAMMPS_MEMALIGN``
define in the LMP_INC makefile variable and add ``-lwsock32 -lpsapi`` to
@ -79,20 +83,27 @@ Using Microsoft Visual Studio
Following the integration of the :doc:`platform namespace
<Developer_platform>` into the LAMMPS code base, portability of LAMMPS
to be compiled on Windows using Visual Studio has been significantly
improved. This has been tested with Visual Studio 2019 (aka version
16) and Visual Studio 2022 (aka version 17). Not all features and
packages in LAMMPS are currently supported out of the box, but a preset
``cmake/presets/windows.cmake`` is provided that contains the packages
that have been compiled successfully. You **must** use the CMake based
build procedure, and either use the integrated CMake support of the
Visual Studio IDE or use an external CMake installation to create build
files for the Visual Studio build system. Please note that
on launching Visual Studio it will scan the directory tree and likely
miss the correct master ``CMakeLists.txt``. Try to open the
``cmake/CMakeSettings.json`` and use those CMake configurations as a
starting point. It is also possible to configure and compile LAMMPS
from the command line with a CMake binary from `cmake.org <https://cmake.org>`_.
for native compilation on Windows using Visual Studio has been
significantly improved. This has been tested with Visual Studio 2019
(aka version 16) and Visual Studio 2022 (aka version 17). We strongly
recommend using Visual Studio 2022 version 17.1 or later. Not all
features and packages in LAMMPS are currently supported out of the box,
but a preset ``cmake/presets/windows.cmake`` is provided that contains
the packages that have been compiled successfully so far. You **must**
use the CMake based build procedure, since there is no support for GNU
make or the Unix shell utilities required for the GNU make build
procedure.
It is possible to use both the integrated CMake support of the Visual
Studio IDE or use an external CMake installation (e.g. downloaded from
cmake.org) to create build files and compile LAMMPS from the command line.
.. note::
Versions of Visual Studio before version 17.1 may scan the entire
LAMMPS source tree and likely miss the correct master
``CMakeLists.txt`` and get confused since there are multiple files
of that name in different folders but none in top level folder.
Please note, that for either approach CMake will create a so-called
:ref:`"multi-configuration" build environment <cmake_multiconfig>`, and
@ -103,9 +114,11 @@ To support running in parallel you can compile with OpenMP enabled using
the OPENMP package or install Microsoft MPI (including the SDK) and compile
LAMMPS with MPI enabled.
This is work in progress and you should contact the LAMMPS developers
via GitHub, the forum, or the mailing list, if you have questions or
LAMMPS specific problems.
.. note::
This is work in progress and you should contact the LAMMPS developers
via GitHub, the forum, or the mailing list, if you have questions or
LAMMPS specific problems.
.. _cross: