STYLE: adjust wording in compilation notes

doc/cross-compile-mingw.md

@@ -1,6 +1,8 @@
-Notes for cross-compiling with mingw.
+# Notes for cross-compiling with mingw
 
-On openSUSE use the packages:
+## Host setup
+
+On openSUSE use the packages for compilation:
 ```
 mingw64-cross-binutils
 mingw64-cross-cpp
@@ -16,41 +18,32 @@ mingw64-winpthreads-devel
 mingw64-libfftw3
 mingw64-fftw3-devel
 ```
-
-This setup is missing zlib, so download that manually and compile as a
+This setup is missing `zlib`, so download that manually and compile as a
 *static* library.
-
 ```
-CC="$(wmake -show-c) CFLAGS="$(wmake -show-cflags) ./configure --static
+CC="$(wmake -show-c)" CFLAGS="$(wmake -show-cflags)" ./configure --static
+make
 ```
 
 The resulting output files (zconf.h zlib.h) and (libz.a) either need
-to be installed in system locations where OpenFOAM can find it, or if
+to be installed in system locations where OpenFOAM can find them, or if
 they are to be shipped directly with OpenFOAM, they can also be placed
 in the `src/OpenFOAM/include` and `platforms/XXX/lib` paths.
 
-When using the cross-compiled executables and libraries, additional
-runtime libraries are required. On openSUSE these are provided by the
-packages:
-```
-mingw64-libgcc_s_seh1
-mingw64-libstdc++6
-```
+If the header files are only needed during compilation, it can be a
+fairly convenient hack to simply place copies of them in the
+`src/OSspecific/MSwindows` directory.
 
-In a few locations within OpenFOAM, flex is used to generate code. The
-generated C++ code requires the `FlexLexer.h` header file.
-This is normally located under `/usr/include/FlexLexer.h`, which will
-be ignored by the cross-compiler.
+Flex is used in a few locations within OpenFOAM for generating code.
+The generated C++ code requires the `FlexLexer.h` header file, but
+its `/usr/include` location will be ignored by the cross-compiler.
 
-As a fairly ugly hack, a copy of this file can be made in a standard
+As another ugly hack, a copy of this file can be made in a standard
 project include location. For example,
-
 ```
-mkdir src/OpenFOAM/lnInclude
-cp /usr/include/FlexLexer.h src/OpenFOAM/lnInclude
+ln -s /usr/include/FlexLexer.h src/OSspecific/MSwindows
 ```
 
-
 The last point to consider when cross-compiling is the behaviour of
 the OpenFOAM tools used during compilation. These are found under
 `wmake/src`. When these are compiled they will create executables that
@@ -80,30 +73,16 @@ cp wmake/platforms/linux64Gcc/* wmake/platforms/linux64Mingw/
 The `wmake/platforms/linux64Mingw/` directory should now contain
 native and cross-compiled tools:
 ```
-dirToString
-wmkdep
-wmkdepend
-
-dirToString.exe
-wmkdep.exe
-wmkdepend.exe
+dirToString     dirToString.exe
+wmkdep          wmkdep.exe
+wmkdepend       wmkdepend.exe
 ```
 
 The native tools are the one that will (automatically) be used
 throughout the balance of the cross-compilation process.
 
-
-Adjust paths for third-party sources. Eg, in `etc/config.sh/FFTW` you
-may wish to have the following:
-```
-fftw_version=fftw-system
-export FFTW_ARCH_PATH=/usr/x86_64-w64-mingw32/sys-root/mingw
-```
-
-
 The settings for cross-compilation are normally defined in the
 `etc/pref.sh` file with contents like this:
-
 ```
 # For mingw cross-compile
 
@@ -114,7 +93,6 @@ export WM_LABEL_SIZE=32
 # other settings...
 ```
 
-
 Additional adjustments may be required in some other places. For example
 in `etc/config.sh/FFTW`
 ```
@@ -123,9 +101,26 @@ export FFTW_ARCH_PATH=/usr/x86_64-w64-mingw32/sys-root/mingw
 ```
 
 
-Known limitations (2019-05-01)
+## Run-time setup
 
-- No CGAL support (ie, no foamyHexMesh)
-- No ParaView plugin, runTimepostProcessing
+When using the cross-compiled executables and libraries, the
+corresponding runtime libraries will be required.
+These will need to be copied across from the Linux host system to the
+target machine.
+On openSUSE these runtime libraries are provided by the packages:
+```
+mingw64-libgcc_s_seh1
+mingw64-libstdc++6
+```
+
+When running, the `WM_PROJECT_DIR` environment must be set.
+OpenFOAM will otherwise not be able to locate its files.
+
+
+## Known limitations (2019-05-01)
+
+- kahip does not build
+- boost should build ok, but no CGAL support (ie, no foamyHexMesh)
+- no ParaView plugin, runTimePostProcessing
 - reacting EulerFoam solvers have too many interdependencies and do
-  not yet compile.
+  not yet compile cleanly.