AuroraMiddleware/winpty
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
179d1af900
winpty/README.md
Ryan Prichard 5a65fdc11c Use more sensible executable flags for source files 
My motivation at the moment is that I'm trying to share a
git checkout between multiple VMs using VirtualBox's Shared
Folders feature.  git in the guest VM isn't able to see the
executable bits from the host due to the VirtualBox/SMB/CIFS
layer.  Instead, it thinks text files are non-executable,
unless they have a shebang line.  That's a sensible way to
set the flags anyway, so set them like that.

With this commit, there's still one file that isn't handled:
src/shared/GetCommitHash.cmd.  It's still marked executable,
but it lacks a shebang line, so the guest thinks it's
non-executable.  I'm not sure it should be changed.
2016-04-20 21:44:44 -07:00

4.7 KiB
Raw Blame History

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.

Supported Windows versions

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

Cygwin/MSYS adapter (winpty.exe)

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 winpty.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 winpty.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

Building the Unix adapter

In the project directory, run ./configure, then make, then make install. By default, winpty is installed into /usr/local. Pass PREFIX=<path> to make install to override this default.

Using the Unix adapter

To run a Windows console program in mintty or Cygwin sshd, prepend winpty to the command-line:

$ winpty powershell
Windows PowerShell
Copyright (C) 2009 Microsoft Corporation. All rights reserved.

PS C:\rprichard\proj\winpty> 10 + 20
30
PS C:\rprichard\proj\winpty> exit

Embedding winpty / MSVC compilation

See src/include/winpty.h for the prototypes of functions exported by winpty.dll.

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

Compiling winpty with MSVC currently requires MSVC 2013 or newer.

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 winpty.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.