Skip to content

Latest commit

 

History

History
240 lines (162 loc) · 11.6 KB

using_libraries_pacman.md

File metadata and controls

240 lines (162 loc) · 11.6 KB

How to install libraries in MSYS2's pacman?

Check if the library exists in MSYS2's pacman

Use pacman -Ss ... to search through MSYS2 "packages" (things you can install). Try pacman -Ss openal to search for OpenAL. It'll print the list of matching packages.

⚠ NOTE: As before, we're looking only for things named mingw-w64-clang-x86_64-.... But if you haven't followed the rest of this tutorial when installing MSYS2, and are instead coming in with an existing MSYS2 installation, you might need to use a different name prefix. In that case, consult this for more details.

If you scroll through the list, you'll quickly find this:

clang64/mingw-w64-clang-x86_64-openal 1.23.1-2
    OpenAL audio library for use with opengl (mingw-w64)

If you can't find your library, it means MSYS2 maintainers didn't add it, and you have to compile it yourself.

Install the library in MSYS2

Install the library using the name you found above. In our case:

pacman -S mingw-w64-clang-x86_64-openal

Again, make sure the libraries you install are prefixed with mingw-w64-clang-x86_64-....

Look at what you have installed

After you installed the library using pacman -S ..., use pacman -Ql ... to list the installed files, e.g. pacman -Ql mingw-w64-clang-x86_64-openal in our case.

You should see a list of files:

openal package contents

Here /clang64/... refers to the C:\msys64\clang64\ directory. You could open that directory and look at the files yourself.

As you can see, you get headers (.h files), the compiled library (.dll, .a, .dll.a on MinGW; or .so, .a on Linux; or .dll, .lib on MSVC), the .pc file (see below), and some other things.

We're particularly interested in the .pc file. It describes the compiler flags needed to use this library. If it's missing, you have to guess the flags.

Figure out the required compiler flags

Try to compile a small test program using this library. (Find one for your library in its manual.)

Here's a small program using OpenAL that does nothing:

#include <alc.h>

int main()
{
    alcOpenDevice(nullptr);
}

If you just try to compile it using clang++ prog.cpp, you'll get errors. (Try it.) You need to add some compiler flags.

Determining compiler flags using pkg-config

IF the .pc file exists, we'll use it to figure out the correct compiler flags. For libraries that don't provide it, see below.

First, you need to install pkg-config, which is the program that reads those files:

pacman -S mingw-w64-clang-x86_64-pkgconf

