1# Building LAMMPS and its documentation on offline systems 2 3In some situations it might be necessary to build LAMMPS on a system without 4internet. The scripts in this folder allow you to preload external dependencies 5for both the documentation build and for building with CMake. 6 7It does so by 8 91. Downloading necessary pip packages 102. Cloning git repositories 113. Downloading tarballs 12 13As of April 2021, all of these downloads make up around 600MB. By 14default, it will download everything into $HOME/.cache/lammps, but this can be 15changed with the ``LAMMPS_CACHING_DIR`` environment variable. 16 17Once the caches have been initialized, they can be used for building 18LAMMPS documentation or compiling using CMake on an offline system. 19 20The ``use_caches.sh`` must be sourced into the current shell to initialize the 21offline build environment. Note that it must use the same ``LAMMPS_CACHING_DIR``. 22This script does the following: 23 241. Sets up environment variables that modify the behavior of both pip and git 252. Starts a simple local HTTP server to host files for CMake 26 27Afterwards, it will print out instruction on how to modify the CMake command 28line to make sure it uses the local HTTP server. 29 30To undo the environment changes and shutdown the local HTTP server, run the 31``deactivate_caches`` command. 32 33## Examples 34 35For all of the examples below, you first need to create the cache, which requires an internet connection. 36 37```bash 38./tools/offline/init_caches.sh 39``` 40 41Afterwards, you can disconnect or copy the contents of the ``LAMMPS_CACHING_DIR`` folder to an offline system. 42 43### Documentation 44 45The documentation build will create a new virtual environment that typically first installs dependencies from pip. 46With the offline environment loaded, these installations will instead grab the necessary packages from your local cache. 47 48```bash 49# if LAMMPS_CACHING_DIR is different from default, make sure to set it first 50# export LAMMPS_CACHING_DIR=path/to/folder 51source tools/offline/use_caches.sh 52cd doc/ 53make html 54 55deactivate_caches 56``` 57 58### CMake Build 59 60When compiling certain packages with external dependencies, the CMake build system will download some things from the web. 61For more flexibility it allows users to specify the URL of each of these dependencies. What the ``init_caches.sh`` script does is 62create a CMake preset file, which sets the URL for all of the known dependencies and redirects the download to a local cache. 63 64```bash 65# if LAMMPS_CACHING_DIR is different from default, make sure to set it first 66# export LAMMPS_CACHING_DIR=path/to/folder 67source tools/offline/use_caches.sh 68 69mkdir build 70cd build 71cmake -D LAMMPS_DOWNLOADS_URL=${HTTP_CACHE_URL} -C "${LAMMPS_HTTP_CACHE_CONFIG}" -C ../cmake/presets/most.cmake ../cmake 72make -j 8 73 74deactivate_caches 75``` 76