Windows (Visual Studio)

Building using Visual Studio (2019, 2022)

Environment Setup

Visual Studio

You must first install Visual Studio with the Desktop development with C++ feature set installed. Additionally, you’ll need to make sure the optional component C++ CMake tools for Windows is installed.

vcpkg

KiCad uses vcpkg for dependencies and uses manifest mode to declare the dependencies and our kicad registry on top of vcpkg.

  1. Obtain vcpkg for your system from https://github.com/microsoft/vcpkg

  2. In order to benefit from pre-built packages, checkout the specific vcpkg commit used by KiCad’s continuous integration pipeline. This is defined as the $vcpkgCommit variable in the build.ps1 script in the kicad-win-builder repository

  3. Bootstrap vcpkg, so the vcpkg tool is installed

In summary, decide where you want vcpkg to be installed and run the following commands:

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
# Replace commit hash with that defined as $vcpkgCommit of https://gitlab.com/kicad/packaging/kicad-win-builder/-/blob/master/build.ps1
git checkout ef7dbf94b9198bc58f45951adcf1f041fcbc5ea0
.\bootstrap-vcpkg.bat
KiCad requires a vcpkg.exe tool released since Jan 2022,therefore ensure any existing copy of vcpkg is up to date and bootstrap it again if required.

KiCad Specific Setup

1. Manual installation of SWIG

SWIG must be installed manually. Obtain the latest swigwin package from https://sourceforge.net/projects/swig/files/swigwin/ (at the time of this writing, the latest is swigwin-4.1.1) and extract the zip file to a known location.

2. Configuring NuGet package source

In order to benefit from pre-built packages that will significantly speed up your first build, you should add KiCad’s package repository to your NuGet sources with the name kicad-gitlab

For this, you need the nuget.exe command line utility. This can be obtained at https://www.nuget.org/downloads/

Go to the directory where your nuget.exe is located and run:

./nuget.exe sources add -Name kicad-gitlab -Source "https://gitlab.com/api/v4/projects/27426693/packages/nuget/index.json"
For this to work, you must ensure your local copy of vcpkg is checked out at the same commit as is used in KiCad’s continuous integration pipeline. Refer to the vcpkg section above for more details. After you check-out the commit, ensure you run .\bootstrap-vcpkg.bat again.

3. CMakeSettings.json

Contained in the build root is a CMakeSettings.json.sample

  1. Copy and rename this file to CMakeSettings.json

  2. Edit your renamed CMakeSettings.json to:

    1. Update the VcPkgDir environment variable up top to match the location of your vcpkg clone.

    2. Update the SwigExePath environment variable up top to match the location of where you extracted the SWIG tool in step 1 above.

{ "VcPkgDir": "D:/vcpkg/" },
...
{ "SwigExePath": "D:/swigwin-4.1.1/swig.exe" },

4. "Open Folder" in Visual Studio

  • Launch Visual Studio (only after completing the above steps).

  • When the initial wizard launches, select to Open a local folder. This is the correct way to make Visual Studio directly handle CMake projects.

  • Select the build root folder.

  • Ensure x64-Debug build configuration is selected. This will start the cmake configuration process and building of vcpkg dependencies. Note: You can see the progress by opening the Output window (if not already open) by navigating to View → Output

If correctly configured, vcpkg should download the pre-built binaries of all dependencies from the KiCad packaging repository and usually complete in about 1-10 minutes depending on your internet connection. However, if there are any differences in your build environment, this step will take a long time (several hours, depending on the speed of your computer). In particular you should double check that you checked out the correct vcpkg commit and bootstrapped. At some points, it might appear as if the process is stuck because the output window doesn’t update for many minutes (or even an hour, depending on your machine) with a message like Building x64-windows. This is nomal. Keep visual studio open until it is complete.

  • Wait until the "CMake in Visual Studio" tab appears and the CMake process finishes with the message CMake generation finished.

5. Running and debugging

Running or debugging KiCad directly from the build directory through Visual Studio requires that you set certain environment variables so that KiCad can find runtime dependencies and Python works. To configure the runtime environment for programs run from Visual Studio, edit the launch.vs.json file in the project root directory. To open this file, select Debug and Launch Settings for kicad from the Debug menu.

If you have multiple launch configurations, for example to debug standalone pcbnew or eeschema in addition to kicad, you will need to configure each one separately.

The variable KICAD_RUN_FROM_BUILD_DIR must be present (it can be set to any value) to run from the build directory. Setting this variable allows KiCad to find dynamic libraries when running from the build directory.

