Expanded information about building on MacOS and Windows.

Author: James Barbetti

.vscode/launch.json

@@ -16,7 +16,7 @@
             "cwd": "${workspaceRoot}/build",
             "externalConsole": false,
 
-            //Windows and GNU
+            //Windows and gcc
             //"MIMode": "gdb",
             //"miDebuggerPath": "C:\\msys64\\mingw64\\bin\\gdb.exe"
 
@@ -38,6 +38,8 @@
                       "-no-banner", "-no-out", "-t", "NONE"],
             "cwd": "${workspaceRoot}/build",
             "externalConsole": false,
+
+            //Windows and gcc
             //"MIMode": "gdb",
             //"miDebuggerPath": "C:\\msys64\\mingw64\\bin\\gdb.exe"
 

doco/Algorithms.md

@@ -1,13 +1,12 @@
 <h1>decenttree Algorithm Implementation Details</h1>
 All neighbour-joining algorithms rely on matrices of distances between clusters (of one taxon or multiple taxa). Most calculate adjusted distances, taking into account how far individual clusters are, on average, from other clusters, and some use auxiliary matrices (such as the estimated variance matrix of BIONJ), but all use matrices of distances.<p>
 
-The decenttree algorithms (except for the ONJ algorithms, which use triangular matrices), make use of square matrices (using triangular matrices would reduce memory consumption by a factor of 2, but would considerably increase the cost of accessing entries in the matrix, and matrix access would also be much harder to vectorize efficiently).
+The decenttree algorithms (except for the ONJ algorithms, which use triangular matrices), make use of square matrices (using triangular matrices would reduce memory consumption by a factor of 2, but would considerably increase the cost of accessing entries in the matrix, and matrix access would also have been much more difficult to vectorize efficiently).
 
-The vast bulk of the memory required by the decenttree distance matrix tree inference algorithms, is that used to track the ( n * n entry) distance matrices themselves.  There are also some vectors, the track clusters to be considered, or the structure of the subtrees for the clsuters yet to be joined, but these are much smaller (of size proportional to n, rather than n * n).
+The bulk of the memory required by the decenttree distance matrix tree inference algorithms, is that used to track the ( n * n entry) distance matrices themselves.  There are also some vectors, the track clusters to be considered, or the structure of the subtrees for the clsuters yet to be joined, but these are much smaller (of size proportional to n, rather than n * n).
 
 <h2>Memory Requirements</h2>
 
-
 Each of the working matrices require the same amount of memory (approximately 4 * n * n bytes,
 where n is the number of taxa), except for the double precision versions (where the D, V, and S
 matrices are twice as large).  The D matrix tracks distances between taxa (or clusters). The V 
@@ -36,3 +35,4 @@ appear to be slightly slower) than the NJ-R and NJ-R-V implementations.
 | BIONJ-V  | D, V        | Vectorized version of BIONJ              | |
 | BIONJ-R  | D, V, S, I  | BIONJ with branch-and-bound optimization | Recommended. But slower than NJ-R |
 | AUCTION  | D, S, I     | Reverse auction cluster joining          | Experimental. Not recommended |
+

doco/Compilation.md

@@ -8,8 +8,8 @@ on Macintosh, or on Linux (using GCC).  It hasn't been tested with other compile
 | Macintosh        | 64-bit   | Parallelization | Link with libmac/libomp.a |
 | Unix/Linux       | 64-bit   | Parallelization | Link with lib/libomp.a or lib/libomp.a |
 | Unix/Linux.      | 32-bit   | Parallelization | Link with lib32/libomp.a |
-| Windows          | 64-bit   | Parallelization | Ensure that lib/libiomp5md.dll is in a folder in the PATH |
-| Windows          | 32-bit   | Parallelization | Ensure that lib32/libiomp5md.dll and lib32/libiomp5md.lib.dll are in the PATH |
+| Windows          | 64-bit   | Parallelization | Ensure that lib/libiomp5md.dll is in a folder in the PATH <br> (if building with Microsoft Visual Studio)|
+| Windows          | 32-bit   | Parallelization | Ensure that lib32/libiomp5md.dll and lib32/libiomp5md.lib.dll are in the PATH<br>(if building with Microsoft Visual Studio) |
 
 <h2>Compiling on specific operating systems</h2>
 Instructions are (or will shortly be) available for compilying pydecenttree on the following operating systems:

doco/Compilation_on_MacOS_X.md

@@ -1,17 +1,16 @@
 <h1>Compiling decenttree on Mac OS X</h1>
-(Note: These instructions have only been tested with Intel Macintoshes).
+(Note: These instructions have only been tested with Intel Macintoshes; they have not been tested with Apple Silicon).
 
 <h2>Installing compile time dependencies</h2>
-Decenttree's dependencies are the same, regardless of whether you
-intend to build it with XCode, the development environment 
-provided by Apple, or with Visual Code, the development environment
-provided by Macintosh.
+Decenttree's dependencies are the same, regardless of whether you intend to build it with XCode, the development environment 
+provided by Apple, or with Visual Code, the development environment provided by Macintosh.
 
 |Dependency|Comments|
 |----------|--------|
