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