The variable KICAD_USE_EXTERNAL_PYTHONHOME must be present (it can be set to any value) when running from either the build or the install directory, which allows you to specify PYTHONHOME in the environment. Normally, KiCad on Windows uses a Python that is bundled and placed in a specific location by the installer, and when running from Visual Studio, Python will be in a different location.

The variable PYTHONHOME must be present and set to the location of the Python installed by vcpkg.

The variable PYTHONPATH must be present and set to include the paths to the pcbnew python module and the kicad_pyshell module. The former is built next to pcbnew.exe in the build directory, and the latter lives in the source tree in the scripting directory.

Use the env section of each configuration entry to set the required environment variables, including the path to the vcpkg installed packages directory, which will allow KiCad to find dynamic libraries from dependencies. For example, the below configuration allows running and debugging kicad.exe from the build directory.

Create this file as <kicad_source>/.vs/launch.vs.json to have a baseline/working default launch configuration:

{
  "version": "0.2.1",
  "defaults": {},
  "configurations": [
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "kicad.exe (kicad\\kicad.exe)",
      "name": "kicad.exe (kicad\\kicad.exe)",
      "env": {
        "KICAD_RUN_FROM_BUILD_DIR": "1",
        "KICAD_USE_EXTERNAL_PYTHONHOME": "1",
        "PYTHONHOME": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\tools\\python3",
        "PYTHONPATH": "${cmake.buildRoot}\\pcbnew;${projectDir}\\scripting",
        "PATH": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\debug\\bin;${cmake.buildRoot}\\common;${cmake.buildRoot}\\api;${cmake.buildRoot}\\common\\gal;${env.PATH}"
      }
    },
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "pcbnew.exe (pcbnew\\pcbnew.exe)",
      "name": "pcbnew.exe (pcbnew\\pcbnew.exe)",
      "env": {
        "KICAD_RUN_FROM_BUILD_DIR": "1",
        "KICAD_USE_EXTERNAL_PYTHONHOME": "1",
        "PYTHONHOME": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\tools\\python3",
        "PYTHONPATH": "${cmake.buildRoot}\\pcbnew;${projectDir}\\scripting",
        "PATH": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\debug\\bin;${cmake.buildRoot}\\common;${cmake.buildRoot}\\api;${cmake.buildRoot}\\common\\gal;${env.PATH}"
      }
    },
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "eeschema.exe (eeschema\\eeschema.exe)",
      "name": "eeschema.exe (eeschema\\eeschema.exe)",
      "env": {
        "KICAD_RUN_FROM_BUILD_DIR": "1",
        "KICAD_USE_EXTERNAL_PYTHONHOME": "1",
        "PYTHONHOME": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\tools\\python3",
        "PYTHONPATH": "${cmake.buildRoot}\\pcbnew;${projectDir}\\scripting",
        "PATH": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\debug\\bin;${cmake.buildRoot}\\common;${cmake.buildRoot}\\api;${cmake.buildRoot}\\common\\gal;${env.PATH}"
      }
    },
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "gerbview.exe (gerbview\\gerbview.exe)",
      "name": "gerbview.exe (gerbview\\gerbview.exe)",
      "env": {
        "KICAD_RUN_FROM_BUILD_DIR": "1",
        "KICAD_USE_EXTERNAL_PYTHONHOME": "1",
        "PYTHONHOME": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\tools\\python3",
        "PYTHONPATH": "${cmake.buildRoot}\\pcbnew;${projectDir}\\scripting",
        "PATH": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\debug\\bin;${cmake.buildRoot}\\common;${cmake.buildRoot}\\api;${cmake.buildRoot}\\common\\gal;${env.PATH}"
      }
    },
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "pl_editor.exe (pagelayout_editor\\pl_editor.exe)",
      "name": "pl_editor.exe (pagelayout_editor\\pl_editor.exe)",
      "env": {
        "KICAD_RUN_FROM_BUILD_DIR": "1",
        "KICAD_USE_EXTERNAL_PYTHONHOME": "1",
        "PYTHONHOME": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\tools\\python3",
        "PYTHONPATH": "${cmake.buildRoot}\\pcbnew;${projectDir}\\scripting",
        "PATH": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\debug\\bin;${cmake.buildRoot}\\common;${cmake.buildRoot}\\api;${cmake.buildRoot}\\common\\gal;${env.PATH}"
      }
    },
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "pcb_calculator.exe (pcb_calculator\\pcb_calculator.exe)",
      "name": "pcb_calculator.exe (pcb_calculator\\pcb_calculator.exe)",
      "env": {
        "KICAD_RUN_FROM_BUILD_DIR": "1",
        "KICAD_USE_EXTERNAL_PYTHONHOME": "1",
        "PYTHONHOME": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\tools\\python3",
        "PYTHONPATH": "${cmake.buildRoot}\\pcbnew;${projectDir}\\scripting",
        "PATH": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\debug\\bin;${cmake.buildRoot}\\common;${cmake.buildRoot}\\api;${cmake.buildRoot}\\common\\gal;${env.PATH}"
      }
    },
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "bitmap2component.exe (bitmap2component\\bitmap2component.exe)",
      "name": "bitmap2component.exe (bitmap2component\\bitmap2component.exe)",
      "env": {
        "KICAD_RUN_FROM_BUILD_DIR": "1",
        "KICAD_USE_EXTERNAL_PYTHONHOME": "1",
        "PYTHONHOME": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\tools\\python3",
        "PYTHONPATH": "${cmake.buildRoot}\\pcbnew;${projectDir}\\scripting",
        "PATH": "${cmake.buildRoot}\\vcpkg_installed\\x64-windows\\debug\\bin;${cmake.buildRoot}\\common;${cmake.buildRoot}\\api;${cmake.buildRoot}\\common\\gal;${env.PATH}"
      }
    }
  ]
}

