User Guide (Version 1.21)

Setting Up PyCharm for Debugging Waf

AZ Code Generator is in preview release and is subject to change.

PyCharm is an integrated development environment for Python which includes a graphical debugger that is useful for debugging Waf.

To set up PyCharm and Waf for debugging

  1. Download PyCharm Community Edition.

  2. Start PyCharm.

  3. At the welcome screen, choose Open Directory

  4. From the Lumberyard root directory, navigate to any branch that contains a _WAF_ or dev directory.  There should be a file called wscript and under this folder.

  5. Configure the Python interpreter.

    1. Choose File, Settings, Project:dev, Project Interpreter to open the project interpreter page.

    2. Click the gear icon on the right of the Project Interpreter and choose Add Local.

                Add Local
    3. Navigate to the folder where python.exe resides.  The Python executable file must be in the same folder as the project or you may have issues running Waf.

                Verify the location of python.exe
  6. Set up a debugging profile for Waf.

    1. To set up Waf for debugging, use the project explorer in the left pane.  If you don't see the project explorer, press Alt+1).  Navigate to the \dev\Tools\Build\waf-<version> node and expand it. You should see a file called lmbr_waf inside this node.

                The lmbr_waf file
    2. Right-click lmbr_waf and choose Create lmbr_waf


      The Indexing... operation must finish before the option appears. You can verify status in the bar at the bottom.

                Create lmbr_waf
    3. In the Create Run/Debug Configuration dialog, ensure that the following values are configured correctly:

      • Single instance only should be selected.

      • Script Parameters is the command to use to run Waf for the run/debug session.

      • Python Interpreter should be the interpreter that you specified earlier.

      • The Working directory must be the root of the project (for example, the dev directory).

              Configure debugging

      Next, you must to set up wscript files as debuggable Python files. Waf uses files called wscript to define the build rules per project.  These are dynamically loaded Python modules that can be debugged like any other Python module. 

    4. Choose File, Settings, Editor, File Types, Python.

    5. To add a registered pattern for wscript, choose Python in Recognized File Types.

                Choose Python
    6. Under Registered Patterns, click the green plus sign (+).

    7. In the Add Wildcard dialog box, enter wscript.

                Add wscript wildcard
  7. Make sure IncrediBuild is turned off.

    1. Open the _WAF_/usersettings.options file.

    2. Verify that use_incredibuild is set to false, as in the following example. use_incredibuild = False

  8. (Optional) Enable file outlining.

    By default, file outlining is switched off in PyCharm. This feature facilitates navigation in the source files, as the following image shows.

            File outlining

    To enable file outlining, right-click the Project tab and choose Show Members.