This is not a bug per se, though perhaps documentation rewrite might be appropriate.

I've been building python for windows for several years now. I have found that it is unnecessarily problematic. Perhaps my expectations are too high. When I started building python, I expected to build a whole stable version of python thing without error. In my experience, 
it is not true that one can build python on windows by simply loading the .sln file into Visual studio, selecting Debug or Release, and then clicking build.

Over time I have worked out steps that allow me to build all bits of python and minimize the aggravation and failures. These steps follow. Hopefully they will help folks to avoid some of the problems I encountered. Perhaps this will attract commentary that will document the way things actually should be done. I would be happy to stand corrected and know that there is a simple single point and click or single line command that would build python on windows.

Regardless, here you go. 

The online directions for downloading the development version source are fine and can be found at http://docs.python.org/devguide/. Mercurial must be installed on your machine. Stable released version source is available on the download page. 

Python building/rebuilding assumes the existence of subversion, perl, and a version of Visual Studio on your system. If you have all three, skip to step three. Otherwise download and install any of those
that are missing. If it is  necessary to have on hand multiple versions of python built from scratch, you should isolate them from each other by putting them in a container directory perhaps of the same name.

e.g. I use a style like python331/python331, python32/python32

where the subdirectory is the source root directory. I use the upper directory to isolate the external subprojects created by the buildbots described later. If you don't do this, the buildbots of one version can wipe out required subprojects of another version of python. I can assure you this will cause you a lot of confusion until you realize the source of the problem.

0. Download and install at least a subversion client and add the executable to your path.
   I got mine from Collabnet and here is how it appears in my path
   "C:\Program Files\CollabNet\Subversion Client"

1. Download and install  perl and add the executable to your path  
   I vaguely recall I downloaded ActivePerl
   Your Perl path will look something like this.
       C:\Perl\site\bin;C:\Perl\bin

2. Download and install VC++ express and add the bin area to your path
   Your VC++ bin path will look something like this:
   C:\Program Files\Microsoft Visual Studio 10.0\VC\bin

   I use the free version of VC++, which may be the source of all my 
   python build issues.
   When I load the solution file which you will see later, VC++    
   complains that the version
   I have doesn't support various features. It is free though and I am 
   able to work with it. 

2  Download and install nasm:
   There are several downloading sites. This seems to be the latest and    
   greatest. 
   http://www.windows7download.com/win7-nasm/ldyuniel.html

4. Download and build the external subprojects with the buildbots using 
   either: 
    Tools\buildbot\external.bat         # for 32 bit processors
    Tools\buildbot\external-amd64.bat   # for 64 bit processors
    from the root directory or your python distribution.
    This step will download the correct versions of the external 
    projects for this version of python. There are several projects

4. openssl is used for python on windows
   ssl rarely succeeds if you proceed to build using "pcbuild.sln: 

   The following steps will resolve many problems if you executing them 
   before building with the .sln file

   cd into the openssl directory created by the buildbots
     perl util\mkdef.pl crypto ssl update
     perl Configure VC-WIN32 --prefix=C:\opt\openssl-1.0.1d
     ms\do_nasm  

   You may get compilation errors anyway when you attempt to build the 
   .sln file with Visual Studio. The errors I have seen have always been 
   the same type, namely a forced error contained within a block of   
   conditional code. In all cases so far I have been able to comment out 
   the forced error. Most recently I had to comment out code blocks in 
   mdc2.h and idea.h.
   
   Historically, the openssl build has not had a "clean" function. This 
   used to cause me a lot of problems if rebuilding was required for  
   whatever reason. I cleaned the project by deleting and letting the 
   buildbot download again what was required. 

5. Finally Build python and its internal subprojects  
     open the solution "pcbuild.sln" in Visual Studio (VC++ in my case)
       - If you have an express version, then ignore the warning 
     select the  configuration  Release or Debug
        "Release" builds python.exe
        "Debug" builds python_d.exe 
     select the platform   Win32 or x64
     build the solution.   
       Right click "Solution 'pccuild'"  and select
         build - for fresh build
         clean - to delete all files created for build , i.e. objects, 
                 libraries, executable, etc.
         rebuild - clean and build everything
     Note that you can clean and build individual subprojects by just 
     right clicking on the subproject and selecting build, clean, or 
     rebuild for that project

I have also had problems, and I think the devguide needs a chapter on the subject. I have additional info from Steve Dower of MS to add. There are also proposed rewrites of the .bat files to be factored it to any doc. Thank you for your writeup.

Michael, you may be interested in a configure.bat/make.bat system which I have proposed in issue16895.  I would certainly be interested in your review of it, as it seems that core developers who have the ability, inclination, and (probably most importantly) time to review such a patch are few and far between :).

