| 1 |
# winpty |
| 2 |
|
| 3 |
[](https://tea-ci.org/rprichard/winpty) |
| 4 |
|
| 5 |
winpty is a Windows software package providing an interface similar to a Unix |
| 6 |
pty-master for communicating with Windows console programs. The package |
| 7 |
consists of a library (libwinpty) and a tool for Cygwin and MSYS for running |
| 8 |
Windows console programs in a Cygwin/MSYS pty. |
| 9 |
|
| 10 |
The software works by starting the `winpty-agent.exe` process with a new, |
| 11 |
hidden console window, which bridges between the console API and terminal |
| 12 |
input/output escape codes. It polls the hidden console's screen buffer for |
| 13 |
changes and generates a corresponding stream of output. |
| 14 |
|
| 15 |
The Unix adapter allows running Windows console programs (e.g. CMD, PowerShell, |
| 16 |
IronPython, etc.) under `mintty` or Cygwin's `sshd` with |
| 17 |
properly-functioning input (e.g. arrow and function keys) and output (e.g. line |
| 18 |
buffering). The library could be also useful for writing a non-Cygwin SSH |
| 19 |
server. |
| 20 |
|
| 21 |
## Supported Windows versions |
| 22 |
|
| 23 |
winpty runs on Windows XP through Windows 10, including server versions. It |
| 24 |
can be compiled into either 32-bit or 64-bit binaries. |
| 25 |
|
| 26 |
## Cygwin/MSYS adapter (`winpty.exe`) |
| 27 |
|
| 28 |
### Prerequisites |
| 29 |
|
| 30 |
You need the following to build winpty: |
| 31 |
|
| 32 |
* A Cygwin or MSYS installation |
| 33 |
* GNU make |
| 34 |
* A MinGW g++ toolchain capable of compiling C++11 code to build `winpty.dll` |
| 35 |
and `winpty-agent.exe` |
| 36 |
* A g++ toolchain targeting Cygwin or MSYS to build `winpty.exe` |
| 37 |
|
| 38 |
Winpty requires two g++ toolchains as it is split into two parts. The |
| 39 |
`winpty.dll` and `winpty-agent.exe` binaries interface with the native |
| 40 |
Windows command prompt window so they are compiled with the native MinGW |
| 41 |
toolchain. The `winpty.exe` binary interfaces with the MSYS/Cygwin terminal so |
| 42 |
it is compiled with the MSYS/Cygwin toolchain. |
| 43 |
|
| 44 |
MinGW appears to be split into two distributions -- MinGW (creates 32-bit |
| 45 |
binaries) and MinGW-w64 (creates both 32-bit and 64-bit binaries). Either |
| 46 |
one is generally acceptable. |
| 47 |
|
| 48 |
#### Cygwin packages |
| 49 |
|
| 50 |
The default g++ compiler for Cygwin targets Cygwin itself, but Cygwin also |
| 51 |
packages MinGW-w64 compilers. As of this writing, the necessary packages are: |
| 52 |
|
| 53 |
* Either `mingw64-i686-gcc-g++` or `mingw64-x86_64-gcc-g++`. Select the |
| 54 |
appropriate compiler for your CPU architecture. |
| 55 |
* `gcc-g++` |
| 56 |
* `make` |
| 57 |
|
| 58 |
As of this writing (2016-01-23), only the MinGW-w64 compiler is acceptable. |
| 59 |
The MinGW compiler (e.g. from the `mingw-gcc-g++` package) is no longer |
| 60 |
maintained and is too buggy. |
| 61 |
|
| 62 |
#### MSYS packages |
| 63 |
|
| 64 |
For the original MSYS, use the `mingw-get` tool (MinGW Installation Manager), |
| 65 |
and select at least these components: |
| 66 |
|
| 67 |
* `mingw-developer-toolkit` |
| 68 |
* `mingw32-base` |
| 69 |
* `mingw32-gcc-g++` |
| 70 |
* `msys-base` |
| 71 |
* `msys-system-builder` |
| 72 |
|
| 73 |
When running `./configure`, make sure that `mingw32-g++` is in your |
| 74 |
`PATH`. It will be in the `C:\MinGW\bin` directory. |
| 75 |
|
| 76 |
#### MSYS2 packages |
| 77 |
|
| 78 |
For MSYS2, use `pacman` and install at least these packages: |
| 79 |
|
| 80 |
* `msys/gcc` |
| 81 |
* `mingw32/mingw-w64-i686-gcc` or `mingw64/mingw-w64-x86_64-gcc`. Select |
| 82 |
the appropriate compiler for your CPU architecture. |
| 83 |
* `make` |
| 84 |
|
| 85 |
MSYS2 provides three start menu shortcuts for starting MSYS2: |
| 86 |
|
| 87 |
* MinGW-w64 Win32 Shell |
| 88 |
* MinGW-w64 Win64 Shell |
| 89 |
* MSYS2 Shell |
| 90 |
|
| 91 |
To build winpty, use the MinGW-w64 {Win32,Win64} shortcut of the architecture |
| 92 |
matching MSYS2. These shortcuts will put the g++ compiler from the |
| 93 |
`{mingw32,mingw64}/mingw-w64-{i686,x86_64}-gcc` packages into the `PATH`. |
| 94 |
|
| 95 |
Alternatively, instead of installing `mingw32/mingw-w64-i686-gcc` or |
| 96 |
`mingw64/mingw-w64-x86_64-gcc`, install the `mingw-w64-cross-gcc` and |
| 97 |
`mingw-w64-cross-crt-git` packages. These packages install cross-compilers |
| 98 |
into `/opt/bin`, and then any of the three shortcuts will work. |
| 99 |
|
| 100 |
### Building the Unix adapter |
| 101 |
|
| 102 |
In the project directory, run `./configure`, then `make`, then `make install`. |
| 103 |
By default, winpty is installed into `/usr/local`. Pass `PREFIX=<path>` to |
| 104 |
`make install` to override this default. |
| 105 |
|
| 106 |
### Using the Unix adapter |
| 107 |
|
| 108 |
To run a Windows console program in `mintty` or Cygwin `sshd`, prepend |
| 109 |
`winpty` to the command-line: |
| 110 |
|
| 111 |
$ winpty powershell |
| 112 |
Windows PowerShell |
| 113 |
Copyright (C) 2009 Microsoft Corporation. All rights reserved. |
| 114 |
|
| 115 |
PS C:\rprichard\proj\winpty> 10 + 20 |
| 116 |
30 |
| 117 |
PS C:\rprichard\proj\winpty> exit |
| 118 |
|
| 119 |
## Embedding winpty / MSVC compilation |
| 120 |
|
| 121 |
See `src/include/winpty.h` for the prototypes of functions exported by |
| 122 |
`winpty.dll`. |
| 123 |
|
| 124 |
Only the `winpty.exe` binary uses Cygwin; all the other binaries work without |
| 125 |
it and can be compiled with either MinGW or MSVC. To compile using MSVC, |
| 126 |
download gyp and run `gyp -I configurations.gypi` in the `src` subdirectory. |
| 127 |
This will generate a `winpty.sln` and associated project files. See the |
| 128 |
`src/winpty.gyp` and `src/configurations.gypi` files for notes on dealing with |
| 129 |
MSVC versions and different architectures. |
| 130 |
|
| 131 |
Compiling winpty with MSVC currently requires MSVC 2013 or newer. |
| 132 |
|
| 133 |
## Debugging winpty |
| 134 |
|
| 135 |
winpty comes with a tool for collecting timestamped debugging output. To use |
| 136 |
it: |
| 137 |
|
| 138 |
1. Run `winpty-debugserver.exe` on the same computer as winpty. |
| 139 |
2. Set the `WINPTY_DEBUG` environment variable to `trace` for the |
| 140 |
`winpty.exe` process and/or the process using `libwinpty.dll`. |
| 141 |
|
| 142 |
winpty also recognizes a `WINPTY_SHOW_CONSOLE` environment variable. Set it |
| 143 |
to 1 to prevent winpty from hiding the console window. |
| 144 |
|
| 145 |
## Copyright |
| 146 |
|
| 147 |
This project is distributed under the MIT license (see the `LICENSE` file in |
| 148 |
the project root). |
| 149 |
|
| 150 |
By submitting a pull request for this project, you agree to license your |
| 151 |
contribution under the MIT license to this project. |