At some point you'll probably want to include some data or resources into the executable itself (e.g. fonts, images etc). This is particularly true for my case, as I'm trying to keep to a portable single-executable model. That means that I can't keep resources in a surrounding folder and load at runtime, and I don't want to assume that the user already happens to have the files on their system.

Icons are one example of a useful resource that takes an application from looking amateurish to looking like a Real Product (tm).

This post will show some cross-platform methods of adding resources to your application, and a Windows-only method, with icons as an example.

Contents

Intro

Compiled resources (platform-independent)

xxd

GIMP

Linking (Windows-specific)

Linking icons as resources

RC file text

RC to RES

Linking the RES to your executable

Resource access from code

Using icons

Concluding thoughts

Intro

You can divide methods of including resources in your application into 3 groups based on when they are attached, each with an analogous form for adding libraries:

Runtime [.dll/.so files] - loaded with fopen and that family of functions.
I won't be going into this here as there are tutorials for them all over the internet and it's not relevant to my use case.

Linked [.lib/.a files] - processed and added by the linker, these have to be 'found' in the executable at runtime.

Compiled [files added with #include] - added to source code, commonly as an array of bytes in a header.

Inherent in linking resources to your executable is that it will get larger. The resources that I'm using in an editor are few and small, and as such, the pros of portability and simplicity win out. If you're making a game with large textures and audio files, the trade-off may not be so appealing.

The ease of modding resources in a folder layout is also something that might be more appreciated for a game.

Compiled resources (platform-independent)

Adding resources via an array in a header file is the simplest in terms of runtime use: they can be accessed like any normal variable/array. As such, this is my preferred method unless there are major reasons to go a different way.

xxd

xxd is a command-line utility for interacting with binary files, primarily converting to and from hex data. It's normally a unix application, but it also comes bundled with the Windows version of Vim, which is handy for me... (You can access it directly through Vim with :!xxd ... or find it in the application's folder.)

The default output of xxd is what you see in a hex viewer, and is actually what I was using in my last blog post to validate my file format:

1

xxd test.geo

Hey, this is just a bunch of hexadecimal numbers; you can format numbers like this in normal C code by slapping "0x" at the front:

1

char Fifteen = 0x0F;

Why not just make an array of these and add them to the code?

Helpfully for our purposes, xxd has an option to format its output for an include file:

1

xxd -i test.geo test_geo.h

My test.geo file has changed since the hex dump image above, but here's a look at the current version.

Note that the size on disc of your h file will be about 6 times larger than the file you're including - you're using 6 bytes to encode a single one: "0x47, ". I tend to search and replace to remove the spaces, making it about 5x the orginal filesize. This shouldn't be a problem unless you're really strapped for space on your development machine. It won't affect the executable size.

I currently do this with a font. In one of my earlier releases I forgot that I was loading the font from disc at runtime, so the first feedback I got was that it was crashing on opening... not great!

If you change the data contents of your files frequently, they can be converted to C headers as part of your build process (before you compile).

If you don't want to get xxd for whatever reason, there are alternatives out there, or you can make your own, which you can do pretty quickly.

GIMP

(Examples are from GIMP 2.8)

While xxd outputs generic bytes from any old file type, if you want to easily include some images, GIMP has a nice feature where it will let you export C source code/headers in RGB(A). This is the basic format:

There are quite a few options, including basic run-length encoding, which dramatically decreases the size of images with blocks of colour. This also includes a macro for reading the RLE data.

You can trade off a significant reduction in executable size with a slightly easier file to read. Have a play around with the various settings and see what you get.

Linking (Windows-specific)

The other option we're exploring here is for the linker to bundle the file into the executable. Once it's there, we need a way to find it at runtime. On Windows, this is done using the 'Resource' API/system. The simplified process for this is:

Notate the files you want included in a .rc text file

'Compile' the .rc file to a .res file

Link the .res file in with your program

Access the resource data in your code

Use the data

I'll work through this with icons as an example. It seems as though you have to include icons with this method to get them to show up everywhere you want.

Linking icons as resources

I'll assume here that you have an icon. If not, you can create and export .ico files with GIMP.

RC file text

These have a pretty simple format: the name of the resource (as you'll access it in the code), the type, and the relative file location.

1
2

Icon ICON "G_32.ico"
IconSmall ICON "G_16.ico"

There are a number of types, including a generic/custom data format.

RC to RES

This just involves running the rc executable on the RC file. (The nologo flag just stops it from spitting out copyright information).

1

rc -nologo geometer.rc

This outputs geometer.res. If you're doing this from the command line then as with cl, you have to run the vcvarsall.bat in the shell before you run rc:

I've shown how I include data in my executables on Windows and with a platform-independent method. I default to using the platform-independent method unless there's a good reason to use something else (like the special treatment icons get as 'Resources'). Other people I know just put everything in the resource files as they're only/primarily targeting Windows, and the RC files keeps everything in one place. There doesn't seem to be much difference in speed at compile- or run-time.

Please do let me know if you attach files to your executable with these methods or if you have any related tips to share.

insofaras If you are using the GNU ld linker, there is another way to turn any file into a .o object file that you can then link with the rest of your code...

Very cool, I wasn't aware of that. Thanks for sharing!

I'm probably being dim, but why do you need 2 arrays? Or is the second just acting as a sentinel pointer? If that's the case I assume that size is redundant... otherwise how come you don't need to define a symbol for that?

I'm probably being dim, but why do you need 2 arrays? Or is the second just acting as a sentinel pointer? If that's the case I assume that size is redundant... otherwise how come you don't need to define a symbol for that?

The _end array is just pointing one past the end of the data, so you can use it interchangeably with the _size symbol depending on what you prefer.

I think I also ran into an issue with the _size symbol in position-independent (PIE) ELFs since it is declared as absolute (A) but was getting relocated for some reason so the size was way out. That's why I ended up manually calculating the size based on the _start and _end in cgiquotes.