From 8c5ac3d49c04e3a316b4d73fea9d9a50cec0ffb5 Mon Sep 17 00:00:00 2001
From: Axel Kohlmeyer <akohlmey@gmail.com>
Date: Mon, 19 Oct 2020 01:01:06 -0400
Subject: [PATCH] add README file to SWIG tool

---
 tools/swig/README | 50 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 tools/swig/README

diff --git a/tools/swig/README b/tools/swig/README
new file mode 100644
index 0000000000..1f30ecdc7e
--- /dev/null
+++ b/tools/swig/README
@@ -0,0 +1,50 @@
+SWIG generated script library wrappers
+
+The "swig" tool and library ( http://swig.org )
+offers an automated way to incorporate compiled code
+modules into scripting languages.  It processes the
+function prototypes in C and generates wrappers for
+a variety of scripting languages from it.
+
+We provide here an "interface file", "lammps.i" file
+that has the content of the "library.h" adapted so SWIG
+can process it.  Please note that not all kinds of C
+interfaces can be automatically translated, so you
+would have to add custom functions.  In the case of
+python, a ctypes based lammps module already exists,
+that is object oriented while SWIG will generate a 1:1
+translation of the functions in the interface file.
+
+When using CMake, the build steps for building a wrapper
+module are integrated for the languages: java, lua,
+perl5, python, ruby, and tcl.  These require that the
+LAMMPS library is build as a shared library and all
+necessary development headers and libraries are present.
+
+Manual building allows a little more flexibility. E.g.
+with Tcl one can build and use a dynamically loaded object with:
+
+$ swig -tcl -module tcllammps lammps.i
+$ gcc -fPIC -shared $(pkgconfig --cflags tcl) -o tcllammps.so lammps_wrap.c -L ../src/ -llammps
+$ tclsh
+% load ./tcllammps.so
+% set lmp [lammps_open_no_mpi 0 NULL NULL]
+% puts "LAMMPS version: [lammps_version $lmp]
+% lammps_close $lmp
+
+Equivalently with Python the manual steps are:
+
+$ swig -python -module pylammps lammps.i
+$ gcc -fPIC -shared $(pkgconfig --cflags python) -o _pylammps.so lammps_wrap.c -L ../src/ -llammps
+$ python
+% from pylammps import *
+
+
+
+You may need to set or extend the LD_LIBRARY_PATH environment
+variable to include the folder where the LAMMPS shared library
+file is located, if it is not found automatically.
+
+
+For details on how to build the wrappers for other
+individual http://swig.org/doc.html