python: docs update
authorBen McGinnes <ben@adversary.org>
Tue, 4 Dec 2018 21:42:08 +0000 (08:42 +1100)
committerBen McGinnes <ben@adversary.org>
Tue, 4 Dec 2018 21:42:08 +0000 (08:42 +1100)
* Expanded the section on issues with Windows installations, with
  greater detail of which versions of Visual Studio are needed
  depending on which version of CPython is to be used.
* Included a recommendation which is a bit harsh without being totally
  prickish.
* Updated all files to not link to author's key or related data in
  order to make them all consistent with the changes in commit
  649b19688132dd315e361c0f5b63ba6d8f45996d.

Signed-off-by: Ben McGinnes <ben@adversary.org>
15 files changed:
lang/python/doc/rst/gpgme-python-howto.rst
lang/python/doc/rst/maintenance-mode.rst
lang/python/doc/rst/short-history.rst
lang/python/doc/rst/what-is-new.rst
lang/python/doc/rst/what-was-new.rst
lang/python/doc/src/gpgme-python-howto
lang/python/doc/src/maintenance-mode
lang/python/doc/src/short-history
lang/python/doc/src/what-is-new
lang/python/doc/src/what-was-new
lang/python/doc/texinfo/gpgme-python-howto.texi
lang/python/doc/texinfo/maintenance-mode.texi
lang/python/doc/texinfo/short-history.texi
lang/python/doc/texinfo/what-is-new.texi
lang/python/doc/texinfo/what-was-new.texi

index d1cb3fd..7843a65 100644 (file)
@@ -3,27 +3,19 @@
 Introduction
 ============
 
-+-----------------------------------+-----------------------------------+
-| Version:                          | 0.1.4                             |
-+-----------------------------------+-----------------------------------+
-| GPGME Version:                    | 1.12.1                            |
-+-----------------------------------+-----------------------------------+
-| Author:                           | `Ben                              |
-|                                   | McGinnes <https://gnupg.org/peopl |
-|                                   | e/index.html#sec-1-5>`__          |
-|                                   | <ben@gnupg.org>                   |
-+-----------------------------------+-----------------------------------+
-| Author GPG Key:                   | `DB4724E6FA4286C92B4E55C4321E4E23 |
-|                                   | 73590E5D <https://hkps.pool.sks-k |
-|                                   | eyservers.net/pks/lookup?search=0 |
-|                                   | xDB4724E6FA4286C92B4E55C4321E4E23 |
-|                                   | 73590E5D&exact=on&op=get>`__      |
-+-----------------------------------+-----------------------------------+
-| Language:                         | Australian English, British       |
-|                                   | English                           |
-+-----------------------------------+-----------------------------------+
-| Language codes:                   | en-AU, en-GB, en                  |
-+-----------------------------------+-----------------------------------+
++-----------------+------------------------------------------+
+| Version:        | 0.1.4                                    |
++-----------------+------------------------------------------+
+| GPGME Version:  | 1.12.1                                   |
++-----------------+------------------------------------------+
+| Author:         | Ben McGinnes <ben@gnupg.org>             |
++-----------------+------------------------------------------+
+| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
++-----------------+------------------------------------------+
+| Language:       | Australian English, British English      |
++-----------------+------------------------------------------+
+| Language codes: | en-AU, en-GB, en                         |
++-----------------+------------------------------------------+
 
 This document provides basic instruction in how to use the GPGME Python
 bindings to programmatically leverage the GPGME library.
@@ -468,11 +460,12 @@ around far longer than it should have been.
 There are two theoretical solutions to this issue:
 
 #. Compile and install the GnuPG stack, including GPGME and the Python
-   bibdings using the same version of Microsoft Visual Studio used by
+   bindings using the same version of Microsoft Visual Studio used by
    the Python Foundation to compile the version of Python installed.
 
    If there are multiple versions of Python then this will need to be
-   done with each different version of Visual Studio used.
+   done with each different version of Visual Studio used for those
+   versions of Python.
 
 #. Compile and install Python using the same tools used by choice, such
    as MinGW or Msys2.