In the meantime, I agree that the documentation for building on Windows is a bit lacking.  If you would like to make a patch to the devguide, I'd be happy to review it.

Thanks for the pointer to your work and discussion in issue16895. I was
contemplating something along those lines. I had not started down that path
first because I've only relatively recently thrashed the problem enough to
understand the issues, and second because I wasn't thrilled with the
prospect of implementing anything in microsoft's shell scripting language
(called PowerShell now yes?), which being proprietary and primitive would
discourage I would think the python community from even considering looking
at the code when the inevitable bugs appear. I was intrigued to read in the
recent replies to issue
16895 about the suggestion to bootstrap. There is a lot of history to the
merits of that approach in other languages. It is surprising to me that the
approach isn't used in python. Well I guess, given that python is C under
the skin and configure/make is well established unix idiom

My progress on this topic has been in fits and starts. It's about what I can
tolerate. The state of OpenSLL all by itself is pretty bizarre. Regardless,
I believe another fit is in my near future.  Judging by the response to your
issue there is interest and hope in getting this corner of python under
control.
I will review your configure/make solution, with luck a patch to the
devguide can be just a massive simplification. On the other hand, the
discussion of what is going on in automating the process would be useful.
The existing docs did help me decode what was going on envetually.

-m

Since I am new to Python, I'll take a look at the documentation and see if I can help.

I've gone through and followed the online directions.  They do allow the person following the directions to "build Python".  

My question:  I assume that isn't sufficient to really build a patch.

The readme has directions that includes the information that is below.  I haven't gone through those directions yet.

My question: Do we want those directions both places?  I personally think they should be online, and have the readme refer to the online directions, but what is the thought of the community?  I think it is redundant to do it in both places.

Why are you suggesting the use of Subversion?  Why not stick with Mercurial?

Because some of the third party components for the windows built are still in a subversion repository.

I think I have everything now.

Hmmm, it looks like your patch is missing a file.  You may need to run "hg add", then create your patch again.

After hg add

Whoops, that patch contains way more than you wanted :).  I should have suggested "hg add *.rst".  Attaching what should be the right patch, review to come.

Review of kw-issue17846.diff:

setup.rst
- hunks 1 & 2 (@@ -49,9 and @@ -216,7):
  Both changes should be reverted.  The change from 3.4 -> 3.3 reverts a very
  recent change made due to 3.4 becoming the newest maintenance branch.  If
  I'm not mistaken, the blank line after the Windows heading is important.

- hunk 3 (@@ -240,11)
  I think the added sentence here would be better tacked onto the end of the
  previous paragraph:
  "[limitations are] here (2010).  Not listed on those pages, Visual C++ Express
  does not support Solution Folders.  Because the Python solution file uses
  Solution Folders, VS Express will warn you about that fact every time you
  open the ``pcbuild.sln`` file.  You can safely dismiss the warning with no
  impact on your ability to build Python."

  If you can improve on my English or brevity there, please do :)

  Also, there's a lot of trailing whitespace in that paragraph.  I'd suggest
  using an editor that can strip trailing spaces for you (I like Notepad++).

setupwindows.rst
- throughout
  Lots of trailing whitespace.

- line 7
  Seems a bit pointless to point back and forth between the two sections.  I'm
  open to suggestions on how best to avoid that.

- line 11
  A suggestion of TortoiseHg and a link thereto wouldn't be amiss.

- line 12
  Source for what?  What download page?

- line 13-14
  Doesn't fit here in the narrative flow.  This should be in the section about
  Subversion.

- line 17-19
  Subversion and Perl should be capitalized.  Also, this isn't true:  svn is
  necessary to pull the external library sources from svn.python.org, but you
  can actually download your sources directly from their respective vendors,
  provided you put them where the VS project files expect them to be.  Perl is
  not necessary at all if you pulled your OpenSSL sources from svn.python.org,
  it is only required if you're using sources you got straight from the
  OpenSSL folks.

