readme.md
1# Unity Memory
2
3This Framework is an optional add-on to Unity. By including unity.h and then
4unity_memory.h, you have the added ability to track malloc and free calls. This
5addon requires that the stdlib functions be overridden by its own defines. These
6defines will still malloc / realloc / free etc, but will also track the calls
7in order to ensure that you don't have any memory leaks in your programs.
8
9Note that this is only useful in situations where a unit is in charge of both
10the allocation and deallocation of memory. When it is not symmetric, unit testing
11can report a number of false failures. A more advanced runtime tool is required to
12track complete system memory handling.
13
14# Module API
15
16## `UnityMalloc_StartTest` and `UnityMalloc_EndTest`
17
18These must be called at the beginning and end of each test. For simplicity, they can
19be added to `setUp` and `tearDown` in order to do their job. When using the test
20runner generator scripts, these will be automatically added to the runner whenever
21unity_memory.h is included.
22
23## `UnityMalloc_MakeMallocFailAfterCount`
24
25This can be called from the tests themselves. Passing this function a number will
26force the reference counter to start keeping track of malloc calls. During that test,
27if the number of malloc calls exceeds the number given, malloc will immediately
28start returning `NULL`. This allows you to test error conditions. Think of it as a
29simplified mock.
30
31# Configuration
32
33## `UNITY_MALLOC` and `UNITY_FREE`
34
35By default, this module tries to use the real stdlib `malloc` and `free` internally.
36If you would prefer it to use something else, like FreeRTOS's `pvPortMalloc` and
37`pvPortFree`, then you can use these defines to make it so.
38
39## `UNITY_EXCLUDE_STDLIB_MALLOC`
40
41If you would like this library to ignore stdlib or other heap engines completely, and
42manage the memory on its own, then define this. All memory will be handled internally
43(and at likely lower overhead). Note that this is not a very featureful memory manager,
44but is sufficient for most testing purposes.
45
46## `UNITY_INTERNAL_HEAP_SIZE_BYTES`
47
48When using the built-in memory manager (see `UNITY_EXCLUDE_STDLIB_MALLOC`) this define
49allows you to set the heap size this library will use to manage the memory.
50