<type>documentation</type>
<domain>scripting</domain>
<id>example</id>
<title>Debugging Extension Scripts</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

Wing can debug extension scripts that you develop for the IDE. To do this, you will need
to create a new project with ``New Project`` in Wing's ``Project`` menu. Select ``Use
Existing Directory``, enter the full path of Wing's ``Install Directory``, as listed in
Wing's `About box <script:about-application>`__, and set ``Project Type`` to ``Custom``.
Then press ``Next``, select ``Use Existing Python``, choose ``Command Line`` and enter the
full path to Wing's Python, which is located under the ``Install Directory`` as follows:

  **macOS:** ``Contents/Resources/bin/__os__/osx/runtime-python3.9/bin/python3``
    
  **Linux:** ``bin/__os__/linux-x64/runtime-python3.9/bin/python3``
    
  **Windows:** ``bin\__os__\win32\runtime-python3.9\bin\python.exe``

Be sure to use the *full path* to the executable and not the above partial paths.

Press ``Create Project`` in the ``New Project`` dialog to create the project and save
it to disk when prompted or at any time with ``Save Project As`` in the ``Project`` menu.

Next navigate to ``bootstrap/wing.py`` in the ``Project`` tool, right click on it, and 
select ``Set As Main Entry Point``.

Then set up Wing to run Python in optimized mode, so it can load the precompiled code
in your Wing installation, by setting ``Python Options`` under the ``Debug/Execute``
tab of ``Project Properties`` to ``Custom`` with a value of ``-u -O``.

Finally, **on macOS only**, you will need to open ``Project Properties`` from the ``Project`` 
menu, select ``Add To inherited environment`` under ``Environment``, and paste in the
following::

  INSTALLDIR=/Applications/WingPro.app/Contents/Resources
  RUNTIMES=${INSTALLDIR}/bin/__os__/osx
  QTVERSION=qt5.15
  QTRUNTIME=${RUNTIMES}/runtime-${QTVERSION}
  SCIRUNTIME=${RUNTIMES}/runtime-scintillaedit-${QTVERSION}
  DYLD_LIBRARY_PATH=${QTRUNTIME}/lib:${SCIRUNTIME}/lib
  DYLD_FRAMEWORK_PATH=${DYLD_LIBRARY_PATH}

If you didn't install Wing in the ``/Applications`` folder then you will need to edit
the first line to specify the correct ``Install Dir``.  You may also need to adjust
the value of ``QTVERSION`` for your Wing installation.

You should now be able to select ``Start/Continue`` from the ``Debug`` menu to start up a
copy of Wing in the debugger. Any breakpoints set in scripts that you have added in the
``scripts`` directory will be reached as you work with the debugged copy of Wing. You will
see and can navigate the entire stack, but Wing will not be able to show files for most of
Wing's code. If you need to see the source code of Wing itself, you will have to obtain
the source code as described in `Advanced Scripting <ref:scripting/advanced>`__.

