Using Visual Studio Code

Introduction

Visual Studio Code is an editor from Microsoft which is becoming increasingly popular. It is an editor, not a full IDE, so it must be used in conjunction with a build system. It runs on Windows, Linux and MacOS. These instructions are based on version 1.52.

VScode with Makefiles under Linux and MacOS

First install the prerequisites:

• Allegro 5
• C compiler
• VScode
• pkg-config

You can get Allegro, compiler and pkg-config from your distribution (use apt, dnf or brew as appropriate.) If you've never compiled anything before you may need to install additional software but that is beyond the scope of this document. VScode may be available or you may need to download it direct from Microsoft.

As a first example, we will compile hello.c from the Quickstart.

View source

#include <allegro5/allegro5.h>
#include <allegro5/allegro_font.h>
#include <stdbool.h>

int main()
{
    al_init();
    al_install_keyboard();

    ALLEGRO_TIMER* timer = al_create_timer(1.0 / 30.0);
    ALLEGRO_EVENT_QUEUE* queue = al_create_event_queue();
    ALLEGRO_DISPLAY* disp = al_create_display(320, 200);
    ALLEGRO_FONT* font = al_create_builtin_font();

    al_register_event_source(queue, al_get_keyboard_event_source());
    al_register_event_source(queue, al_get_display_event_source(disp));
    al_register_event_source(queue, al_get_timer_event_source(timer));

    bool redraw = true;
    ALLEGRO_EVENT event;

    al_start_timer(timer);
    while(1)
    {
        al_wait_for_event(queue, &event);

        if(event.type == ALLEGRO_EVENT_TIMER)
            redraw = true;
        else if((event.type == ALLEGRO_EVENT_KEY_DOWN) || (event.type == ALLEGRO_EVENT_DISPLAY_CLOSE))
            break;

        if(redraw && al_is_event_queue_empty(queue))
        {
            al_clear_to_color(al_map_rgb(0, 0, 0));
            al_draw_text(font, al_map_rgb(255, 255, 255), 0, 0, 0, "Hello world!");
            al_flip_display();

            redraw = false;
        }
    }

    al_destroy_font(font);
    al_destroy_display(disp);
    al_destroy_timer(timer);
    al_destroy_event_queue(queue);

    return 0;
}

Set-up

Create a new directory hello for this project and put hello.c in it.

Start VScode and open the directory - don't just open hello.c as this will not enable the project features properly.

Then, open hello.c by clicking the file list at the left.

At this point, VScode may ask to install the C/C++ tools. Accept this, which may take a while but only needs doing once.

The next step is to create the Makefile. Create a new file using VScode, and add these contents.

CFLAGS:=`pkg-config --cflags allegro-5 allegro_main-5 allegro_font-5` -Os -W
LDLIBS:=`pkg-config --libs allegro-5 allegro_main-5 allegro_font-5`
all: hello

Again, this assumes that you understand makefiles.

Building

Now, in VScode, choose the "Terminal" menu and "Configure Tasks..."

Select "Create tasks.json file from template" and then "Others"

Edit the "label" and "command" parts of tasks.json so it looks like this:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build program",
            "type": "shell",
            "command": "make all"
        }
    ]
}

To build the program, choose the "Terminal" menu and then "Run Build Task". From the list of tasks, choose "Build program" (the choices are all the labelled tasks in tasks.json). If this is the first time, the task will be configured but won't actually run, so choose "Run Build Task" again and "Build Program".

The program should now compile and link with output from the compiler visible in the terminal at the bottom of the VScode window.

Running and Debugging

Next, to run and debug the program, select the "Run" menu and "Add configuration...". Choose C++ GDB. Edit the launch.json file as follows:

launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "preLaunchTask": "${defaultBuildTask}",
            "name": "Debug Program",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/hello",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "environment": [],
            "externalConsole": false,
            "MIMode": "gdb",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ]
        }
    ]
}

Specifically, change the "program" entry to "${workspaceFolder}/hello". I find it useful to add "preLaunchTask": "${defaultBuildTask}" - this will make sure that your program is up-to-date before running it.

Now you can run/debug the program from the "Run" menu or the Debug pane on the left. If you want to set breakpoints in your program, you have to ensure debugging info is available in the executable. Add -g to the CFLAGS in the Makefile and consider changing -Os to -O0. Otherwise, your breakpoints will never be hit.

VScode with CMake

This is actually easier because VScode has good support for CMake, provided as an extension.

If a project already has a CMakeLists.txt, then VScode will automatically run the configuration stage when you first open the directory, and a list of targets will appear in the CMake view on the left (looks like a rectangle with a triangle in it.)

To start a new CMake project, a minimal CMakeLists.txt would be:

cmake_minimum_required(VERSION 3.12)

find_package(PkgConfig)

pkg_check_modules(ALLEGRO5 REQUIRED allegro-5 allegro_main-5)

project(AllegroProject) 

add_executable(AllegroTest main.c) 
target_include_directories(AllegroTest PUBLIC ${ALLEGRO5_INCLUDE_DIRS})
target_compile_options(AllegroTest PUBLIC ${ALLEGRO5_CFLAGS_OTHER})
target_link_libraries(AllegroTest ${ALLEGRO5_LIBRARIES})
target_link_directories(AllegroTest PUBLIC ${ALLEGRO5_LIBRARY_DIRS})

The name of the project is AllegroProject set by the project line. The name of the executable is AllegroTest and this can be changed on the add_executable line and the ones following. The source files that make up the exe should be listed on the add_executable line. The Allegro library, main library and any add-ons are listed on the pkg_check_module line.

Note this requires a working pkg-config, which may not be the case on Windows.