Building & Debugging Blender with Visual Studio Code

Visual Studio Code is an open source and multiplatform IDE for code editing (and compiling, debugging, etc.) available here : https://code.visualstudio.com/

I wanted to see if I could build, run and debug Blender using this IDE, and the anwser is : yes. Here is how to do it.

Edit: Updated the scripts and configuration of Visual Studio Code (no longer requires an CMake install, will load scripts and datafiles directly from the sources)

Setup

Based on : https://wiki.blender.org/index.php/Dev:Doc/Building_Blender/Linux/Generic_Distro/CMake.

I’m using the following folder hierarchy to build:

Blender         # with a B.
   |--- blender # with a b, this is a clone of the Blender source repository
   |--- libs    # will contains Blender's dependencies (external libraries)

So, first step is to create this structure, retrieve the Blender sources, and build the dependencies. To do that, here is the bootstrap script I’m using (put that in a bootstrap.sh file and execute it)

# create our root folder
mkdir Blender
cd Blender

# this will download Blender's sources
git clone --recursive https://git.blender.org/blender.git

# now create the libs folders
mkdir -p libs/sources
mkdir -p libs/install

# and build them. Note that the source and install path need
# to be absolute
./blender/build_files/build_environment/install_deps.sh \
    --with-all                                          \
    --source $PWD/libs/sources                          \
    --install $PWD/libs/install

This can take quite a bit of time, depending on your computer. But you only need to do it once (well, sometime the libs are updated, but it doesn’t happen very often)

Also, after this is done, you’ll notice a file BUILD_NOTES.txt in the root Blender folder. This is a generated file which contains useful information about the dependencies (we’ll use this file to configure Visual Studio Code to build Blender)

Install Visual Studio Code

Once you’ve installed Visual Studio Code, install the following addons :

C/C++ (Microsoft) – C/C++ support. Required
CMake (twxs) – CMake syntax coloring, code completion, etc. Optional but useful if you have to modify a CMake script file
CMake Tools (Microsoft) – Add Configure/Build features based on CMake. Required
Clang-Format (xaver) – Used to automatically format code to follow Blender’s coding style. Optional but highly recommended if you want to contribute.

Note that CMake Tools plugin requires CMake version 3.7.1 or greater, with server mode enabled (if you installed a recent prebuilt version from the CMake website, it should be enabled by default. But if you build your own, make sure it’s enabled)

Build

Now, open Visual Studio Code, and open the Blender/blender folder. If CMake Tools worked correctly, the status bar should look like this:

Before going further, we will setup the project to configure CMake to use the dependencies. In the sources (Blender/blender) create a .vscode folder. In this folder, create a settings.json file:

{
    // Where Blender is built. DO NOT BUILD IN SOURCES !
    "cmake.buildDirectory": "${workspaceRoot}/../build",

    // If you want to generate an install of Blender, setup this path:
    "cmake.installPrefix":  "${workspaceRoot}/../install"

    // The options used by CMake to configure how Blender is built
    "cmake.configureSettings": {
        // this part comes from the BUILD_NOTES.txt file generated when we build the libs
        "WITH_CODEC_SNDFILE": "ON",
        "PYTHON_VERSION": "3.7",
        "WITH_OPENCOLORIO": "ON",
        // ... the rest of the file
    },

    // Clang-format options (only if your installed the extension)
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "xaver.clang-format"
}

Notice that the options in BUILD_NOTES.txt are not formatted the same way as CMake Tools want, so you need to format them like in the example above.

Now after this step, you’ll be able to build Blender. Just setup the kit you want to use, select the build type (both actions are done using the CMake Tools helpers that appear on the status bar, on the bottom-left of Visual Studio Code) and hit F7

Debug

Time for fun! Blender is built, we’d like to dive in the code. There’s one last thing to do: add a launch configuration. Indeed, unless you make an install, the scripts and datafiles are not accessible to the Blender’s executable. So to debug, we need to create a launch.json next to our settings.json file.

This is the content on my file on Linux, with comments on the relevent sections:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(gdb) Launch",
            "type": "cppdbg",
            "request": "launch",
            // path to the Blender's executable
            "program": "${command:cmake.buildDirectory}/bin/blender",
            // in here you can add arguments that will be passed to blender when the debugging session starts
            "args": [],
            "stopAtEntry": false,
            // by default it runs in the source folder, but you can use any other you like
            "cwd": "${workspaceFolder}",
            // this one is the most important! Without those environment variable, Blender will fail to start because it won't find its Python scripts and data files.
            "environment": [
                { "name": "BLENDER_SYSTEM_SCRIPTS", "value": "${workspaceFolder}/release/scripts" },
                { "name": "BLENDER_SYSTEM_DATAFILES", "value": "${workspaceFolder}/release/datafiles" }
            ],
            "externalConsole": false,
            "MIMode": "gdb",
            "setupCommands": [ { "description": "", "text": "-enable-pretty-printing", "ignoreFailures": true } ]
        }
    ],
    "compounds": []
}

And there, you’re done. Now you can run Blender from inside Visual Studio Code by hitting F5. If you selected a Debug build type, breakpoints will work as excepted, etc.

Conclusion

It was my first time using Visual Studio Code, and I must say I’m very impressed by the ease of use and feature set ! Out of the box, it has Git support, and through the embedded extension manager you can enable C/C++ building/debugging/etc., CMake support, etc. with only a few clicks !

And then the setup part is completely straightforward ! You have a .vscode folder in your project containing the various .json setting files, and in each of those files, autocompletion works like a charm so you can easily find what you want, without even having to bother looking online for documentation / help !! (in my first tests, I was on an old computer where I had to specify the path to my custom CMake, and the path to my custom GDB, and I found them in a few seconds without having to leave the IDE)

Anyway, I highly recommend you to give a try to this software, CMake support is almost perfect (I still have to delete the build folder manually whenever I want to change the options CMake was configured with, but other than that, perfect) and building / debugging is fast, intuitive, user friendly and powerful.

Le blog de Citron