<type>documentation</type>
<domain>proj</domain>
<id>launch-configs</id>
<title>Launch Configurations</title>
<date>$Date: 2010-05-14 11:53:19 -0400 (Fri, 14 May 2010) $</date>
<version>$Revision: 22093 $</version>
<product-version>5+</product-version>
<product>per+</product>

Launch configurations define environment in a way similar to ``Project Properties`` but in
a form that can be applied to an individual file through `File Properties
<ref:proj/file-properties>`__, in the creation of `named entry points
<ref:debug/named-entry-points>`__, and for running the ``Python Shell``.

They are managed from `Launch Configurations <script:manage-launch-configs>`__ in the
``Project`` menu. Use the icons or right click to create, edit, duplicate, or delete
items.

Launch configurations contain the following properties. For all of these, environment
variable references may be used, as described in `Environment Variable Expansion
<ref:proj/variable-expansion>`__:

Python Tab
----------

**Python Executable** sets the full path to the Python executable that 
should be used when running code with this launch configuration.  When 
``Use default`` is selected, Wing uses the value from ``Project Properties``.

~~~if WINGPRO:
In Wing Pro, this property can be used to run Python on a remote host.  
When this is done, the launch configuration will only be usable with files that are 
also stored on that remote host. See `Remote Hosts <ref:proj/remote-hosts>`__ for details.
~~~

**Python Path** sets the ``PYTHONPATH`` that is used by Python to locate modules that are
imported with the ``import`` statement. By default this uses the path set in ``Project
Properties``. When ``Use default`` is selected, the ``PYTHONPATH`` environment variable
inherited by Wing at startup is used instead. Otherwise, when ``Custom`` is selected, the
specified ``PYTHONPATH`` is used.

Setting this property is usually only necessary if your code changes ``sys.path`` at 
runtime in a way that Wing can't auto-detect or if it depends on ``PYTHONPATH``
being set from the outside.  You should not add the Python standard
library's ``PYTHONPATH`` entries here, since Wing will be able to obtain those by
inspecting your selected ``Python Executable``.

This property allows displaying the entered Python Path either as a list or as text
using the path separator appropriate for the OS.  If you need to paste in a path,
select ``View as Text`` first and then right-click to ``Paste``.

**Python Options** sets the command line options sent to the Python
interpreter while debugging or executing code with this launch configuration. The default
uses the setting in ``Project Properties``. Using ``-u`` sets Python into unbuffered I/O
mode, which ensures that the debug process output, including prompts shown for keyboard
input, will appear in a timely fashion.

Note that these are *not* the command line arguments to send to your code, but instead
options sent to Python itself. To send arguments to your code, set ``Run Arguments`` 
under the ``Environment`` tab.

Environment Tab
---------------

**Run Arguments** sets the command line arguments to send to code debugged
or executed with this launch configuration.  Wing does not interpret backslashes ('\\') on the
command line and passes them unchanged to the sub-process. The only exceptions to this rule are
``\'`` and ``\"`` (backslash followed by single or double quote), which allow inclusion of quotes
inside quoted multi-word arguments.
  
**Initial Directory** selects the initial working directory to use for processes started
with this launch configuration. By default this uses the ``Initial Directory`` specified
in `Project Properties <ref:proj/project-properties>`__. When ``Use default`` is
selected, the directory of the launched file is used instead. When ``Custom`` is selected,
the specified directory is used instead. Use ``${WING:PROJECT_DIR}`` for the project's
directory.

**Environment** specifies environment variables that should be added,
modified, or removed from the environment when using this launch configuration. The drop
down menu selects the environment to modify: ``Add to inherited environment`` modifies the
environment inherited when Wing was started, and ``Add to project values`` modifies the
environment from ``Project Properties``. When ``Use project values`` or ``Use inherited
environment`` is chosen, any entered values are ignored and the selected environment is
used without changes.

Each entry is in ``var=value`` form, without any quotes around the value, and must be
specified one per line. An entry in the form ``var=`` (without a value) will remove the
given variable so it is undefined.

Note that you are operating on the environment inherited by the IDE when it started
(optionally, as modified in ``Project Properties``) and not modifying an empty
environment. On OS X the environment inherited by Wing may differ according to whether you
launched Wing from the command line or with the Finder.

**Build Command** sets a command that will be executed before starting debug with this launch
configuration. This is useful to make sure that extension modules, Cython modules, and
other compiled build targets are rebuilt before each run. The build is configured and run
by the `OS Commands <ref:oscommands/index>`__ tool.

Shared Launch Configurations
----------------------------

By default each launch configuration is stored in the project file. The ``Shared``
checkbox in the launch configuration dialog causes Wing to store that launch configuration
in the `Settings Directory <ref:install/user-settings-dir>`__ instead, in a file
named ``launch``.  Shared launch configurations are accessible from all projects.

Working on Different Machines or OSes
-------------------------------------

When the ``Shared`` checkbox is selected for a launch configuration, or when `shared projects
<ref:proj/project-types>`__ are used, launch configurations must be configured so
that they will work across projects, machines, and operating systems. 

For example, specifying a full path in the ``Python Path`` may not work on a different OS. The key to
making this work is to use environment variable references in the form ``${VARNAME}`` as described
in `Environment Variable Expansion <ref:proj/variable-expansion>`__. The referenced environment variables can be
special environment variables defined by Wing, as in ``${WING:PROJECT_DIR}``, or user-defined values
that are set either system-wide, or in `Project Properties <ref:proj/project-properties>`__. 
Values set in ``Environment`` in ``Project Properties`` are by default not stored in the shared
project file, so those may vary on each development machine.

A common example in configuring ``Python Path`` is to replace a full path like
``/Users/myname/src/project/src`` with ``${WING:PROJECT_DIR}/src`` (this assumes you store the
project in ``/Users/myname/src/project``).  In general, working off the project's location is a
good approach to maintaining some independence from the configuration and disk layout
on different development machines and OSes.

To make file paths work across OSes, use forward slashes instead of back slashes. The character
sequence ``..`` can be used to move up a directory on all OSes, as for example in
``{WING:PROJECT_DIR}/../libs/src``.

