1# Unity Configuration Guide 2 3## C Standards, Compilers and Microcontrollers 4 5The embedded software world contains its challenges. 6Compilers support different revisions of the C Standard. 7They ignore requirements in places, sometimes to make the language more usable in some special regard. 8Sometimes it's to simplify their support. 9Sometimes it's due to specific quirks of the microcontroller they are targeting. 10Simulators add another dimension to this menagerie. 11 12Unity is designed to run on almost anything that is targeted by a C compiler. 13It would be awesome if this could be done with zero configuration. 14While there are some targets that come close to this dream, it is sadly not universal. 15It is likely that you are going to need at least a couple of the configuration options described in this document. 16 17All of Unity's configuration options are `#defines`. 18Most of these are simple definitions. 19A couple are macros with arguments. 20They live inside the unity_internals.h header file. 21We don't necessarily recommend opening that file unless you really need to. 22That file is proof that a cross-platform library is challenging to build. 23From a more positive perspective, it is also proof that a great deal of complexity can be centralized primarily to one place to provide a more consistent and simple experience elsewhere. 24 25### Using These Options 26 27It doesn't matter if you're using a target-specific compiler and a simulator or a native compiler. 28In either case, you've got a couple choices for configuring these options: 29 301. Because these options are specified via C defines, you can pass most of these options to your compiler through command line compiler flags. Even if you're using an embedded target that forces you to use their overbearing IDE for all configuration, there will be a place somewhere in your project to configure defines for your compiler. 312. You can create a custom `unity_config.h` configuration file (present in your toolchain's search paths). 32 In this file, you will list definitions and macros specific to your target. All you must do is define `UNITY_INCLUDE_CONFIG_H` and Unity will rely on `unity_config.h` for any further definitions it may need. 33 34Unfortunately, it doesn't usually work well to just #define these things in the test itself. 35These defines need to take effect where ever unity.h is included. 36This would be test test, the test runner (if you're generating one), and from unity.c when it's compiled. 37 38## The Options 39 40### Integer Types 41 42If you've been a C developer for long, you probably already know that C's concept of an integer varies from target to target. 43The C Standard has rules about the `int` matching the register size of the target microprocessor. 44It has rules about the `int` and how its size relates to other integer types. 45An `int` on one target might be 16 bits while on another target it might be 64. 46There are more specific types in compilers compliant with C99 or later, but that's certainly not every compiler you are likely to encounter. 47Therefore, Unity has a number of features for helping to adjust itself to match your required integer sizes. 48It starts off by trying to do it automatically. 49 50#### `UNITY_EXCLUDE_STDINT_H` 51 52The first thing that Unity does to guess your types is check `stdint.h`. 53This file includes defines like `UINT_MAX` that Unity can use to learn a lot about your system. 54It's possible you don't want it to do this (um. why not?) or (more likely) it's possible that your system doesn't support `stdint.h`. 55If that's the case, you're going to want to define this. 56That way, Unity will know to skip the inclusion of this file and you won't be left with a compiler error. 57 58_Example:_ 59 60```C 61#define UNITY_EXCLUDE_STDINT_H 62``` 63 64#### `UNITY_EXCLUDE_LIMITS_H` 65 66The second attempt to guess your types is to check `limits.h`. 67Some compilers that don't support `stdint.h` could include `limits.h` instead. 68If you don't want Unity to check this file either, define this to make it skip the inclusion. 69 70_Example:_ 71 72```C 73#define UNITY_EXCLUDE_LIMITS_H 74``` 75 76If you've disabled both of the automatic options above, you're going to have to do the configuration yourself. 77Don't worry. 78Even this isn't too bad... there are just a handful of defines that you are going to specify if you don't like the defaults. 79 80#### `UNITY_INT_WIDTH` 81 82Define this to be the number of bits an `int` takes up on your system. 83The default, if not autodetected, is 32 bits. 84 85_Example:_ 86 87```C 88#define UNITY_INT_WIDTH 16 89``` 90 91#### `UNITY_LONG_WIDTH` 92 93Define this to be the number of bits a `long` takes up on your system. 94The default, if not autodetected, is 32 bits. 95This is used to figure out what kind of 64-bit support your system can handle. 96Does it need to specify a `long` or a `long long` to get a 64-bit value. 97On 16-bit systems, this option is going to be ignored. 98 99_Example:_ 100 101```C 102#define UNITY_LONG_WIDTH 16 103``` 104 105#### `UNITY_POINTER_WIDTH` 106 107Define this to be the number of bits a pointer takes up on your system. 108The default, if not autodetected, is 32-bits. 109If you're getting ugly compiler warnings about casting from pointers, this is the one to look at. 110 111_Hint:_ In order to support exotic processors (for example TI C55x with a pointer width of 23-bit), choose the next power of two (in this case 32-bit). 112 113_Supported values:_ 16, 32 and 64 114 115_Example:_ 116 117```C 118// Choose on of these #defines to set your pointer width (if not autodetected) 119//#define UNITY_POINTER_WIDTH 16 120//#define UNITY_POINTER_WIDTH 32 121#define UNITY_POINTER_WIDTH 64 // Set UNITY_POINTER_WIDTH to 64-bit 122``` 123 124#### `UNITY_COMPARE_PTRS_ON_ZERO_ARRAY` 125 126Define this to make all array assertions compare pointers instead of contents when a length of zero is specified. When not enabled, 127defining a length of zero will always result in a failure and a message warning the user that they have tried to compare empty 128arrays. 129 130#### `UNITY_SUPPORT_64` 131 132Unity will automatically include 64-bit support if it auto-detects it, or if your `int`, `long`, or pointer widths are greater than 32-bits. 133Define this to enable 64-bit support if none of the other options already did it for you. 134There can be a significant size and speed impact to enabling 64-bit support on small targets, so don't define it if you don't need it. 135 136_Example:_ 137 138```C 139#define UNITY_SUPPORT_64 140``` 141 142### Floating Point Types 143 144In the embedded world, it's not uncommon for targets to have no support for floating point operations at all or to have support that is limited to only single precision. 145We are able to guess integer sizes on the fly because integers are always available in at least one size. 146Floating point, on the other hand, is sometimes not available at all. 147Trying to include `float.h` on these platforms would result in an error. This leaves manual configuration as the only option. 148 149#### `UNITY_INCLUDE_FLOAT` 150 151#### `UNITY_EXCLUDE_FLOAT` 152 153#### `UNITY_INCLUDE_DOUBLE` 154 155#### `UNITY_EXCLUDE_DOUBLE` 156 157By default, Unity guesses that you will want single precision floating point support, but not double precision. 158It's easy to change either of these using the include and exclude options here. 159You may include neither, either, or both, as suits your needs. 160For features that are enabled, the following floating point options also become available. 161 162_Example:_ 163 164```C 165//what manner of strange processor is this? 166#define UNITY_EXCLUDE_FLOAT 167#define UNITY_INCLUDE_DOUBLE 168``` 169 170#### `UNITY_EXCLUDE_FLOAT_PRINT` 171 172Unity aims for as small of a footprint as possible and avoids most standard library calls (some embedded platforms don’t have a standard library!). 173Because of this, its routines for printing integer values are minimalist and hand-coded. 174Therefore, the display of floating point values during a failure are optional. 175By default, Unity will print the actual results of floating point assertion failure (e.g. ”Expected 4.56 Was 4.68”). 176To not include this extra support, you can use this define to instead respond to a failed assertion with a message like ”Values Not Within Delta”. 177If you would like verbose failure messages for floating point assertions, use these options to give more explicit failure messages. 178 179_Example:_ 180 181```C 182#define UNITY_EXCLUDE_FLOAT_PRINT 183``` 184 185#### `UNITY_FLOAT_TYPE` 186 187If enabled, Unity assumes you want your `FLOAT` asserts to compare standard C floats. 188If your compiler supports a specialty floating point type, you can always override this behavior by using this definition. 189 190_Example:_ 191 192```C 193#define UNITY_FLOAT_TYPE float16_t 194``` 195 196#### `UNITY_DOUBLE_TYPE` 197 198If enabled, Unity assumes you want your `DOUBLE` asserts to compare standard C doubles. 199If you would like to change this, you can specify something else by using this option. 200For example, defining `UNITY_DOUBLE_TYPE` to `long double` could enable gargantuan floating point types on your 64-bit processor instead of the standard `double`. 201 202_Example:_ 203 204```C 205#define UNITY_DOUBLE_TYPE long double 206``` 207 208#### `UNITY_FLOAT_PRECISION` 209 210#### `UNITY_DOUBLE_PRECISION` 211 212If you look up `UNITY_ASSERT_EQUAL_FLOAT` and `UNITY_ASSERT_EQUAL_DOUBLE` as documented in the big daddy Unity Assertion Guide, you will learn that they are not really asserting that two values are equal but rather that two values are "close enough" to equal. 213"Close enough" is controlled by these precision configuration options. 214If you are working with 32-bit floats and/or 64-bit doubles (the normal on most processors), you should have no need to change these options. 215They are both set to give you approximately 1 significant bit in either direction. 216The float precision is 0.00001 while the double is 10-12. 217For further details on how this works, see the appendix of the Unity Assertion Guide. 218 219_Example:_ 220 221```C 222#define UNITY_FLOAT_PRECISION 0.001f 223``` 224 225#### `UNITY_IS_NAN` and `UNITY_IS_INF` 226 227If your toolchain defines `isnan` and `isinf` in `math.h` as macros, nothing needs to be done. If your toolchain doesn't define these, Unity 228will create these macros itself. You may override either or both of these defines to specify how you want to evaluate if a number is NaN or Infinity. 229 230_Example:_ 231 232```C 233#define UNITY_IS_NAN(n) ((n != n) ? 1 : 0) 234``` 235 236### Miscellaneous 237 238#### `UNITY_EXCLUDE_STDDEF_H` 239 240Unity uses the `NULL` macro, which defines the value of a null pointer constant, defined in `stddef.h` by default. 241If you want to provide your own macro for this, you should exclude the `stddef.h` header file by adding this define to your configuration. 242 243_Example:_ 244 245```C 246#define UNITY_EXCLUDE_STDDEF_H 247``` 248 249#### `UNITY_INCLUDE_PRINT_FORMATTED` 250 251Unity provides a simple (and very basic) printf-like string output implementation, which is able to print a string modified by the following format string modifiers: 252 253- __%d__ - signed value (decimal) 254- __%i__ - same as __%d__ 255- __%u__ - unsigned value (decimal) 256- __%f__ - float/Double (if float support is activated) 257- __%g__ - same as __%f__ 258- __%b__ - binary prefixed with "0b" 259- __%x__ - hexadecimal (upper case) prefixed with "0x" 260- __%X__ - same as __%x__ 261- __%p__ - pointer (same as __%x__ or __%X__) 262- __%c__ - a single character 263- __%s__ - a string (e.g. "string") 264- __%%__ - The "%" symbol (escaped) 265 266Length specifiers are also supported. If you are using long long types, make sure UNITY_SUPPORT_64 is true to ensure they are printed correctly. 267 268- __%ld__ - signed long value (decimal) 269- __%lld__ - signed long long value (decimal) 270- __%lu__ - unsigned long value (decimal) 271- __%llu__ - unsigned long long value (decimal) 272- __%lx__ - unsigned long value (hexadecimal) 273- __%llx__ - unsigned long long value (hexadecimal) 274 275_Example:_ 276 277```C 278#define UNITY_INCLUDE_PRINT_FORMATTED 279 280int a = 0xfab1; 281TEST_PRINTF("Decimal %d\n", -7); 282TEST_PRINTF("Unsigned %u\n", 987); 283TEST_PRINTF("Float %f\n", 3.1415926535897932384); 284TEST_PRINTF("Binary %b\n", 0xA); 285TEST_PRINTF("Hex %X\n", 0xFAB); 286TEST_PRINTF("Pointer %p\n", &a); 287TEST_PRINTF("Character %c\n", 'F'); 288TEST_PRINTF("String %s\n", "My string"); 289TEST_PRINTF("Percent %%\n"); 290TEST_PRINTF("Unsigned long long %llu\n", 922337203685477580); 291TEST_PRINTF("Color Red \033[41mFAIL\033[0m\n"); 292TEST_PRINTF("\n"); 293TEST_PRINTF("Multiple (%d) (%i) (%u) (%x)\n", -100, 0, 200, 0x12345); 294``` 295 296### Toolset Customization 297 298In addition to the options listed above, there are a number of other options which will come in handy to customize Unity's behavior for your specific toolchain. 299It is possible that you may not need to touch any of these... but certain platforms, particularly those running in simulators, may need to jump through extra hoops to run properly. 300These macros will help in those situations. 301 302#### `UNITY_OUTPUT_CHAR(a)` 303 304#### `UNITY_OUTPUT_FLUSH()` 305 306#### `UNITY_OUTPUT_START()` 307 308#### `UNITY_OUTPUT_COMPLETE()` 309 310By default, Unity prints its results to `stdout` as it runs. 311This works perfectly fine in most situations where you are using a native compiler for testing. 312It works on some simulators as well so long as they have `stdout` routed back to the command line. 313There are times, however, where the simulator will lack support for dumping results or you will want to route results elsewhere for other reasons. 314In these cases, you should define the `UNITY_OUTPUT_CHAR` macro. 315This macro accepts a single character at a time (as an `int`, since this is the parameter type of the standard C `putchar` function most commonly used). 316You may replace this with whatever function call you like. 317 318_Example:_ 319Say you are forced to run your test suite on an embedded processor with no `stdout` option. 320You decide to route your test result output to a custom serial `RS232_putc()` function you wrote like thus: 321 322```C 323#include "RS232_header.h" 324... 325#define UNITY_OUTPUT_CHAR(a) RS232_putc(a) 326#define UNITY_OUTPUT_START() RS232_config(115200,1,8,0) 327#define UNITY_OUTPUT_FLUSH() RS232_flush() 328#define UNITY_OUTPUT_COMPLETE() RS232_close() 329``` 330 331_Note:_ 332`UNITY_OUTPUT_FLUSH()` can be set to the standard out flush function simply by specifying `UNITY_USE_FLUSH_STDOUT`. 333No other defines are required. 334 335#### `UNITY_OUTPUT_FOR_ECLIPSE` 336 337#### `UNITY_OUTPUT_FOR_IAR_WORKBENCH` 338 339#### `UNITY_OUTPUT_FOR_QT_CREATOR` 340 341When managing your own builds, it is often handy to have messages output in a format which is recognized by your IDE. 342These are some standard formats which can be supported. 343If you're using Ceedling to manage your builds, it is better to stick with the standard format (leaving these all undefined) and allow Ceedling to use its own decorators. 344 345#### `UNITY_PTR_ATTRIBUTE` 346 347Some compilers require a custom attribute to be assigned to pointers, like `near` or `far`. 348In these cases, you can give Unity a safe default for these by defining this option with the attribute you would like. 349 350_Example:_ 351 352```C 353#define UNITY_PTR_ATTRIBUTE __attribute__((far)) 354#define UNITY_PTR_ATTRIBUTE near 355``` 356 357#### `UNITY_PRINT_EOL` 358 359By default, Unity outputs \n at the end of each line of output. 360This is easy to parse by the scripts, by Ceedling, etc, but it might not be ideal for YOUR system. 361Feel free to override this and to make it whatever you wish. 362 363_Example:_ 364 365```C 366#define UNITY_PRINT_EOL { UNITY_OUTPUT_CHAR('\r'); UNITY_OUTPUT_CHAR('\n'); } 367``` 368 369#### `UNITY_EXCLUDE_DETAILS` 370 371This is an option for if you absolutely must squeeze every byte of memory out of your system. 372Unity stores a set of internal scratchpads which are used to pass extra detail information around. 373It's used by systems like CMock in order to report which function or argument flagged an error. 374If you're not using CMock and you're not using these details for other things, then you can exclude them. 375 376_Example:_ 377 378```C 379#define UNITY_EXCLUDE_DETAILS 380``` 381 382#### `UNITY_PRINT_TEST_CONTEXT` 383 384This option allows you to specify your own function to print additional context as part of the error message when a test has failed. 385It can be useful if you want to output some specific information about the state of the test at the point of failure, and `UNITY_SET_DETAILS` isn't flexible enough for your needs. 386 387_Example:_ 388 389```C 390#define UNITY_PRINT_TEST_CONTEXT PrintIterationCount 391 392extern int iteration_count; 393 394void PrintIterationCount(void) 395{ 396 UnityPrintFormatted("At iteration #%d: ", iteration_count); 397} 398``` 399 400#### `UNITY_EXCLUDE_SETJMP` 401 402If your embedded system doesn't support the standard library setjmp, you can exclude Unity's reliance on this by using this define. 403This dropped dependence comes at a price, though. 404You will be unable to use custom helper functions for your tests, and you will be unable to use tools like CMock. 405Very likely, if your compiler doesn't support setjmp, you wouldn't have had the memory space for those things anyway, though... so this option exists for those situations. 406 407_Example:_ 408 409```C 410#define UNITY_EXCLUDE_SETJMP 411``` 412 413#### `UNITY_TEST_PROTECT` 414 415#### `UNITY_TEST_ABORT` 416 417Unity handles test failures via `setjmp`/`longjmp` pair by default. As mentioned above, you can disable this with `UNITY_EXCLUDE_SETJMP`. You can also customise what happens on every `TEST_PROTECT` and `TEST_ABORT` call. This can be accomplished by providing user-defined `UNITY_TEST_PROTECT` and `UNITY_TEST_ABORT` macros (and these may be defined independently). 418 419`UNITY_TEST_PROTECT` is used as an `if` statement expression, and has to evaluate to `true` on the first call (when saving stack environment with `setjmp`), and to `false` when it returns as a result of a `TEST_ABORT` (when restoring the stack environment with `longjmp`). 420 421Whenever an assert macro fails, `TEST_ABORT` is used to restore the stack environment previously set by `TEST_PROTECT`. This part may be overriden with `UNITY_TEST_ABORT`, e.g. if custom failure handling is needed. 422 423_Example 1:_ 424 425Calling `longjmp` on your target is possible, but has a platform-specific (or implementation-specific) set of prerequisites, e.g. privileged access level. You can extend the default behaviour of `TEST_PROTECT` and `TEST_ABORT` as: 426 427`unity_config.h`: 428 429```C 430#include "my_custom_test_handlers.h" 431 432#define UNITY_TEST_PROTECT() custom_test_protect() 433#define UNITY_TEST_ABORT() custom_test_abort() 434``` 435 436`my_custom_test_handlers.c`: 437 438```C 439int custom_test_protect(void) { 440 platform_specific_code(); 441 return setjmp(Unity.AbortFrame) == 0; 442} 443 444UNITY_NORETURN void custom_test_abort(void) { 445 more_platform_specific_code(); 446 longjmp(Unity.AbortFrame, 1); 447} 448``` 449 450_Example 2:_ 451 452Unity is used to provide the assertion macros only, and an external test harness/runner is used for test orchestration/reporting. In this case you can easily plug your code by overriding `TEST_ABORT` as: 453 454`unity_config.h`: 455 456```C 457#include "my_custom_test_handlers.h" 458 459#define UNITY_TEST_PROTECT() 1 460#define UNITY_TEST_ABORT() custom_test_abort() 461``` 462 463`my_custom_test_handlers.c`: 464 465```C 466void custom_test_abort(void) { 467 if (Unity.CurrentTestFailed == 1) { 468 custom_failed_test_handler(); 469 } else if (Unity.CurrentTestIgnored == 1) { 470 custom_ignored_test_handler(); 471 } 472} 473``` 474 475#### `UNITY_OUTPUT_COLOR` 476 477If you want to add color using ANSI escape codes you can use this define. 478 479_Example:_ 480 481```C 482#define UNITY_OUTPUT_COLOR 483``` 484 485#### `UNITY_INCLUDE_EXEC_TIME` 486 487Define this to measure and report execution time for each test in the suite. When enabled, Unity will do 488it's best to automatically find a way to determine the time in milliseconds. On most Windows, macos, or 489Linux environments, this is automatic. If not, you can give Unity more information. 490 491#### `UNITY_CLOCK_MS` 492 493If you're working on a system (embedded or otherwise) which has an accessible millisecond timer. You can 494define `UNITY_CLOCK_MS` to be the name of the function which returns the millisecond timer. It will then 495attempt to use that function for timing purposes. 496 497#### `UNITY_EXEC_TIME_START` 498 499Define this hook to start a millisecond timer if necessary. 500 501#### `UNITY_EXEC_TIME_STOP` 502 503Define this hook to stop a millisecond timer if necessary. 504 505#### `UNITY_PRINT_EXEC_TIME` 506 507Define this hook to print the current execution time. Used to report the milliseconds elapsed. 508 509#### `UNITY_TIME_TYPE` 510 511Finally, this can be set to the type which holds the millisecond timer. 512 513#### `UNITY_SHORTHAND_AS_INT` 514 515#### `UNITY_SHORTHAND_AS_MEM` 516 517#### `UNITY_SHORTHAND_AS_RAW` 518 519#### `UNITY_SHORTHAND_AS_NONE` 520 521These options give you control of the `TEST_ASSERT_EQUAL` and the `TEST_ASSERT_NOT_EQUAL` shorthand assertions. 522Historically, Unity treated the former as an alias for an integer comparison. 523It treated the latter as a direct comparison using `!=`. 524This asymmetry was confusing, but there was much disagreement as to how best to treat this pair of assertions. 525These four options will allow you to specify how Unity will treat these assertions. 526 527- AS INT - the values will be cast to integers and directly compared. 528 Arguments that don't cast easily to integers will cause compiler errors. 529- AS MEM - the address of both values will be taken and the entire object's memory footprint will be compared byte by byte. 530 Directly placing constant numbers like `456` as expected values will cause errors. 531- AS_RAW - Unity assumes that you can compare the two values using `==` and `!=` and will do so. 532 No details are given about mismatches, because it doesn't really know what type it's dealing with. 533- AS_NONE - Unity will disallow the use of these shorthand macros altogether, insisting that developers choose a more descriptive option. 534 535#### `UNITY_SUPPORT_VARIADIC_MACROS` 536 537This will force Unity to support variadic macros when using its own built-in RUN_TEST macro. 538This will rarely be necessary. Most often, Unity will automatically detect if the compiler supports variadic macros by checking to see if it's C99+ compatible. 539In the event that the compiler supports variadic macros, but is primarily C89 (ANSI), defining this option will allow you to use them. 540This option is also not necessary when using Ceedling or the test runner generator script. 541 542#### `UNITY_SUPPORT_TEST_CASES` 543 544Unity can automatically define all supported parameterized tests macros. 545That feature is disabled by default. 546To enable it, use the following example: 547 548```C 549#define UNITY_SUPPORT_TEST_CASES 550``` 551 552You can manually provide required `TEST_CASE`, `TEST_RANGE` or `TEST_MATRIX` macro definitions 553before including `unity.h`, and they won't be redefined. 554If you provide one of the following macros, some of default definitions will not be 555defined: 556| User defines macro | Unity will _not_ define following macro | 557|---|---| 558| `UNITY_EXCLUDE_TEST_CASE` | `TEST_CASE` | 559| `UNITY_EXCLUDE_TEST_RANGE` | `TEST_RANGE` | 560| `UNITY_EXCLUDE_TEST_MATRIX` | `TEST_MATRIX` | 561| `TEST_CASE` | `TEST_CASE` | 562| `TEST_RANGE` | `TEST_RANGE` | 563| `TEST_MATRIX` | `TEST_MATRIX` | 564 565`UNITY_EXCLUDE_TEST_*` defines is not processed by test runner generator script. 566If you exclude one of them from definition, you should provide your own definition 567for them or avoid using undefined `TEST_*` macro as a test generator. 568Otherwise, compiler cannot build source code file with provided call. 569 570_Note:_ 571That feature requires variadic macro support by compiler. If required feature 572is not detected, it will not be enabled, even though preprocessor macro is defined. 573 574## Getting Into The Guts 575 576There will be cases where the options above aren't quite going to get everything perfect. 577They are likely sufficient for any situation where you are compiling and executing your tests with a native toolchain (e.g. clang on Mac). 578These options may even get you through the majority of cases encountered in working with a target simulator run from your local command line. 579But especially if you must run your test suite on your target hardware, your Unity configuration will 580require special help. 581This special help will usually reside in one of two places: the `main()` function or the `RUN_TEST` macro. 582Let's look at how these work. 583 584### `main()` 585 586Each test module is compiled and run on its own, separate from the other test files in your project. 587Each test file, therefore, has a `main` function. 588This `main` function will need to contain whatever code is necessary to initialize your system to a workable state. 589This is particularly true for situations where you must set up a memory map or initialize a communication channel for the output of your test results. 590 591A simple main function looks something like this: 592 593```C 594int main(void) { 595 UNITY_BEGIN(); 596 RUN_TEST(test_TheFirst); 597 RUN_TEST(test_TheSecond); 598 RUN_TEST(test_TheThird); 599 return UNITY_END(); 600} 601``` 602 603You can see that our main function doesn't bother taking any arguments. 604For our most barebones case, we'll never have arguments because we just run all the tests each time. 605Instead, we start by calling `UNITY_BEGIN`. 606We run each test (in whatever order we wish). 607Finally, we call `UNITY_END`, returning its return value (which is the total number of failures). 608 609It should be easy to see that you can add code before any test cases are run or after all the test cases have completed. 610This allows you to do any needed system-wide setup or teardown that might be required for your special circumstances. 611 612#### `RUN_TEST` 613 614The `RUN_TEST` macro is called with each test case function. 615Its job is to perform whatever setup and teardown is necessary for executing a single test case function. 616This includes catching failures, calling the test module's `setUp()` and `tearDown()` functions, and calling `UnityConcludeTest()`. 617If using CMock or test coverage, there will be additional stubs in use here. 618A simple minimalist RUN_TEST macro looks something like this: 619 620```C 621#define RUN_TEST(testfunc) \ 622 UNITY_NEW_TEST(#testfunc) \ 623 if (TEST_PROTECT()) { \ 624 setUp(); \ 625 testfunc(); \ 626 } \ 627 if (TEST_PROTECT() && (!TEST_IS_IGNORED)) \ 628 tearDown(); \ 629 UnityConcludeTest(); 630``` 631 632So that's quite a macro, huh? 633It gives you a glimpse of what kind of stuff Unity has to deal with for every single test case. 634For each test case, we declare that it is a new test. 635Then we run `setUp` and our test function. 636These are run within a `TEST_PROTECT` block, the function of which is to handle failures that occur during the test. 637Then, assuming our test is still running and hasn't been ignored, we run `tearDown`. 638No matter what, our last step is to conclude this test before moving on to the next. 639 640Let's say you need to add a call to `fsync` to force all of your output data to flush to a file after each test. 641You could easily insert this after your `UnityConcludeTest` call. 642Maybe you want to write an xml tag before and after each result set. 643Again, you could do this by adding lines to this macro. 644Updates to this macro are for the occasions when you need an action before or after every single test case throughout your entire suite of tests. 645 646## Happy Porting 647 648The defines and macros in this guide should help you port Unity to just about any C target we can imagine. 649If you run into a snag or two, don't be afraid of asking for help on the forums. 650We love a good challenge! 651 652*Find The Latest of This And More at [ThrowTheSwitch.org][]* 653 654[ThrowTheSwitch.org]: https://throwtheswitch.org 655