<type>documentation</type>
<domain>debug</domain>
<id>external-i-o-consoles</id>
<title>External I/O Consoles</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

In cases where a debug process launched from Wing requires specific characteristics
provided by a full-featured terminal emulator or Windows console, or to better handle very
large amounts of debug process output, you can redirect debug I/O to a new external window
using the `Debugger > I/O > Use External Console
<script:show_preferences_gui#prefname="debug.external-console">`__ preference.

The most effective way to keep the external console visible after the debug process exits
is to place a breakpoint on the last line of your code. Alternatively, enable the
`Debugger > I/O > External Console Waits on Exit
<script:show_preferences_gui#prefname="debug.persist-console">`__ preference. However,
this can result in many external consoles being displayed at once if you do not press
``Enter`` inside the consoles after each debug run.

On Linux and macOS it is possible to select which console applications will be tried for
the external console by altering the `Debugger > I/O > External Consoles
<script:show_preferences_gui#prefname="debug.x-terminal">`__ preference.

On Windows, Wing always uses the standard DOS Console that comes with your version of
Windows.

**Environment Limitations**

Depending on the terminal implementation used, environment variables set by Wing may not
be inherited by the Python process that runs within the external console. This breaks
virtualenv, Anaconda environments, and any other case where the configured environment is
needed for code to be able to run.

An easy work-around for virtualenv is to selected the ``Command Line`` option for ``Python
Executable`` in ``Project Properties`` or the launch configuration. Then enter the full
path of the virtualenv's Python. This is the value of ``sys.executable`` (after ``import
sys``) in the desired virtualenv.

To work around this in other cases, create a launch script that sets up your environment
and then starts Python with all arguments that were passed to the script. Then set this
script as the ``Command Line`` in your ``Python Executable`` in ``Project Properties`` or
your launch configuration.

For example on Windows::

  @echo off
  set MYENV=value
  call C:\path\to\envsetup.bat
  C:\path\to\python.exe %* 

Or on macOS and Linux::

  #!/usr/bin/env bash
  export MYENV=value
  . /path/to/envsetup.sh
  /path/to/python "$@"

Both examples show setting ``MYENV`` within the script and calling an external environment
setup script ``envsetup``. Either may be used as a way to provide the environment to the
invoked Python.
