The Allegro Wiki is migrating to github at https://github.com/liballeg/allegro_wiki/wiki

Compiling Allegro Programs

From Allegro Wiki
Jump to: navigation, search


FIXME: I'm not familiar with how to build 4.4.x or 5.x.y programs in Windows so somebody else fill that in.

GNU/Linux

n00b Introduction (Skip If Not New)

The most popular C/C++ toolchain for GNU/Linux is the GNU Compiler Collection (GCC). You generally use the 'gcc' command to compile and link C programs and the 'g++' command to compile and link C++ programs. See the man or info documentation by typing 'man <command>' or 'info <command>' into a terminal. You can also look up their documentation online.

The basic command to compile a C or C++ program is:

   gcc main.c

OR

   g++ main.cpp

Since you didn't specify what to call the output GCC defaults to 'a.out'. You could then run the program by executing that command.

   ./a.out

That's not very pretty and it's rather ambiguous so you'll probably want to specify the name of the output. You can do that with the -o option.

   gcc -o myprogram main.c

OR

   g++ -o myprogram main.cpp

Header files are typically located in standardized directories within the file system (e.g., /usr/include). Some are system-wide and others are toolchain specific. You may opt to store your program-specific header files in a directory also. For example, within the root directory of your project, you might have an 'include' directory containing all of your header files. You probably don't want to have to #include "include/foo.h". Instead, you'd prefer to just #include "foo.h". Use the -I option for that. For example:

   gcc -Iinclude -o myprogram main.c

OR

   g++ -Iinclude -o myprogram main.cpp

Finally, library files are also typically stored in standardized directories within the file system (e.g., /lib or /usr/lib). The paths for these are typically stored in /etc/ld.so.conf and/or /etc/ld.so.conf.d. A system-wide cache is kept of libraries to speed up finding and loading them (at runtime, shared object files need to be found and linked). This same cache is used when initially linking programs into a final executable. The /sbin/ldconfig program is used to update this cache. Typically only root can write to /etc, where the configuration, or /var, where the cache is stored. Other users that need to specify extra directories for libraries can specify them using the -L option. For example, perhaps you build your own libraries and store them in a 'lib' directory within your project root. You could then specify for the linker to search that directory (after system directories) like so:

   gcc -Iinclude -o myprogram main.cpp -Llib

OR

   g++ -Iinclude -o myprogram main.cpp -Llib

Finally, you need to actually specify the exact libraries that you want to link to. These can be statically-linked (.a) or dynamically-linked (.so). The difference is that statically-linked libraries are actually baked into your program at link-time. You don't need to distribute a copy of the library anymore because it is actually copied into your program. A dynamically-linked library is not. Instead, when you run your program the linker is run and dynamically links your program to the dynamic library. Each has its own pros and cons. To link a library you specify it with the -l option. Libraries are typically named libfoo.a or libbar.so.<version>. You only need to specify the 'foo' or 'bar' parts. The linker is smart enough to figure out the rest. For example:

   gcc -Iinclude -o myprogram main.cpp -Llib -lfoo -lbar

OR

   g++ -Iinclude -o myprogram main.cpp -Llib -lfoo -lbar

With all of that aside, it can be rather tedious to manage all of these options yourself, especially when different libraries require different ones.

When it comes to Allegro you typically want to invoke a subshell with an appropriate command to list the compiler and linker options for you. A subshell is typically invoked with either backtick (`) delimiters or a dollar-sign ($) followed by parenthesis-delimiters. The subshell will be substituted with its output before the outer command is executed. For example:

   gcc -Iinclude -o myprogram `allegro-config --cflags --libs`
   

OR

   gcc -Iinclude -o myprogram $(allegro-config --cflags --libs)

'allegro-config' will be explained in a bit. If I test that out on my current machine (running Fedora 15 amd64 AKA x86_64) this is what it evaluates to:

   gcc -Iinclude -o myprogram -I/usr/include -L/usr/lib64 -Wl,--export-dynamic -lalleg-4.2.3 -lalleg_unsharable

As you can see, it saves you a bit of typing (and perhaps a bit of memorization). It can also take care of certain peculiarities with the installation of Allegro. See below for the specific helper command and options for each recent version of Allegro.

As one final note, it is generally a good idea to use the -Wall option with GCC so that it warns you about probable mistakes you've made.

   gcc -Wall -Iinclude -o myprogram `allegro-config --cflags --libs`

Allegro 4.2.x

Use allegro-config. Example:

   gcc -Wall main.c `allegro-config --cflags --libs`

Allegro 4.4.x

Use pkg-config. If the pkg-config command isn't on your system then you should be able to install it with your package manager. Search for it. Example:

   gcc -Wall main.c `pkg-config --cflags --libs allegrogl allegro jpgalleg loadpng logg`

You only need to list the libraries that you actually use. Only the 'allegro' one is required for all Allegro programs. The others are optional depending on the addons that you use.

Allegro 5.x.y

Use pkg-config. Example:

   gcc -Wall main.c `pkg-config --cflags --libs allegro-5.0 allegro_acodec-5.0 allegro_audio-5.0 allegro_color-5.0 allegro_dialog-5.0 allegro_font-5.0 allegro_image-5.0 allegro_main-5.0 allegro_memfile-5.0 allegro_physfs-5.0 allegro_primitives-5.0 allegro_ttf-5.0`

Again, you only need to list the libraries that you actually use. Again, only 'allegro-5.0' is required for all Allegro programs. The others are optional depending on the addons that you use.


Note that the unstable branch is the default install from source if pulled using git. In this case, simply change each '5.0' to '5.1' as in:

   gcc -Wall main.c `pkg-config --cflags --libs allegro-5.1 allegro_acodec-5.1 allegro_audio-5.1  \
   allegro_color-5.1 allegro_dialog-5.1 allegro_font-5.1 allegro_image-5.1 allegro_main-5.1 \ 
   allegro_memfile-5.1 allegro_physfs-5.1 allegro_primitives-5.1 allegro_ttf-5.1`

Depending on your install, configuration, and what you use in your program, you may want to add or remove packages and flags from this generic example. If you encounter errors, such as missing libraries, see if rebuilding with the monolith option and then link using:

   `pkg-config --cflags --libs allegro_monolith-5.1`

Windows

You can use a number of toolchains in Windows. The most popular are probably MinGW and Microsoft Visual C++ (Express Edition is free [as in beer]). If you don't know what you want to use then I would recommend MinGW. It seems a majority of community members use this in Windows which will mean that there is more help available for you if you have trouble. In addition to the core toolchain you can also use a variety of IDEs with them. Obviously, Microsoft Visual Studio is the most popular IDE to use with Microsoft Visual C++. I think the most popular IDE used with MinGW is Code::Blocks.

MinGW / Command Line

See the instructions above for compiling in GNU/Linux. The GCC toolchain is used in MinGW and is mostly the same as in Linux.

pkg-config is available in the MSYS2 project (Not sure about allegro-config).