tx258/lammps-gran-kokkos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

improve LAMMPS GUI docs, add info about using the Linux-2-Windows cross-compiler

Browse Source
This commit is contained in:
Axel Kohlmeyer
2023-08-04 16:38:51 -04:00
parent b6f7a27b09
commit 9b0fe3eeda
1 changed files with 66 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
doc/src/Tools.rst
View File

@ -752,63 +752,66 @@ Prerequisites and portability
LAMMPS GUI is programmed in C++ based on the C++11 standard and using
the `Qt GUI framework <https://www.qt.io/product/framework>`_.
Currently, Qt version 5.12 or later is required; Qt 5.15LTS is
recommended Qt 6.x not (yet) supported. Furthermore, CMake version 3.16
is required and LAMMPS must be configured with ``-D
LAMMPS_EXCETIONS=on`` and ``-D BUILD_MPI=off``. It has been successfully
recommended; Qt 6.x not (yet) supported. Furthermore, CMake version 3.16
is required and LAMMPS must be configured with ``-D BUILD_MPI=off`` and
``-D BUILD_LAMMPS_GUI=on``. The LAMMPS GUI has been successfully
compiled and tested on:
- Ubuntu Linux 20.04LTS x86_64 using GCC 9, Qt version 5.12
- Fedora Linux 38 x86\_64 using GCC 13 and Clang 16, Qt version 5.15LTS
- Apple macOS 12 (Monterey) and macOS 13 (Ventura) with Xcode on arm64 and x86\_64, Qt version 5.15LTS
- Windows 10 and 11 x86_64 with Visual Studio 2022 and Visual C++ 14.36, Qt version 5.15LTS
- Windows 10 and 11 x86_64 with MinGW / GCC 10.0 cross-compiler on Fedora 37, Qt version 5.15LTS
Pre-compiled executables
^^^^^^^^^^^^^^^^^^^^^^^^
Pre-compiled LAMMPS executables including the GUI are currently
available from https://download.lammps.org/static. You can unpack the
archive (or mount the macOS disk image) and run the GUI directly in
place. The folder may also be moved around and added to the ``PATH``
environment variable so the executables will be found automatically. The
LAMMPS GUI executable is called ``lammps-gui`` and takes no arguments or
will interpret the first argument as filename to load.
available from https://download.lammps.org/static or
https://github.com/lammps/lammps/releases. You can unpack the archive
(or mount the macOS disk image) and run the GUI directly in place. The
folder may also be moved around and added to the ``PATH`` environment
variable so the executables will be found automatically. The LAMMPS GUI
executable is called ``lammps-gui`` and either takes no arguments or
attempts to load the first argument as LAMMPS input file.
Compilation
^^^^^^^^^^^
The source for the LAMMPS GUI is included with the LAMMPS source code
distribution in the folder `tools/lammps-gui` and thus it can be can be
built as part of a regular LAMMPS compilation.
:doc:`Using CMake <Howto_cmake>` is required.
To enable its compilation the CMake variable ``-D BUILD_LAMMPS_GUI=on``
must be set when creating the CMake configuration. All other settings
(compiler, flags, compile type) for LAMMPS GUI are then inherited from
the regular LAMMPS build. If the Qt library is packaged for Linux
distributions, then its location is typically auto-detected since the
required CMake configuration files are stored in a location where CMake
can find them without additional help. Otherwise, the location of the
Qt library installation must be indicated by setting
``-D Qt5_DIR=/path/to/qt5/lib/cmake/Qt5``, which is a path to a folder inside
distribution in the folder ``tools/lammps-gui`` and thus it can be can
be built as part of a regular LAMMPS compilation. :doc:`Using CMake
<Howto_cmake>` is required. To enable its compilation use the CMake
variables ``-D BUILD_LAMMPS_GUI=on`` ``-D BUILD_MPI=off`` must be set
when creating the CMake configuration. All other settings (compiler,
flags, compile type) for LAMMPS GUI are then inherited from the regular
LAMMPS build. If the Qt library is packaged for Linux distributions,
then its location is typically auto-detected since the required CMake
configuration files are stored in a location where CMake can find them
without additional help. Otherwise, the location of the Qt library
installation must be indicated by setting ``-D
Qt5_DIR=/path/to/qt5/lib/cmake/Qt5``, which is a path to a folder inside
the Qt installation that contains the file ``Qt5Config.cmake``.
It is also possible to build the LAMMPS GUI as a standalone executable
It is possible to build the LAMMPS GUI as a standalone compilation
(e.g. when LAMMPS has been compiled with traditional make), then the
CMake configuration needs to be told where to find the LAMMPS headers
and the LAMMPS library, via `-D LAMMPS_SOURCE_DIR=/path/to/lammps/src`.
and the LAMMPS library, via ``-D LAMMPS_SOURCE_DIR=/path/to/lammps/src``.
CMake will try to guess a build folder with the LAMMPS library from that
path, but it can also be set with `-D LAMMPS_LIB_DIR=/path/to/lammps/lib`.
path, but it can also be set with ``-D LAMMPS_LIB_DIR=/path/to/lammps/lib``.
Rather than linking to the LAMMPS library during compilation, it is also
possible to compile the GUI with a plugin loader library that will load
the LAMMPS library dynamically at runtime during the start of the GUI
from a shared library; e.g. `liblammps.so` or `liblammps.dylib` or
`liblammps.dll` (depending on the operating system). This has the
from a shared library; e.g. ``liblammps.so`` or ``liblammps.dylib`` or
``liblammps.dll`` (depending on the operating system). This has the
advantage that the LAMMPS library can be updated LAMMPS without having
to recompile the GUI. The ABI of the LAMMPS C-library interface is very
stable and generally backward compatible. This feature is enabled by
setting ``-D LAMMPS_GUI_USE_PLUGIN=on`` and then
``-D LAMMPS_PLUGINLIB_DIR=/path/to/lammps/plugin/loader``. Typically, this
would be the ``examples/COUPLE/plugin`` folder of the LAMMPS distribution.
setting ``-D LAMMPS_GUI_USE_PLUGIN=on`` and then ``-D
LAMMPS_PLUGINLIB_DIR=/path/to/lammps/plugin/loader``. Typically, this
would be the ``examples/COUPLE/plugin`` folder of the LAMMPS
distribution.
Platform notes
^^^^^^^^^^^^^^
@ -818,7 +821,7 @@ macOS
When building on macOS, the build procedure will try to manufacture a
drag-n-drop installer, LAMMPS-macOS-multiarch.dmg, when using the 'dmg'
target (i.e. `cmake --build <build dir> --target dmg` or `make dmg`.
target (i.e. ``cmake --build <build dir> --target dmg`` or ``make dmg``.
To build multi-arch executables that will run on both, arm64 and x86_64
architectures natively, it is necessary to set the CMake variable ``-D
@ -831,18 +834,39 @@ version.
Windows
"""""""
On Windows currently only compilation from within Visual Studio 2022 is
supported and tested. Using CMake and Ninja as build system is
required. Qt needs to be installed, tested was a package downloaded from
https://www.qt.io, into the ``C:\\Qt`` folder. There is a custom
`x64-GUI-MSVC` build configuration provided that will activate building
the `lammps-gui.exe` executable in addition to LAMMPS. When requesting
an installation from the `Build` menu, it will create a compressed zip
file with the executables and required dependent .dll files. This zip
file can be uncompressed and ``lammps-gui.exe`` run directly from there.
The uncompressed folder can be added to the ``PATH`` environment and
LAMMPS and LAMMPS GUI can be launched from anywhere from the command
line.
On Windows either native compilation from within Visual Studio 2022 with
Visual C++ is supported and tested, or compilation with the MinGW / GCC
cross-compiler environment on Fedora Linux.
**Visual Studio**
Using CMake and Ninja as build system are required. Qt needs to be
installed, tested was a binary package downloaded from
https://www.qt.io, which installs into the ``C:\\Qt`` folder by default.
There is a custom `x64-GUI-MSVC` build configuration provided in the
``CMakeSettings.json`` file that Visual Studio uses to store different
compilation settings for project. Choosing this configuration will
activate building the `lammps-gui.exe` executable in addition to LAMMPS
through importing package selection from the ``windows.cmake`` preset
file and enabling building the LAMMPS GUI and disable building with MPI.
When requesting an installation from the `Build` menu in Visual Studio,
it will create a compressed ``LAMMPS-Win10-amd64.zip`` zip file with the
executables and required dependent .dll files. This zip file can be
uncompressed and ``lammps-gui.exe`` run directly from there. The
uncompressed folder can be added to the ``PATH`` environment and LAMMPS
and LAMMPS GUI can be launched from anywhere from the command line.
**MinGW64 Cross-compiler**
The standard CMake build procedure can be applied and the
``mingw-cross.cmake`` preset used. By using ``mingw64-cmake`` the CMake
command will automatically include a suitable CMake toolset file (the
regular cmake command can be used after that). After building the
libraries and executables, you can build the target 'zip'
(i.e. ``cmake --build <build dir> --target zip`` or ``make zip``
to stage all installable files into a LAMMPS_GUI folder and then
run a script to copy all required dependencies, some other files,
and create a zip file from it.
Linux
"""""