Issue 2599, 2940 - Fix the presence of correct ATL version

README.md

 Adblock Plus for Internet Explorer
 ==================================
 
 This combines a Browser Helper Object with a singleton engine process to block
 ads in Internet Explorer. The engine process embeds libadblockplus.
+
+Requirements to work with the repository and the code
+-----------------------------------------------------
+
+### Python
+You need to have installed python 2.7. It should be the version available by
+default from Visual Studio as well as in your command line environment.
+Simply put, make sure that path to `python.exe` is in your `PATH` environment
+variable.
+
+### Visual C++ toolset
+There should be available v110 and v110_xp toolsets. For instance, they are
+contained in freely available Visual Studio 2012 Express for Windows Desktop
+and in any paid edition of Visual Studio 2012. Take into account that you might
+need to get the recent updates of mentioned editions, more details about
+v110_xp https://msdn.microsoft.com/en-us/library/jj851139.aspx.
+
+### ATL versions
+It works with ATL shipped with any paid edition of Visual Studio 2012 as well
+as with ATL shipped with Visual Studio 2013 Community edition.
+If you use Visual Studio 2013 Community Edition as the source of ATL then set
+`ADBLOCKPLUS_ATL` environment variable to the directory of the corresponding
+ATL (e.g, `C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\atlmfc`)
+Attention:
+- ATL is not shipped with Express edition of any Visual Studio.
+- ATL from Visual Studio 2015 is not supported.
+More information about libraies and headers in Visual Studios:
+2015 - https://msdn.microsoft.com/en-us/library/hs24szh9(v=vs.140).aspx
+2013 - https://msdn.microsoft.com/en-us/library/hs24szh9(v=vs.120).aspx
+2012 - https://msdn.microsoft.com/en-us/library/hs24szh9(v=vs.110).aspx
+
+### Visual Studio as an IDE
+Currently the project configured to work with MS Visual Studio 2012 as an IDE
+because the main development and release builds are in Visual Studio 2012.
+However one can also use any higher version of Visual Studio as and IDE, the
+caveat is to disable "Upgrade C++ Compilers and Libraries".
 
 Getting/updating the dependencies
 ---------------------------------
 
 adblockplusie has dependencies that aren't part of this repository. They are
 retrieved and updated when you're generating the VS solution for the build, but
 you can also manually update them by running the following:
 
     ./ensure_dependencies.py
 
 Building
 --------
 
-You need Microsoft Visual C++ 2012 and Python 2.7. Make sure that `python.exe` 

[Eric, 2015/10/08 14:36:35]

This line of text has become confusing given the facts. First and easiest, split
out the Python requirements into their own paragraph.

Given how much of a mess it is to set up a proper development environment, it
behooves us to explain it in detail and with as little confusion as possible.
This means one paragraph on each of the following topics.
  -- which VC++ toolset we require
  -- which ATL versions will work
  -- which version of Visual Studio as an IDE will work
Please don't quibble about the need to be verbose here. Just because you already
understand it doesn't mean someone coming in cold will. The comment policy in
the code is "someone familiar with the code base". That policy can't work in
this case, because you can't be familiar with the code base before you can get
to compile, and you can't do that before you get a development environment up
and running.

Microsoft does not have a product named "Microsoft Visual C++ 2012". When you
search for that, all you get is the redistributable library packages. It is more
accurate to say that you need the "Visual C++ 2012 toolset". To my knowledge,
the only standard way to get this toolset installed is to install some version
of Visual Studio 2012. We know that any version of VS 2012 satisfies the toolset
requirement.

For ATL, we can list three sources we know work.
  -- (free) VS 2013 Community
  -- (paid) VS 2012 Professional and Ultimate
I presume that the ATL in paid versions of VS 2013 does work, but we shouldn't
list it until after we've tested it. We should also mention here that the ATL in
VS 2015 Community does _not_ work.

For Visual Studio as an IDE, it seems that any version 2012, 2013, 2015 works. I
have tested the following configuration.
  -- toolset from VS 2012 Express
  -- ATL from VS 2013 Community
  -- IDE from VS 2015 Community

-is on your `PATH`. When building with Express edition you also need some
-Visual Studio which comes with ATL. For example, if you use Visual Studio 2013
-Community Edition then set `VCInstallDir_120` environment variable to the
-directory of Visual C++ (for example,
-`C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC`).
-
 Building is tested on the following configurations
 - [free for everybody] "Microsoft Visual Studio Express 2012 for Windows
-Desktop" with "Microsoft Visual Studio Community 2013" as the source of ATL.
-- "Microsoft Visual Studio Express 2012 for Windows Desktop" with "Microsoft
-Visual Studio Professional 2012" as the source of ATL.
+Desktop" as the source of toolset with "Microsoft Visual Studio Community 2013"
+as the source of ATL. Pay attention to the configuring of the environment
+described in "ATL versions" section.
 - "Microsoft Visual Studio Professional 2012"
 - "Microsoft Visual Studio Ultimate 2012"
 
 * Execute `createsolution.bat` to retrieve dependencies and generate project
 files, this will create `build\ia32\adblockplus.sln` (solution for the 32 bit
 build) and `build\x64\adblockplus.sln` (solution for the 64 bit build). 
 Unfortunately, V8 (which is used by libadblockplus) doesn't support creating 
 both from the same project files.

[Eric, 2015/10/08 14:36:35]

I would add a separate paragraph about the environment variable for VS 2013 used
to find ATL here. You don't need the environment variable set when you run
'gyp'. 'gyp' passes through the name of the variable for resolution at build
time. The environment variable needs to be set when you invoke the IDE. Stating
this fact after talking about 'createsolution' makes this point clear.

There's a missing piece in our knowledge about this, I realize. I don't know if
you can leave this environment variable undefined if you're using a paid version
of VS 2012. I can't test that, because I don't have such a paid version. I
presume it gets picked up in the default path. Regardless, this detail is not
mentioned in the current text.

So this paragraph should say the following:
-- either 
    (1a) use VS 2013 Community
    and (1b) set the environment variable
-- or 
    (2) use a paid version of VS 2012

 * Open `build\ia32\adblockplus.sln` or `build\x64\adblockplus.sln` in
 Visual Studio and build the solution there. Alternatively you can use the
 `msbuild` command line tool, e.g. run `msbuild /m build\ia32\adblockplus.sln`
 from the Visual Studio Developer Command Prompt to create a 32 bit debug build.
 
 Running
 -------
 
 In order to test the extension, you need to register the Browser
 Helper Object with IE. You can do this by locating _AdblockPlus.dll_
@@ skipping 14 matching lines @@
 files, this will create a bunch of project files in the _installer\build\ia32_
 and _installer\build\x64_ directories.
 * Open and build `installer\build\ia32\installer.sln` and
 `installer\build\x64\installer.sln` in Visual Studio. Alternatively you can use
 the `msbuild` command line tool, i.e. run
 `msibuild /m installer\build\ia32\adblockplus.sln` and
 `msibuild /m installer\build\x64\adblockplus.sln` from the Visual Studio
 Developer Command Prompt.
 * Either open and compile `installer\src\innosetup-exe\64BitTwoArch.iss` in
 InnoSetup or run `iscc.exe installer\src\innosetup-exe\64bitTwoArch.iss`.