(There's also mingw-w64-clang-x86_64-pkg-config. Both install a program called pkg-config, but ...-pkgconf is a more modern rewrite of the same thing.)

Run it to get the flags: pkg-config --libs --cflags openal.

NOTE: The library name (openal here) matches the name of the .pc file (openal.pc). You can also use pkg-config --list-all to list all libraries known to pkg-config (all installed .pc files).

(If you compile and link separately, you can use pkg-config --cflags openal and pkg-config --libs openal to get compiler flags and linker flags separately.)

You should see output like this:

-IC:/msys64/clang64/include/AL -lopenal

Now try using those flags when compiling the test program above:

clang++ prog.cpp -IC:/msys64/clang64/include/AL -lopenal

If everything is done correctly, it should compile without any errors.

⚠ NOTE: You might see red squiggles in VSCode, this isn't a problem. Configuring VSC to understand the library is a separate issue. For now just compile in the terminal, I'll explain this later.

NOTE: While most compiler flags are order-independent, in some cases it might be important to have -l... to the right of any .cpp/.c/.o files. (If you're using the LD linker as opposed to LLD.)

NOTE: To avoid having to paste the flags manually, you can run the compiler this way: clang++ prog.cpp $(pkg-config --libs --cflags openal) (if using Powershell, use $(...).Split() instead of just $(...)).

If you're curious, here's a full program that plays a short beep using OpenAL. Try running it. For now, you don't have to understand it.

Code
#include <al.h>
#include <alc.h>

#include <chrono>
#include <iostream>
#include <thread>

int main()
{
    ALCdevice *device = alcOpenDevice(nullptr);
    if (!device) {std::cout << "Can't open device!\n"; return 1;}

    ALCcontext *context = alcCreateContext(device, nullptr);
    if (!context) {std::cout << "Can't create context!\n"; return 1;}
    if (!alcMakeContextCurrent(context)) {std::cout << "Can't create make the context current!\n"; return 1;}

    ALuint buffer;
    alGenBuffers(1, &buffer);
    if (!buffer) {std::cout << "Can't create a buffer!\n"; return 1;}

    short sine[24000];
    for (int i = 0; i < 24000; i++)
        sine[i] = short(std::sin(i / 50.) * 32767);
    alBufferData(buffer, AL_FORMAT_MONO16, sine, sizeof sine, 48000);

    ALuint source;
    alGenSources(1, &source);
    if (!source) {std::cout << "Can't create a source!\n"; return 1;}
    alSourcei(source, AL_BUFFER, buffer);

    alSourcePlay(source);

    while (true)
    {
        int state;
        alGetSourcei(source, AL_SOURCE_STATE, &state);
        if (state != AL_PLAYING)
            break;
        std::cout << ".";
        std::this_thread::sleep_for(std::chrono::milliseconds(1));
    }
    std::cout << "\nBye!\n";
}

Guessing the compiler flags

If a library doesn't have a .pc file, or if you want to practice, you can guess the correct compiler flags yourself.

Step 1: Make sure #include works

Try including your library. Start with a simple program like this one:

#include <alc.h>

int main() {}

(Replace the header name with the one for your library. Look at what headers it installs.)

If you compile this without any flags (clang++ prog.cpp), you can get an error:

prog.cpp:1:10: fatal error: 'alc.h' file not found
    1 | #include <alc.h>
      |          ^~~~~~~
1 error generated.

For some libraries it will just work out of the box, then you can immediately go to the next step.

For OpenAL it doesn't work, because the compiler looks for headers in C:\msys64\clang64\include, while alc.h is installed into C:\msys64\clang64\include\AL (as you can see above).

At this point you have two options. You either:

  1. Tell the compiler to look in this directory as well: -IC:/msys64/clang64/include/AL,

    OR

  2. You add the directory name to #include: #include <AL/alc.h>

For some libraries both approaches work. Some are picky. In any case, read the manual to know how the library prefers you to spell the header ("<alc.h>" in our case, or pkgconf wouldn't have printed -I...), spell it that way, and add -I as needed to make it work.

Try compiling the test program again, now with -I..., and it should compile successfully:

#include <alc.h>

int main() {}
clang++ prog.cpp -IC:/msys64/clang64/include/AL

The -I flag can also be replaced with -isystem (e.g. -isystemC:/msys64/clang64/include/AL). This additionally disables warnings coming from those headers, which is a good thing (they are useful only for the developers of those libraries, not for you).

Step 2: Make sure calling functions works

The previous step alone isn't enough. If you now try to call any function from this library, you'll see a different error:

#include <alc.h>

int main()
{
    alcOpenDevice(nullptr);
}
clang++ prog.cpp -IC:/msys64/clang64/include/AL
ld.lld: error: undefined symbol: __declspec(dllimport) alcOpenDevice
>>> referenced by C:/msys64/tmp/1-f8cdc7.o:(main)
clang++: error: linker command failed with exit code 1 (use -v to see invocation)

If you don't get any errors, the library is likely header-only, and you can skip this step.

This error happens because the function definitions are in .a/.dll files (see above), and you need to point your compiler to them (or your linker, rather).

You need to use either the .dll (dynamic linking; this would be .so on Linux) OR .a (static linking). If you link dynamically, your executable will need a copy of the .dll to run (for more information, read What is a DLL?, Why do DLLs exist?, and Static linking).

Use one of the two options:

  1. Link dynamically

    This will use the lib__.dll.a file (or directly .so on Linux). If you only have .a and not .dll.a, use option (2) instead.

    Given lib__.dll.a, pass the __ part of its name to the -l... flag. (E.g. given libopenal.dll.a, use -lopenal.)

    .dll.a is an "import library". It's a tiny file that doesn't contain the function definitions, but will silence the undefined symbol errors and cause your application to load the respective .dll when started, which does contain the definitions. (Import libraries are not a thing on Linux, where you directly link against .sos. Modern MinGW can similarly link .dlls directly, but the import libraries are still commonly used. MSVC requires the use of import libraries, which are named .lib there, same as static libraries, so there can be some confusion between the two on MSVC.)

    Since all .dll.a/.a files are installed to the same directory (C:\msys64\clang64\lib), you normally don't need to manually specify their location. But -L... lets you do that if needed (like -I... for headers).

  2. Link statically

    This will use the lib__.a file. Use this option if this library has no .dll.a, or if you intentionally want to link statically.

    Given lib__.a, pass the __ part of its name to the -l... flag. (E.g. given libopenal.a, use -lopenal.)

    This embeds the library into the executable (so it can run without the .dll, but your users also can't update the library themselves).

    In most libraries you'll notice that .dll.a and .a have the same name, so how does -l select which one to use? (How does -lopenal pick between libopenal.dll.a vs libopenal.a?) It prefers .dll.a by default if it exists. Passing -static makes it prefer .a for all libraries, including the implicitly linked standard libraries. (It's also possible to configure it per library: use -Bstatic to link all subsequent libraries statically, and -Bdynamic to switch back to linking them dynamically.)

Adding the -l... flag should fix the error. Run the resulting application to confirm that everything works.

For any problems at runtime, consult Debugging DLL issues. You also need to read that if you're planning to distribute the application to other people.

If you want to know how to compile libraries manually, proceed to here.