@@ -488,6 +481,89 @@ Visual Studio to compile and build all of it, no matter what.
 Investigations into the extent or the limitations of this issue are
 ongoing.
 
+The following table lists the version of Microsoft Visual Studio which
+needs to be used when compiling GPGME and the Python bindings with each
+version of the CPython binary released `for
+Windows <https://www.python.org/downloads/windows/>`__:
+
++---------+------------------------+------------------+
+| CPython | Microsoft product name | runtime filename |
++---------+------------------------+------------------+
+| 2.7.6   | Visual Studio 2008     | MSVCR90.DLL      |
++---------+------------------------+------------------+
+| 3.4.0   | Visual Studio 2010     | MSVCR100.DLL     |
++---------+------------------------+------------------+
+| 3.5.0   | Visual Studio 2015     | **see below**    |
++---------+------------------------+------------------+
+| 3.6.0   | Visual Studio 2015     | **see below**    |
++---------+------------------------+------------------+
+| 3.7.0   | Visual Studio 2017\*   | **see below**    |
++---------+------------------------+------------------+
+
+It is important to note that MingW and Msys2 ship with the Visual C
+runtime from Microsoft Visual Studio 2005 and are thus **incompatible**
+with all the versions of CPython which can be used with the GPGME Python
+bindings.
+
+It is also important to note that from CPython 3.5 onwards, the Python
+Foundation has adopted the reworking of the Visual C runtime which was
+performed for Visual Studio 2015 and aimed at resolving many of these
+kinds of issues. Much greater detail on these issues and the correct
+file(s) to link to are available from Matthew Brett\'s invaluable page,
+`Using Microsoft Visual C with
+Python <https://matthew-brett.github.io/pydagogue/python_msvc.html>`__.
+It is also worth reading the Microsoft Developer Network blog post on
+`the universal
+CRT <http://blogs.msdn.com/b/vcblog/archive/2015/03/03/introducing-the-universal-crt.aspx>`__
+and Steve Dower\'s blog posts on Python extensions (`part
+1 <http://stevedower.id.au/blog/building-for-python-3-5>`__ and `part
+2 <http://stevedower.id.au/blog/building-for-python-3-5-part-two>`__).
+
+The second of those two posts by Steve Dower contains the details of
+specific configuration options required for compiling anything to be
+used with official CPython releases. In addition to those configuration
+and compiler settings to use, the versions of Visual Studio prior to
+Visual Studio 2015 did not support 64-bit systems by default. So
+compiling a 64-bit version of these bindings for a 64-bit version of
+CPython 2.7 or 3.4 requires additional work.
+
+In addition to the blog posts, the `Windows
+compilers <https://wiki.python.org/moin/WindowsCompilers>`__ wiki page
+on the CPython wiki is another essential reference on the relevant
+versions of Visual Studio to use and the degree of compatibility with
+CPython releases.
+
+Eventually someone will ask why there isn\'t an installable binary for
+Windows, which the GPGME of the licenses do not preclude as long as the
+source code is available in conjunction with such a release.
+
+The sheer number of versions of Visual Studio in conjunction with
+differing configuration options depending on the target Windows version
+and whether the architecture is 64-bit or 32-bit makes it difficult to
+provide a correct binary installer for Windows users. At the bare
+minimum doing so would require the GnuPG project compile ten different
+versions of the bindings with each release; both 32-bit and 64-bit
+versions for CPython 2.7 and 3.4, with 64-bit versions for both x86-64
+(i.e. Intel and AMD) and ARM architectures for CPython 3.5, 3.6, 3.7 and
+later releases. That\'s the bare **minimum**, it\'d probably be higher.
+
+Considering all of that, what do we recommend?
+
+#. Use a recent version of CPython; at least 3.5, but ideally 3.6 or
+   later.
+
+#. Use Visual Studio 2015 or the standalone build tools for Visual
+   Studio 2017 (or later).
+
+#. Compile both CPython and GPGME with these bindings using the tools
+   selected in step 2.
+
+#. Ignore MingW, Msys2 and the official CPython binary installers.
+
+#. Be thankful the answer to this question wasn\'t simply to say
+   something like, "install Linux" or "install FreeBSD" (or even
+   Apple\'s OS X).
+
 .. _snafu-cffi:
 
 CFFI is the Best™ and GPGME should use it instead of SWIG
index bbd2521..770fbe8 100644 (file)
@@ -3,27 +3,19 @@
 Maintenance Mode from 2019
 ==========================
 
-+-----------------------------------+-----------------------------------+
-| Version:                          | 0.0.1-draft                       |
-+-----------------------------------+-----------------------------------+
-| GPGME Version:                    | 1.13.0                            |
-+-----------------------------------+-----------------------------------+
-| Author:                           | `Ben                              |
-|                                   | McGinnes <https://gnupg.org/peopl |
-|                                   | e/index.html#sec-1-5>`__          |
-|                                   | <ben@gnupg.org>                   |
-+-----------------------------------+-----------------------------------+
-| Author GPG Key:                   | `DB4724E6FA4286C92B4E55C4321E4E23 |
-|                                   | 73590E5D <https://hkps.pool.sks-k |
-|                                   | eyservers.net/pks/lookup?search=0 |
-|                                   | xDB4724E6FA4286C92B4E55C4321E4E23 |
-|                                   | 73590E5D&exact=on&op=get>`__      |
-+-----------------------------------+-----------------------------------+
-| Language:                         | Australian English, British       |
-|                                   | English                           |
-+-----------------------------------+-----------------------------------+
-| xml:lang:                         | en-AU, en-GB, en                  |
-+-----------------------------------+-----------------------------------+
++-----------------+------------------------------------------+
+| Version:        | 0.0.1                                    |
++-----------------+------------------------------------------+
+| GPGME Version:  | 1.13.0                                   |
++-----------------+------------------------------------------+
+| Author:         | Ben McGinnes <ben@gnupg.org>             |
++-----------------+------------------------------------------+
+| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
++-----------------+------------------------------------------+
+| Language:       | Australian English, British English      |
++-----------------+------------------------------------------+
+| xml:lang:       | en-AU, en-GB, en                         |
++-----------------+------------------------------------------+
 
 From the beginning of 2019 the Python bindings to GPGME will enter
 maintenance mode, meaning that new features will not be added and only
index 70f9b25..071ca9e 100644 (file)
@@ -1,27 +1,19 @@
 Overview
 ========
 
-+-----------------------------------+-----------------------------------+
-| Version:                          | 0.0.1-draft                       |
-+-----------------------------------+-----------------------------------+
-| GPGME Version:                    | 1.13.0                            |
-+-----------------------------------+-----------------------------------+
-| Author:                           | `Ben                              |
-|                                   | McGinnes <https://gnupg.org/peopl |
-|                                   | e/index.html#sec-1-5>`__          |
-|                                   | <ben@gnupg.org>                   |
-+-----------------------------------+-----------------------------------+
-| Author GPG Key:                   | `DB4724E6FA4286C92B4E55C4321E4E23 |
-|                                   | 73590E5D <https://hkps.pool.sks-k |
-|                                   | eyservers.net/pks/lookup?search=0 |
-|                                   | xDB4724E6FA4286C92B4E55C4321E4E23 |
-|                                   | 73590E5D&exact=on&op=get>`__      |
-+-----------------------------------+-----------------------------------+
-| Language:                         | Australian English, British       |
-|                                   | English                           |
-+-----------------------------------+-----------------------------------+
-| xml:lang:                         | en-AU, en-GB, en                  |
-+-----------------------------------+-----------------------------------+
++-----------------+------------------------------------------+
+| Version:        | 0.0.1                                    |
++-----------------+------------------------------------------+
+| GPGME Version:  | 1.13.0                                   |
++-----------------+------------------------------------------+
+| Author:         | Ben McGinnes <ben@gnupg.org>             |
++-----------------+------------------------------------------+
+| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
++-----------------+------------------------------------------+
+| Language:       | Australian English, British English      |
++-----------------+------------------------------------------+
+| xml:lang:       | en-AU, en-GB, en                         |
++-----------------+------------------------------------------+
 
 The GPGME Python bindings passed through many hands and numerous phases
 before, after a fifteen year journey, coming full circle to return to
index b3ec06a..123d8d8 100644 (file)
@@ -3,27 +3,19 @@
 What\'s New
 ===========
 
-+-----------------------------------+-----------------------------------+
-| Version:                          | 0.0.1-draft                       |
-+-----------------------------------+-----------------------------------+
-| GPGME Version:                    | 1.13.0                            |
-+-----------------------------------+-----------------------------------+
-| Author:                           | `Ben                              |
-|                                   | McGinnes <https://gnupg.org/peopl |
-|                                   | e/index.html#sec-1-5>`__          |
-|                                   | <ben@gnupg.org>                   |
-+-----------------------------------+-----------------------------------+
-| Author GPG Key:                   | `DB4724E6FA4286C92B4E55C4321E4E23 |
-|                                   | 73590E5D <https://hkps.pool.sks-k |
-|                                   | eyservers.net/pks/lookup?search=0 |
-|                                   | xDB4724E6FA4286C92B4E55C4321E4E23 |
-|                                   | 73590E5D&exact=on&op=get>`__      |
-+-----------------------------------+-----------------------------------+
-| Language:                         | Australian English, British       |
-|                                   | English                           |
-+-----------------------------------+-----------------------------------+
-| xml:lang:                         | en-AU, en-GB, en                  |
-+-----------------------------------+-----------------------------------+
++-----------------+------------------------------------------+
+| Version:        | 0.0.1                                    |
++-----------------+------------------------------------------+
+| GPGME Version:  | 1.13.0                                   |
++-----------------+------------------------------------------+
+| Author:         | Ben McGinnes <ben@gnupg.org>             |
++-----------------+------------------------------------------+
+| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
++-----------------+------------------------------------------+
+| Language:       | Australian English, British English      |
++-----------------+------------------------------------------+
+| xml:lang:       | en-AU, en-GB, en                         |
++-----------------+------------------------------------------+
 
 Last time the most obviously new thing was adding the *What\'s New*
 section to the HOWTO. Now it\'s moving it out of the HOWTO.
@@ -43,5 +35,7 @@ Additions since GPGME 1.12.0 include:
 -  Added ``gpg.version.versionintlist`` to make it easier for Python
    developers to check for a specific version number, even with beta
    versions (it will drop the \"-betaN\" part).
+-  Added expanded detail on issues pertaining to installing for Windows
+   users.
 -  Bindings enter `maintenance mode <maintenance-mode>`__ from January,
    2019.
index cc11bbf..7b18280 100644 (file)
@@ -3,27 +3,19 @@
 What Was New
 ============
 
-+-----------------------------------+-----------------------------------+
-| Version:                          | 0.0.1-draft                       |
-+-----------------------------------+-----------------------------------+
-| GPGME Version:                    | 1.13.0                            |
-+-----------------------------------+-----------------------------------+
-| Author:                           | `Ben                              |
-|                                   | McGinnes <https://gnupg.org/peopl |
-|                                   | e/index.html#sec-1-5>`__          |
-|                                   | <ben@gnupg.org>                   |
-+-----------------------------------+-----------------------------------+
-| Author GPG Key:                   | `DB4724E6FA4286C92B4E55C4321E4E23 |
-|                                   | 73590E5D <https://hkps.pool.sks-k |
-|                                   | eyservers.net/pks/lookup?search=0 |
-|                                   | xDB4724E6FA4286C92B4E55C4321E4E23 |
-|                                   | 73590E5D&exact=on&op=get>`__      |
-+-----------------------------------+-----------------------------------+
-| Language:                         | Australian English, British       |
-|                                   | English                           |
-+-----------------------------------+-----------------------------------+
-| xml:lang:                         | en-AU, en-GB, en                  |
-+-----------------------------------+-----------------------------------+
++-----------------+------------------------------------------+
+| Version:        | 0.0.1                                    |
++-----------------+------------------------------------------+
+| GPGME Version:  | 1.13.0                                   |
++-----------------+------------------------------------------+
+| Author:         | Ben McGinnes <ben@gnupg.org>             |
++-----------------+------------------------------------------+
+| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
++-----------------+------------------------------------------+
+| Language:       | Australian English, British English      |
++-----------------+------------------------------------------+
+| xml:lang:       | en-AU, en-GB, en                         |
++-----------------+------------------------------------------+
 
 The following are all the past *What\'s New* sections for the Python
 Bindings HOWTO and other documentation.
index 43d0c2b..5436bfb 100644 (file)
@@ -17,8 +17,8 @@
 
 | Version:        | 0.1.4                                    |
 | GPGME Version:  | 1.12.1                                   |
-| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]>             |
-| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] |
+| Author:         | Ben McGinnes <ben@gnupg.org>             |
+| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
 | Language:       | Australian English, British English      |
 | Language codes: | en-AU, en-GB, en                         |
 
