<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** selects the Python that should be used when running code with this
launch configuration. This can be set to ``Use project setting`` to use the setting in
``Project Properties``. 

``Use default`` uses Python found on the PATH, or if none is found there
then the latest version found anywhere on the system. Use ``Command Line`` to enter any
command that invokes Python with all provided arguments. This is the
value of ``sys.executable`` (after ``import sys``) in the selected Python.  A list of all
found Python installations is given in the drop down to the right of the entry area.

To use an environment set up by virtualenv or Anaconda, choose ``Activated Env`` to enter
the full path to ``activate`` or ``activate.bat`` for the selected environment. The drop
down menu to the right of this field lists recently used and automatically found
environments.  This will not work if the full path to the activate script contains spaces.
In that case, use the ``Command Line`` option as described above.

~~~if WINGPRO:
In Wing Pro, this property can tell Wing to run Python on a `container
<ref:proj/containers>`__ or `remote host <ref:proj/remote-hosts>`__. On a container, some
of the other properties listed below (as noted) are ignored since the container defines
the runtime environment. On a remote host, the default directory used for other fields in
``Project Properties``, and for adding files and directories to the project, will be the
base directory defined for the selected remote host.
~~~

When this property invokes Anaconda Python, Wing will automatically run ``conda activate
base`` before it starts Python. This is needed to avoid failure to import some modules as
a result of missing environment. See About Anaconda Environments in the `Anaconda How-To
<ref:howtos/anaconda>`__ 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``.

~~~if WINGPRO:
When using a container as the ``Python Executable``, this property is disabled because
Wing instead obtains the Python path from the container.
~~~

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

~~~if WINGPRO:
When using a container as the ``Python Executable``, this property is disabled because
Wing instead obtains the initial directory from the container.
~~~

**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 macOS the environment inherited by Wing may differ according to whether you
launched Wing from the command line or with the Finder.

~~~if WINGPRO:
When using a container as the ``Python Executable``, this property is disabled because
Wing instead obtains the environment from the container.
~~~

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

