unity_config.h

00001 /* Unity Configuration
00002  * As of May 11th, 2016 at ThrowTheSwitch/Unity commit 837c529
00003  * See Also: Unity/docs/UnityConfigurationGuide.pdf
00004  *
00005  * Unity is designed to run on almost anything that is targeted by a C compiler.
00006  * It would be awesome if this could be done with zero configuration. While
00007  * there are some targets that come close to this dream, it is sadly not
00008  * universal. It is likely that you are going to need at least a couple of the
00009  * configuration options described in this document.
00010  *
00011  * All of Unity's configuration options are `#defines`. Most of these are simple
00012  * definitions. A couple are macros with arguments. They live inside the
00013  * unity_internals.h header file. We don't necessarily recommend opening that
00014  * file unless you really need to. That file is proof that a cross-platform
00015  * library is challenging to build. From a more positive perspective, it is also
00016  * proof that a great deal of complexity can be centralized primarily to one
00017  * place in order to provide a more consistent and simple experience elsewhere.
00018  *
00019  * Using These Options
00020  * It doesn't matter if you're using a target-specific compiler and a simulator
00021  * or a native compiler. In either case, you've got a couple choices for
00022  * configuring these options:
00023  *
00024  *  1. Because these options are specified via C defines, you can pass most of
00025  *     these options to your compiler through command line compiler flags. Even
00026  *     if you're using an embedded target that forces you to use their
00027  *     overbearing IDE for all configuration, there will be a place somewhere in
00028  *     your project to configure defines for your compiler.
00029  *  2. You can create a custom `unity_config.h` configuration file (present in
00030  *     your toolchain's search paths). In this file, you will list definitions
00031  *     and macros specific to your target. All you must do is define
00032  *     `UNITY_INCLUDE_CONFIG_H` and Unity will rely on `unity_config.h` for any
00033  *     further definitions it may need.
00034  */
00035 
00036 #ifndef UNITY_CONFIG_H
00037 #define UNITY_CONFIG_H
00038 
00039 #ifdef __cplusplus
00040 extern "C"
00041 {
00042 #endif
00043 
00044 /* ************************* AUTOMATIC INTEGER TYPES ***************************
00045  * C's concept of an integer varies from target to target. The C Standard has
00046  * rules about the `int` matching the register size of the target
00047  * microprocessor. It has rules about the `int` and how its size relates to
00048  * other integer types. An `int` on one target might be 16 bits while on another
00049  * target it might be 64. There are more specific types in compilers compliant
00050  * with C99 or later, but that's certainly not every compiler you are likely to
00051  * encounter. Therefore, Unity has a number of features for helping to adjust
00052  * itself to match your required integer sizes. It starts off by trying to do it
00053  * automatically.
00054  **************************************************************************** */
00055 
00056 /* The first thing that Unity does to guess your types is check `stdint.h`. This
00057  * file includes defines like `UINT_MAX` that Unity can make use of to learn a
00058  * lot about your system. It's possible you don't want it to do this or it's
00059  * possible that your system doesn't support `stdint.h`. If that's the case,
00060  * you're going to want to define this. That way, Unity will know to skip the
00061  * inclusion of this file and you won't be left with a compiler error.
00062  */
00063 /* #define UNITY_EXCLUDE_STDINT_H */
00064 
00065 /* The second attempt to guess your types is to check `limits.h`. Some compilers
00066  * that don't support `stdint.h` could include `limits.h` instead. If you don't
00067  * want Unity to check this file either, define this to make it skip the
00068  * inclusion.
00069  */
00070 /* #define UNITY_EXCLUDE_LIMITS_H */
00071 
00072 /* The third and final attempt to guess your types is to use the `sizeof()`
00073  * operator. Even if the first two options don't work, this one covers most
00074  * cases. There _is_ a rare compiler or two out there that doesn't support
00075  * `sizeof()` in the preprocessing stage, though. For these, you have the
00076  * ability to disable this feature as well.
00077  */
00078 /* #define UNITY_EXCLUDE_SIZEOF */
00079 
00080 
00081 /* ********************** MANUAL INTEGER TYPE DEFINITION ***********************
00082  * If you've disabled all of the automatic options above, you're going to have
00083  * to do the configuration yourself. There are just a handful of defines that
00084  * you are going to specify if you don't like the defaults.
00085  **************************************************************************** */
00086 
00087  /* Define this to be the number of bits an `int` takes up on your system. The
00088  * default, if not auto-detected, is 32 bits.
00089  *
00090  * Example:
00091  */
00092 /* #define UNITY_INT_WIDTH 16 */
00093 
00094 /* Define this to be the number of bits a `long` takes up on your system. The
00095  * default, if not autodetected, is 32 bits. This is used to figure out what
00096  * kind of 64-bit support your system can handle.  Does it need to specify a
00097  * `long` or a `long long` to get a 64-bit value. On 16-bit systems, this option
00098  * is going to be ignored.
00099  *
00100  * Example:
00101  */
00102 /* #define UNITY_LONG_WIDTH 16 */
00103 
00104 /* Define this to be the number of bits a pointer takes up on your system. The
00105  * default, if not autodetected, is 32-bits. If you're getting ugly compiler
00106  * warnings about casting from pointers, this is the one to look at.
00107  *
00108  * Example:
00109  */
00110 /* #define UNITY_POINTER_WIDTH 64 */
00111 
00112 /* Unity will automatically include 64-bit support if it auto-detects it, or if
00113  * your `int`, `long`, or pointer widths are greater than 32-bits. Define this
00114  * to enable 64-bit support if none of the other options already did it for you.
00115  * There can be a significant size and speed impact to enabling 64-bit support
00116  * on small targets, so don't define it if you don't need it.
00117  */
00118 /* #define UNITY_INCLUDE_64 */
00119 
00120 
00121 /* *************************** FLOATING POINT TYPES ****************************
00122  * In the embedded world, it's not uncommon for targets to have no support for
00123  * floating point operations at all or to have support that is limited to only
00124  * single precision. We are able to guess integer sizes on the fly because
00125  * integers are always available in at least one size. Floating point, on the
00126  * other hand, is sometimes not available at all. Trying to include `float.h` on
00127  * these platforms would result in an error. This leaves manual configuration as
00128  * the only option.
00129  **************************************************************************** */
00130 
00131  /* By default, Unity guesses that you will want single precision floating point
00132   * support, but not double precision. It's easy to change either of these using
00133   * the include and exclude options here. You may include neither, either, or
00134   * both, as suits your needs.
00135   */
00136 /* #define UNITY_INCLUDE_FLOAT  */
00137 /* #define UNITY_EXCLUDE_FLOAT  */
00138 /* #define UNITY_INCLUDE_DOUBLE */
00139 /* #define UNITY_EXCLUDE_DOUBLE */
00140 
00141 /* For features that are enabled, the following floating point options also
00142  * become available.
00143  */
00144 
00145 /* Unity aims for as small of a footprint as possible and avoids most standard
00146  * library calls (some embedded platforms don't have a standard library!).
00147  * Because of this, its routines for printing integer values are minimalist and
00148  * hand-coded. To keep Unity universal, though, we chose to _not_ develop our
00149  * own floating point print routines. Instead, the display of floating point
00150  * values during a failure are optional. By default, Unity will not print the
00151  * actual results of floating point assertion failure. So a failed assertion
00152  * will produce a message like `"Values Not Within Delta"`. If you would like
00153  * verbose failure messages for floating point assertions, use these options to
00154  * give more explicit failure messages (e.g. `"Expected 4.56 Was 4.68"`). Note
00155  * that this feature requires the use of `sprintf` so might not be desirable in
00156  * all cases.
00157  */
00158 /* #define UNITY_FLOAT_VERBOSE  */
00159 /* #define UNITY_DOUBLE_VERBOSE */
00160 
00161 /* If enabled, Unity assumes you want your `FLOAT` asserts to compare standard C
00162  * floats. If your compiler supports a specialty floating point type, you can
00163  * always override this behavior by using this definition.
00164  *
00165  * Example:
00166  */
00167 /* #define UNITY_FLOAT_TYPE float16_t */
00168 
00169 /* If enabled, Unity assumes you want your `DOUBLE` asserts to compare standard
00170  * C doubles. If you would like to change this, you can specify something else
00171  * by using this option. For example, defining `UNITY_DOUBLE_TYPE` to `long
00172  * double` could enable gargantuan floating point types on your 64-bit processor
00173  * instead of the standard `double`.
00174  *
00175  * Example:
00176  */
00177 /* #define UNITY_DOUBLE_TYPE long double */
00178 
00179 /* If you look up `UNITY_ASSERT_EQUAL_FLOAT` and `UNITY_ASSERT_EQUAL_DOUBLE` as
00180  * documented in the Unity Assertion Guide, you will learn that they are not
00181  * really asserting that two values are equal but rather that two values are
00182  * "close enough" to equal. "Close enough" is controlled by these precision
00183  * configuration options. If you are working with 32-bit floats and/or 64-bit
00184  * doubles (the normal on most processors), you should have no need to change
00185  * these options. They are both set to give you approximately 1 significant bit
00186  * in either direction. The float precision is 0.00001 while the double is
00187  * 10^-12. For further details on how this works, see the appendix of the Unity
00188  * Assertion Guide.
00189  *
00190  * Example:
00191  */
00192 /* #define UNITY_FLOAT_PRECISION 0.001f  */
00193 /* #define UNITY_DOUBLE_PRECISION 0.001f */
00194 
00195 
00196 /* *************************** TOOLSET CUSTOMIZATION ***************************
00197  * In addition to the options listed above, there are a number of other options
00198  * which will come in handy to customize Unity's behavior for your specific
00199  * toolchain. It is possible that you may not need to touch any of these but
00200  * certain platforms, particularly those running in simulators, may need to jump
00201  * through extra hoops to operate properly. These macros will help in those
00202  * situations.
00203  **************************************************************************** */
00204 
00205 /* By default, Unity prints its results to `stdout` as it runs. This works
00206  * perfectly fine in most situations where you are using a native compiler for
00207  * testing. It works on some simulators as well so long as they have `stdout`
00208  * routed back to the command line. There are times, however, where the
00209  * simulator will lack support for dumping results or you will want to route
00210  * results elsewhere for other reasons. In these cases, you should define the
00211  * `UNITY_OUTPUT_CHAR` macro. This macro accepts a single character at a time
00212  * (as an `int`, since this is the parameter type of the standard C `putchar`
00213  * function most commonly used). You may replace this with whatever function
00214  * call you like.
00215  *
00216  * Example:
00217  * Say you are forced to run your test suite on an embedded processor with no
00218  * `stdout` option. You decide to route your test result output to a custom
00219  * serial `RS232_putc()` function you wrote like thus:
00220  */
00221 /* #define UNITY_OUTPUT_CHAR(a)    RS232_putc(a) */
00222 /* #define UNITY_OUTPUT_FLUSH()    RS232_config(115200,1,8,0) */
00223 /* #define UNITY_OUTPUT_START()    RS232_flush() */
00224 /* #define UNITY_OUTPUT_COMPLETE() RS232_close() */
00225 
00226 /* For some targets, Unity can make the otherwise required `setUp()` and
00227  * `tearDown()` functions optional. This is a nice convenience for test writers
00228  * since `setUp` and `tearDown` don't often actually _do_ anything. If you're
00229  * using gcc or clang, this option is automatically defined for you. Other
00230  * compilers can also support this behavior, if they support a C feature called
00231  * weak functions. A weak function is a function that is compiled into your
00232  * executable _unless_ a non-weak version of the same function is defined
00233  * elsewhere. If a non-weak version is found, the weak version is ignored as if
00234  * it never existed. If your compiler supports this feature, you can let Unity
00235  * know by defining `UNITY_SUPPORT_WEAK` as the function attributes that would
00236  * need to be applied to identify a function as weak. If your compiler lacks
00237  * support for weak functions, you will always need to define `setUp` and
00238  * `tearDown` functions (though they can be and often will be just empty). The
00239  * most common options for this feature are:
00240  */
00241 /* #define UNITY_SUPPORT_WEAK weak */
00242 /* #define UNITY_SUPPORT_WEAK __attribute__((weak)) */
00243 
00244 /* Some compilers require a custom attribute to be assigned to pointers, like
00245  * `near` or `far`. In these cases, you can give Unity a safe default for these
00246  * by defining this option with the attribute you would like.
00247  *
00248  * Example:
00249  */
00250 /* #define UNITY_PTR_ATTRIBUTE __attribute__((far)) */
00251 /* #define UNITY_PTR_ATTRIBUTE near */
00252 
00253 #ifdef __cplusplus
00254 }
00255 #endif /* extern "C" */
00256 
00257 #endif /* UNITY_CONFIG_H */