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

   • Install the following workloads:
     • .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.
   • Install the following individual components (see https://aka.ms/Ofhn4c for more info):
     • MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (Latest)
     • C++ ATL for latest v143 build tools with Spectre Mitigations (x86 & x64)
     • C++ MFC for latest v143 build tools with Spectre Mitigations (x86 & x64)

2. Open a Visual Studio command prompt as Administrator, change to the root of where you cloned the PTVS repo, and run .\Python\Prerequisites\deploy_test_targets.cmd

3. Right-click on <repopath>\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 nodejs/npm from https://nodejs.org/en/download/

5. MICROSOFT EMPLOYEES ONLY - 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.

6. MICROSOFT EMPLOYEES ONLY - 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. You will need to run the second command as an administrator:

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

7. Restore npm and nuget packages by running powershell .\Build\PreBuild.ps1

   • If you get an error about not being allowed to run scripts, you may need to change the execution policy on your machine. From a PowerShell run as administrator, you can use Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine to allow local script execution. Once done you should probably go back to prior restrictions (typically done with Set-ExecutionPolicy -ExecutionPolicy AllSigned -Scope LocalMachine).
   • If you get 401 unauthorized errors...
     • If you ARE a Microsoft Employee, you need to authenticate. To do this, run .\Build\PreBuild.ps1 -interactive. After you login, a personal access token will be created for you. You won't need to do this again until the token expires. You will get an e-mail about the token, and you can browse to it and extend the expiration date by quite a while.
     • If you are NOT a Microsoft Employee, this should never happen to you. If it does, please create an issue in the PTVS repo and our team will get it fixed.

8. BUILD WITH MSBUILD BEFORE BUILDING THROUGH VISUAL STUDIO (SEE BELOW)

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.

• Note, you need to run the build and deploy from the command line step at least once for deployment to work in the IDE.

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
   

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.

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.