1  # Copyright (c) Microsoft Corporation. All rights reserved.
   2  # Licensed under the MIT License. See LICENSE in the project root
   3  # for license information.
   4  
   5  import sys
   6  
   7  if __name__ == "__main__":
   8  
   9      # There are three ways to run debugpy:
  10      #
  11      # 1. Installed as a module in the current environment (python -m debugpy ...)
  12      # 2. Run as a script from source code (python <repo_root>/src/debugpy ...)
  13      # 3. Installed as a module in a random directory
  14      #
  15      # -----
  16      #
  17      # In the first case, no extra work is needed. Importing debugpy will work as expected.
  18      # Also, running 'debugpy' instead of 'python -m debugpy' will work because of the entry point
  19      # defined in setup.py.
  20      #
  21      # -----
  22      #
  23      # In the second case, sys.path[0] is the one added automatically by Python for the directory 
  24      # containing this file. 'import debugpy' will not work since we need the parent directory 
  25      # of debugpy/ to be in sys.path, rather than debugpy/ itself. So we need to modify sys.path[0].
  26      # Running 'debugpy' will not work because the entry point is not defined in this case.
  27      #
  28      # -----
  29      #
  30      # In the third case, running 'python -m debugpy' will not work because the module is not installed
  31      # in any environment. Running 'python <install_dir>/debugpy' will work, just like the second case. 
  32      # But running the entry point will not work because python doesn't know where to find the debugpy module.
  33      #
  34      # In this case, no changes to sys.path are required. You just have to do the following before calling
  35      # the entry point:
  36      #   1. Add <install_dir> to PYTHONPATH.
  37      #       On Windows, this is set PYTHONPATH=%PYTHONPATH%;<install_dir>
  38      #   2. Add <install_dir>/bin to PATH. (OPTIONAL)
  39      #       On Windows, this is set PATH=%PATH%;<install_dir>\bin
  40      #   3. Run the entry point from a command prompt
  41      #       On Windows, this is <install_dir>\bin\debugpy.exe, or just 'debugpy' if you did the previous step.
  42      #
  43      # -----
  44      #
  45      # If we modify sys.path, 'import debugpy' will work, but it will break other imports
  46      # because they will be resolved relative to debugpy/ - e.g. `import debugger` will try
  47      # to import debugpy/debugger.py.
  48      #
  49      # To fix both problems, we need to do the following steps:
  50      # 1. Modify sys.path[0] to point at the parent directory of debugpy/ instead of debugpy/ itself.
  51      # 2. Import debugpy.
  52      # 3. Remove sys.path[0] so that it doesn't affect future imports. 
  53      # 
  54      # For example, suppose the user did:
  55      #
  56      #   python /foo/bar/debugpy ...
  57      #
  58      # At the beginning of this script, sys.path[0] will contain "/foo/bar/debugpy".
  59      # We want to replace it with "/foo/bar', then 'import debugpy', then remove the replaced entry.
  60      # The imported debugpy module will remain in sys.modules, and thus all future imports of it 
  61      # or its submodules will resolve accordingly.
  62      if "debugpy" not in sys.modules:
  63  
  64          # Do not use dirname() to walk up - this can be a relative path, e.g. ".".
  65          sys.path[0] = sys.path[0] + "/../"
  66          import debugpy  # noqa
  67          del sys.path[0]
  68  
  69      from debugpy.server import cli
  70  
  71      cli.main()
  72