-| clang    | A C++ compiler that decenttree is built with ([pydecenttree](pydecenttree.md) may be built with gcc, another compiler, depending on how python is configured) |
-| cmake    | A system for managing build processes,  independently of your choice of Operating System and compiler. |
-| libomp   | A library for supporting the use of [OpenMP](https://en.wikipedia.org/wiki/OpenMP), which decenttree uses for Operating-System-Independent parallel execution and multithreading  <br> (note: decenttree only makes use of OpenMP 2.0 features)
+| clang    | A C++ compiler that decenttree is built with ([pydecenttree](pydecenttree.md) may be built with gcc, another compiler, depending on how python is configured). Decenttree has been built with version 12 and may build with version 13 (as of yet it compiles, but does not link, with version 15 of the clang compiler). |
+| gcc*     | (Alternative for clang). decenttree can be built with version 12.2 of gcc (and it may be possible to build decenttree with earlier versions, as it builds - even for 32-bit targets - with version 9.2 on Windows). |
+| cmake    | A system for managing build processes,  independently of your choice of Operating System and compiler. decentree will not build with versions earlier than 3.18. On Mac OS, decenttree has most recently been built with version 3.24.2.  |
+| libomp   | A library for supporting the use of [OpenMP](https://en.wikipedia.org/wiki/OpenMP), which decenttree uses for Operating-System-Independent parallel execution and multithreading.  More recent versions of the clang and gcc compilers have their own integrated OMP support. <br> (note: decenttree only makes use of OpenMP 2.0 features).
 | python   | An interpreter for the Python programming language. It is only required if you wish to compile the pydecenttree Python extension module. |
 | numpy    | A package for scientific computing in python.  It is only required if you wish to compile the pydecenttree Python extension module. |
 | zlib | [zlib](https://en.wikipedia.org/wiki/Zlib) provides de-compression and compression, for reading and writing .gzip files.  decenttree includes zlib 1.2.7 (and you may either use the version that comes with decenttree, or the version installed on your operating system). 
@@ -22,16 +21,31 @@ decenttree includes MacOS versions of the zlib and vectorclass libraries.
 The easiest way to install each of the other components is with 
 [homebrew](https://brew.sh). 
 
-
-
 | Installation Command | Comment |
 |----------------------|------------------|
 | brew install cmake   | decenttree compilation has only been tested with cmake 3.20.1 and 3.24.1 |
 | brew install libomp  | parallelization in decenttree has only been tested with libomp 14.0.6 |
 | brew install python  | [pydecenttree](pydecenttree.md) compliation has only been tested with python 3.10 |
 | brew install numpy   | [pydecenttree](pydecenttree.md) compilation has only been tested with numpy 1.23.1.1 |
+| brew install gcc     | compilation has only been tested (on Intel Mac OS) with version 12.2 |
+
+If you install more recent versions of the clang compiler (via homebrew)
+it may be necessary to add compiler definitions to /Users/[me]/.local/share/CMakeTools/cmake-tools-kits.json 
+to ensure that Microsoft Code can find the Clang compiler.
+```
+{ "name": "Clang 15.0.2",
+  "compilers": {
+    "C": "/usr/local/opt/llvm/bin/clang",
+    "CXX": "/usr/local/opt/llvm/bin/clang++"
+  },
+  "keep": true
+},
+```
+
+#                                   ... had to be added to
+#                                   /Users/[me]/.local/share/CMakeTools/cmake-tools-kits.json
+#                                   ... because Microsoft Code wasn't finding the compiler.
 
 <h2>Compiling dcenttree with XCode</h2>
 This section not written yet.
 <h2>Compiling decenttree with Visual Code</h2>
-This section not written yet.

doco/Compilation_on_Windows.md

@@ -1,2 +1,29 @@
 <h1>Compiling decenttree on Windows</h1>
-These instructions have not yet been written.
+The easiest way to build decenttree is with Microsoft Visual Studio 2022 (Community Edition). It should be possible to build 32-bit or 64-bit versions (but 64-bit builds are recommended).
+
+<h2>Compiling using Visual Studio</h2>
+decenttree has been built with Visual Studio 2017, 2019, and 2022. If you have Visual Studio (Community Edition) installed, this is the easiest way to build decenttree on Windows. [todo: explain how - it boils down to "point VS at the github repository and build!" but more detail would be good.]
+<h3>Compiling using Visual Studio and Clang</h3>
+<br>
+
+<h2>Compiling using Microsoft Code</h2>
+
+You may need to download Ninja to get Clang and GCC builds to work, by downloading a recent version from the official Ninja website, and put that somewhere in your path (one of the folders listed by the PATH environment variable).
+
+<h3>Compiling with Microsoft Code and Clang</h3>
+[todo: this bit not written yet.  There are two different ways to do this, one where you build with a version of Clang that mimics the Microsoft C++ Compiler (badly), using the Microsoft include folders, and another where you build with a MingW version of Clang running in a pretend Linux environment, with its own include folders and Open MP libraries.  I can't 
+recommend either option! I had serious problems getting the Open MP libraries to link, and worse problems getting the vectorization to work!]
+<br><br>
+
+<h3>Compiling with Microsoft Code and GCC</h3>
+<h4>Compiling with Microsoft Code and GCC 9.2</h4>
+Building decenttree on Windows with GCC 9.2 is not recommended.
+The compiler may not be installed with the OpenMP libraries that are needed (the problematic files are libgomp.a, libgomp.dll.a, libgomp.spec), which may may linking difficult.
+<br><br>
+<h4>Compiling with Microsoft Code and GCC 12.2</h4>
+At present (October 2022), the version of CMake that MS Code uses (3.23 or 3.24) doesn't automatically recognize the compiler.
+Builds may fail outright (with no error messages), due to missing DLLs (libisl-23.dll, for example) (the version number might vary). If you are installing GCC using MSYS2 and pacman you may find it necessary to copy files from c:\msys64\user\bin (where pacman puts them!) into c:\msys64\mingw64\bin (which is where pacman probably should put them, but might not).
+<br><br>
+<h4>Compiling with Microsoft Code and the Visual Studio Compiler</h4>
+[todo: this bit not written yet]
+