Skip to content

Quickstart

pinguxx28 edited this page Jan 12, 2022 · 69 revisions
Clone this wiki locally

Read on to get up-and-running with Allegro quickly.

It's assumed that you already have some knowledge of C or C++, and have a compiler installed - if not, see Learning C and C++.

Installation

Installing Allegro as a binary package is the easiest method for most operating systems.

Choose your weapon:

Linux

Ubuntu 18.04+ (or derivatives thereof)

First, add the Allegro PPA. This gives you up-to-date versions of Allegro; the base repos only provide 5.2.3 at the time of writing.

sudo add-apt-repository ppa:allegro/5.2

Then, install Allegro:

sudo apt-get install liballegro*5.2 liballegro*5-dev

Debian-based distributions (Debian, Mint, Ubuntu, etc..)

sudo apt-get install liballegro-ttf5-dev

Fedora

sudo dnf install allegro5*

Others

Binary packages may be available for your distro; feel free to add them here if so.

Otherwise, select "Something else" below.

OSX

Install with Homebrew

brew install allegro

You will also need to install pkg-config, if it is not already installed.

brew install pkg-config
Windows

Visual Studio 2015+

Install per-project using NuGet in PowerShell:

cd MyProjectDir\
Install-Package Allegro

Or, just install from within Visual Studio.

MinGW (via MSYS2)

  • Go to the Allegro releases page and find the most recent Allegro 5 version.
    • There are a few options for MinGW - but for those new to Allegro, we recommend downloading the x86_64 dynamic package.
    • This will be named - e.g. for v5.2.6 - allegro-x86_64-w64-mingw32-gcc-9.2.0-posix-seh-dynamic-5.2.6.0.zip.
  • Extract the relevant directories into your MinGW install's include & library paths:
    • Find out where you installed MinGW (C:\msys64 is the default).
    • The .zip contains three directories under allegro\: bin\ include\ lib\.
    • Extract the files from each to e.g. C:\msys64\mingw64\bin, C:\msys64\mingw64\include, C:\msys64\mingw64\lib respectively.
Android


Using Allegro for mobile apps is a bit trickier. We recommend building a desktop program first.

See the Maven repository.

iOS


Using Allegro for mobile apps is a bit trickier. We recommend building a desktop program first.

See the iOS README.

TODO: Adapt from this.

Something else

Install from source

If you're running another OS or want to do something that's not possible with the provided binary packages (eg. static linking often isn't trivial with them), you'll need to build Allegro from source.


If you're having problems installing, refer to the in-depth instructions.

Hello World

Once you've installed Allegro, you can check that it compiles into a simple program.

Screenshot of a black window with "Hello world!" shown in white in the top-left corner

The program will just display the above window and exit when any key is pressed.

Create hello.c with the below code:

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;
}

Compile and run

Linux

gcc hello.c -o hello $(pkg-config allegro-5 allegro_font-5 --libs --cflags)
./hello

Windows (MinGW)

Note that on Windows, a terminal window will also appear when you run your program. This is useful for debugging, but can be disabled by using the -mwindows flag when compiling.

gcc hello.c -o hello.exe -lallegro -lallegro_font
hello.exe

macOS

gcc hello.c -o hello $(pkg-config allegro-5 allegro_main-5 allegro_font-5 --libs --cflags)
./hello

See Creating-macOS-bundles for how to distribute your game as an OSX bundle.

Windows (Visual Studio)

Configure Allegro for your project and then simply compile and run as normal.

What next?

Congratulations - you've got a working program! (hopefully.)

Next, read Allegro Vivace for a proper tutorial.

Or, dive straight into the reference manual.