• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /* Unity Configuration
2  * As of May 11th, 2016 at ThrowTheSwitch/Unity commit 837c529
3  * Update: December 29th, 2016
4  * See Also: Unity/docs/UnityConfigurationGuide.pdf
5  *
6  * Unity is designed to run on almost anything that is targeted by a C compiler.
7  * It would be awesome if this could be done with zero configuration. While
8  * there are some targets that come close to this dream, it is sadly not
9  * universal. It is likely that you are going to need at least a couple of the
10  * configuration options described in this document.
11  *
12  * All of Unity's configuration options are `#defines`. Most of these are simple
13  * definitions. A couple are macros with arguments. They live inside the
14  * unity_internals.h header file. We don't necessarily recommend opening that
15  * file unless you really need to. That file is proof that a cross-platform
16  * library is challenging to build. From a more positive perspective, it is also
17  * proof that a great deal of complexity can be centralized primarily to one
18  * place in order to provide a more consistent and simple experience elsewhere.
19  *
20  * Using These Options
21  * It doesn't matter if you're using a target-specific compiler and a simulator
22  * or a native compiler. In either case, you've got a couple choices for
23  * configuring these options:
24  *
25  *  1. Because these options are specified via C defines, you can pass most of
26  *     these options to your compiler through command line compiler flags. Even
27  *     if you're using an embedded target that forces you to use their
28  *     overbearing IDE for all configuration, there will be a place somewhere in
29  *     your project to configure defines for your compiler.
30  *  2. You can create a custom `unity_config.h` configuration file (present in
31  *     your toolchain's search paths). In this file, you will list definitions
32  *     and macros specific to your target. All you must do is define
33  *     `UNITY_INCLUDE_CONFIG_H` and Unity will rely on `unity_config.h` for any
34  *     further definitions it may need.
35  */
36 
37 #ifndef UNITY_CONFIG_H
38 #define UNITY_CONFIG_H
39 
40 /* ************************* AUTOMATIC INTEGER TYPES ***************************
41  * C's concept of an integer varies from target to target. The C Standard has
42  * rules about the `int` matching the register size of the target
43  * microprocessor. It has rules about the `int` and how its size relates to
44  * other integer types. An `int` on one target might be 16 bits while on another
45  * target it might be 64. There are more specific types in compilers compliant
46  * with C99 or later, but that's certainly not every compiler you are likely to
47  * encounter. Therefore, Unity has a number of features for helping to adjust
48  * itself to match your required integer sizes. It starts off by trying to do it
49  * automatically.
50  **************************************************************************** */
51 
52 /* The first attempt to guess your types is to check `limits.h`. Some compilers
53  * that don't support `stdint.h` could include `limits.h`. If you don't
54  * want Unity to check this file, define this to make it skip the inclusion.
55  * Unity looks at UINT_MAX & ULONG_MAX, which were available since C89.
56  */
57 /* #define UNITY_EXCLUDE_LIMITS_H */
58 
59 /* The second thing that Unity does to guess your types is check `stdint.h`.
60  * This file defines `UINTPTR_MAX`, since C99, that Unity can make use of to
61  * learn about your system. It's possible you don't want it to do this or it's
62  * possible that your system doesn't support `stdint.h`. If that's the case,
63  * you're going to want to define this. That way, Unity will know to skip the
64  * inclusion of this file and you won't be left with a compiler error.
65  */
66 /* #define UNITY_EXCLUDE_STDINT_H */
67 
68 /* ********************** MANUAL INTEGER TYPE DEFINITION ***********************
69  * If you've disabled all of the automatic options above, you're going to have
70  * to do the configuration yourself. There are just a handful of defines that
71  * you are going to specify if you don't like the defaults.
72  **************************************************************************** */
73 
74  /* Define this to be the number of bits an `int` takes up on your system. The
75  * default, if not auto-detected, is 32 bits.
76  *
77  * Example:
78  */
79 /* #define UNITY_INT_WIDTH 16 */
80 
81 /* Define this to be the number of bits a `long` takes up on your system. The
82  * default, if not autodetected, is 32 bits. This is used to figure out what
83  * kind of 64-bit support your system can handle.  Does it need to specify a
84  * `long` or a `long long` to get a 64-bit value. On 16-bit systems, this option
85  * is going to be ignored.
86  *
87  * Example:
88  */
89 /* #define UNITY_LONG_WIDTH 16 */
90 
91 /* Define this to be the number of bits a pointer takes up on your system. The
92  * default, if not autodetected, is 32-bits. If you're getting ugly compiler
93  * warnings about casting from pointers, this is the one to look at.
94  *
95  * Example:
96  */
97 /* #define UNITY_POINTER_WIDTH 64 */
98 
99 /* Unity will automatically include 64-bit support if it auto-detects it, or if
100  * your `int`, `long`, or pointer widths are greater than 32-bits. Define this
101  * to enable 64-bit support if none of the other options already did it for you.
102  * There can be a significant size and speed impact to enabling 64-bit support
103  * on small targets, so don't define it if you don't need it.
104  */
105 /* #define UNITY_INCLUDE_64 */
106 
107 
108 /* *************************** FLOATING POINT TYPES ****************************
109  * In the embedded world, it's not uncommon for targets to have no support for
110  * floating point operations at all or to have support that is limited to only
111  * single precision. We are able to guess integer sizes on the fly because
112  * integers are always available in at least one size. Floating point, on the
113  * other hand, is sometimes not available at all. Trying to include `float.h` on
114  * these platforms would result in an error. This leaves manual configuration as
115  * the only option.
116  **************************************************************************** */
117 
118  /* By default, Unity guesses that you will want single precision floating point
119   * support, but not double precision. It's easy to change either of these using
120   * the include and exclude options here. You may include neither, just float,
121   * or both, as suits your needs.
122   */
123 /* #define UNITY_EXCLUDE_FLOAT  */
124 #define UNITY_INCLUDE_DOUBLE
125 /* #define UNITY_EXCLUDE_DOUBLE */
126 
127 /* For features that are enabled, the following floating point options also
128  * become available.
129  */
130 
131 /* Unity aims for as small of a footprint as possible and avoids most standard
132  * library calls (some embedded platforms don't have a standard library!).
133  * Because of this, its routines for printing integer values are minimalist and
134  * hand-coded. To keep Unity universal, though, we eventually chose to develop
135  * our own floating point print routines. Still, the display of floating point
136  * values during a failure are optional. By default, Unity will print the
137  * actual results of floating point assertion failures. So a failed assertion
138  * will produce a message like "Expected 4.0 Was 4.25". If you would like less
139  * verbose failure messages for floating point assertions, use this option to
140  * give a failure message `"Values Not Within Delta"` and trim the binary size.
141  */
142 /* #define UNITY_EXCLUDE_FLOAT_PRINT */
143 
144 /* If enabled, Unity assumes you want your `FLOAT` asserts to compare standard C
145  * floats. If your compiler supports a specialty floating point type, you can
146  * always override this behavior by using this definition.
147  *
148  * Example:
149  */
150 /* #define UNITY_FLOAT_TYPE float16_t */
151 
152 /* If enabled, Unity assumes you want your `DOUBLE` asserts to compare standard
153  * C doubles. If you would like to change this, you can specify something else
154  * by using this option. For example, defining `UNITY_DOUBLE_TYPE` to `long
155  * double` could enable gargantuan floating point types on your 64-bit processor
156  * instead of the standard `double`.
157  *
158  * Example:
159  */
160 /* #define UNITY_DOUBLE_TYPE long double */
161 
162 /* If you look up `UNITY_ASSERT_EQUAL_FLOAT` and `UNITY_ASSERT_EQUAL_DOUBLE` as
163  * documented in the Unity Assertion Guide, you will learn that they are not
164  * really asserting that two values are equal but rather that two values are
165  * "close enough" to equal. "Close enough" is controlled by these precision
166  * configuration options. If you are working with 32-bit floats and/or 64-bit
167  * doubles (the normal on most processors), you should have no need to change
168  * these options. They are both set to give you approximately 1 significant bit
169  * in either direction. The float precision is 0.00001 while the double is
170  * 10^-12. For further details on how this works, see the appendix of the Unity
171  * Assertion Guide.
172  *
173  * Example:
174  */
175 /* #define UNITY_FLOAT_PRECISION 0.001f  */
176 /* #define UNITY_DOUBLE_PRECISION 0.001f */
177 
178 
179 /* *************************** TOOLSET CUSTOMIZATION ***************************
180  * In addition to the options listed above, there are a number of other options
181  * which will come in handy to customize Unity's behavior for your specific
182  * toolchain. It is possible that you may not need to touch any of these but
183  * certain platforms, particularly those running in simulators, may need to jump
184  * through extra hoops to operate properly. These macros will help in those
185  * situations.
186  **************************************************************************** */
187 
188 /* By default, Unity prints its results to `stdout` as it runs. This works
189  * perfectly fine in most situations where you are using a native compiler for
190  * testing. It works on some simulators as well so long as they have `stdout`
191  * routed back to the command line. There are times, however, where the
192  * simulator will lack support for dumping results or you will want to route
193  * results elsewhere for other reasons. In these cases, you should define the
194  * `UNITY_OUTPUT_CHAR` macro. This macro accepts a single character at a time
195  * (as an `int`, since this is the parameter type of the standard C `putchar`
196  * function most commonly used). You may replace this with whatever function
197  * call you like.
198  *
199  * Example:
200  * Say you are forced to run your test suite on an embedded processor with no
201  * `stdout` option. You decide to route your test result output to a custom
202  * serial `RS232_putc()` function you wrote like thus:
203  */
204 /* #define UNITY_OUTPUT_CHAR(a)                    RS232_putc(a) */
205 /* #define UNITY_OUTPUT_CHAR_HEADER_DECLARATION    RS232_putc(int) */
206 /* #define UNITY_OUTPUT_FLUSH()                    RS232_flush() */
207 /* #define UNITY_OUTPUT_FLUSH_HEADER_DECLARATION   RS232_flush(void) */
208 /* #define UNITY_OUTPUT_START()                    RS232_config(115200,1,8,0) */
209 /* #define UNITY_OUTPUT_COMPLETE()                 RS232_close() */
210 
211 /* For some targets, Unity can make the otherwise required `setUp()` and
212  * `tearDown()` functions optional. This is a nice convenience for test writers
213  * since `setUp` and `tearDown` don't often actually _do_ anything. If you're
214  * using gcc or clang, this option is automatically defined for you. Other
215  * compilers can also support this behavior, if they support a C feature called
216  * weak functions. A weak function is a function that is compiled into your
217  * executable _unless_ a non-weak version of the same function is defined
218  * elsewhere. If a non-weak version is found, the weak version is ignored as if
219  * it never existed. If your compiler supports this feature, you can let Unity
220  * know by defining `UNITY_SUPPORT_WEAK` as the function attributes that would
221  * need to be applied to identify a function as weak. If your compiler lacks
222  * support for weak functions, you will always need to define `setUp` and
223  * `tearDown` functions (though they can be and often will be just empty). The
224  * most common options for this feature are:
225  */
226 /* #define UNITY_SUPPORT_WEAK weak */
227 /* #define UNITY_SUPPORT_WEAK __attribute__((weak)) */
228 /* #define UNITY_NO_WEAK */
229 
230 /* Some compilers require a custom attribute to be assigned to pointers, like
231  * `near` or `far`. In these cases, you can give Unity a safe default for these
232  * by defining this option with the attribute you would like.
233  *
234  * Example:
235  */
236 /* #define UNITY_PTR_ATTRIBUTE __attribute__((far)) */
237 /* #define UNITY_PTR_ATTRIBUTE near */
238 
239 #endif /* UNITY_CONFIG_H */
240