add notes on compiling LAMMPS for windows

doc/src/Build.txt

@@ -28,6 +28,7 @@ as described on the "Install"_Install.html doc page.
    Build_settings
    Build_package
    Build_extras
+   Build_windows
 
 END_RST -->
 
@@ -39,7 +40,8 @@ END_RST -->
 "Basic build options"_Build_basics.html
 "Optional build settings"_Build_settings.html
 "Include packages in build"_Build_package.html
-"Packages with extra build options"_Build_extras.html :all(b)
+"Packages with extra build options"_Build_extras.html
+"Notes for building LAMMPS on Windows"_Build_windows.html  :all(b)
 
 If you have problems building LAMMPS, it is often due to software
 issues on your local machine.  If you can, find a local expert to

doc/src/Build_windows.txt

@@ -0,0 +1,83 @@
+"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS
+Documentation"_ld - "LAMMPS Commands"_lc :c
+
+:link(lws,http://lammps.sandia.gov)
+:link(ld,Manual.html)
+:link(lc,Commands_all.html)
+
+:line
+
+Notes for building LAMMPS on Windows :h3
+
+"General remarks"_#general
+"Running Linux on Windows"_#linux
+"Using GNU GCC ported to Windows"_#gnu
+"Using a cross-compiler"_#cross
+
+:line
+
+General remarks :h4,link(general)
+
+LAMMPS is developed and tested primarily on Linux machines.  The vast
+majority of HPC clusters and supercomputers today runs on Linux as well.
+Thus portability to other platforms is desired, but not always achieved.
+The LAMMPS developers strongly rely on LAMMPS users giving feedback and
+providing assistance in resolving portability issues. This particularly
+true for compiling LAMMPS on Windows, since this platform has significant
+differences with some low-level functionality.
+
+
+Running Linux on Windows :h4,link(linux)
+
+So before trying to build LAMMPS on Windows, please consider if using
+the pre-compiled Windows binary packages are sufficient for your needs
+(as an aside, those packages themselves are build on a Linux machine
+using cross-compilers).  If it is necessary for your to compile LAMMPS
+on a Windows machine (e.g. because it is your main desktop), please also
+consider using a virtual machine software and run a Linux virtual machine,
+or - if have a recently updated Windows 10 installation - consider using
+the Windows subsystem for Linux, which allows to run a bash shell from
+Ubuntu and from there on, you can pretty much use that shell like you
+are running on an Ubuntu Linux machine (e.g. installing software via
+apt-get). For more details on that, please see "this tutorial"_Howto_bash.html
+
+
+Using GNU GCC ported to Windows :h4,link(gnu)
+
+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. The CMake build system is untested
+for this; you will have to request that makefiles are generated and
+manually set the compiler.  In case of problems, you are recommended to
+contact somebody with experience in using cygwin.  If you come across
+portability problems requiring changes to the LAMMPS source code, or
+figure out corrections yourself, please report them on the lammps-users
+mailing list, or file them as an issue or pull request on the LAMMPS
+github project.
+
+
+Using a cross-compiler :h4,link(cross)
+
+If you need to provide custom LAMMPS binaries for Windows, but do not
+need to do the compilation on Windows, please consider using a Linux
+to Windows cross-compiler. This is how currently the Windows binary
+packages are created by the LAMMPS developers. Because of that, this is
+probably the currently best tested and supported way to build LAMMPS
+executables for Windows. Please keep in mind, though, that this only
+applies to compiling. Whether the resulting binaries do work correctly
+is no tested. The LAMMPS developers rely on the feedback of the users
+of the precompiled LAMMPS packages for Windows to become aware of
+issues and then try to apply corrections, if possible.
+
+
+Native Visual C++ support :h4,link(native)
+
+Support for the Visual C++ compilers is currently not available. The
+CMake build system is capable of creating suitable a Visual Studio
+style build environment, but the LAMMPS code itself is not fully ported
+to support Visual C++. Volunteers to take on this task are welcome.

doc/src/lammps.book

@@ -25,6 +25,7 @@ Build_basics.html
 Build_settings.html
 Build_package.html
 Build_extras.html
+Build_windows.html
 Run_head.html
 Run_basics.html
 Run_options.html