winpty/README.rst
Ryan Prichard b844635158 Remove support for the MinGW compiler packaged with Cygwin.
MinGW-w64 is still supported, as is the MinGW compiler distributed by
mingw.org.

Cygwin's MinGW toolchain uses the 4.0-1 mingw-runtime package by
default, which appears to correspond to the "WSL-4" 4.x version of the
MinGW project's mingwrt packages.  (The version numbers in the
/usr/i686-pc-mingw32/sys-root/mingw/include/_mingw.h file are also
consistent with this theory.)

The WSL-4 branch was repudiated by the MinGW project as a mistake [1].
The MinGW project claims no responsibility for Cygwin's MinGW packages
[2].  There were several releases in short succession [3]:
  4.0.3 2013-09-22
  4.0.2 2013-09-15
  4.0.1 2013-09-14
  4.0.0 2013-08-23
There have been no 4.x releases since then, though there have been more
3.x releases (3.21 and 3.21.1).  The FILE_FLAG_FIRST_PIPE_INSTANCE bug
that this project has worked around was fixed in 4.0.3 [4], which was
never propagated to the Cygwin package.

The MinGW packages were apparantly orphaned on 2014-09-18 [5] and are
still orphaned [6].

[1] http://sourceforge.net/p/mingw/bugs/1673/#5260/41ec
[2] http://sourceforge.net/p/mingw/bugs/1673/#2556/35d4
[3] http://sourceforge.net/projects/mingw/files/MinGW/Base/mingwrt/
[4] http://sourceforge.net/p/mingw/bugs/2050/
[5] https://cygwin.com/ml/cygwin/2014-09/msg00289.html
[6] https://cygwin.com/cygwin-pkg-maint
2016-01-23 06:19:56 -06:00

128 lines
4.1 KiB
ReStructuredText

======
winpty
======
winpty is a Windows software package providing an interface similar to a Unix
pty-master for communicating with Windows console programs. The package
consists of a library (libwinpty) and a tool for Cygwin and MSYS for running
Windows console programs in a Cygwin/MSYS pty.
The software works by starting the ``winpty-agent.exe`` process with a new,
hidden console window, which bridges between the console API and terminal
input/output escape codes. It polls the hidden console's screen buffer for
changes and generates a corresponding stream of output.
The Unix adapter allows running Windows console programs (e.g. CMD, PowerShell,
IronPython, etc.) under ``mintty`` or Cygwin's ``sshd`` with
properly-functioning input (e.g. arrow and function keys) and output (e.g. line
buffering). The library could be also useful for writing a non-Cygwin SSH
server.
Prerequisites
=============
You need the following to build winpty:
* A Cygwin or MSYS installation
* GNU make
* A MinGW g++ toolchain capable of compiling C++11 code to build ``winpty.dll``
and ``winpty-agent.exe``
* A g++ toolchain targeting Cygwin or MSYS to build ``console.exe``
Winpty requires two g++ toolchains as it is split into two parts. The
``winpty.dll`` and ``winpty-agent.exe`` binaries interface with the native
Windows command prompt window so they are compiled with the native MinGW
toolchain. The console.exe binary interfaces with the MSYS/Cygwin terminal so
it is compiled with the MSYS/Cygwin toolchain.
MinGW appears to be split into two distributions -- MinGW (creates 32-bit
binaries) and MinGW-w64 (creates both 32-bit and 64-bit binaries). Either
one is generally acceptable.
Cygwin packages
---------------
The default g++ compiler for Cygwin targets Cygwin itself, but Cygwin also
packages MinGW-w64 compilers. As of this writing, the necessary packages are:
* Either ``mingw64-i686-gcc-g++`` or ``mingw64-x86_64-gcc-g++``. Select the
appropriate compiler for your CPU architecture.
* ``gcc-g++``
* ``make``
As of this writing (2016-01-23), only the MinGW-w64 compiler is acceptable.
The MinGW compiler (e.g. from the ``mingw-gcc-g++`` package) is no longer
maintained and is too buggy.
MSYS packages
-------------
For the original MSYS, use the ``mingw-get`` tool (MinGW Installation Manager),
and select at least these components:
* ``mingw-developer-toolkit``
* ``mingw32-base``
* ``mingw32-gcc-g++``
* ``msys-base``
* ``msys-system-builder``
When running ``./configure``, make sure that ``mingw32-g++`` is in your
``PATH``. It will be in the ``C:\MinGW\bin`` directory.
MSYS2 packages
--------------
For MSYS2, use ``pacman`` and install at least these packages:
* ``msys/gcc``
* ``mingw32/mingw-w64-i686-gcc`` or ``mingw64/mingw-w64-x86_64-gcc``. Select
the appropriate compiler for your CPU architecture.
* ``make``
Build
=====
In the project directory, run ``./configure``, then ``make``.
This will produce three binaries:
* ``build/winpty.dll``
* ``build/winpty-agent.exe``
* ``build/console.exe``
Using the Unix adapter
======================
To run a Windows console program in ``mintty`` or Cygwin ``sshd``, prepend
``console.exe`` to the command-line::
$ build/console.exe c:/Python27/python.exe
Python 2.7.2 (default, Jun 12 2011, 15:08:59) [MSC v.1500 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> 10 + 20
30
>>> exit()
$
Debugging winpty
================
winpty comes with a tool for collecting timestamped debugging output. To use
it:
1. Run ``winpty-debugserver.exe`` on the same computer as winpty.
2. Set the ``WINPTY_DEBUG`` environment variable to ``trace`` for the
``console.exe`` process and/or the process using ``libwinpty.dll``.
winpty also recognizes a ``WINPTY_SHOW_CONSOLE`` environment variable. Set it
to 1 to prevent winpty from hiding the console window.
Copyright
=========
This project is distributed under the MIT license (see the ``LICENSE`` file in
the project root).
By submitting a pull request for this project, you agree to license your
contribution under the MIT license to this project.