- line 21-30
  This should be rewritten to explain the problem, then suggest a solution.
  Something like:

  """
  The VS project files expect external libraries that they need to be in
  folders on the same level as the cpython source checkout, for example, at
  ``PCbuild\..\..\openssl-1.0.1e``.  Since different versions of Python use
  different versions (or different builds) of the various external libraries,
  it is recommended to build different Python versions in isolated folders.
  For example: 

     C:\
      |_ Source
            |_ python3.4
            |      |_ cpython
            |      |_ tcl-8.6.1.0
            |      |_ tk-8.6.1.0
            |      |_ tcltk
            |      |_ ...
            |
            |_ python3.3
                   |_ cpython
                   |_ tcl-8.5.11.0
                   |_ tk-8.5.11.0
                   |_ tcltk
                   |_ ...
  """

  Either way, the term "buildbots" is used incorrectly here, referring to the
  scripts in the Tools/buildbot directory, which our CI system ("the
  buildbots", see buildbot.python.org) use to build and test Python.

- line 36
  Subversion should be capitalized.  This would also be the place to explain
  why svn is needed, and also to link to a place to get it.  TortoiseSVN is
  probably a good choice to link to, and mention its installer option to add
  svn to PATH.

- line 42
  Perl should be capitalized.  It should be explained that Perl is not
  absolutely necessary (and the cases in which it is).  It would also be good
  to link to ActivePerl, which is what the build_ssl.py script actually looks
  for.

- line 48-50
  Grammar issues.  Also, this is covered in the _windows-compiling section.

- line 52
  This is not true.

- line 58
  There should be an explanation of why.

- line 64
  Incorrect use of the term "buildbots".

- line 70
  Those scripts download the sources for every external project, but only
  build Tcl and Tk.

- line 71
  Sentence fragment.  Unfinished thought?

- line 78-93
  Poor grammar.  Also, none of this is true: I have never had any problems
  letting the solution build OpenSSL.  There is no need to jump through those
  hoops.  If building with pcbuild.sln doesn't work correctly, it's a bug that
  should be fixed, not documented as being broken.

- line 96
  Incorrect use of the term "buildbot".

- line 125-126
  I would rephrase this as "`Python Tools for Visual Studio <...>`_ is an
  add-on published by Microsoft for editing Python in Visual Studio.  It is
  not usable with Express editions."


Frankly, I don't see much added benefit from the new file.  It's mostly
duplication of PCbuild/readme.txt, and what little isn't already there should
be.  I would much rather see a patch making sure PCbuild/readme.txt is up to
date, and a link to http://hg.python.org/cpython/file/default/PCbuild/readme.txt
added to the devguide's existing compilation on Windows section.

I agree -- so should that be a separate patch since it's in cpython, not devguide?

Quoting:

Frankly, I don't see much added benefit from the new file.  It's mostly
duplication of PCbuild/readme.txt, and what little isn't already there should
be.  I would much rather see a patch making sure PCbuild/readme.txt is up to
date, and a link to http://hg.python.org/cpython/file/default/PCbuild/readme.txt
added to the devguide's existing compilation on Windows section.

It will have to be a separate patch, but can be done in this issue.

Does this mean that Python 3.4 doesn't use VS 2010?


hunks 1 & 2 (@@ -49,9 and @@ -216,7):
  Both changes should be reverted.  The change from 3.4 -> 3.3 reverts a very
  recent change made due to 3.4 becoming the newest maintenance branch.  If
  I'm not mistaken, the blank line after the Windows heading is important.

No, 3.4 uses VS 2010.  Your patch changes the line from "hg update 3.4" to "hg update 3.3", which is not a legitimate change, in fact it undoes a change that Éric Araujo just made.  With the release of 3.4.0, 3.4 became the current maintenance branch and 3.3 moved into security fix only mode, so we want the devguide discussion of maintenance branches to deal with 3.4.

Please get perl out of this discussion. A perl installation shouldn't be necessary to compile Python. (IOW, -1 on any patch that recommends that Perl should be installed to build Python)

I simply do not understand the last comment, Perl has always been part of the build process on Windows.  Are you saying that the build process has to change?

No, Perl has not been mandatory for the build process, at least not for the last decade or so. It may occasionally happen that it is mandatory to build OpenSSL, but that would be a bug in our copy of OpenSSL.

I've got a patch for the readme from cpyton and for the setup from devguide

I have had trouble reading the comments.

Devguide patch review, review comment lines start with # (in column 1)

diff -r e665cddd6cde setup.rst
--- a/setup.rst	Sun Mar 23 19:31:22 2014 -0400
+++ b/setup.rst	Tue Mar 25 07:47:54 2014 -0500
@@ -217,8 +217,9 @@
 Windows
 '''''''
 
-The readme included in the solution has more details, especially on the 
-software needed to resolve the below mentioned build errors.
+The readme http://hg.python.org/cpython/file/default/PCbuild/readme.txt
# This should be a link, not just a URL thrown inline.  'readme' can be
# the linked word.
+included in the solution has more details, especially on the software
+needed to resolve the below mentioned build errors.
 
 **Python 3.3** and later use Microsoft Visual Studio 2010.  You can
 download Microsoft Visual C++ 2010 Express `from Microsoft's site
@@ -238,6 +239,9 @@
 <http://msdn.microsoft.com/en-us/library/hs24szh9%28v=VS.90%29.aspx>`_
 and `here (2010)
 <http://msdn.microsoft.com/en-us/library/hs24szh9%28v=vs.100%29.aspx>`_.
+Because the Python solution file uses Solution Folders, VS Express will warn
+you about that fact every time you open the ``pcbuild.sln`` file.  You can
+safely dismiss the warning with no impact on your ability to build Python."
# What fact?  If you're going to copy my words verbatim, copy all of them.
# Otherwise, rewrite them so it makes sense.
 
 To build from the Visual Studio GUI, open the ``pcbuild.sln`` solution file
 with Visual Studio.  Choose the :menuselection:`Build Solution` option
@@ -267,6 +271,7 @@
 ``PCBuild\amd64\python_d.exe``.  If you are compiling in release mode (which
 you shouldn't, in general), replace ``python_d.exe`` with ``python.exe``.
 
+
# No need to add a blank line here.
 .. _build_troubleshooting:
 
 Troubleshooting the build

Patch from comments on March 29

New readme.txt patch

Observation:
    Tools\buildbot\build.bat solves all the problems I was having.

That is to say, a single command exists to build python on 
windows w/o problems. It has worked since at least since python 3.3.1, which I think preceded my original submission. 

So this has existed all this time, but has not been suggested 
as the solution it seems to be. What's wrong with it? Is it 
about to be deprecated perhaps? The DevGuide recommends external.bat
in the same directory. build.bat calls external.bat and does more. 


Detail:
 If I
     1. place the unzipped downloaded file folder isolated within another folder so that external projects can be built adjacent to python.
     2. make certain that svn,nasm,VC++, are in my path. 
     3. cd to the python root
     4. execute the command : Tools\buildbot\build.bat
Then
     python_d.exe is created in the PCbuild folder.

This is true for python 3.3.1, 3.3.2, 3.3.4, 3.4.0, and the current development version. I have built all since yesterday. I skipped 3.3.3 only because I didn't have the source downloaded 

OK, I lied a little.
     1. The 3.3.1 release python.org areas had a corrupt openSSL rev d, I think. I modified my local external.bat to get a later version to solve that problem.
     2. Other releases build debug tcltk release libs when debug libs are needed, and vice versa. I made copies of whatever existed and renamed the copy to whatever was required.
     
But this is nothing compared what I was going through before.       

I personally like to have python.exe around also. To create python.exe, I only now open pcbuild.sln to start VC++,  chose the release configuration, and hit F7. I have learned that it is best to run build.bat first before using pcbuild.sln with the VC++ IDE to build anything.

It currently does not work for AMD64 but I maguessing that ti would be a good model to follow.

The limitation of build.bat (as you also reported) is that it builds a debug build.

Since a debug build (F7 in VS) is the only thing I have ever built, or that a developer like me needs to build, that is not a limitation.

New changeset bb3f1afcd082 by Zachary Ware in branch '3.4':
Issue #17846: Clarify note about Solution Folders.
http://hg.python.org/cpython/rev/bb3f1afcd082

New changeset 39f9cd7ad19a by Zachary Ware in branch 'default':
Issue #17846: Merge with 3.4
http://hg.python.org/cpython/rev/39f9cd7ad19a

New changeset 369891476cf8 by Zachary Ware in branch 'default':
Issue #17846: Add a note about solution folders with VS Express.
http://hg.python.org/devguide/rev/369891476cf8

Issue #21907 changed how things are done somewhat, and has made PCbuild/build.bat the new obvious place to go for building Python from the command line; the devguide has been updated to reflect that (although I may have missed a place to update).  What else still needs to be done here in light of those changes?

Because the name 'tcltk' is unversioned and contents rebuilt for each compile, isolated build directories of the sort diagrammed in msg214138 are required if one want to build and run both 2.7, which requires tcl8.5, and 3.4+, which require tcl8.6.  Since other dependency subdir names include the version, multiple versions can live in the same dir.

Thank you kathweaver and others who worked on this issue. After reviewing the long history of this issue and the changes made to the Windows sections of the devguide, I am closing this issue. 

I recognize that Terry Reedy's final comment about isolated build directories may need additional documentation. My recommendation would be to file a new issue if more documentation is needed on isolated build directories for Windows and tcl.

My comment was addressed by other patches (by Zach, I believe).  There now is an external directory for each version, within each pythonxy repository.  I agree with closing this.  Any documentation issues with the current build process should be a new issue.