Build and Debug Instructions for PTVS

Cloning

First, you will require a local copy of our Git repository. It can be cloned from https://github.com/Microsoft/PTVS.git. (If you're behind a corporate firewall you may need to enter your proxy settings.)

If you intend to contribute back to PTVS, you should Create a Fork and use the source URL provided there. Pull requests associated with an issue or feature request are the preferred way for making contributions.

Prerequisites

1. Install Visual Studio 2022 Preview Community edition or higher, with the following workloads selected:

   • .NET desktop development
   • Desktop development with C++
   • Visual Studio extension development
   • ASP.NET and web development
     • Only if you intend to build Django
   • DO NOT install the Python workload into the Visual Studio version you are going to be building PTVS with.
     • You CAN install the Python workload into other Visual Studio versions.

2. Run ./Python/Prerequisites/deploy_test_targets.cmd as Administrator

3. Right-click on ./Python/Prerequisites/EnableSkipVerification.reg (or …X86.reg on 32-bit OS) and click on merge

   • This disables strong name verification for the built binaries.
   • If you've already run \\vspreinstall\preinstall\preinstall.cmd, you can skip the registry script
   • If you get exception on missing target, either you forgot to run deploy_test_targets.cmd or VS install dir in the deploy_test_targets.cmd is incorrect. Fix the location and try again.

4. Install the azure artifacts credential provider.

   • To do this, open a powershell prompt and run the following: iex "& { $(irm https://aka.ms/install-artifacts-credprovider.ps1) } -AddNetfx"
   • If this doesn't work, you can download the ps1 file and run it manually. See https://github.com/microsoft/artifacts-credprovider for more info.

5. Install nodejs/npm from https://nodejs.org/en/download/

6. Install the vsts-npm-auth package through npm. This will allow the script to download pylance from the azure artifacts feed as part of the next step.

   • npm install -g vsts-npm-auth
   • vsts-npm-auth -config .npmrc -force

7. Run ./Build/PreBuild.ps1 through powershell

Building and debugging with Visual Studio

PTVS is packaged into several VSIX packages that get installed into the Visual Studio Experimental (Exp) Hive when you build.

1. Open ./Python/PythonTools.sln in Visual Studio and select Product\Core as the Startup Project.
2. Push F5 to build and run
   • This will launch the Exp instance of VS through the debugger, with all the Python extensions installed.
     • This is indicated by Exp in the upper right corner of the VS window.
   • If an error appears rather than a new instance of VS, ensure the Project|Debug settings are correctly starting your devenv.exe with arguments /rootSuffix Exp (and optionally /log).
   • Sometimes the updated vsix packages don't get installed to the Exp hive. A rebuild will usually fix this.
3. To debug, set breakpoints in the non-Exp instance of Visual Studio, and perform actions in the Exp instance.

Optional Projects

Core projects are always required to be built, and you will receive build errors if you unload one by mistake. They are grouped under the CoreProduct solution folder. The PythonTools.sln solution file includes a solution platform called "Minimal" that may be selected within Visual Studio to only build these projects. This will give the fastest possible build times, while only providing core functionality.

Projects under the "Product" solution folder are optional and may be unloaded to reduce build time. Once they are built, you should Clean the solution before unloading them. Note that some of the tests require these projects.

Projects under the "Tests" solution folder are also optional, but as we expect tests to be added or fixed for contributions you will likely need to run some of them. We do not require 100% test pass rate to accept a pull request, as there are a number of tests that rely on precise system configuration or are known to be unreliable.

Building with MSBuild

Building from the command line does NOT install PTVS into the VS Experimental hive (by default), nor create an installer, nor affect your main VS installation.

1. To build from the command line, run the following from your repo root:

   msbuild Python\dirs.proj
   

2. To build AND deploy to the Experimental hive, run the following:

   msbuild Python\dirs.proj /p:VSTarget=17.0 /p:DeployExtension=true /p:RegisterOutputPackage=true
   

   • If you get errors when deploying the Python - C++ project debugging support extension to the Exp hive, it's probably due to path length issues. Follow the steps at https://www.tenforums.com/tutorials/51704-enable-disable-win32-long-paths-windows-10-a.html#option1 to enable long paths and try again.

3. To launch the VS Experimental hive, open the Visual Studio Command Prompt and run the following:

   devenv /rootSuffix Exp
   

Clearing the Exp hive

Sometimes the Exp hive can get corrupted, which leads to all sorts of problems. The safest way to clear it is to just delete it, since a new one will be created the next time you build and run.

1. Browse to %localappdata%\Microsoft\VisualStudio
   • For example, C:\Users\<yourUserName>\AppData\Local\Microsoft\VisualStudio
2. Look for folders starting with your Visual Studio major version and ending in Exp
   • For example, 16.0_e9fd16d8Exp
3. Delete all of the folders that match what you found from the previous step

Running Automated Tests

PTVS contains a large number of automated tests, including a mix of UI-based tests (which will start another VS, take control of your mouse, etc.) and non-UI tests. Some of the UI-based tests may fail intermittently or interfere with each other, while some tests may make incorrect assumptions about your system configuration (such as the availability of certain versions of Python). It is best to select the tests you need from the Test Explorer window and supervise them as they run.