incbin.h File Reference

Utility for including binary files. More...

#include <limits.h>

Include dependency graph for incbin.h:

Go to the source code of this file.

Macros
#define	INCBIN_ALIGNMENT_INDEX   3
#define	INCBIN_ALIGN_SHIFT_0   1
#define	INCBIN_ALIGN_SHIFT_1   2
#define	INCBIN_ALIGN_SHIFT_2   4
#define	INCBIN_ALIGN_SHIFT_3   8
#define	INCBIN_ALIGN_SHIFT_4   16
#define	INCBIN_ALIGN_SHIFT_5   32
#define	INCBIN_ALIGN_SHIFT_6   64
#define	INCBIN_ALIGNMENT
#define	INCBIN_STR(X)    #X
#define	INCBIN_STRINGIZE(X)    INCBIN_STR(X)
#define	INCBIN_CAT(X, Y)    X ## Y
#define	INCBIN_CONCATENATE(X, Y)    INCBIN_CAT(X, Y)
#define	INCBIN_EVAL(X)    X
#define	INCBIN_INVOKE(N, ...)    INCBIN_EVAL(N(__VA_ARGS__))
#define	INCBIN_MACRO   ".incbin"
#define	INCBIN_ALIGN    __attribute__((aligned(INCBIN_ALIGNMENT)))
#define	INCBIN_ALIGN_HOST   ".align " INCBIN_STRINGIZE(INCBIN_ALIGNMENT) "\n"
#define	INCBIN_ALIGN_BYTE   ".align 1\n"
#define	INCBIN_EXTERNAL   extern
#define	INCBIN_CONST   const
#define	INCBIN_OUTPUT_SECTION   ".rodata"
	Optionally override the linker section into which data is emitted.
#define	INCBIN_SECTION   ".section " INCBIN_OUTPUT_SECTION "\n"
#define	INCBIN_GLOBAL(NAME)   ".global " INCBIN_STRINGIZE(INCBIN_PREFIX) #NAME "\n"
#define	INCBIN_INT   ".int "
#define	INCBIN_MANGLE   ""
#define	INCBIN_TYPE(NAME)   ".type " INCBIN_STRINGIZE(INCBIN_PREFIX) #NAME ", @object\n"
#define	INCBIN_BYTE   ".byte "
#define	INCBIN_STYLE_CAMEL   0
#define	INCBIN_STYLE_SNAKE   1
#define	INCBIN_PREFIX   g
	Specify the prefix to use for symbol names.
#define	INCBIN_STYLE   INCBIN_STYLE_CAMEL
	Specify the style used for symbol names.
#define	INCBIN_STYLE_0_DATA   Data
#define	INCBIN_STYLE_0_END   End
#define	INCBIN_STYLE_0_SIZE   Size
#define	INCBIN_STYLE_1_DATA   _data
#define	INCBIN_STYLE_1_END   _end
#define	INCBIN_STYLE_1_SIZE   _size
#define	INCBIN_STYLE_IDENT(TYPE)
#define	INCBIN_STYLE_STRING(TYPE)
#define	INCBIN_GLOBAL_LABELS(NAME, TYPE)
#define	INCBIN_EXTERN(NAME)
	Externally reference binary data included in another translation unit.
#define	INCBIN(NAME, FILENAME)
	Include a binary file into the current translation unit.

Detailed Description

Utility for including binary files.

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information, please refer to http://unlicense.org/

Author

Dale Weiler

Facilities for including binary files into the current translation unit and making use from them externally in other translation units.

Macro Definition Documentation

INCBIN

#define INCBIN	(		NAME,
			FILENAME
	)

Value:

    __asm__(INCBIN_SECTION \
            INCBIN_GLOBAL_LABELS(NAME, DATA) \
            INCBIN_ALIGN_HOST \
            INCBIN_MANGLE INCBIN_STRINGIZE(INCBIN_PREFIX) #NAME INCBIN_STYLE_STRING(DATA) ":\n" \
            INCBIN_MACRO " \"" FILENAME "\"\n" \
            INCBIN_GLOBAL_LABELS(NAME, END) \
            INCBIN_ALIGN_BYTE \
            INCBIN_MANGLE INCBIN_STRINGIZE(INCBIN_PREFIX) #NAME INCBIN_STYLE_STRING(END) ":\n" \
                INCBIN_BYTE "1\n" \
            INCBIN_GLOBAL_LABELS(NAME, SIZE) \
            INCBIN_ALIGN_HOST \
            INCBIN_MANGLE INCBIN_STRINGIZE(INCBIN_PREFIX) #NAME INCBIN_STYLE_STRING(SIZE) ":\n" \
                INCBIN_INT INCBIN_MANGLE INCBIN_STRINGIZE(INCBIN_PREFIX) #NAME INCBIN_STYLE_STRING(END) " - " \
                           INCBIN_MANGLE INCBIN_STRINGIZE(INCBIN_PREFIX) #NAME INCBIN_STYLE_STRING(DATA) "\n" \
            INCBIN_ALIGN_HOST \
            ".text\n" \
    ); \
    INCBIN_EXTERN(NAME)

Include a binary file into the current translation unit.

Includes a binary file into the current translation unit, producing three symbols for objects that encode the data and size respectively.

The symbol names are a concatenation of ‘INCBIN_PREFIX’ before NAME; with "Data", as well as "End" and "Size" after. An example is provided below.

Parameters

NAME	The name to associate with this binary data (as an identifier.)
FILENAME	The file to include (as a string literal.)

INCBIN(Icon, "icon.png");
 
// Now you have the following symbols:
// const unsigned char <prefix>IconData[];
// const unsigned char *const <prefix>IconEnd;
// const unsigned int <prefix>IconSize;

Warning

This must be used in global scope

The identifiers may be different if INCBIN_STYLE is not default

To externally reference the data included by this in another translation unit please

See also

INCBIN_EXTERN.

INCBIN_ALIGNMENT

#define INCBIN_ALIGNMENT

Value:

    INCBIN_CONCATENATE( \
        INCBIN_CONCATENATE(INCBIN_ALIGN_SHIFT, _), \
        INCBIN_ALIGNMENT_INDEX)

INCBIN_EXTERN

#define INCBIN_EXTERN

(

NAME

)

Value:

    INCBIN_EXTERNAL const INCBIN_ALIGN unsigned char \
        INCBIN_CONCATENATE( \
            INCBIN_CONCATENATE(INCBIN_PREFIX, NAME), \
            INCBIN_STYLE_IDENT(DATA))[]; \
    INCBIN_EXTERNAL const INCBIN_ALIGN unsigned char *const \
    INCBIN_CONCATENATE( \
        INCBIN_CONCATENATE(INCBIN_PREFIX, NAME), \
        INCBIN_STYLE_IDENT(END)); \
    INCBIN_EXTERNAL const unsigned int \
        INCBIN_CONCATENATE( \
            INCBIN_CONCATENATE(INCBIN_PREFIX, NAME), \
            INCBIN_STYLE_IDENT(SIZE))

Externally reference binary data included in another translation unit.

Produces three external symbols that reference the binary data included in another translation unit.

The symbol names are a concatenation of ‘INCBIN_PREFIX’ before NAME; with "Data", as well as "End" and "Size" after. An example is provided below.

Parameters

NAME	The name given for the binary data

INCBIN_EXTERN(Foo);
 
// Now you have the following symbols:
// extern const unsigned char <prefix>FooData[];
// extern const unsigned char *const <prefix>FooEnd;
// extern const unsigned int <prefix>FooSize;

INCBIN_GLOBAL_LABELS

#define INCBIN_GLOBAL_LABELS	(		NAME,
			TYPE
	)

Value:

    INCBIN_INVOKE( \
        INCBIN_GLOBAL, \
        INCBIN_CONCATENATE( \
            NAME, \
            INCBIN_INVOKE( \
                INCBIN_STYLE_IDENT, \
                TYPE))) \
    INCBIN_INVOKE( \
        INCBIN_TYPE, \
        INCBIN_CONCATENATE( \
            NAME, \
            INCBIN_INVOKE( \
                INCBIN_STYLE_IDENT, \
                TYPE)))

INCBIN_OUTPUT_SECTION

#define INCBIN_OUTPUT_SECTION   ".rodata"

Optionally override the linker section into which data is emitted.

Warning

If you use this facility, you'll have to deal with platform-specific linker output section naming on your own

Overriding the default linker output section, e.g for esp8266/Arduino:

#define INCBIN_OUTPUT_SECTION ".irom.text"
#include "incbin.h"
INCBIN(Foo, "foo.txt");
// Data is emitted into program memory that never gets copied to RAM

INCBIN_PREFIX

#define INCBIN_PREFIX   g

Specify the prefix to use for symbol names.

By default this is ‘g’, producing symbols of the form:

#include "incbin.h"
INCBIN(Foo, "foo.txt");
 
// Now you have the following symbols:
// const unsigned char gFooData[];
// const unsigned char *const gFooEnd;
// const unsigned int gFooSize;

If however you specify a prefix before including: e.g:

#define INCBIN_PREFIX incbin
#include "incbin.h"
INCBIN(Foo, "foo.txt");
 
// Now you have the following symbols instead:
// const unsigned char incbinFooData[];
// const unsigned char *const incbinFooEnd;
// const unsigned int incbinFooSize;

INCBIN_STYLE

#define INCBIN_STYLE   INCBIN_STYLE_CAMEL

Specify the style used for symbol names.

Possible options are

• INCBIN_STYLE_CAMEL "CamelCase"
• INCBIN_STYLE_SNAKE "snake_case"

Default option is INCBIN_STYLE_CAMEL producing symbols of the form:

#include "incbin.h"
INCBIN(Foo, "foo.txt");
 
// Now you have the following symbols:
// const unsigned char <prefix>FooData[];
// const unsigned char *const <prefix>FooEnd;
// const unsigned int <prefix>FooSize;

If however you specify a style before including: e.g:

#define INCBIN_STYLE INCBIN_STYLE_SNAKE
#include "incbin.h"
INCBIN(foo, "foo.txt");
 
// Now you have the following symbols:
// const unsigned char <prefix>foo_data[];
// const unsigned char *const <prefix>foo_end;
// const unsigned int <prefix>foo_size;

INCBIN_STYLE_IDENT

#define INCBIN_STYLE_IDENT

(

TYPE

)

Value:

    INCBIN_CONCATENATE( \
        INCBIN_STYLE_, \
        INCBIN_CONCATENATE( \
            INCBIN_EVAL(INCBIN_STYLE), \
            INCBIN_CONCATENATE(_, TYPE)))

INCBIN_STYLE_STRING

#define INCBIN_STYLE_STRING

(

TYPE

)

Value:

    INCBIN_STRINGIZE( \
        INCBIN_STYLE_IDENT(TYPE)) \