<type>documentation</type>
<domain>oscommands</domain>
<id>index</id>
<title>OS Commands Tool</title>
<date>$Date: 2006-05-26 17:43:42 -0400 (Fri, 26 May 2006) $</date>
<version>$Revision: 13128 $</version>
<product>per+</product>

The `OS Commands <script:show_panel#panel_type="os-command">`__ tool in Wing Pro and Wing
Personal executes and interacts with external commands provided by the OS or by other
software. It can be used to execute Python code outside of the debugger, run build commands,
integrate external tools into Wing, start code that is debugged using ``wingdbstub``,
and so forth.

**Adding and Editing Commands**

There are three types of OS Commands: 

(1) *Command Lines* are executed in the environment configured in the OS 
Command itself.

(2) *Python Files* are executed in the environment configured in their 
`File Properties <ref:proj/file-properties>`__.

(3) *Named Entry Points* are executed in the environment configured by the
selected `Named Entry Point <ref:debug/named-entry-points>`__.

Commands can be added, edited, and deleted with the icons in the ``OS Commands`` tool and
from its ``Options`` menu.

Additionally, whenever a file is executed outside of the debugger, or when a build command
is configured in `Project Properties <ref:proj/project-properties>`__ or `Launch
Configurations <ref:proj/launch-configs>`__, these are added automatically to the ``OS
Commands`` tool.

For details on setting up a new command, see `OS Command Properties 
<ref:oscommands/properties>`__.

**Executing Commands**

Commands can be executed and terminated from icons in the ``OS Command`` tool and from its 
``Options`` menu.

The bottom portion of the ``OS Commands`` tool contains the console where commands are
executed, where output is shown, and where input can be entered for sending to the
sub-process. Use the popup menu to switch between running processes, or add multiple
instances of the ``OS Commands`` tool to view them at the same time. 

The console provides a right-click context menu for controlling the process, copy/pasting,
and clearing or saving a copy of the output to a file.

**Start Terminal**

Wing offers ``Start Terminal`` in the ``OS Commands`` tool menus and the ``Tools`` menu in
the menu bar. This configures and starts a new *Command Line* style OS Command that
runs a shell terminal.  On Windows, this uses ``cmd.exe`` and on Linux and macOS it
uses ``bash``.

On Windows, the default I/O encoding is UTF-8.  When this is the case, terminal
commands are started with ``chcp 65001`` so that ``cmd.exe`` also uses UTF-8 for
non-Python programs.  To use the system's default code page instead, change
``I/O Encoding`` in the `OS Command Properties <ref:oscommands/properties>`__ or the
default encoding under `Debugger > I/O > OS Commands Encoding
<script:show_preferences_gui#prefname="consoles.encoding">`__ to
``Console default``.

For projects that use a virtualenv Python, the terminal will be started after
running the appropriate activate script (``activate`` on Linux/macOS or ``activate.bat``
on Windows).  On Windows, this is set in the ``Command Line`` property, which can be
set back to ``cmd.exe`` to avoid activating the virtualenv.  On Linux and macOS, it can
be set back to ``bash -norc``.

The terminal uses a TTY-enabled console that supports color, cursor movement, and other
ANSI escape sequences.  On Linux and macOS, ``TERM`` is set to ``xterm-256color``.  On
Windows 10 (version 1809 and later) and Windows 11, the console uses the ConPTY pseudo-terminal
interface.

To set up a terminal that runs a different shell on Linux or macOS, add a *Command Line*
style OS Command with ``Command Line`` set to your shell executable (for example, Wing's
default terminal configuration uses ``bash -norc``), enable ``Use pseudo-TTY``, and
disable ``Line mode``.

**Console Keys**

When a TTY-enabled console has keyboard focus, keystrokes are sent directly to the
sub-process by default, rather than being processed as IDE key bindings.  This is
controlled by the ``Send Keys Directly to Console Tools`` preference under
`User Interface > Console Keys <script:show_preferences_gui#prefname="gui.console-send-keys-directly">`__.

To use IDE key bindings while the console has focus, use Ctrl+Shift+ in place of Ctrl+
for bindings that would otherwise be handled by the terminal.  For example, Ctrl+Shift+C
activates the Copy command (normally bound to Ctrl+C) instead of sending a Ctrl+C
interrupt to the process.  This is controlled by the ``Use Ctrl+Shift+ For Ctrl+ Bindings``
preference.

On macOS, Command+ key bindings such as Command+C for Copy continue to work as usual in
consoles, controlled by the ``Use Command+ Bindings`` preference.

The ``Console Key Bindings`` table in the same preference page allows defining additional
key bindings that are active only when a console has focus.

**Options**

The ``Options`` menu includes items for restarting a command and clearing the execution 
console, and also the following options:

* ``Auto-Clear Consoles`` controls whether the console is automatically cleared each time
  a command is started or restarted.

* ``Python Prompt After Execution`` controls whether *Python File* style commands drop
  into the Python prompt after the file is executed, rather than exiting the process.

* ``Wrap Long Lines`` controls whether long lines are shown on a single line or wrapped
  to the width of the ``OS Commands`` tool.

**Toolbox**

The ``OS Commands`` toolbox contains the same items in the popup menu at the top of the
tool, but is more convenient for editing or removing multiple items, or quickly executing
a series of commands. The toolbox is hidden by default but can be shown with ``Show
Toolbox`` in the ``Options`` menu. Right-click on the list for available actions, or
middle-click or double-click on the list to execute items.