@@ -493,12 +493,13 @@ been kept around far longer than it should have been.
 There are two theoretical solutions to this issue:
 
  1. Compile and install the GnuPG stack, including GPGME and the
-    Python bibdings using the same version of Microsoft Visual Studio
+    Python bindings using the same version of Microsoft Visual Studio
     used by the Python Foundation to compile the version of Python
     installed.
 
     If there are multiple versions of Python then this will need to be
-    done with each different version of Visual Studio used.
+    done with each different version of Visual Studio used for those
+    versions of Python.
 
  2. Compile and install Python using the same tools used by choice,
     such as MinGW or Msys2.
@@ -515,6 +516,76 @@ what.
 Investigations into the extent or the limitations of this issue are
 ongoing.
 
+The following table lists the version of Microsoft Visual Studio which
+needs to be used when compiling GPGME and the Python bindings with
+each version of the CPython binary released [[https://www.python.org/downloads/windows/][for Windows]]:
+
+| CPython | Microsoft product name | runtime filename |
+|  2.7.6  |   Visual Studio 2008   |   MSVCR90.DLL    |
+|  3.4.0  |   Visual Studio 2010   |   MSVCR100.DLL   |
+|  3.5.0  |   Visual Studio 2015   |   *see below*    |
+|  3.6.0  |   Visual Studio 2015   |   *see below*    |
+|  3.7.0  |   Visual Studio 2017*  |   *see below*    |
+
+It is important to note that MingW and Msys2 ship with the Visual C
+runtime from Microsoft Visual Studio 2005 and are thus *incompatible*
+with all the versions of CPython which can be used with the GPGME
+Python bindings.
+
+It is also important to note that from CPython 3.5 onwards, the Python
+Foundation has adopted the reworking of the Visual C runtime which was
+performed for Visual Studio 2015 and aimed at resolving many of these
+kinds of issues.  Much greater detail on these issues and the correct
+file(s) to link to are available from Matthew Brett's invaluable page,
+[[https://matthew-brett.github.io/pydagogue/python_msvc.html][Using Microsoft Visual C with Python]].  It is also worth reading the
+Microsoft Developer Network blog post on [[http://blogs.msdn.com/b/vcblog/archive/2015/03/03/introducing-the-universal-crt.aspx][the universal CRT]] and Steve
+Dower's blog posts on Python extensions ([[http://stevedower.id.au/blog/building-for-python-3-5][part 1]] and [[http://stevedower.id.au/blog/building-for-python-3-5-part-two][part 2]]).
+
+The second of those two posts by Steve Dower contains the details of
+specific configuration options required for compiling anything to be
+used with official CPython releases.  In addition to those
+configuration and compiler settings to use, the versions of Visual
+Studio prior to Visual Studio 2015 did not support 64-bit systems by
+default.  So compiling a 64-bit version of these bindings for a 64-bit
+version of CPython 2.7 or 3.4 requires additional work.
+
+In addition to the blog posts, the [[https://wiki.python.org/moin/WindowsCompilers][Windows compilers]] wiki page on the
+CPython wiki is another essential reference on the relevant versions
+of Visual Studio to use and the degree of compatibility with CPython
+releases.
+
+Eventually someone will ask why there isn't an installable binary for
+Windows, which the GPGME of the licenses do not preclude as long as
+the source code is available in conjunction with such a release.
+
+The sheer number of versions of Visual Studio in conjunction with
+differing configuration options depending on the target Windows
+version and whether the architecture is 64-bit or 32-bit makes it
+difficult to provide a correct binary installer for Windows users.  At
+the bare minimum doing so would require the GnuPG project compile ten
+different versions of the bindings with each release; both 32-bit and
+64-bit versions for CPython 2.7 and 3.4, with 64-bit versions for both
+x86-64 (i.e. Intel and AMD) and ARM architectures for CPython 3.5,
+3.6, 3.7 and later releases.  That's the bare *minimum*, it'd probably
+be higher.
+
+Considering all of that, what do we recommend?
+
+ 1. Use a recent version of CPython; at least 3.5, but ideally 3.6 or
+    later.
+
+ 2. Use Visual Studio 2015 or the standalone build tools for Visual
+    Studio 2017 (or later).
+
+ 3. Compile both CPython and GPGME with these bindings using the tools
+    selected in step 2.
+
+ 4. Ignore MingW, Msys2 and the official CPython binary installers.
+
+ 5. Be thankful the answer to this question wasn't simply to say
+    something like, “install Linux” or “install FreeBSD” (or even
+    Apple's OS X).
+
 
 *** CFFI is the Best™ and GPGME should use it instead of SWIG
     :PROPERTIES:
index e7a8f28..48c3d40 100644 (file)
   :CUSTOM_ID: maintenance-mode
   :END:
 
-| Version:        | 0.0.1-draft                              |
+| Version:        | 0.0.1                                    |
 | GPGME Version:  | 1.13.0                                   |
-| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]>             |
-| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] |
+| Author:         | Ben McGinnes <ben@gnupg.org>             |
+| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
 | Language:       | Australian English, British English      |
 | xml:lang:       | en-AU, en-GB, en                         |
 
index c91f029..bc874aa 100644 (file)
   :CUSTOM_ID: overview
   :END:
 
-| Version:        | 0.0.1-draft                              |
+| Version:        | 0.0.1                                    |
 | GPGME Version:  | 1.13.0                                   |
-| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]>             |
-| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] |
+| Author:         | Ben McGinnes <ben@gnupg.org>             |
+| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
 | Language:       | Australian English, British English      |
 | xml:lang:       | en-AU, en-GB, en                         |
 
index ab94e3e..c33ab3a 100644 (file)
   :CUSTOM_ID: new-stuff
   :END:
 
-| Version:        | 0.0.1-draft                              |
+| Version:        | 0.0.1                                    |
 | GPGME Version:  | 1.13.0                                   |
-| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]>             |
-| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] |
+| Author:         | Ben McGinnes <ben@gnupg.org>             |
+| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
 | Language:       | Australian English, British English      |
 | xml:lang:       | en-AU, en-GB, en                         |
 
@@ -40,4 +40,6 @@ Additions since GPGME 1.12.0 include:
 - Added =gpg.version.versionintlist= to make it easier for Python
   developers to check for a specific version number, even with beta
   versions (it will drop the "-betaN" part).
+- Added expanded detail on issues pertaining to installing for Windows
+  users.
 - Bindings enter [[file:maintenance-mode][maintenance mode]] from January, 2019.
index 1d3494c..8440373 100644 (file)
   :CUSTOM_ID: new-stuff
   :END:
 
-| Version:        | 0.0.1-draft                              |
+| Version:        | 0.0.1                                    |
 | GPGME Version:  | 1.13.0                                   |
-| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]>             |
-| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] |
+| Author:         | Ben McGinnes <ben@gnupg.org>             |
+| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
 | Language:       | Australian English, British English      |
 | xml:lang:       | en-AU, en-GB, en                         |
 
index ad3fbed..a68026d 100644 (file)
@@ -171,15 +171,15 @@ Copyright and Licensing
 @node Introduction
 @chapter Introduction
 
-@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
+@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
 @item Version:
 @tab 0.1.4
 @item GPGME Version:
 @tab 1.12.1
 @item Author:
-@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}>
+@tab Ben McGinnes <ben@@gnupg.org>
 @item Author GPG Key:
