node_modules/node-pty/deps/winpty/README.md

   1 # winpty
   2
   3 [![Build Status](https://tea-ci.org/api/badges/rprichard/winpty/status.svg)](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.