Let’s Learn Zig #2 — Setting up a Zig Development Environment

Visual Studio Code 1.81.1, Zig 0.11.0

The following instructions were written in Mac but can be easily be followed for Linux systems.

Introduction

One of the most important tools for programmers is none other than where the code writing itself occurs, a pleasant and helpful development environment sets us up for success in our programming endeavor; especially when learning a new programming language like Zig. Although I admire all you vim and emacs wizards out there(vim > emacs, btw), we will be setting up a Visual Studio Code development environment for our Zig programming journey; mostly because it provides the easiest setup to quickly get features like code completion and

Visual Studio Code

First, we will need to download Visual Studio Code(VSCode) from Microsoft.

Zig

Next, let’s go ahead and grab the Zig binary version 0.11.0 from the official Zig download website by the Zig Software Foundation.

Once downloaded, make sure to extract the contents to a folder in your desired path, for example:

/Users/andy/zig-versions/zig-macos-aarch64–0.11.0/

Now, we can setup our environment path to the Zig binary, we can edit either the ~/.zshrc on Mac or the ~/.bashrc on Linux (Windows users must do the equivalent of this) with the following

export PATH="$PATH:/Users/andy/zig-versions/zig-macos-aarch64-0.11.0/"

Make sure to restart your terminal and then type zig version command to make sure the path is setup correctly, you should get your downloaded version number as the output.

andy@laptop ~ % zig version
0.11.0

Visual Studio Code Extensions

For me, this is where VSCode really shines, the amount of extensions and support there is for it is great, also installing and maintaining extensions up to date is really easy and user friendly.

In the extensions tab in VSCode, search and install the following:

Zig Language

This will enable a wide variety of features that will make our Zig programming experience much more pleasant in VSCode, but I will highlight the zls, zig language server, in specific; which enables code completion for Zig, a handy tool to make us more efficient programmers.

After installing Zig Language, you may need to set the path in the extension settings. Go to the Zig Language Extension page, click on Settings icon and enter Extension Settings. Then put your zig path on the Zig: Zig Path field. Remember to include the path with the binary included. For example: /Users/andy/zig-versions/zig-macos-aarch64–0.11.0/zig

CodeLLDB

This extension will allow us to debug our Zig programs right inside VSCode, making VSCode a fairly lightweight full fledge IDE experience for Zig.

C/C++ (Windows only)

If you are on windows you will need C/C++ extension instead of the CodeLLDB.

Additional Configurations

We need to do some additional configurations in our project folder. But first, let’s make a new Zig project folder initialize. In the terminal:

andyx@laptop ~ % mkdir zig-test-proj
andyx@laptop ~ % cd zig-test-proj
andyx@laptop ~ % zig init-exe

The last command, “zig init-exe”, initializes a zig build application; it basically does some initial setup for us like creating certain directories and files. You may notice the build.zig, file, that is right, no more make files, zig has its own build system and uses zig language to boot! We will be covering build.zig in a later tutorial but it is important to highlight this feature early.

Next, open the project folder you just called zig init-exe in vscode. Now, we need to edit both our launch.json and tasks.json files in vscode, do note that these are vscode only specific configurations and special thanks to zig community member lukemerrick on the discord for providing these files and steps.

First we must edit our tasks.json, you can access this file by doing ctrl+p in linux and shift+command+p in mac os and selecting Tasks: Open User Tasks. This will generate your tasks.json file, now copy the following into it:

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "label": "zig build",
            "type": "shell",
            "command": "zig",
            "args": [
                "build",
                "--summary",
                "all"
            ],
            "options": {
                "cwd": "${workspaceRoot}"
            },
            "presentation": {
                "echo": true,
                "reveal": "always",
                "focus": false,
                "panel": "shared",
                "showReuseMessage": true,
                "clear": false
            },
            "problemMatcher": [],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        }
    ]
}

<your-project-name>/.vscode/tasks.json

This is basically just defining a VSCode tasks with label “zig build”, command “zig” and the args “build”, “ — — summary” and “all”. This is just a VSCode task that will build our zig program by running the shell command “zig build — —summary all” whenever we try to build from inside VSCode.

Next we need to edit our launch.json file. We can create this file under the hidden folder .vscode inside our root project directory. If you do not have a .vscode folder, create it and create launch.json in it. Then copy the following:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "lldb",
            "request": "launch",
            "name": "Debug",
            "program": "${workspaceFolder}/zig-out/bin/<your-project-name>",
            "args": [],
            "cwd": "${workspaceFolder}",
            "preLaunchTask": "zig build"
        },
    ]
}

<your-project-name>/.vscode/launch.json

If you are on windows, in the “type” field, switch “lldb” for “cppvsdbg”.

Next up, your VSCode may not be correctly reading you environment path variables when the task is run. To fix this issue, you need to configure your terminal settings in VSCode. First open a new terminal, Terminal->New Terminal; then in the terminal window click on the downwards arrow next to the plus sign and select Configure Terminal Settings. Now scroll down till you find Terminal > Integrated > Default Profile: <Your OS>, in my case I will go to Osx and make sure that on the drop down menu, zsh is selected. Linux users will need to make sure bash is selected. Next scroll to find Terminal > Integrated > Automation Profile: <Your OS> and click on Edit in settings.json. On Mac OS it is supposed to include something like this: (this file may have your other additional settings you could have set in the past)

{
    "zig.zls.path": "/Users/andy/Library/Application Support/Code/User/globalStorage/ziglang.vscode-zig/zls_install/zls",
    "zig.zigPath": "/Users/andy/zig-versions/zig-macos-aarch64-0.11.0/zig",
    "terminal.integrated.profiles.osx": {
        "zsh": {
            "path": "zsh",
            "args": [
                "-i"
            ]
        }
    },
    "terminal.integrated.defaultProfile.osx": "zsh",
}

Notice that this is for osx fields, on linux you would see terminal.integrated.profiles.linux and terminal.integrated.defaultProfile.linux, also instead of zsh, bash. If not, add them. Same would be for windows but for windows parameters.

Now, test that debugging is working by setting up a breakpoint in the generated main.zig file inside the src folder and running the program inside VSCode with Run->Start Debugging. If everything is setup correctly you should be good to go!

If you are still having issues, feel free to leave a comment below with your issue and I will try my best to help.

Conclusion

Now you should be familiar with setting up a Zig development environment with VSCode. Hopefully you were able to follow along and are ready to embark on your Zig development journey!