Setting Up PyCharm for Debugging Waf - Lumberyard User Guide

Setting Up PyCharm for Debugging Waf

AZ Code Generator is in preview release and is subject to change.
Open 3D Engine (O3DE), the successor to Lumberyard, is now available in Developer Preview. Download O3DE or visit the AWS Game Tech blog to learn more.

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. Navigate to the lumberyard_version\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....

                Screenshot displaying the gear icon to select.
    3. Select the Existing environment radio button, and then click the ellipsis (...) icon to the right of it.

      GUI display of the "Existing environment" radio button and the ellipsis button to the right of the "Interpreter" field.
    4. Navigate to the folder containing the python executable. The executable will be contained under the path lumberyard_version\dev\Tools\Python\3.7.5\platform, with the exact path depending on your platform. The Python executable file must be in the same folder as the project or you may have issues running Waf.

      Window displaying the full directory tree and location of python.exe on Windows.
  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:

      • Allow parallel run should be unselected.

      • 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 dev directory.

              Configure debugging
  7. 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. 

    1. Choose File, Settings, Editor, File Types.

    2. Choose Python in Recognized File Types. Select the + icon to the right of the Registered patterns section to add a new file type.

    3. Under Registered Patterns, click the green plus sign (+).

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

                Add wscript wildcard
  8. Turn off IncrediBuild.

    1. Open the _WAF_/usersettings.options file.

    2. Verify that use_incredibuild = False

  9. (Optional) Enable file outlining. This feature makes it easier to navigate source files.

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