<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 is 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**

The ``Options`` menu includes items for starting, terminating, or restarting a command,
clearing the execution console, and specifying whether consoles should auto-clear each time
the process is started or restarted.

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.

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

**Starting a Terminal**

On Linux and OS X, or when working with a project that points to a remote host, the
``Tools`` menu includes an item ``Start Terminal`` that will start a new ``bash``
terminal.

To set up a terminal that runs a different shell, add a *Command Line* style OS Command
with ``Command Line`` set to your shell executable (for example, for the ``Start
Terminal`` menu item Wing sets this to``bash -norc``) and then enable the ``Use
pseudo-TTY`` and ``Line mode`` options.

Note that Wing's ``OS Commands`` tool does not fully emulate a TTY, so the tab key,
color, and cursor movement are not supported.