-@tab @uref{https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get, DB4724E6FA4286C92B4E55C4321E4E2373590E5D}
+@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
 @item Language:
 @tab Australian English, British English
 @item Language codes:
@@ -655,12 +655,13 @@ There are two theoretical solutions to this issue:
 @enumerate
 @item
 Compile and install the GnuPG stack, including GPGME and the
-Python bibdings using the same version of Microsoft Visual Studio
+Python bindings using the same version of Microsoft Visual Studio
 used by the Python Foundation to compile the version of Python
 installed.
 
 If there are multiple versions of Python then this will need to be
-done with each different version of Visual Studio used.
+done with each different version of Visual Studio used for those
+versions of Python.
 
 @item
 Compile and install Python using the same tools used by choice,
@@ -679,6 +680,97 @@ what.
 Investigations into the extent or the limitations of this issue are
 ongoing.
 
+The following table lists the version of Microsoft Visual Studio which
+needs to be used when compiling GPGME and the Python bindings with
+each version of the CPython binary released @uref{https://www.python.org/downloads/windows/, for Windows}:
+
+@multitable {aaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaa}
+@item CPython
+@tab Microsoft product name
+@tab runtime filename
+@item 2.7.6
+@tab Visual Studio 2008
+@tab MSVCR90.DLL
+@item 3.4.0
+@tab Visual Studio 2010
+@tab MSVCR100.DLL
+@item 3.5.0
+@tab Visual Studio 2015
+@tab @strong{see below}
+@item 3.6.0
+@tab Visual Studio 2015
+@tab @strong{see below}
+@item 3.7.0
+@tab Visual Studio 2017*
+@tab @strong{see below}
+@end multitable
+
+It is important to note that MingW and Msys2 ship with the Visual C
+runtime from Microsoft Visual Studio 2005 and are thus @strong{incompatible}
+with all the versions of CPython which can be used with the GPGME
+Python bindings.
+
+It is also important to note that from CPython 3.5 onwards, the Python
+Foundation has adopted the reworking of the Visual C runtime which was
+performed for Visual Studio 2015 and aimed at resolving many of these
+kinds of issues.  Much greater detail on these issues and the correct
+file(s) to link to are available from Matthew Brett's invaluable page,
+@uref{https://matthew-brett.github.io/pydagogue/python_msvc.html, Using Microsoft Visual C with Python}.  It is also worth reading the
+Microsoft Developer Network blog post on @uref{http://blogs.msdn.com/b/vcblog/archive/2015/03/03/introducing-the-universal-crt.aspx, the universal CRT} and Steve
+Dower's blog posts on Python extensions (@uref{http://stevedower.id.au/blog/building-for-python-3-5, part 1} and @uref{http://stevedower.id.au/blog/building-for-python-3-5-part-two, part 2}).
+
+The second of those two posts by Steve Dower contains the details of
+specific configuration options required for compiling anything to be
+used with official CPython releases.  In addition to those
+configuration and compiler settings to use, the versions of Visual
+Studio prior to Visual Studio 2015 did not support 64-bit systems by
+default.  So compiling a 64-bit version of these bindings for a 64-bit
+version of CPython 2.7 or 3.4 requires additional work.
+
+In addition to the blog posts, the @uref{https://wiki.python.org/moin/WindowsCompilers, Windows compilers} wiki page on the
+CPython wiki is another essential reference on the relevant versions
+of Visual Studio to use and the degree of compatibility with CPython
+releases.
+
+Eventually someone will ask why there isn't an installable binary for
+Windows, which the GPGME of the licenses do not preclude as long as
+the source code is available in conjunction with such a release.
+
+The sheer number of versions of Visual Studio in conjunction with
+differing configuration options depending on the target Windows
+version and whether the architecture is 64-bit or 32-bit makes it
+difficult to provide a correct binary installer for Windows users.  At
+the bare minimum doing so would require the GnuPG project compile ten
+different versions of the bindings with each release; both 32-bit and
+64-bit versions for CPython 2.7 and 3.4, with 64-bit versions for both
+x86-64 (i.e. Intel and AMD) and ARM architectures for CPython 3.5,
+3.6, 3.7 and later releases.  That's the bare @strong{minimum}, it'd probably
+be higher.
+
+Considering all of that, what do we recommend?
+
+@enumerate
+@item
+Use a recent version of CPython; at least 3.5, but ideally 3.6 or
+later.
+
+@item
+Use Visual Studio 2015 or the standalone build tools for Visual
+Studio 2017 (or later).
+
+@item
+Compile both CPython and GPGME with these bindings using the tools
+selected in step 2.
+
+@item
+Ignore MingW, Msys2 and the official CPython binary installers.
+
+@item
+Be thankful the answer to this question wasn't simply to say
+something like, “install Linux” or “install FreeBSD” (or even
+Apple's OS X).
+@end enumerate
+
 @node CFFI is the Best™ and GPGME should use it instead of SWIG
 @subsection CFFI is the Best™ and GPGME should use it instead of SWIG
 
index a60236f..cf47f6f 100644 (file)
@@ -36,15 +36,15 @@ Maintenance Mode from 2019
 @node Maintenance Mode from 2019
 @chapter Maintenance Mode from 2019
 
-@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
+@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
 @item Version:
-@tab 0.0.1-draft
+@tab 0.0.1
 @item GPGME Version:
 @tab 1.13.0
 @item Author:
-@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}>
+@tab Ben McGinnes <ben@@gnupg.org>
 @item Author GPG Key:
-@tab @uref{https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get, DB4724E6FA4286C92B4E55C4321E4E2373590E5D}
+@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
 @item Language:
 @tab Australian English, British English
 @item xml:lang:
index 480aebf..41e71d8 100644 (file)
@@ -49,15 +49,15 @@ The Perils of PyPI
 @node Overview
 @chapter Overview
 
-@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
+@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
 @item Version:
-@tab 0.0.1-draft
+@tab 0.0.1
 @item GPGME Version:
 @tab 1.13.0
 @item Author:
-@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}>
+@tab Ben McGinnes <ben@@gnupg.org>
 @item Author GPG Key:
-@tab @uref{https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get, DB4724E6FA4286C92B4E55C4321E4E2373590E5D}
+@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
 @item Language:
 @tab Australian English, British English
 @item xml:lang:
index 25d12c2..4ce1373 100644 (file)
@@ -35,15 +35,15 @@ What's New
 @node What's New
 @chapter What's New
 
-@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
+@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
 @item Version:
-@tab 0.0.1-draft
+@tab 0.0.1
 @item GPGME Version:
 @tab 1.13.0
 @item Author:
-@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}>
+@tab Ben McGinnes <ben@@gnupg.org>
 @item Author GPG Key:
-@tab @uref{https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get, DB4724E6FA4286C92B4E55C4321E4E2373590E5D}
+@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
 @item Language:
 @tab Australian English, British English
 @item xml:lang:
@@ -74,6 +74,9 @@ Added @samp{gpg.version.versionintlist} to make it easier for Python
 developers to check for a specific version number, even with beta
 versions (it will drop the "-betaN" part).
 @item
+Added expanded detail on issues pertaining to installing for Windows
+users.
+@item
 Bindings enter @uref{maintenance-mode, maintenance mode} from January, 2019.
 @end itemize
 
index 63317d8..fa4de8a 100644 (file)
@@ -39,15 +39,15 @@ What Was New in GPGME 1·12·0
 @node What Was New
 @chapter What Was New
 
-@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
+@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
 @item Version:
-@tab 0.0.1-draft
+@tab 0.0.1
 @item GPGME Version:
 @tab 1.13.0
 @item Author:
-@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}>
+@tab Ben McGinnes <ben@@gnupg.org>
 @item Author GPG Key:
-@tab @uref{https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get, DB4724E6FA4286C92B4E55C4321E4E2373590E5D}
+@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
 @item Language:
 @tab Australian English, British English
 @item xml:lang: