Skip to content

Commit 41e9c89

Browse files
committed
61
1 parent c7badc3 commit 41e9c89

File tree

11 files changed

+891
-0
lines changed

11 files changed

+891
-0
lines changed

incbin/.travis.yml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
language: c
2+
3+
os:
4+
- linux
5+
- osx
6+
7+
compiler:
8+
- gcc
9+
- clang
10+
11+
script:
12+
- make -C test test

incbin/README.md

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# incbin
2+
3+
Include binary files in your C/C++ applications with ease
4+
5+
## Example
6+
7+
``` c
8+
#include "incbin.h"
9+
10+
INCBIN(Icon, "icon.png");
11+
12+
// This translation unit now has three symbols
13+
// const unsigned char gIconData[];
14+
// const unsigned char *const gIconEnd; // a marker to the end, take the address to get the ending pointer
15+
// const unsigned int gIconSize;
16+
17+
// Reference in other translation units like this
18+
INCBIN_EXTERN(Icon);
19+
20+
// This translation unit now has three extern symbols
21+
// Use `extern "C"` in case of writing C++ code
22+
// extern const unsigned char gIconData[];
23+
// extern const unsigned char *const gIconEnd; // a marker to the end, take the address to get the ending pointer
24+
// extern const unsigned int gIconSize;
25+
```
26+
27+
## Portability
28+
29+
Known to work on the following compilers
30+
31+
* GCC
32+
* Clang
33+
* PathScale
34+
* Intel
35+
* Solaris & Sun Studio
36+
* Green Hills
37+
* SNC (ProDG)
38+
* Diab C++ (WindRiver)
39+
* XCode
40+
* ArmCC
41+
* RealView
42+
* ImageCraft
43+
* Stratus VOS C
44+
* TinyCC
45+
* cparser & libfirm
46+
* LCC
47+
* MSVC _See MSVC below_
48+
49+
If your compiler is not listed, as long as it supports GCC inline assembler, this
50+
should work.
51+
52+
## MISRA
53+
INCBIN can be used in MISRA C setting. However it should be independently checked
54+
due to its use of inline assembly to achieve what it does. Independent verification
55+
of the header has been done several times based on commit: 7e327a28ba5467c4202ec37874beca7084e4b08c
56+
57+
## Alignment
58+
59+
The data included by this tool will be aligned on the architectures word boundary
60+
unless some variant of SIMD is detected, then it's aligned on a byte boundary that
61+
respects SIMD convention just incase your binary data may be used in vectorized
62+
code. The table of the alignments for SIMD this header recognizes is as follows:
63+
64+
| SIMD | Alignment |
65+
|-----------------------------------------|-----------|
66+
| SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2 | 16 |
67+
| Neon | 16 |
68+
| AVX, AVX2 | 32 |
69+
| AVX512 | 64 |
70+
71+
## Prefix
72+
By default, `incbin.h` emits symbols with a `g` prefix. This can be adjusted by
73+
defining `INCBIN_PREFIX` before including `incbin.h` with a desired prefix. For
74+
instance
75+
76+
``` c
77+
#define INCBIN_PREFIX g_
78+
#include "incbin.h"
79+
INCBIN(test, "test.txt");
80+
81+
// This translation unit now has three symbols
82+
// const unsigned char g_testData[];
83+
// const unsigned char *const g_testEnd;
84+
// const unsigned int g_testSize;
85+
```
86+
87+
You can also choose to have no prefix by defining the prefix with nothing, for example:
88+
89+
``` c
90+
#define INCBIN_PREFIX
91+
#include "incbin.h"
92+
INCBIN(test, "test.txt");
93+
94+
// This translation unit now has three symbols
95+
// const unsigned char testData[];
96+
// const unsigned char *const testEnd;
97+
// const unsigned int testSize;
98+
```
99+
100+
## Style
101+
By default, `incbin.h` emits symbols with `CamelCase` style. This can be adjusted
102+
by defining `INCBIN_STYLE` before including `incbin.h` to change the style. There
103+
are two possible styles to choose from
104+
105+
* INCBIN_STYLE_CAMEL (CamelCase)
106+
* INCBIN_STYLE_SNAKE (snake_case)
107+
108+
For instance:
109+
110+
``` c
111+
#define INCBIN_STYLE INCBIN_STYLE_SNAKE
112+
#include "incbin.h"
113+
INCBIN(test, "test.txt");
114+
115+
// This translation unit now has three symbols
116+
// const unsigned char gtest_data[];
117+
// const unsigned char *const gtest_end;
118+
// const unsigned int gtest_size;
119+
```
120+
121+
Combining both the style and prefix allows for you to adjust `incbin.h` to suite
122+
your existing style and practices.
123+
124+
## Overriding Linker Output section
125+
By default, `incbin.h` emits into the read-only linker output section used on
126+
the detected platform. If you need to override this for whatever reason, you
127+
can manually specify the linker output section.
128+
129+
For example, to emit data into program memory for
130+
[esp8266/Arduino](github.com/esp8266/Arduino):
131+
132+
``` c
133+
#define INCBIN_OUTPUT_SECTION ".irom.text"
134+
#include "incbin.h"
135+
INCBIN(Foo, "foo.txt");
136+
// Data is emitted into program memory that never gets copied to RAM
137+
```
138+
139+
## Explanation
140+
141+
`INCBIN` is a macro which uses the inline assembler provided by almost all
142+
compilers to include binary files. It achieves this by utilizing the `.incbin`
143+
directive of the inline assembler. It then uses the assembler to calculate the
144+
size of the included binary and exports two global symbols that can be externally
145+
referenced in other translation units which contain the data and size of the
146+
included binary data respectively.
147+
148+
## MSVC
149+
150+
Supporting MSVC is slightly harder as MSVC lacks an inline assembler which can
151+
include data. To support this we ship a tool which can process source files
152+
containing `INCBIN` macro usage and generate an external source file containing
153+
the data of all of them combined. This file is named `data.c` by default.
154+
Just include it into your build and use the `incbin.h` to reference data as
155+
needed. It's suggested you integrate this tool as part of your projects's
156+
pre-build events so that this can be automated. A more comprehensive list of
157+
options for this tool can be viewed by invoking the tool with `-help`
158+
159+
If you're using a custom prefix, be sure to specify the prefix on the command
160+
line with `-p <prefix>` so that everything matches up; similarly, if you're
161+
using a custom style, be sure to specify the style on the command line with
162+
`-S <style>` as well.
163+
164+
## Miscellaneous
165+
166+
Documentation for the API is provided by the header using Doxygen notation.
167+
For licensing information see UNLICENSE.

incbin/UNLICENSE

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
This is free and unencumbered software released into the public domain.
2+
3+
Anyone is free to copy, modify, publish, use, compile, sell, or
4+
distribute this software, either in source code form or as a compiled
5+
binary, for any purpose, commercial or non-commercial, and by any
6+
means.
7+
8+
In jurisdictions that recognize copyright laws, the author or authors
9+
of this software dedicate any and all copyright interest in the
10+
software to the public domain. We make this dedication for the benefit
11+
of the public at large and to the detriment of our heirs and
12+
successors. We intend this dedication to be an overt act of
13+
relinquishment in perpetuity of all present and future rights to this
14+
software under copyright law.
15+
16+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19+
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
20+
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21+
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22+
OTHER DEALINGS IN THE SOFTWARE.
23+
24+
For more information, please refer to <http://unlicense.org/>

0 commit comments

Comments
 (0)