Visual Studio Extras

Trailing Whitespace Remover (Extension)

It is highly recommended users install the Trailing Whitespace Visualizer for Visual Studio 2022 which will not only highlight trailing whitespace as you type but also automatically remove it by default when you save the file.

natvis definitions for libraries

Visual Studio supports defining decoders for objects in debug views.

You can find some useful ones here:

Simply download the files and drop them into: %USERPROFILE%\Documents\Visual Studio 2022\Visualizers

VS will load them after it starts up.

Advanced

It is recommended to only try these changes after getting a basic configuration working using the above steps.

Binary caching

By default vcpkg will bundle up each dependency and store it in a binary cache which maintains copies of all past built dependencies by version.

The binary cache is located usually in %LOCALAPPDATA%\vcpkg\archives

If storage space consumed is a problem.

You may change the location of the binary cache by setting the environment variable VCPKG_DEFAULT_BINARY_CACHE to a different path.

or

You may disable binary caching by setting the environment variable VCPKG_FEATURE_FLAGS with value -binarycaching. This is not advisable as the intention of the cache is to avoid rebuilds if the application cmake cache is destroyed and rebuilt and rebuilding kicad dependencies is quite time consuming.

Manifest mode

The KiCad repository is configured to use Manifest Mode.

The benefits of using this is that it ensures the developer’s dependencies always match that of the project so that if any dependencies are added or version bumped, they will be automatically build. The negative side of manifest mode is that whenever you update your version of visual studio or navigate the git history, you will need to rebuild vcpkg dependencies.

If this is deemed undesirable, it is possible to disable manifest mode locally by following these steps:

  1. Copy vcpkg-configuration.json from kicad root into your vcpkg root

  2. Manually run a vcpkg install command for all dependencies currently defined in the KiCad root vcpkg.json. E.g. something like below:

    .\vcpkg.exe install --recurse --triplet x64-windows boost-algorithm boost-bimap boost-filesystem boost-functional boost-iterator boost-locale boost-optional boost-property-tree boost-ptr-container boost-range boost-test boost-uuid cairo wxwidgets glew curl gettext[tools] harfbuzz glm opencascade[rapidjson] opengl python3 openssl sqlite3[fts5,fts4,fts3,rtree,session] icu ngspice wxpython libgit2[ssh,winhttp] nng protobuf zstd

  3. .\vcpkg upgrade --no-dry-run

  4. Set cmake variable VCPKG_MANIFEST_MODE to OFF

  5. Ensure launch.vs.json PATH and PYTHONHOME variables point to the vcpkg folder (instead of the one in cmake root) - i.e. modify to be as follows:

            "PYTHONHOME": "C:\\PATH\\TO\\vcpkg_installed\\x64-windows\\tools\\python3",
        "PYTHONPATH": "${cmake.buildRoot}\\pcbnew;${projectDir}\\scripting",
        "PATH": "C:\\PATH\\TO\\vcpkg\\installed\\x64-windows\\debug\\bin;${env.PATH}",

  6. Delete cmake cache and reconfigure

Disabling manifest mode means you have to manually ensure that the dependencies you have installed locally match those required by the KiCad project.

Troubleshooting

vcpkg cannot finish installing a dependency

Antivirus software is known to block interim steps in the package build process. Try temporarily disabling your antivirus or adding an exception.

Error: Couldn’t find the versions database file

If this occurs, a mismatch between vcpkg and registries occurred when it was checking your already installed libraries within the kicad build repo. The easiest fix is to simply Delete Cache and Reconfigure under the Project menu option