Repository files navigation

winpty is a Windows software package providing an interface similar to a Unixpty-master for communicating with Windows console programs. The packageconsists of a library (libwinpty) and a tool for Cygwin and MSYS for runningWindows console programs in a Cygwin/MSYS pty.

The software works by starting thewinpty-agent.exe process with a new,hidden console window, which bridges between the console API and terminalinput/output escape codes. It polls the hidden console's screen buffer forchanges and generates a corresponding stream of output.

The Unix adapter allows running Windows console programs (e.g. CMD, PowerShell,IronPython, etc.) undermintty or Cygwin'ssshd withproperly-functioning input (e.g. arrow and function keys) and output (e.g. linebuffering). The library could be also useful for writing a non-Cygwin SSHserver.

winpty runs on Windows XP through Windows 10, including server versions. Itcan be compiled into either 32-bit or 64-bit binaries.

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 buildwinpty.dllandwinpty-agent.exe
• A g++ toolchain targeting Cygwin or MSYS to buildwinpty.exe

Winpty requires two g++ toolchains as it is split into two parts. Thewinpty.dll andwinpty-agent.exe binaries interface with the nativeWindows command prompt window so they are compiled with the native MinGWtoolchain. Thewinpty.exe binary interfaces with the MSYS/Cygwin terminal soit is compiled with the MSYS/Cygwin toolchain.

MinGW appears to be split into two distributions -- MinGW (creates 32-bitbinaries) and MinGW-w64 (creates both 32-bit and 64-bit binaries). Eitherone is generally acceptable.

The default g++ compiler for Cygwin targets Cygwin itself, but Cygwin alsopackages MinGW-w64 compilers. As of this writing, the necessary packages are:

• Eithermingw64-i686-gcc-g++ ormingw64-x86_64-gcc-g++. Select theappropriate 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 themingw-gcc-g++ package) is no longermaintained and is too buggy.

For the original MSYS, use themingw-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 thatmingw32-g++ is in yourPATH. It will be in theC:\MinGW\bin directory.

For MSYS2, usepacman and install at least these packages:

• msys/gcc
• mingw32/mingw-w64-i686-gcc ormingw64/mingw-w64-x86_64-gcc. Selectthe appropriate compiler for your CPU architecture.
• make

MSYS2 provides three start menu shortcuts for starting MSYS2:

• MinGW-w64 Win32 Shell
• MinGW-w64 Win64 Shell
• MSYS2 Shell

To build winpty, use the MinGW-w64 {Win32,Win64} shortcut of the architecturematching MSYS2. These shortcuts will put the g++ compiler from the{mingw32,mingw64}/mingw-w64-{i686,x86_64}-gcc packages into thePATH.

Alternatively, instead of installingmingw32/mingw-w64-i686-gcc ormingw64/mingw-w64-x86_64-gcc, install themingw-w64-cross-gcc andmingw-w64-cross-crt-git packages. These packages install cross-compilersinto/opt/bin, and then any of the three shortcuts will work.

In the project directory, run./configure, thenmake, thenmake install.By default, winpty is installed into/usr/local. PassPREFIX=<path> tomake install to override this default.

To run a Windows console program inmintty or Cygwinsshd, prependwinpty to the command-line:

$ winpty powershellWindows PowerShellCopyright (C) 2009 Microsoft Corporation. All rights reserved.PS C:\rprichard\proj\winpty> 10 + 2030PS C:\rprichard\proj\winpty> exit

Seesrc/include/winpty.h for the prototypes of functions exported bywinpty.dll.

Only thewinpty.exe binary uses Cygwin; all the other binaries work withoutit and can be compiled with either MinGW or MSVC. To compile using MSVC,download gyp and rungyp -I configurations.gypi in thesrc subdirectory.This will generate awinpty.sln and associated project files. See thesrc/winpty.gyp andsrc/configurations.gypi files for notes on dealing withMSVC versions and different architectures.

Compiling winpty with MSVC currently requires MSVC 2013 or newer.

winpty comes with a tool for collecting timestamped debugging output. To useit:

1. Runwinpty-debugserver.exe on the same computer as winpty.
2. Set theWINPTY_DEBUG environment variable totrace for thewinpty.exe process and/or the process usinglibwinpty.dll.

winpty also recognizes aWINPTY_SHOW_CONSOLE environment variable. Set itto 1 to prevent winpty from hiding the console window.

This project is distributed under the MIT license (see theLICENSE file inthe project root).

By submitting a pull request for this project, you agree to license yourcontribution under the MIT license to this project.