Updated notes about compiling with visual studio

README.md

@@ -21,6 +21,11 @@ mkdir build; cd build; cmake .. -DUSE_AVX_INSTRUCTIONS=1; cmake --build .
 
 Doing so will make some things run faster.
 
+Finally, Visual Studio users should usually do everything in 64bit mode.  By default Visual Studio is 32bit, both in its outputs and its own execution, so you have to explicitly tell it to use 64bits.  Since it's not the 1990s anymore you probably want to use 64bits.  Do that with a cmake invocation like this:
+```bash
+cmake .. -G "Visual Studio 14 2015 Win64" -T host=x64 
+```
+
 ## Compiling your own C++ programs that use dlib
 
 The examples folder has a [CMake tutorial](https://github.com/davisking/dlib/blob/master/examples/CMakeLists.txt) that tells you what to do.  There are also additional instructions on the [dlib web site](http://dlib.net/compile.html).

docs/docs/compile.xml

@@ -38,8 +38,10 @@ tell CMake which one you want it to use via the -G option.
    Finally, note that when using Visual Studio, CMake will by default generate a 32bit executable.  
    This means the programs you compile will only be able to use 2GB of RAM.  To avoid this, you need
    to tell CMake to generate a 64bit executable.  You do this by using a command like 
-   <code_box>cmake -G "Visual Studio 14 2015 Win64" ..</code_box> instead of <code_box>cmake ..</code_box>  
+   <code_box>cmake -G "Visual Studio 14 2015 Win64" -T host=x64 ..</code_box> instead of <code_box>cmake ..</code_box>  
-   You can see the list of valid arguments to <tt>-G</tt> by running <tt>cmake</tt> with no options. 
+   You can see the list of valid arguments to <tt>-G</tt> by running <tt>cmake</tt> with no options.   Note also the <tt>-T host=x64</tt>
+   option, which tells Visual Studio to let the compiler use more than 2GB of RAM.  That is important if you don't want the compiler to
+   crash from running out of RAM in some situations.
 </p>
             
 

docs/docs/faq.xml

@@ -460,13 +460,24 @@ cross_validate_trainer_threaded(trainer,
          tools in dlib.  So make sure you have a version no older than October
          2016.
          <p>
-            However, as of this writing, the newest version of Visual Studio is Visual Studio 2017, which 
+            To make this even more complicated, Visual Studio 2017 had
-            has WORSE C++11 support that Visual Studio 2015.  In particular, if you try to use
+            regressions in its C++11 support.  So all versions of Visual Studio
-            the DNN tooling in Visual Studio 2017 the compiler will just hang.  So use Visual Studio 2015.
+            2017 prior to December 2017 would just hang if you tried to compile
+            the DNN examples.  Happily, the newest versions of Visual Studio
+            2017 appear to have good C++11 support and will compile the DNN
+            codes without any issue.  So make sure your Visual Studio is
+            fully updated.
          </p>
          <p>
-            It should also be noted that not even Visual Studio 2015 has perfect C++11 support.  Specifically, the 
+            Finally, it should be noted that you should give the <tt>-T host=x64</tt>
-            larger and more complex imagenet and metric learning training examples don't compile in Visual Studio 2015.
+            cmake option when generating a Visual Studio project.  If you don't
+            do this then you will get the default Visual Studio toolchain,
+            <b>which runs the compiler in 32bit mode, restricting it to 2GB of
+            RAM, leading to compiler crashes due to it running out of RAM in some
+            cases</b>.  This isn't the 1990s anymore, so you should probably
+            run your compiler in 64bit mode so it can use your computer's RAM.
+            Giving <tt>-T host=x64</tt> will let Visual Studio use as much RAM
+            as it needs.
          </p>
       </question>