ncurses 6.2 - patch 20210213
[ncurses.git] / README.MinGW
index 8bc5dad8c0e82d948216cbb12afbd66a268466a4..3add2e7de3e2c868617e2bb2295beeaabde44e1c 100644 (file)
@@ -1,5 +1,6 @@
 -------------------------------------------------------------------------------
--- Copyright (c) 2008,2010 Free Software Foundation, Inc.                    --
+-- Copyright 2020 Thomas E. Dickey                                           --
+-- Copyright 2008-2011,2012 Free Software Foundation, Inc.                   --
 --                                                                           --
 -- Permission is hereby granted, free of charge, to any person obtaining a   --
 -- copy of this software and associated documentation files (the             --
 -- sale, use or other dealings in this Software without prior written        --
 -- authorization.                                                            --
 -------------------------------------------------------------------------------
--- $Id: README.MinGW,v 1.4 2010/12/18 21:07:03 tom Exp $
+-- $Id: README.MinGW,v 1.14 2020/09/06 22:22:44 tom Exp $
 -- Author: Juergen Pfeifer
 -------------------------------------------------------------------------------
 
-This is work in progress, but it's in an state where one can see it
+This is work in progress, but it is in an state where one can see it
 works at least on the Windows Console.
 
-You should install the MSYS package, so that you've a shell environment that
-allows you to run the scripts, especially configure etc.  You can get that
-from http://www.mingw.org
+You should install the MSYS2 package, so that you have a shell environment that
+allows you to run scripts, especially configure, etc.  You can get that
+from
+       https://www.msys2.org/
 
-To build ncurses for native Windows, you need the MinGW toolchain.  The
-original MinGW toolchain from the above site is only for 32-Bit Windows.  As
-Windows Server - and also regular workstations - are moving to 64-Bit, it
-seems to be reasonable to have a toolchain that supports both architectures. 
-I recommend to use the TDM gcc toolchain which you can find at
-http://tdm-gcc.tdragon.net/download.  Go to the download section and select
-the bundle installer for tdm64 (MinGW-w64).  This installs a multilib version
-of the gcc toolchain that can compile for native 32- and 64-Bit Windows
-versions.  It also comes with a working pthread implementation.
+or the individual packages from
 
-The latest config and build scripts we use for MinGW have only been tested
-for the gcc-4.4 compiler toolchain (or better).
+       https://sourceforge.net/projects/msys2/files/
 
-Using MinGW is a pragmatic decision, it's the easiest way to port this
+You may also use a hosted MinGW cross-compile toolchain, e.g., on Ubuntu or
+ArchLinux to build the libraries and tools.
+
+To build ncurses for native Windows with support for the new Windows 10 Virtual
+Terminal and PseudoConsole support, you should install at least version 8.0 of
+the mingw-w64-x86_64-headers package as it appears to have support for the
+required Windows SDK level.  Please note that some of the Linux distributions
+are a bit behind with respect to the required MinGW header versions and you may
+not be able to properly build the libraries for current Windows 10 using these
+toolchains.  Although it is a bit slow, MSYS2 on Windows 10 64-Bit is the
+authoritative build environment for the MinGW version of ncurses.
+
+Using MinGW is a pragmatic decision, it is the easiest way to port this
 heavily UNIX based sourcebase to native Windows. The goal is of course
 to provide the includes, libraries and DLLs to be used with the more
 common traditional development environments on Windows, mainly with
 Microsoft Visual Studio.
 
-If you start a bash from the MSYS environment, please make sure that the
-Microsoft Development tools are in your PATH right after the MinGW
-tools. The LIB.EXE tool is the only one needed. You need this only if 
-you want to build DLLs that work with native Windows programs. If you 
-don't have any Microsoft  Development tools on your machine, consider 
-at least to get the free "Visual C++ 2010 Express Edition". 
-It contains the LIB.EXE tool. You may also use this compiler to test 
-writing native Windows programs using the ncurses DLLs without using 
-MinGW then for writing apps.
-
-It is necessary to unset the TERM environment variable, to activate the
-Windows console-driver.
-
-Please also make sure that MSYS links to the correct directory containing
-your MinGW toolchain. For TDM this is usually C:\MinGW64. In your Windows
-CMD.EXE command shell go to the MSYS root directory (most probably 
-C:\MSYS or C:\MSYS\1.0) and verify, that there is a junction point mingw
-that points to the MinGW toolchain directory. If not, delete the mingw
-directory and use the mklink command (or the linkd.exe utility on older
-Windows) to create the junction point.
-
-This code requires WindowsNT 5.1 or better, which means on the client
-Windows XP or better, on the server Windows Server 2003 or better.
-
-In order to build ncurses for the planned interop layer with .NET, we
-recommend to use these options with configure
-
-         --disable-home-terminfo
-         --enable-reentrant
-         --enable-sp-funcs
-         --enable-term-driver
-         --enable-interop
-         --with-pthread         (if using TDM toolchain as recommended)
-
-This is the configuration commandline as I'm using it at the moment:
+The TERM environment variable must be set especially to activate the Windows
+console-driver.  The driver checks if TERM is set to "#win32con" (explicit
+use) or if TERM is unset or empty (implicit).
+
+Beginning with build 17763 (Fall 2018 update), Windows 10 supports ANSI escape
+sequences (Virtual Terminal support). If ncurses detects this or a later
+Windows 10 version, the interpretation of the implicit TERM setting (which
+means: TERM is not set or empty) changes. In this case, TERM is to be assumed
+to be "ms-terminal" and ncurses acts using the regular terminfo based driver,
+thus acting like a regular Terminal we all know from UNIX like environments.
+
+This code requires WindowsNT 6.0 or better, which means on the client
+Windows Vista or better, on the server Windows Server 2008 or better.
+
+If running on Windows 10 Build 17763 or later is detected, any program
+spawning a subprocess running a ncurses program should use the new
+PseudoConsole support, which provides what we know as pty from the UNIX
+world also for Windows. Using the CreatePseudoConsole API
+(see https://docs.microsoft.com/en-us/windows/console/createpseudoconsole)
+in the calling process, it is guaranteed that the called ncurses program has
+a console that is required by its implementation, even if the calling program
+is NOT a console program, e.g., MSYS2's own mintty Terminal emulator.
+
+In the current MSYS2/minGW setup, building MinGW shared libraries with
+libtool for ncurses seems to be broken, so I recommend NOT to use libtool.
+
+To build a modern but still small footprint ncurses that provides
+hooks for interop, I recommend using these options:
+
+       --without-libtool
+       --disable-home-terminfo
+       --enable-database
+       --disable-termcap
+       --enable-sp-funcs
+       --enable-term-driver
+       --enable-interop
+
+This is the configuration command line which I am using at the moment
+(assuming environment variable MINGW_ROOT holds the root directory name of
+your MinGW build):
 
 ./configure \
-       --prefix=/mingw \
-       --without-cxx-binding \
+       --prefix=/mingw64 \
+       --without-cxx \
        --without-ada \
        --enable-warnings \
        --enable-assertions \
-       --enable-reentrant \
-       --with-debug \
-       --with-normal \
+       --enable-exp-win32 \
+       --enable-ext-funcs \
        --disable-home-terminfo \
+       --disable-echo \
+       --disable-getcap \
+       --disable-hard-tabs \
+       --disable-leaks \
+       --disable-macros \
+       --disable-overwrite \
+       --enable-opaque-curses \
+       --enable-opaque-panel \
+       --enable-opaque-menu \
+       --enable-opaque-form \
+       --enable-database \
        --enable-sp-funcs \
        --enable-term-driver \
        --enable-interop \
-       --with-pthread
-
-If you are on a 64-Bit Windows system and want to build a 32-Bit version
-of ncurses, you may use this commandline for configuration (when using
-the TDM toolchain):
-
-CC="gcc -m32" LD="ld -m32" ./configure \
-       --prefix=/mingw \
-       --without-cxx-binding \
-       --without-ada \
-       --enable-warnings \
-       --enable-assertions \
-       --enable-reentrant \
-       --with-debug \
+       --disable-termcap \
+       --enable-database \
+       --with-progs \
+       --without-libtool \
+       --enable-pc-files \
+       --with-shared \
        --with-normal \
-       --disable-home-terminfo \
-       --enable-sp-funcs \
-       --enable-term-driver \
-       --enable-interop \
-       --with-pthread
-
-All the options above are - like the whole Windows support -
-experimental.
+       --without-debug \
+       --with-fallbacks=ms-terminal \
+       --without-manpages
 
-In order to build the DLLs, after your regular make you must call
+Please note that it is also necessary to set this environment variable:
 
-   make dlls
+export PATH_SEPARATOR=";"
 
-A lot is still TODO, e.g.:
+in order to parse the terminfo paths correctly. Terminfo paths should
+always be separated by a semicolon, even when running under MSYS2.
 
-  - Wide Character support
-    The Win32Con driver should actually only use Unicode in the
-    future.
-  - Thread support (locking). If using TDM toolchain this is done by
-    configuring pthreads.
-  - A GUI console driver
-  - Support for Terminals attached via a serial port (via terminfo)
-  - Support for networked Terminal connections (via terminfo)
+All the options above are - like the whole Windows support -
+experimental.
 
-To support terminfo, we need to have an ioctl() simulation for the
-serial and networked Terminals.
+-- vile:txtmode