diff options
Diffstat (limited to 'tinyusb/test/vendor/ceedling/docs')
| -rwxr-xr-x | tinyusb/test/vendor/ceedling/docs/CException.md | 292 | ||||
| -rwxr-xr-x | tinyusb/test/vendor/ceedling/docs/CMock_Summary.md | 603 | ||||
| -rwxr-xr-x | tinyusb/test/vendor/ceedling/docs/CeedlingPacket.md | 2060 | ||||
| -rwxr-xr-x | tinyusb/test/vendor/ceedling/docs/ThrowTheSwitchCodingStandard.md | 206 | ||||
| -rwxr-xr-x | tinyusb/test/vendor/ceedling/docs/UnityAssertionsCheatSheetSuitableforPrintingandPossiblyFraming.pdf | bin | 0 -> 144467 bytes | |||
| -rwxr-xr-x | tinyusb/test/vendor/ceedling/docs/UnityAssertionsReference.md | 779 | ||||
| -rwxr-xr-x | tinyusb/test/vendor/ceedling/docs/UnityConfigurationGuide.md | 433 | ||||
| -rwxr-xr-x | tinyusb/test/vendor/ceedling/docs/UnityGettingStartedGuide.md | 192 | ||||
| -rwxr-xr-x | tinyusb/test/vendor/ceedling/docs/UnityHelperScriptsGuide.md | 260 |
9 files changed, 4825 insertions, 0 deletions
diff --git a/tinyusb/test/vendor/ceedling/docs/CException.md b/tinyusb/test/vendor/ceedling/docs/CException.md new file mode 100755 index 00000000..c3718191 --- /dev/null +++ b/tinyusb/test/vendor/ceedling/docs/CException.md @@ -0,0 +1,292 @@ + +CException +========== + +CException is a basic exception framework for C, suitable for use in +embedded applications. It provides an exception framework similar in +use to C++, but with much less overhead. + + +CException uses C standard library functions `setjmp` and `longjmp` to +operate. As long as the target system has these two functions defined, +this library should be useable with very little configuration. It +even supports environments where multiple program flows are in use, +such as real-time operating systems. + + +There are about a gabillion exception frameworks using a similar +setjmp/longjmp method out there... and there will probably be more +in the future. Unfortunately, when we started our last embedded +project, all those that existed either (a) did not support multiple +tasks (therefore multiple stacks) or (b) were way more complex than +we really wanted. CException was born. + + +*Why use CException?* + + +0. It's ANSI C, and it beats passing error codes around. +1. You want something simple... CException throws a single id. You can + define those ID's to be whatever you like. You might even choose which + type that number is for your project. But that's as far as it goes. + We weren't interested in passing objects or structs or strings... + just simple error codes. +2. Performance... CException can be configured for single tasking or + multitasking. In single tasking, there is very little overhead past + the setjmp/longjmp calls (which are already fast). In multitasking, + your only additional overhead is the time it takes you to determine + a unique task id 0 - num_tasks. + + +For the latest version, go to [ThrowTheSwitch.org](http://throwtheswitch.org) + + +CONTENTS OF THIS DOCUMENT +========================= + +* Usage +* Limitations +*API +* Configuration +* Testing +* License + + +Usage +----- + +Code that is to be protected are wrapped in `Try { } Catch { }` blocks. +The code directly following the Try call is "protected", meaning that +if any Throws occur, program control is directly transferred to the +start of the Catch block. + + +A numerical exception ID is included with Throw, and is made accessible +from the Catch block. + + +Throws can occur from within function calls (nested as deeply as you +like) or directly from within the function itself. + + + +Limitations +----------- + + +This library was made to be as fast as possible, and provide basic +exception handling. It is not a full-blown exception library. Because +of this, there are a few limitations that should be observed in order +to successfully utilize this library: + +1. Do not directly "return" from within a `Try` block, nor `goto` + into or out of a `Try` block. + + *Why?* + + The `Try` macro allocates some local memory and alters a global + pointer. These are cleaned up at the top of the `Catch` macro. + Gotos and returns would bypass some of these steps, resulting in + memory leaks or unpredictable behavior. + + +2. If (a) you change local (stack) variables within your `Try` block, + AND (b) wish to make use of the updated values after an exception + is thrown, those variables should be made `volatile`. Note that this + is ONLY for locals and ONLY when you need access to them after a + `Throw`. + + *Why?* + + Compilers optimize. There is no way to guarantee that the actual + memory location was updated and not just a register unless the + variable is marked volatile. + + +3. Memory which is `malloc`'d or `new`'d is not automatically released + when an error is thrown. This will sometimes be desirable, and + othertimes may not. It will be the responsibility of the `Catch` + block to perform this kind of cleanup. + + *Why?* + + There's just no easy way to track `malloc`'d memory, etc., without + replacing or wrapping malloc calls or something like that. This + is a light framework, so these options were not desirable. + + + +API +--- + +###Try + +`Try` is a macro which starts a protected block. It MUST be followed by +a pair of braces or a single protected line (similar to an 'if'), +enclosing the data that is to be protected. It **must** be followed by a +`Catch` block (don't worry, you'll get compiler errors to let you know if +you mess any of that up). + + +###Catch(e) + +`Catch` is a macro which ends the `Try` block and starts the error handling +block. The `Catch` block is called if and only if an exception was thrown +while within the `Try` block. This error was thrown by a `Throw` call +somewhere within `Try` (or within a function called within `Try`, or a function +called by a function called within `Try`, etc). + +The single parameter `e` is filled with the error code which was thrown. +This can be used for reporting, conditional cleanup, etc. (or you can just +ignore it if you really want... people ignore return codes all the time, +right?). `e` should be of type `EXCEPTION_T` + + +###Throw(e) + +This is the method of throwing an error. A `Throw` should only occur from within a +protected (`Try` ... `Catch`) block, though it may easily be nested many function +calls deep without an impact on performance or functionality. `Throw` takes +a single argument, which is an exception id which will be passed to `Catch` +as the reason for the error. + +If you wish to rethrow an error, this can be done by calling `Throw(e)` with +the error code you just caught. It **is** valid to throw from a catch block. + + +###ExitTry() + +On rare occasion, you might want to immediately exit your current `Try` block +but **not** treat this as an error. Don't run the `Catch`. Just start executing +from after the `Catch` as if nothing had happened... That's what `ExitTry` is +for. + + +CONFIGURATION +------------- + +CException is a mostly portable library. It has one universal +dependency, and some macros which are required if working in a +multi-tasking environment. + +1. The standard C library setjmp must be available. Since this is part + of the standard library, chances are good that you'll be fine. + +2. If working in a multitasking environment, methods for obtaining an + index into an array of frames and to get the overall number of + id's are required. If the OS supports a method to retrieve Task + ID's, and those Tasks are number 0, 1, 2... you are in an ideal + situation. Otherwise, a more creative mapping function may be + required. Note that this function is likely to be called twice + for each protected block and once during a throw. This is the + only overhead in the system. + + +Exception.h +----------- + +By convention, most projects include `Exception.h` which defines any +further requirements, then calls `CException.h` to do the gruntwork. All +of these are optional. You could directly include `CException.h` if +you wanted and just use the defaults provided. + +* `EXCEPTION_T` + * Set this to the type you want your exception id's to be. Defaults to 'unsigned int'. + +* `EXCEPTION_NONE` + * Set this to a number which will never be an exception id in your system. Defaults to `0x5a5a5a5a`. + +* `EXCEPTION_GET_ID` + * If in a multi-tasking environment, this should be + set to be a call to the function described in #2 above. + Defaults to just return `0` all the time (good for + single tasking environments) + +* `EXCEPTION_NUM_ID` + * If in a multi-tasking environment, this should be set + to the number of ID's required (usually the number of + tasks in the system). Defaults to `1` (for single + tasking environments). + +* `CEXCEPTION_NO_CATCH_HANDLER(id)` + * This macro can be optionally specified. + It allows you to specify code to be called when a Throw + is made outside of `Try` ... `Catch` protection. Consider + this the emergency fallback plan for when something has + gone terribly wrong. + + +You may also want to include any header files which will commonly be +needed by the rest of your application where it uses exception handling +here. For example, OS header files or exception codes would be useful. + + +Finally, there are some hook macros which you can implement to inject +your own target-specific code in particular places. It is a rare instance +where you will need these, but they are here if you need them: + + +* `CEXCEPTION_HOOK_START_TRY` + * called immediately before the Try block + +* `CEXCEPTION_HOOK_HAPPY_TRY` + * called immediately after the Try block if no exception was thrown + +* `CEXCEPTION_HOOK_AFTER_TRY` + * called immediately after the Try block OR before an exception is caught + +* `CEXCEPTION_HOOK_START_CATCH` + * called immediately before the catch + + + +TESTING +------- + + +If you want to validate that CException works with your tools or that +it works with your custom configuration, you may want to run the test +suite. + + +The test suite included makes use of the `Unity` Test Framework. It will +require a native C compiler. The example makefile uses MinGW's gcc. +Modify the makefile to include the proper paths to tools, then run `make` +to compile and run the test application. + +* `C_COMPILER` + * The C compiler to use to perform the tests + +* `C_LIBS` + * The path to the C libraries (including setjmp) + +* `UNITY_DIR` + * The path to the Unity framework (required to run tests) + (get it at [ThrowTheSwitch.org](http://throwtheswitch.org)) + + + +LICENSE +------- + +This software is licensed under the MIT License + +Copyright (c) 2007-2017 Mark VanderVoord + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/tinyusb/test/vendor/ceedling/docs/CMock_Summary.md b/tinyusb/test/vendor/ceedling/docs/CMock_Summary.md new file mode 100755 index 00000000..87f9c00b --- /dev/null +++ b/tinyusb/test/vendor/ceedling/docs/CMock_Summary.md @@ -0,0 +1,603 @@ +CMock: A Summary +================ + +*[ThrowTheSwitch.org](http://throwtheswitch.org)* + +*This documentation is released under a Creative Commons 3.0 Attribution Share-Alike License* + + +What Exactly Are We Talking About Here? +--------------------------------------- + +CMock is a nice little tool which takes your header files and creates +a Mock interface for it so that you can more easily unit test modules +that touch other modules. For each function prototype in your +header, like this one: + + int DoesSomething(int a, int b); + + +...you get an automatically generated DoesSomething function +that you can link to instead of your real DoesSomething function. +By using this Mocked version, you can then verify that it receives +the data you want, and make it return whatever data you desire, +make it throw errors when you want, and more... Create these for +everything your latest real module touches, and you're suddenly +in a position of power: You can control and verify every detail +of your latest creation. + +To make that easier, CMock also gives you a bunch of functions +like the ones below, so you can tell that generated DoesSomething +function how to behave for each test: + + void DoesSomething_ExpectAndReturn(int a, int b, int toReturn); + void DoesSomething_ExpectAndThrow(int a, int b, EXCEPTION_T error); + void DoesSomething_StubWithCallback(CMOCK_DoesSomething_CALLBACK YourCallback); + void DoesSomething_IgnoreAndReturn(int toReturn); + + +You can pile a bunch of these back to back, and it remembers what +you wanted to pass when, like so: + + test_CallsDoesSomething_ShouldDoJustThat(void) + { + DoesSomething_ExpectAndReturn(1,2,3); + DoesSomething_ExpectAndReturn(4,5,6); + DoesSomething_ExpectAndThrow(7,8, STATUS_ERROR_OOPS); + + CallsDoesSomething( ); + } + + +This test will call CallsDoesSomething, which is the function +we are testing. We are expecting that function to call DoesSomething +three times. The first time, we check to make sure it's called +as DoesSomething(1, 2) and we'll magically return a 3. The second +time we check for DoesSomething(4, 5) and we'll return a 6. The +third time we verify DoesSomething(7, 8) and we'll throw an error +instead of returning anything. If CallsDoesSomething gets +any of this wrong, it fails the test. It will fail if you didn't +call DoesSomething enough, or too much, or with the wrong arguments, +or in the wrong order. + +CMock is based on Unity, which it uses for all internal testing. +It uses Ruby to do all the main work (versions 2.0.0 and above). + + +Installing +========== + +The first thing you need to do to install CMock is to get yourself +a copy of Ruby. If you're on linux or osx, you probably already +have it. You can prove it by typing the following: + + ruby --version + + +If it replied in a way that implies ignorance, then you're going to +need to install it. You can go to [ruby-lang](https://ruby-lang.org) +to get the latest version. You're also going to need to do that if it +replied with a version that is older than 2.0.0. Go ahead. We'll wait. + +Once you have Ruby, you have three options: + +* Clone the latest [CMock repo on github](https://github.com/ThrowTheSwitch/CMock/) +* Download the latest [CMock zip from github](https://github.com/ThrowTheSwitch/CMock/) +* Install Ceedling (which has it built in!) through your commandline using `gem install ceedling`. + + +Generated Mock Module Summary +============================= + +In addition to the mocks themselves, CMock will generate the +following functions for use in your tests. The expect functions +are always generated. The other functions are only generated +if those plugins are enabled: + + +Expect: +------- + +Your basic staple Expects which will be used for most of your day +to day CMock work. By calling this, you are telling CMock that you +expect that function to be called during your test. It also specifies +which arguments you expect it to be called with, and what return +value you want returned when that happens. You can call this function +multiple times back to back in order to queue up multiple calls. + +* `void func(void)` => `void func_Expect(void)` +* `void func(params)` => `void func_Expect(expected_params)` +* `retval func(void)` => `void func_ExpectAndReturn(retval_to_return)` +* `retval func(params)` => `void func_ExpectAndReturn(expected_params, retval_to_return)` + + +ExpectAnyArgs: +-------------- + +This behaves just like the Expects calls, except that it doesn't really +care what the arguments are that the mock gets called with. It still counts +the number of times the mock is called and it still handles return values +if there are some. + +* `void func(void)` => `void func_ExpectAnyArgs(void)` +* `void func(params)` => `void func_ExpectAnyArgs(void)` +* `retval func(void)` => `void func_ExpectAnyArgsAndReturn(retval_to_return)` +* `retval func(params)` => `void func_ExpectAnyArgsAndReturn(retval_to_return)` + + +Array: +------ + +An ExpectWithArray is another variant of Expect. Like expect, it cares about +the number of times a mock is called, the arguments it is called with, and the +values it is to return. This variant has another feature, though. For anything +that resembles a pointer or array, it breaks the argument into TWO arguments. +The first is the original pointer. The second specify the number of elements +it is to verify of that array. If you specify 1, it'll check one object. If 2, +it'll assume your pointer is pointing at the first of two elements in an array. +If you specify zero elements, it will check just the pointer if +`:smart` mode is configured or fail if `:compare_data` is set. + +* `void func(void)` => (nothing. In fact, an additional function is only generated if the params list contains pointers) +* `void func(ptr * param, other)` => `void func_ExpectWithArray(ptr* param, int param_depth, other)` +* `retval func(void)` => (nothing. In fact, an additional function is only generated if the params list contains pointers) +* `retval func(other, ptr* param)` => `void func_ExpectWithArrayAndReturn(other, ptr* param, int param_depth, retval_to_return)` + + +Ignore: +------- + +Maybe you don't care about the number of times a particular function is called or +the actual arguments it is called with. In that case, you want to use Ignore. Ignore +only needs to be called once per test. It will then ignore any further calls to that +particular mock. The IgnoreAndReturn works similarly, except that it has the added +benefit of knowing what to return when that call happens. If the mock is called more +times than IgnoreAndReturn was called, it will keep returning the last value without +complaint. If it's called less times, it will also ignore that. You SAID you didn't +care how many times it was called, right? + +* `void func(void)` => `void func_Ignore(void)` +* `void func(params)` => `void func_Ignore(void)` +* `retval func(void)` => `void func_IgnoreAndReturn(retval_to_return)` +* `retval func(params)` => `void func_IgnoreAndReturn(retval_to_return)` + + +Ignore Arg: +------------ + +Maybe you overall want to use Expect and its similar variations, but you don't care +what is passed to a particular argument. This is particularly useful when that argument +is a pointer to a value that is supposed to be filled in by the function. You don't want +to use ExpectAnyArgs, because you still care about the other arguments. Instead, before +any of your Expect calls are made, you can call this function. It tells CMock to ignore +a particular argument for the rest of this test, for this mock function. + +* `void func(params)` => `void func_IgnoreArg_paramName(void)` + + +ReturnThruPtr: +-------------- + +Another option which operates on a particular argument of a function is the ReturnThruPtr +plugin. For every argument that resembles a pointer or reference, CMock generates an +instance of this function. Just as the AndReturn functions support injecting one or more +return values into a queue, this function lets you specify one or more return values which +are queued up and copied into the space being pointed at each time the mock is called. + +* `void func(param1)` => `void func_ReturnThruPtr_paramName(val_to_return)` +* => `void func_ReturnArrayThruPtr_paramName(cal_to_return, len)` +* => `void func_ReturnMemThruPtr_paramName(val_to_return, size)` + + +Callback: +--------- + +If all those other options don't work, and you really need to do something custom, you +still have a choice. As soon as you stub a callback in a test, it will call the callback +whenever the mock is encountered and return the retval returned from the callback (if any) +instead of performing the usual expect checks. It can be configured to check the arguments +first (like expects) or just jump directly to the callback. + +* `void func(void)` => `void func_StubWithCallback(CMOCK_func_CALLBACK callback)` +where `CMOCK_func_CALLBACK` looks like: `void func(int NumCalls)` +* `void func(params)` => `void func_StubWithCallback(CMOCK_func_CALLBACK callback)` +where `CMOCK_func_CALLBACK` looks like: `void func(params, int NumCalls)` +* `retval func(void)` => `void func_StubWithCallback(CMOCK_func_CALLBACK callback)` +where `CMOCK_func_CALLBACK` looks like: `retval func(int NumCalls)` +* `retval func(params)` => `void func_StubWithCallback(CMOCK_func_CALLBACK callback)` +where `CMOCK_func_CALLBACK` looks like: `retval func(params, int NumCalls)` + + +Cexception: +----------- + +Finally, if you are using Cexception for error handling, you can use this to throw errors +from inside mocks. Like Expects, it remembers which call was supposed to throw the error, +and it still checks parameters first. + +* `void func(void)` => `void func_ExpectAndThrow(value_to_throw)` +* `void func(params)` => `void func_ExpectAndThrow(expected_params, value_to_throw)` +* `retval func(void)` => `void func_ExpectAndThrow(value_to_throw)` +* `retval func(params)` => `void func_ExpectAndThrow(expected_params, value_to_throw)` + + + +Running CMock +============= + +CMock is a Ruby script and class. You can therefore use it directly +from the command line, or include it in your own scripts or rakefiles. + + +Mocking from the Command Line +----------------------------- + +After unpacking CMock, you will find cmock.rb in the 'lib' directory. +This is the file that you want to run. It takes a list of header files +to be mocked, as well as an optional yaml file for a more detailed +configuration (see config options below). + +For example, this will create three mocks using the configuration +specified in MyConfig.yml: + + ruby cmock.rb -oMyConfig.yml super.h duper.h awesome.h + +And this will create two mocks using the default configuration: + + ruby cmock.rb ../mocking/stuff/is/fun.h ../try/it/yourself.h + + +Mocking From Scripts or Rake +---------------------------- + +CMock can be used directly from your own scripts or from a rakefile. +Start by including cmock.rb, then create an instance of CMock. +When you create your instance, you may initialize it in one of +three ways. + +You may specify nothing, allowing it to run with default settings: + + require 'cmock.rb' + cmock = CMock.new + +You may specify a YAML file containing the configuration options +you desire: + + cmock = CMock.new('../MyConfig.yml') + +You may specify the options explicitly: + + cmock = Cmock.new(:plugins => [:cexception, :ignore], :mock_path => 'my/mocks/') + + +Config Options: +--------------- + +The following configuration options can be specified in the +yaml file or directly when instantiating. + +Passed as Ruby, they look like this: + + { :attributes => [“__funky”, “__intrinsic”], :when_ptr => :compare } + +Defined in the yaml file, they look more like this: + + :cmock: + :attributes: + - __funky + - __intrinsic + :when_ptr: :compare + +In all cases, you can just include the things that you want to override +from the defaults. We've tried to specify what the defaults are below. + +* `:attributes`: + These are attributes that CMock should ignore for you for testing + purposes. Custom compiler extensions and externs are handy things to + put here. If your compiler is choking on some extended syntax, this + is often a good place to look. + + * defaults: ['__ramfunc', '__irq', '__fiq', 'register', 'extern'] + * **note:** this option will reinsert these attributes onto the mock's calls. + If that isn't what you are looking for, check out :strippables. + +* `:c_calling_conventions`: + Similarly, CMock may need to understand which C calling conventions + might show up in your codebase. If it encounters something it doesn't + recognize, it's not going to mock it. We have the most common covered, + but there are many compilers out there, and therefore many other options. + + * defaults: ['__stdcall', '__cdecl', '__fastcall'] + * **note:** this option will reinsert these attributes onto the mock's calls. + If that isn't what you are looking for, check out :strippables. + +* `:callback_after_arg_check`: + Tell `:callback` plugin to do the normal argument checking **before** it + calls the callback function by setting this to true. When false, the + callback function is called **instead** of the argument verification. + + * default: false + +* `:callback_include_count`: + Tell `:callback` plugin to include an extra parameter to specify the + number of times the callback has been called. If set to false, the + callback has the same interface as the mocked function. This can be + handy when you're wanting to use callback as a stub. + + * default: true + +* `:cexception_include`: + Tell `:cexception` plugin where to find CException.h... You only need to + define this if it's not in your build path already... which it usually + will be for the purpose of your builds. + + * default: *nil* + +* `:enforce_strict_ordering`: + CMock always enforces the order that you call a particular function, + so if you expect GrabNabber(int size) to be called three times, it + will verify that the sizes are in the order you specified. You might + *also* want to make sure that all different functions are called in a + particular order. If so, set this to true. + + * default: false + +* `:framework`: + Currently the only option is `:unity.` Eventually if we support other + unity test frameworks (or if you write one for us), they'll get added + here. + + : default: :unity + +* `:includes`: + An array of additional include files which should be added to the + mocks. Useful for global types and definitions used in your project. + There are more specific versions if you care WHERE in the mock files + the includes get placed. You can define any or all of these options. + + * `:includes` + * `:includes_h_pre_orig_header` + * `:includes_h_post_orig_header` + * `:includes_c_pre_header` + * `:includes_c_post_header` + * default: nil #for all 5 options + +* `:memcmp_if_unknown`: + C developers create a lot of types, either through typedef or preprocessor + macros. CMock isn't going to automatically know what you were thinking all + the time (though it tries its best). If it comes across a type it doesn't + recognize, you have a choice on how you want it to handle it. It can either + perform a raw memory comparison and report any differences, or it can fail + with a meaningful message. Either way, this feature will only happen after + all other mechanisms have failed (The thing encountered isn't a standard + type. It isn't in the :treat_as list. It isn't in a custom unity_helper). + + * default: true + +* `:mock_path`: + The directory where you would like the mock files generated to be + placed. + + * default: mocks + +* `:mock_prefix`: + The prefix to prepend to your mock files. For example, if it's “Mock”, a file + “USART.h” will get a mock called “MockUSART.c”. This CAN be used with a suffix + at the same time. + + * default: Mock + +* `:mock_suffix`: + The suffix to append to your mock files. For example, it it's "_Mock", a file + "USART.h" will get a mock called "USART_Mock.h". This CAN be used with a prefix + at the same time. + + * default: "" + +* `:plugins`: + An array of which plugins to enable. ':expect' is always active. Also + available currently: + + * `:ignore` + * `:ignore_arg` + * `:expect_any_args` + * `:array` + * `:cexception` + * `:callback` + * `:return_thru_ptr` + +* `:strippables`: + An array containing a list of items to remove from the header + before deciding what should be mocked. This can be something simple + like a compiler extension CMock wouldn't recognize, or could be a + regex to reject certain function name patterns. This is a great way to + get rid of compiler extensions when your test compiler doesn't support + them. For example, use `:strippables: ['(?:functionName\s*\(+.*?\)+)']` + to prevent a function `functionName` from being mocked. By default, it + is ignoring all gcc attribute extensions. + + * default: ['(?:__attribute__\s*\(+.*?\)+)'] + +* `:subdir`: + This is a relative subdirectory for your mocks. Set this to e.g. "sys" in + order to create a mock for `sys/types.h` in `(:mock_path)/sys/`. + + * default: "" + +* `:treat_as`: + The `:treat_as` list is a shortcut for when you have created typedefs + of standard types. Why create a custom unity helper for UINT16 when + the unity function TEST_ASSERT_EQUAL_HEX16 will work just perfectly? + Just add 'UINT16' => 'HEX16' to your list (actually, don't. We already + did that one for you). Maybe you have a type that is a pointer to an + array of unsigned characters? No problem, just add 'UINT8_T*' => + 'HEX8*' + + * NOTE: unlike the other options, your specifications MERGE with the + default list. Therefore, if you want to override something, you must + reassign it to something else (or to *nil* if you don't want it) + + * default: + * 'int': 'INT' + * 'char': 'INT8' + * 'short': 'INT16' + * 'long': 'INT' + * 'int8': 'INT8' + * 'int16': 'INT16' + * 'int32': 'INT' + * 'int8_t': 'INT8' + * 'int16_t': 'INT16' + * 'int32_t': 'INT' + * 'INT8_T': 'INT8' + * 'INT16_T': 'INT16' + * 'INT32_T': 'INT' + * 'bool': 'INT' + * 'bool_t': 'INT' + * 'BOOL': 'INT' + * 'BOOL_T': 'INT' + * 'unsigned int': 'HEX32' + * 'unsigned long': 'HEX32' + * 'uint32': 'HEX32' + * 'uint32_t': 'HEX32' + * 'UINT32': 'HEX32' + * 'UINT32_T': 'HEX32' + * 'void*': 'HEX8_ARRAY' + * 'unsigned short': 'HEX16' + * 'uint16': 'HEX16' + * 'uint16_t': 'HEX16' + * 'UINT16': 'HEX16' + * 'UINT16_T': 'HEX16' + * 'unsigned char': 'HEX8' + * 'uint8': 'HEX8' + * 'uint8_t': 'HEX8' + * 'UINT8': 'HEX8' + * 'UINT8_T': 'HEX8' + * 'char*': 'STRING' + * 'pCHAR': 'STRING' + * 'cstring': 'STRING' + * 'CSTRING': 'STRING' + * 'float': 'FLOAT' + * 'double': 'FLOAT' + +* `:treat_as_void`: + We've seen "fun" legacy systems typedef 'void' with a custom type, + like MY_VOID. Add any instances of those to this list to help CMock + understand how to deal with your code. + + * default: [] + +* `:treat_externs`: + This specifies how you want CMock to handle functions that have been + marked as extern in the header file. Should it mock them? + + * `:include` will mock externed functions + * `:exclude` will ignore externed functions (default). + +* `:unity_helper_path`: + If you have created a header with your own extensions to unity to + handle your own types, you can set this argument to that path. CMock + will then automagically pull in your helpers and use them. The only + trick is that you make sure you follow the naming convention: + `UNITY_TEST_ASSERT_EQUAL_YourType`. If it finds macros of the right + shape that match that pattern, it'll use them. + + * default: [] + +* `:verbosity`: + How loud should CMock be? + + * 0 for errors only + * 1 for errors and warnings + * 2 for normal (default) + * 3 for verbose + +* `:weak`: + When set this to some value, the generated mocks are defined as weak + symbols using the configured format. This allows them to be overridden + in particular tests. + + * Set to '__attribute ((weak))' for weak mocks when using GCC. + * Set to any non-empty string for weak mocks when using IAR. + * default: "" + +* `:when_no_prototypes`: + When you give CMock a header file and ask it to create a mock out of + it, it usually contains function prototypes (otherwise what was the + point?). You can control what happens when this isn't true. You can + set this to `:warn,` `:ignore,` or `:error` + + * default: :warn + +* `:when_ptr`: + You can customize how CMock deals with pointers (c strings result in + string comparisons... we're talking about **other** pointers here). Your + options are `:compare_ptr` to just verify the pointers are the same, + `:compare_data` or `:smart` to verify that the data is the same. + `:compare_data` and `:smart` behaviors will change slightly based on + if you have the array plugin enabled. By default, they compare a + single element of what is being pointed to. So if you have a pointer + to a struct called ORGAN_T, it will compare one ORGAN_T (whatever that + is). + + * default: :smart + +* `:fail_on_unexpected_calls`: + By default, CMock will fail a test if a mock is called without _Expect and _Ignore + called first. While this forces test writers to be more explicit in their expectations, + it can clutter tests with _Expect or _Ignore calls for functions which are not the focus + of the test. While this is a good indicator that this module should be refactored, some + users are not fans of the additional noise. + + Therefore, :fail_on_unexpected_calls can be set to false to force all mocks to start with + the assumption that they are operating as _Ignore unless otherwise specified. + + * default: true + * **note:** + If this option is disabled, the mocked functions will return + a default value (0) when called (and only if they have to return something of course). + + +Compiled Options: +----------------- + +A number of #defines also exist for customizing the cmock experience. +Feel free to pass these into your compiler or whatever is most +convenient. CMock will otherwise do its best to guess what you want +based on other settings, particularly Unity's settings. + +* `CMOCK_MEM_STATIC` or `CMOCK_MEM_DYNAMIC` + Define one of these to determine if you want to dynamically add + memory during tests as required from the heap. If static, you + can control the total footprint of Cmock. If dynamic, you will + need to make sure you make some heap space available for Cmock. + +* `CMOCK_MEM_SIZE` + In static mode this is the total amount of memory you are allocating + to Cmock. In Dynamic mode this is the size of each chunk allocated + at once (larger numbers grab more memory but require less mallocs). + +* `CMOCK_MEM_ALIGN` + The way to align your data to. Not everything is as flexible as + a PC, as most embedded designers know. This defaults to 2, meaning + align to the closest 2^2 -> 4 bytes (32 bits). You can turn off alignment + by setting 0, force alignment to the closest uint16 with 1 or even + to the closest uint64 with 3. + +* `CMOCK_MEM_PTR_AS_INT` + This is used internally to hold pointers... it needs to be big + enough. On most processors a pointer is the same as an unsigned + long... but maybe that's not true for yours? + +* `CMOCK_MEM_INDEX_TYPE` + This needs to be something big enough to point anywhere in Cmock's + memory space... usually it's an unsigned int. + +Examples +======== + +You can look in the [examples directory](/examples/) for a couple of examples on how +you might tool CMock into your build process. You may also want to consider +using [Ceedling](https://throwtheswitch.org/ceedling). Please note that +these examples are meant to show how the build process works. They have +failing tests ON PURPOSE to show what that would look like. Don't be alarmed. ;) + diff --git a/tinyusb/test/vendor/ceedling/docs/CeedlingPacket.md b/tinyusb/test/vendor/ceedling/docs/CeedlingPacket.md new file mode 100755 index 00000000..88cd0202 --- /dev/null +++ b/tinyusb/test/vendor/ceedling/docs/CeedlingPacket.md @@ -0,0 +1,2060 @@ +[All code is copyright © 2010-2012 Ceedling Project +by Mike Karlesky, Mark VanderVoord, and Greg Williams. + +This Documentation Is Released Under a +Creative Commons 3.0 Attribution Share-Alike License] + +What the What? + +Assembling build environments for C projects - especially with +automated unit tests - is a pain. Whether it's Make or Rake or Premake +or what-have-you, set up with an all-purpose build environment +tool is tedious and requires considerable glue code to pull together +the necessary tools and libraries. Ceedling allows you to generate +an entire test and build environment for a C project from a single +YAML configuration file. Ceedling is written in Ruby and works +with the Rake build tool plus other goodness like Unity and CMock +- the unit testing and mocking frameworks for C. Ceedling and +its complementary tools can support the tiniest of embedded +processors, the beefiest 64 bit power houses available, and +everything in between. + +For a build project including unit tests and using the default +toolchain gcc, the configuration file could be as simple as this: + +```yaml +:project: + :build_root: project/build/ + :release_build: TRUE + +:paths: + :test: + - tests/** + :source: + - source/** +``` + +From the command line, to build the release version of your project, +you would simply run `ceedling release`. To run all your unit tests, +you would run `ceedling test:all`. That's it! + +Of course, many more advanced options allow you to configure +your project with a variety of features to meet a variety of needs. +Ceedling can work with practically any command line toolchain +and directory structure – all by way of the configuration file. +Further, because Ceedling piggy backs on Rake, you can add your +own Rake tasks to accomplish project tasks outside of testing +and release builds. A facility for plugins also allows you to +extend Ceedling's capabilities for needs such as custom code +metrics reporting and coverage testing. + +What's with this Name? + +Glad you asked. Ceedling is tailored for unit tested C projects +and is built upon / around Rake (Rake is a Make replacement implemented +in the Ruby scripting language). So, we've got C, our Rake, and +the fertile soil of a build environment in which to grow and tend +your project and its unit tests. Ta da - _Ceedling_. + +What Do You Mean "tailored for unit tested C projects"? + +Well, we like to write unit tests for our C code to make it lean and +mean (that whole [Test-Driven Development][tdd] +thing). Along the way, this style of writing C code spawned two +tools to make the job easier: a unit test framework for C called +_Unity_ and a mocking library called _CMock_. And, though it's +not directly related to testing, a C framework for exception +handling called _CException_ also came along. + +[tdd]: http://en.wikipedia.org/wiki/Test-driven_development + +These tools and frameworks are great, but they require quite +a bit of environment support to pull them all together in a convenient, +usable fashion. We started off with Rakefiles to assemble everything. +These ended up being quite complicated and had to be hand-edited +or created anew for each new project. Ceedling replaces all that +tedium and rework with a configuration file that ties everything +together. + +Though Ceedling is tailored for unit testing, it can also go right ahead +and build your final binary release artifact for you as well. Or, +Ceedling and your tests can live alongside your existing release build +setup. That said, Ceedling is more powerful as a unit test build +environment than it is a general purpose release build environment; +complicated projects including separate bootloaders or multiple library +builds, etc. are not its strong suit. + +Hold on. Back up. Ruby? Rake? YAML? Unity? CMock? CException? + +Seem overwhelming? It's not bad at all, and for the benefits tests +bring us, it's all worth it. + +[Ruby][] is a handy scripting +language like Perl or Python. It's a modern, full featured language +that happens to be quite handy for accomplishing tasks like code +generation or automating one's workflow while developing in +a compiled language such as C. + +[Ruby]: http://www.ruby-lang.org/en/ + +[Rake][] is a utility written in Ruby +for accomplishing dependency tracking and task automation +common to building software. It's a modern, more flexible replacement +for [Make][]). +Rakefiles are Ruby files, but they contain build targets similar +in nature to that of Makefiles (but you can also run Ruby code in +your Rakefile). + +[Rake]: http://rubyrake.org/ +[Make]: http://en.wikipedia.org/wiki/Make_(software) + +[YAML][] is a "human friendly data serialization standard for all +programming languages." It's kinda like a markup language, but don't +call it that. With a YAML library, you can [serialize][] data structures +to and from the file system in a textual, human readable form. Ceedling +uses a serialized data structure as its configuration input. + +[YAML]: http://en.wikipedia.org/wiki/Yaml +[serialize]: http://en.wikipedia.org/wiki/Serialization + +[Unity] is a [unit test framework][test] for C. It provides facilities +for test assertions, executing tests, and collecting / reporting test +results. Unity derives its name from its implementation in a single C +source file (plus two C header files) and from the nature of its +implementation - Unity will build in any C toolchain and is configurable +for even the very minimalist of processors. + +[Unity]: http://github.com/ThrowTheSwitch/Unity +[test]: http://en.wikipedia.org/wiki/Unit_testing + +[CMock] is a tool written in Ruby able to generate entire +[mock functions][mock] in C code from a given C header file. Mock +functions are invaluable in [interaction-based unit testing][ut]. +CMock's generated C code uses Unity. + +[CMock]: http://github.com/ThrowTheSwitch/CMock +[mock]: http://en.wikipedia.org/wiki/Mock_object +[ut]: http://martinfowler.com/articles/mocksArentStubs.html + +[CException] is a C source and header file that provide a simple +[exception mechanism][exn] for C by way of wrapping up the +[setjmp / longjmp][setjmp] standard library calls. Exceptions are a much +cleaner and preferable alternative to managing and passing error codes +up your return call trace. + +[CException]: http://github.com/ThrowTheSwitch/CException +[exn]: http://en.wikipedia.org/wiki/Exception_handling +[setjmp]: http://en.wikipedia.org/wiki/Setjmp.h + +Notes +----- + +* YAML support is included with Ruby - requires no special installation + or configuration. + +* Unity, CMock, and CException are bundled with Ceedling, and + Ceedling is designed to glue them all together for your project + as seamlessly as possible. + + +Installation & Setup: What Exactly Do I Need to Get Started? +------------------------------------------------------------ + +As a [Ruby gem](http://docs.rubygems.org/read/chapter/1): + +1. [Download and install Ruby](http://www.ruby-lang.org/en/downloads/) + +2. Use Ruby's command line gem package manager to install Ceedling: + `gem install ceedling` + (Unity, CMock, and CException come along with Ceedling for free) + +3. Execute Ceedling at command line to create example project + or an empty Ceedling project in your filesystem (executing + `ceedling help` first is, well, helpful). + +Gem install notes: + +1. Steps 1-2 are a one time affair for your local environment. + When steps 1-2 are completed once, only step 3 is needed for + each new project. + + + +General notes: + +1. Certain advanced features of Ceedling rely on gcc and cpp + as preprocessing tools. In most *nix systems, these tools + are already available. For Windows environments, we recommend + the [mingw project](http://www.mingw.org/) (Minimalist + GNU for Windows). This represents an optional, additional + setup / installation step to complement the list above. Upon + installing mingw ensure your system path is updated or set + [:environment][:path] in your `project.yml` file (see + environment section later in this document). + +2. To use a project file name other than the default `project.yml` + or place the project file in a directory other than the one + in which you'll run Rake, create an environment variable + `CEEDLING_MAIN_PROJECT_FILE` with your desired project + file path. + +3. To better understand Rake conventions, Rake execution, + and Rakefiles, consult the [Rake tutorial, examples, and + user guide](http://rubyrake.org/). + +4. When using Ceedling in Windows environments, a test file name may + not include the sequences “patch” or “setup”. The Windows Installer + Detection Technology (part of UAC), requires administrator + privileges to execute file names with these strings. + + + +Now What? How Do I Make It GO? +------------------------------ + +We're getting a little ahead of ourselves here, but it's good +context on how to drive this bus. Everything is done via the command +line. We'll cover conventions and how to actually configure +your project in later sections. + +To run tests, build your release artifact, etc., you will be interacting +with Rake on the command line. Ceedling works with Rake to present +you with named tasks that coordinate the file generation and +build steps needed to accomplish something useful. You can also +add your own independent Rake tasks or create plugins to extend +Ceedling (more on this later). + + +* `ceedling [no arguments]`: + + Run the default Rake task (conveniently recognized by the name default + by Rake). Neither Rake nor Ceedling provide a default task. Rake will + abort if run without arguments when no default task is defined. You can + conveniently define a default task in the Rakefile discussed in the + preceding setup & installation section of this document. + +* `ceedling -T`: + + List all available Rake tasks with descriptions (Rake tasks without + descriptions are not listed). -T is a command line switch for Rake and + not the same as tasks that follow. + +* `ceedling <tasks...> --trace`: + + For advanced users troubleshooting a confusing build error, debug + Ceedling or a plugin, --trace provides a stack trace of dependencies + walked during task execution and any Ruby failures along the way. Note + that --trace is a command line switch for Rake and is not the same as + tasks that follow. + +* `ceedling environment`: + + List all configured environment variable names and string values. This + task is helpful in verifying the evaluatio of any Ruby expressions in + the [:environment] section of your config file.`: Note: Ceedling may + set some convenience environment variables by default. + +* `ceedling paths:*`: + + List all paths collected from [:paths] entries in your YAML config + file where * is the name of any section contained in [:paths]. This + task is helpful in verifying the expansion of path wildcards / globs + specified in the [:paths] section of your config file. + +* `ceedling files:assembly` +* `ceedling files:header` +* `ceedling files:source` +* `ceedling files:test` + + List all files and file counts collected from the relevant search + paths specified by the [:paths] entries of your YAML config file. The + files:assembly task will only be available if assembly support is + enabled in the [:release_build] section of your configuration file. + +* `ceedling options:*`: + + Load and merge configuration settings into the main project + configuration. Each task is named after a *.yml file found in the + configured options directory. See documentation for the configuration + setting [:project][:options_path] and for options files in advanced + topics. + +* `ceedling test:all`: + + Run all unit tests (rebuilding anything that's changed along the way). + +* `ceedling test:delta`: + + Run only those unit tests for which the source or test files have + changed (i.e. incremental build). Note: with the + [:project][:use_test_preprocessor] configuration file option set, + runner files are always regenerated limiting the total efficiency this + text execution option can afford. + +* `ceedling test:*`: + + Execute the named test file or the named source file that has an + accompanying test. No path. Examples: ceedling test:foo.c or ceed + test:test_foo.c + +* `ceedling test:pattern[*]`: + + Execute any tests whose name and/or path match the regular expression + pattern (case sensitive). Example: ceedling "test:pattern[(I|i)nit]" will + execute all tests named for initialization testing. Note: quotes may + be necessary around the ceedling parameter to distinguish regex characters + from command line operators. + +* `ceedling test:path[*]`: + + Execute any tests whose path contains the given string (case + sensitive). Example: ceedling test:path[foo/bar] will execute all tests + whose path contains foo/bar. Note: both directory separator characters + / and \ are valid. + +* `ceedling release`: + + Build all source into a release artifact (if the release build option + is configured). + +* `ceedling release:compile:*`: + + Sometimes you just need to compile a single file dagnabit. Example: + ceedling release:compile:foo.c + +* `ceedling release:assemble:*`: + + Sometimes you just need to assemble a single file doggonit. Example: + ceedling release:assemble:foo.s + +* `ceedling module:create[Filename]`: +* `ceedling module:create[<Path:>Filename]`: + + It's often helpful to create a file automatically. What's better than + that? Creating a source file, a header file, and a corresponding test + file all in one step! + + There are also patterns which can be specified to automatically generate + a bunch of files. Try `ceedling module:create[Poodles,mch]` for example! + + The module generator has several options you can configure. + F.e. Generating the source/header/test file in a subdirectory (by adding <Path> when calling module:create). + For more info, refer to the [Module Generator](https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/CeedlingPacket.md#module-generator) section. + +* `ceedling logging <tasks...>`: + + Enable logging to <build path>/logs. Must come before test and release + tasks to log their steps and output. Log names are a concatenation of + project, user, and option files loaded. User and option files are + documented in the advanced topics section of this document. + +* `ceedling verbosity[x] <tasks...>`: + + Change the default verbosity level. [x] ranges from 0 (quiet) to 4 + (obnoxious). Level [3] is the default. The verbosity task must precede + all tasks in the command line list for which output is desired to be + seen. Verbosity settings are generally most meaningful in conjunction + with test and release tasks. + +* `ceedling summary`: + + If plugins are enabled, this task will execute the summary method of + any plugins supporting it. This task is intended to provide a quick + roundup of build artifact metrics without re-running any part of the + build. + +* `ceedling clean`: + + Deletes all toolchain binary artifacts (object files, executables), + test results, and any temporary files. Clean produces no output at the + command line unless verbosity has been set to an appreciable level. + +* `ceedling clobber`: + + Extends clean task's behavior to also remove generated files: test + runners, mocks, preprocessor output. Clobber produces no output at the + command line unless verbosity has been set to an appreciable level. + +To better understand Rake conventions, Rake execution, and +Rakefiles, consult the [Rake tutorial, examples, and user guide][guide]. + +[guide]: http://rubyrake.org/ + +At present, none of Ceedling's commands provide persistence. +That is, they must each be specified at the command line each time +they are needed. For instance, Ceedling's verbosity command +only affects output at the time it's run. + +Individual test and release file tasks +are not listed in `-T` output. Because so many files may be present +it's unwieldy to list them all. + +Multiple rake tasks can be executed at the command line (order +is executed as provided). For example, `ceed +clobber test:all release` will removed all generated files; +build and run all tests; and then build all source - in that order. +If any Rake task fails along the way, execution halts before the +next task. + +The `clobber` task removes certain build directories in the +course of deleting generated files. In general, it's best not +to add to source control any Ceedling generated directories +below the root of your top-level build directory. That is, leave +anything Ceedling & its accompanying tools generate out of source +control (but go ahead and add the top-level build directory that +holds all that stuff). Also, since Ceedling is pretty smart about +what it rebuilds and regenerates, you needn't clobber often. + +Important Conventions +===================== + +Directory Structure, Filenames & Extensions +------------------------------------------- + +Much of Ceedling's functionality is driven by collecting files +matching certain patterns inside the paths it's configured +to search. See the documentation for the [:extensions] section +of your configuration file (found later in this document) to +configure the file extensions Ceedling uses to match and collect +files. Test file naming is covered later in this section. + +Test files and source files must be segregated by directories. +Any directory structure will do. Tests can be held in subdirectories +within source directories, or tests and source directories +can be wholly separated at the top of your project's directory +tree. + +Search Path Order +----------------- + +When Ceedling searches for files (e.g. looking for header files +to mock) or when it provides search paths to any of the default +gcc toolchain executables, it organizes / prioritizes its search +paths. The order is always: test paths, support paths, source +paths, and then include paths. This can be useful, for instance, +in certain testing scenarios where we desire Ceedling or a compiler +to find a stand-in header file in our support directory before +the actual source header file of the same name. + +This convention only holds when Ceedling is using its default +tool configurations and / or when tests are involved. If you define +your own tools in the configuration file (see the [:tools] section +documented later in this here document), you have complete control +over what directories are searched and in what order. Further, +test and support directories are only searched when appropriate. +That is, when running a release build, test and support directories +are not used at all. + +Source Files & Binary Release Artifacts +--------------------------------------- + +Your binary release artifact results from the compilation and +linking of all source files Ceedling finds in the specified source +directories. At present only source files with a single (configurable) +extension are recognized. That is, *.c and *.cc files will not +both be recognized - only one or the other. See the configuration +options and defaults in the documentation for the [:extensions] +sections of your configuration file (found later in this document). + +Test Files & Executable Test Fixtures +------------------------------------- + +Ceedling builds each individual test file with its accompanying +source file(s) into a single, monolithic test fixture executable. +Test files are recognized by a naming convention: a (configurable) +prefix such as "`test_`" in the file name with the same file extension +as used by your C source files. See the configuration options +and defaults in the documentation for the [:project] and [:extensions] +sections of your configuration file (found later in this document). +Depending on your configuration options, Ceedling can recognize +a variety of test file naming patterns in your test search paths. +For example: `test_some_super_functionality.c`, `TestYourSourceFile.cc`, +or `testing_MyAwesomeCode.C` could each be valid test file +names. Note, however, that Ceedling can recognize only one test +file naming convention per project. + +Ceedling knows what files to compile and link into each individual +test executable by way of the #include list contained in each +test file. Any C source files in the configured search directories +that correspond to the header files included in a test file will +be compiled and linked into the resulting test fixture executable. +From this same #include list, Ceedling knows which files to mock +and compile and link into the test executable (if you use mocks +in your tests). That was a lot of clauses and information in a very +few sentences; the example that follows in a bit will make it clearer. + +By naming your test functions according to convention, Ceedling +will extract and collect into a runner C file calls to all your +test case functions. This runner file handles all the execution +minutiae so that your test file can be quite simple and so that +you never forget to wire up a test function to be executed. In this +generated runner lives the `main()` entry point for the resulting +test executable. There are no configuration options for the +naming convention of your test case functions. A test case function +signature must have these three elements: void return, void +parameter list, and the function name prepended with lowercase +"`test`". In other words, a test function signature should look +like this: `void test``[any name you like]``(void)`. + +A commented sample test file follows on the next page. Also, see +the sample project contained in the Ceedling documentation +bundle. + +```c +// test_foo.c ----------------------------------------------- +#include "unity.h" // compile/link in Unity test framework +#include "types.h" // header file with no *.c file -- no compilation/linking +#include "foo.h" // source file foo.c under test +#include "mock_bar.h" // bar.h will be found and mocked as mock_bar.c + compiled/linked in; + // foo.c includes bar.h and uses functions declared in it +#include "mock_baz.h" // baz.h will be found and mocked as mock_baz.c + compiled/linked in + // foo.c includes baz.h and uses functions declared in it + + +void setUp(void) {} // every test file requires this function; + // setUp() is called by the generated runner before each test case function + +void tearDown(void) {} // every test file requires this function; + // tearDown() is called by the generated runner before each test case function + +// a test case function +void test_Foo_Function1_should_Call_Bar_AndGrill(void) +{ + Bar_AndGrill_Expect(); // setup function from mock_bar.c that instructs our + // framework to expect Bar_AndGrill() to be called once + TEST_ASSERT_EQUAL(0xFF, Foo_Function1()); // assertion provided by Unity + // Foo_Function1() calls Bar_AndGrill() & returns a byte +} + +// another test case function +void test_Foo_Function2_should_Call_Baz_Tec(void) +{ + Baz_Tec_ExpectAnd_Return(1); // setup function provided by mock_baz.c that instructs our + // framework to expect Baz_Tec() to be called once and return 1 + TEST_ASSERT_TRUE(Foo_Function2()); // assertion provided by Unity +} + +// end of test_foo.c ---------------------------------------- +``` + +From the test file specified above Ceedling will generate `test_foo_runner.c`; +this runner file will contain `main()` and call both of the example +test case functions. + +The final test executable will be `test_foo.exe` (for Windows +machines or `test_foo.out` for *nix systems - depending on default +or configured file extensions). Based on the #include list above, +the test executable will be the output of the linker having processed +`unity.o`, `foo.o`, `mock_bar.o`, `mock_baz.o`, `test_foo.o`, +and `test_foo_runner.o`. Ceedling finds the files, generates +mocks, generates a runner, compiles all the files, and links +everything into the test executable. Ceedling will then run +the test executable and collect test results from it to be reported +to the developer at the command line. + +For more on the assertions and mocks shown, consult the documentation +for Unity and CMock. + +The Magic of Dependency Tracking +-------------------------------- + +Ceedling is pretty smart in using Rake to build up your project's +dependencies. This means that Ceedling automagically rebuilds +all the appropriate files in your project when necessary: when +your configuration changes, Ceedling or any of the other tools +are updated, or your source or test files change. For instance, +if you modify a header file that is mocked, Ceedling will ensure +that the mock is regenerated and all tests that use that mock are +rebuilt and re-run when you initiate a relevant testing task. +When you see things rebuilding, it's for a good reason. Ceedling +attempts to regenerate and rebuild only what's needed for a given +execution of a task. In the case of large projects, assembling +dependencies and acting upon them can cause some delay in executing +tasks. + +With one exception, the trigger to rebuild or regenerate a file +is always a disparity in timestamps between a target file and +its source - if an input file is newer than its target dependency, +the target is rebuilt or regenerated. For example, if the C source +file from which an object file is compiled is newer than that object +file on disk, recompilation will occur (of course, if no object +file exists on disk, compilation will always occur). The one +exception to this dependency behavior is specific to your input +configuration. Only if your logical configuration changes +will a system-wide rebuild occur. Reorganizing your input configuration +or otherwise updating its file timestamp without modifying +the values within the file will not trigger a rebuild. This behavior +handles the various ways in which your input configuration can +change (discussed later in this document) without having changed +your actual project YAML file. + +Ceedling needs a bit of help to accomplish its magic with deep +dependencies. Shallow dependencies are straightforward: +a mock is dependent on the header file from which it's generated, +a test file is dependent upon the source files it includes (see +the preceding conventions section), etc. Ceedling handles +these "out of the box." Deep dependencies are specifically a +C-related phenomenon and occur as a consequence of include statements +within C source files. Say a source file includes a header file +and that header file in turn includes another header file which +includes still another header file. A change to the deepest header +file should trigger a recompilation of the source file, a relinking +of all the object files comprising a test fixture, and a new execution +of that test fixture. + +Ceedling can handle deep dependencies but only with the help +of a C preprocessor. Ceedling is quite capable, but a full C preprocessor +it ain't. Your project can be configured to use a C preprocessor +or not. Simple projects or large projects constructed so as to +be quite flat in their include structure generally don't need +deep dependency preprocessing - and can enjoy the benefits of +faster execution. Legacy code, on the other hand, will almost +always want to be tested with deep preprocessing enabled. Set +up of the C preprocessor is covered in the documentation for the +[:project] and [:tools] section of the configuration file (later +in this document). Ceedling contains all the configuration +necessary to use the gcc preprocessor by default. That is, as +long as gcc is in your system search path, deep preprocessing +of deep dependencies is available to you by simply enabling it +in your project configuration file. + +Ceedling's Build Output +----------------------- + +Ceedling requires a top-level build directory for all the stuff +that it, the accompanying test tools, and your toolchain generate. +That build directory's location is configured in the [:project] +section of your configuration file (discussed later). There +can be a ton of generated files. By and large, you can live a full +and meaningful life knowing absolutely nothing at all about +the files and directories generated below the root build directory. + +As noted already, it's good practice to add your top-level build +directory to source control but nothing generated beneath it. +You'll spare yourself headache if you let Ceedling delete and +regenerate files and directories in a non-versioned corner +of your project's filesystem beneath the top-level build directory. + +The `artifacts` directory is the one and only directory you may +want to know about beneath the top-level build directory. The +subdirectories beneath `artifacts` will hold your binary release +target output (if your project is configured for release builds) +and will serve as the conventional location for plugin output. +This directory structure was chosen specifically because it +tends to work nicely with Continuous Integration setups that +recognize and list build artifacts for retrieval / download. + +The Almighty Project Configuration File (in Glorious YAML) +---------------------------------------------------------- + +Please consult YAML documentation for the finer points of format +and to understand details of our YAML-based configuration file. +We recommend [Wikipedia's entry on YAML](http://en.wikipedia.org/wiki/Yaml) +for this. A few highlights from that reference page: + +* YAML streams are encoded using the set of printable Unicode + characters, either in UTF-8 or UTF-16 + +* Whitespace indentation is used to denote structure; however + tab characters are never allowed as indentation + +* Comments begin with the number sign ( # ), can start anywhere + on a line, and continue until the end of the line unless enclosed + by quotes + +* List members are denoted by a leading hyphen ( - ) with one member + per line, or enclosed in square brackets ( [ ] ) and separated + by comma space ( , ) + +* Hashes are represented using the colon space ( : ) in the form + key: value, either one per line or enclosed in curly braces + ( { } ) and separated by comma space ( , ) + +* Strings (scalars) are ordinarily unquoted, but may be enclosed + in double-quotes ( " ), or single-quotes ( ' ) + +* YAML requires that colons and commas used as list separators + be followed by a space so that scalar values containing embedded + punctuation can generally be represented without needing + to be enclosed in quotes + +* Repeated nodes are initially denoted by an ampersand ( & ) and + thereafter referenced with an asterisk ( * ) + + +Notes on what follows: + +* Each of the following sections represent top-level entries + in the YAML configuration file. + +* Unless explicitly specified in the configuration file, default + values are used by Ceedling. + +* These three settings, at minimum, must be specified: + * [:project][:build_root] + * [:paths][:source] + * [:paths][:test] + +* As much as is possible, Ceedling validates your settings in + properly formed YAML. + +* Improperly formed YAML will cause a Ruby error when the YAML + is parsed. This is usually accompanied by a complaint with + line and column number pointing into the project file. + +* Certain advanced features rely on gcc and cpp as preprocessing + tools. In most *nix systems, these tools are already available. + For Windows environments, we recommend the [mingw project](http://www.mingw.org/) + (Minimalist GNU for Windows). + +* Ceedling is primarily meant as a build tool to support automated + unit testing. All the heavy lifting is involved there. Creating + a simple binary release build artifact is quite trivial in + comparison. Consequently, most default options and the construction + of Ceedling itself is skewed towards supporting testing though + Ceedling can, of course, build your binary release artifact + as well. Note that complex binary release artifacts (e.g. + application + bootloader or multiple libraries) are beyond + Ceedling's release build ability. + + +Conventions / features of Ceedling-specific YAML: + +* Any second tier setting keys anywhere in YAML whose names end + in `_path` or `_paths` are automagically processed like all + Ceedling-specific paths in the YAML to have consistent directory + separators (i.e. "/") and to take advantage of inline Ruby + string expansion (see [:environment] setting below for further + explanation of string expansion). + + +**Let's Be Careful Out There:** Ceedling performs validation +on the values you set in your configuration file (this assumes +your YAML is correct and will not fail format parsing, of course). +That said, validation is limited to only those settings Ceedling +uses and those that can be reasonably validated. Ceedling does +not limit what can exist within your configuration file. In this +way, you can take full advantage of YAML as well as add sections +and values for use in your own custom plugins (documented later). +The consequence of this is simple but important. A misspelled +configuration section name or value name is unlikely to cause +Ceedling any trouble. Ceedling will happily process that section +or value and simply use the properly spelled default maintained +internally - thus leading to unexpected behavior without warning. + +project: global project settings + + +* `build_root`: + + Top level directory into which generated path structure and files are + placed. Note: this is one of the handful of configuration values that + must be set. The specified path can be absolute or relative to your + working directory. + + **Default**: (none) + +* `use_exceptions`: + + Configures the build environment to make use of CException. Note that + if you do not use exceptions, there's no harm in leaving this as its + default value. + + **Default**: TRUE + +* `use_mocks`: + + Configures the build environment to make use of CMock. Note that if + you do not use mocks, there's no harm in leaving this setting as its + default value. + + **Default**: TRUE + +* `use_test_preprocessor`: + + This option allows Ceedling to work with test files that contain + conditional compilation statements (e.g. #ifdef) and header files you + wish to mock that contain conditional preprocessor statements and/or + macros. + + Ceedling and CMock are advanced tools with sophisticated parsers. + However, they do not include entire C language preprocessors. + Consequently, with this option enabled, Ceedling will use gcc's + preprocessing mode and the cpp preprocessor tool to strip down / + expand test files and headers to their applicable content which can + then be processed by Ceedling and CMock. + + With this option enabled, the gcc & cpp tools must exist in an + accessible system search path and test runner files are always + regenerated. + + **Default**: FALSE + +* `use_deep_dependencies`: + + The base rules and tasks that Ceedling creates using Rake capture most + of the dependencies within a standard project (e.g. when the source + file accompanying a test file changes, the corresponding test fixture + executable will be rebuilt when tests are re-run). However, deep + dependencies cannot be captured this way. If a typedef or macro + changes in a header file three levels of #include statements deep, + this option allows the appropriate incremental build actions to occur + for both test execution and release builds. + + This is accomplished by using the dependencies discovery mode of gcc. + With this option enabled, gcc must exist in an accessible system + search path. + + **Default**: FALSE + +* `generate_deep_dependencies`: + + When `use_deep_dependencies` is set to TRUE, Ceedling will run a separate + build step to generate the deep dependencies. If you are using gcc as your + primary compiler, or another compiler that can generate makefile rules as + a side effect of compilation, then you can set this to FALSE to avoid the + extra build step but still use the deep dependencies data when deciding + which source files to rebuild. + + **Default**: TRUE + +* `test_file_prefix`: + + Ceedling collects test files by convention from within the test file + search paths. The convention includes a unique name prefix and a file + extension matching that of source files. + + Why not simply recognize all files in test directories as test files? + By using the given convention, we have greater flexibility in what we + do with C files in the test directories. + + **Default**: "test_" + +* `options_paths`: + + Just as you may have various build configurations for your source + codebase, you may need variations of your project configuration. + + By specifying options paths, Ceedling will search for other project + YAML files, make command line tasks available (ceedling options:variation + for a variation.yml file), and merge the project configuration of + these option files in with the main project file at runtime. See + advanced topics. + + Note these Rake tasks at the command line - like verbosity or logging + control - must come before the test or release task they are meant to + modify. + + **Default**: [] (empty) + +* `release_build`: + + When enabled, a release Rake task is exposed. This configuration + option requires a corresponding release compiler and linker to be + defined (gcc is used as the default). + + More release configuration options are available in the release_build + section. + + **Default**: FALSE + + +Example `[:project]` YAML blurb + +```yaml +:project: + :build_root: project_awesome/build + :use_exceptions: FALSE + :use_test_preprocessor: TRUE + :use_deep_dependencies: TRUE + :options_paths: + - project/options + - external/shared/options + :release_build: TRUE +``` + +Ceedling is primarily concerned with facilitating the somewhat +complicated mechanics of automating unit tests. The same mechanisms +are easily capable of building a final release binary artifact +(i.e. non test code; the thing that is your final working software +that you execute on target hardware). + + +* `output`: + + The name of your release build binary artifact to be found in <build + path>/artifacts/release. Ceedling sets the default artifact file + extension to that as is explicitly specified in the [:extensions] + section or as is system specific otherwise. + + **Default**: `project.exe` or `project.out` + +* `use_assembly`: + + If assembly code is present in the source tree, this option causes + Ceedling to create appropriate build directories and use an assembler + tool (default is the GNU tool as - override available in the [:tools] + section. + + **Default**: FALSE + +* `artifacts`: + + By default, Ceedling copies to the <build path>/artifacts/release + directory the output of the release linker and (optionally) a map + file. Many toolchains produce other important output files as well. + Adding a file path to this list will cause Ceedling to copy that file + to the artifacts directory. The artifacts directory is helpful for + organizing important build output files and provides a central place + for tools such as Continuous Integration servers to point to build + output. Selectively copying files prevents incidental build cruft from + needlessly appearing in the artifacts directory. Note that inline Ruby + string replacement is available in the artifacts paths (see discussion + in the [:environment] section). + + **Default**: [] (empty) + +Example `[:release_build]` YAML blurb + +```yaml +:release_build: + :output: top_secret.bin + :use_assembly: TRUE + :artifacts: + - build/release/out/c/top_secret.s19 +``` + +**paths**: options controlling search paths for source and header +(and assembly) files + +* `test`: + + All C files containing unit test code. Note: this is one of the + handful of configuration values that must be set. + + **Default**: [] (empty) + +* `source`: + + All C files containing release code (code to be tested). Note: this is + one of the handful of configuration values that must be set. + + **Default**: [] (empty) + +* `support`: + + Any C files you might need to aid your unit testing. For example, on + occasion, you may need to create a header file containing a subset of + function signatures matching those elsewhere in your code (e.g. a + subset of your OS functions, a portion of a library API, etc.). Why? + To provide finer grained control over mock function substitution or + limiting the size of the generated mocks. + + **Default**: [] (empty) + +* `include`: + + Any header files not already in the source search path. Note there's + no practical distinction between this search path and the source + search path; it's merely to provide options or to support any + peculiar source tree organization. + + **Default**: [] (empty) + +* `test_toolchain_include`: + + System header files needed by the test toolchain - should your + compiler be unable to find them, finds the wrong system include search + path, or you need a creative solution to a tricky technical problem. + Note that if you configure your own toolchain in the [:tools] section, + this search path is largely meaningless to you. However, this is a + convenient way to control the system include path should you rely on + the default gcc tools. + + **Default**: [] (empty) + +* `release_toolchain_include`: + + Same as preceding albeit related to the release toolchain. + + **Default**: [] (empty) + +* `<custom>` + + Any paths you specify for custom list. List is available to tool + configurations and/or plugins. Note a distinction. The preceding names + are recognized internally to Ceedling and the path lists are used to + build collections of files contained in those paths. A custom list is + just that - a custom list of paths. + +Notes on path grammar within the [:paths] section: + +* Order of search paths listed in [:paths] is preserved when used by an + entry in the [:tools] section + +* Wherever multiple path lists are combined for use Ceedling prioritizes + path groups as follows: + test paths, support paths, source paths, include paths. + + This can be useful, for instance, in certain testing scenarios where + we desire Ceedling or the compiler to find a stand-in header file before + the actual source header file of the same name. + +* Paths: + + 1. can be absolute or relative + + 2. can be singly explicit - a single fully specified path + + 3. can include a glob operator (more on this below) + + 4. can use inline Ruby string replacement (see [:environment] + section for more) + + 5. default as an addition to a specific search list (more on this + in the examples) + + 6. can act to subtract from a glob included in the path list (more + on this in the examples) + + +[Globs](http://ruby.about.com/od/beginningruby/a/dir2.htm) +as used by Ceedling are wildcards for specifying directories +without the need to list each and every required search path. +Ceedling globs operate just as Ruby globs except that they are +limited to matching directories and not files. Glob operators +include the following * ** ? [-] {,} (note: this list is space separated +and not comma separated as commas are used within the bracket +operators). + +* `*`: + + All subdirectories of depth 1 below the parent path and including the + parent path + +* `**`: + + All subdirectories recursively discovered below the parent path and + including the parent path + +* `?`: + + Single alphanumeric character wildcard + +* `[x-y]`: + + Single alphanumeric character as found in the specified range + +* `{x,y}`: + + Single alphanumeric character from the specified list + +Example [:paths] YAML blurbs + +```yaml +:paths: + :source: #together the following comprise all source search paths + - project/source/* #expansion yields all subdirectories of depth 1 plus parent directory + - project/lib #single path + :test: #all test search paths + - project/**/test? #expansion yields any subdirectory found anywhere in the project that + #begins with "test" and contains 5 characters + +:paths: + :source: #all source search paths + - +:project/source/** #all subdirectories recursively discovered plus parent directory + - -:project/source/os/generated #subtract os/generated directory from expansion of above glob + #note that '+:' notation is merely aesthetic; default is to add + + :test: #all test search paths + - project/test/bootloader #explicit, single search paths (searched in the order specified) + - project/test/application + - project/test/utilities + + :custom: #custom path list + - "#{PROJECT_ROOT}/other" #inline Ruby string expansion +``` + +Globs and inline Ruby string expansion can require trial and +error to arrive at your intended results. Use the `ceedling paths:*` +command line options (documented in preceding section) to verify +your settings. + +Ceedling relies on file collections automagically assembled +from paths, globs, and file extensions. File collections greatly +simplify project set up. However, sometimes you need to remove +from or add individual files to those collections. + + +* `test`: + + Modify the collection of unit test C files. + + **Default**: [] (empty) + +* `source`: + + Modify the collection of all source files used in unit test builds and release builds. + + **Default**: [] (empty) + +* `assembly`: + + Modify the (optional) collection of assembly files used in release builds. + + **Default**: [] (empty) + +* `include`: + + Modify the collection of all source header files used in unit test builds (e.g. for mocking) and release builds. + + **Default**: [] (empty) + +* `support`: + + Modify the collection of supporting C files available to unit tests builds. + + **Default**: [] (empty) + + +Note: All path grammar documented in [:paths] section applies +to [:files] path entries - albeit at the file path level and not +the directory level. + +Example [:files] YAML blurb + +```yaml +:files: + :source: + - callbacks/comm.c # entry defaults to file addition + - +:callbacks/comm*.c # add all comm files matching glob pattern + - -:source/board/atm134.c # not our board + :test: + - -:test/io/test_output_manager.c # remove unit tests from test build +``` + +**environment:** inserts environment variables into the shell +instance executing configured tools + +Ceedling creates environment variables from any key / value +pairs in the environment section. Keys become an environment +variable name in uppercase. The values are strings assigned +to those environment variables. These value strings are either +simple string values in YAML or the concatenation of a YAML array. + +Ceedling is able to execute inline Ruby string substitution +code to set environment variables. This evaluation occurs when +the project file is first processed for any environment pair's +value string including the Ruby string substitution pattern +`#{…}`. Note that environment value strings that _begin_ with +this pattern should always be enclosed in quotes. YAML defaults +to processing unquoted text as a string; quoting text is optional. +If an environment pair's value string begins with the Ruby string +substitution pattern, YAML will interpret the string as a Ruby +comment (because of the `#`). Enclosing each environment value +string in quotes is a safe practice. + +[:environment] entries are processed in the configured order +(later entries can reference earlier entries). + +Special case: PATH handling + +In the specific case of specifying an environment key named _path_, +an array of string values will be concatenated with the appropriate +platform-specific path separation character (e.g. ':' on *nix, +';' on Windows). All other instances of environment keys assigned +YAML arrays use simple concatenation. + +Example [:environment] YAML blurb + +```yaml +:environment: + - :license_server: gizmo.intranet #LICENSE_SERVER set with value "gizmo.intranet" + - :license: "#{`license.exe`}" #LICENSE set to string generated from shelling out to + #execute license.exe; note use of enclosing quotes + + - :path: #concatenated with path separator (see special case above) + - Tools/gizmo/bin #prepend existing PATH with gizmo path + - "#{ENV['PATH']}" #pattern #{…} triggers ruby evaluation string substitution + #note: value string must be quoted because of '#' + + - :logfile: system/logs/thingamabob.log #LOGFILE set with path for a log file +``` + +**extension**: configure file name extensions used to collect lists of files searched in [:paths] + +* `header`: + + C header files + + **Default**: .h + +* `source`: + + C code files (whether source or test files) + + **Default**: .c + +* `assembly`: + + Assembly files (contents wholly assembly instructions) + + **Default**: .s + +* `object`: + + Resulting binary output of C code compiler (and assembler) + + **Default**: .o + +* `executable`: + + Binary executable to be loaded and executed upon target hardware + + **Default**: .exe or .out (Win or *nix) + +* `testpass`: + + Test results file (not likely to ever need a new value) + + **Default**: .pass + +* `testfail`: + + Test results file (not likely to ever need a new value) + + **Default**: .fail + +* `dependencies`: + + File containing make-style dependency rules created by gcc preprocessor + + **Default**: .d + + +Example [:extension] YAML blurb + + :extension: + :source: .cc + :executable: .bin + +**defines**: command line defines used in test and release compilation by configured tools + +* `test`: + + Defines needed for testing. Useful for: + + 1. test files containing conditional compilation statements (i.e. + tests active in only certain contexts) + + 2. testing legacy source wherein the isolation of source under test + afforded by Ceedling and its complementary tools leaves certain + symbols unset when source files are compiled in isolation + + **Default**: [] (empty) + +* `test_preprocess`: + + If [:project][:use_test_preprocessor] or + [:project][:use_deep_dependencies] is set and code is structured in a + certain way, the gcc preprocessor may need symbol definitions to + properly preprocess files to extract function signatures for mocking + and extract deep dependencies for incremental builds. + + **Default**: [] (empty) + +* `release`: + + Defines needed for the release build binary artifact. + + **Default**: [] (empty) + +* `release_preprocess`: + + If [:project][:use_deep_dependencies] is set and code is structured in + a certain way, the gcc preprocessor may need symbol definitions to + properly preprocess files for incremental release builds due to deep + dependencies. + + **Default**: [] (empty) + + +Example [:defines] YAML blurb + +```yaml +:defines: + :test: + - UNIT_TESTING #for select cases in source to allow testing with a changed behavior or interface + - OFF=0 + - ON=1 + - FEATURE_X=ON + :source: + - FEATURE_X=ON +``` + + +**libraries**: command line defines used in test and release compilation by configured tools + +Ceedling allows you to pull in specific libraries for the purpose of release and test builds. +It has a few levels of support for this. Start by adding a :libraries main section in your +configuration. In this section, you can optionally have the following subsections: + +* `test`: + + Library files that should be injected into your tests when linking occurs. + These can be specified as either relative or absolute paths. These files MUST + exist when the test attempts to build. + +* `source`: + + Library files that should be injected into your release when linking occurs. These + can be specified as either relative or absolute paths. These files MUST exist when + the release attempts to build UNLESS you are using the subprojects plugin. In that + case, it will attempt to build that library for you as a dynamic dependency. + +* `system`: + + These libraries are assumed to be in the tool path somewhere and shouldn't need to be + specified. The libraries added here will be injected into releases and tests. + +* `flag`: + + This is the method of adding an argument for each library. For example, gcc really likes + it when you specify “-l${1}” + +Notes: + +* If you've specified your own link step, you are going to want to add ${4} to your argument +list in the place where library files should be added to the command call. For gcc, this is +often the very end. Other tools may vary. + + +**flags**: configure per-file compilation and linking flags + +Ceedling tools (see later [:tools] section) are used to configure +compilation and linking of test and source files. These tool +configurations are a one-size-fits-all approach. Should individual files +require special compilation or linking flags, the settings in the +[:flags] section work in conjunction with tool definitions by way of +argument substitution to achieve this. + +* `release`: + + [:compile] or [:link] flags for release build + +* `test`: + + [:compile] or [:link] flags for test build + +Notes: + +* Ceedling works with the [:release] and [:test] build contexts + as-is; plugins can add additional contexts + +* Only [:compile] and [:link] are recognized operations beneath + a context + +* File specifiers do not include a path or file extension + +* File specifiers are case sensitive (must match original file + name) + +* File specifiers do support regular expressions if encased in quotes + +* '*' is a special (optional) file specifier to provide flags + to all files not otherwise specified + + +Example [:flags] YAML blurb + +```yaml +:flags: + :release: + :compile: + :main: # add '-Wall' to compilation of main.c + - -Wall + :fan: # add '--O2' to compilation of fan.c + - --O2 + :'test_.+': # add '-pedantic' to all test-files + - -pedantic + :*: # add '-foo' to compilation of all files not main.c or fan.c + - -foo + :test: + :compile: + :main: # add '--O1' to compilation of main.c as part of test builds including main.c + - --O1 + :link: + :test_main: # add '--bar --baz' to linking of test_main.exe + - --bar + - --baz +``` + +Ceedling sets values for a subset of CMock settings. All CMock +options are available to be set, but only those options set by +Ceedling in an automated fashion are documented below. See CMock +documentation. + +**cmock**: configure CMock's code generation options and set symbols used to modify CMock's compiled features +Ceedling sets values for a subset of CMock settings. All CMock options are available to be set, but only those options set by Ceedling in an automated fashion are documented below. See CMock documentation. + +* `enforce_strict_ordering`: + + Tests fail if expected call order is not same as source order + + **Default**: TRUE + +* `mock_path`: + + Path for generated mocks + + **Default**: <build path>/tests/mocks + +* `defines`: + + List of conditional compilation symbols used to configure CMock's + compiled features. See CMock documentation to understand available + options. No symbols must be set unless defaults are inappropriate for + your specific environment. All symbols are used only by Ceedling to + compile CMock C code; contents of [:defines] are ignored by CMock's + Ruby code when instantiated. + + **Default**: [] (empty) + +* `verbosity`: + + If not set, defaults to Ceedling's verbosity level + +* `plugins`: + + If [:project][:use_exceptions] is enabled, the internal plugins list is pre-populated with 'cexception'. + + Whether or not you have included [:cmock][:plugins] in your + configuration file, Ceedling automatically adds 'cexception' to the + plugin list if exceptions are enabled. To add to the list Ceedling + provides CMock, simply add [:cmock][:plugins] to your configuration + and specify your desired additional plugins. + +* `includes`: + + If [:cmock][:unity_helper] set, pre-populated with unity_helper file + name (no path). + + The [:cmock][:includes] list works identically to the plugins list + above with regard to adding additional files to be inserted within + mocks as #include statements. + + +The last four settings above are directly tied to other Ceedling +settings; hence, why they are listed and explained here. The +first setting above, [:enforce_strict_ordering], defaults +to FALSE within CMock. It is set to TRUE by default in Ceedling +as our way of encouraging you to use strict ordering. It's a teeny +bit more expensive in terms of code generated, test execution +time, and complication in deciphering test failures. However, +it's good practice. And, of course, you can always disable it +by overriding the value in the Ceedling YAML configuration file. + + +**cexception**: configure symbols used to modify CException's compiled features + +* `defines`: + + List of conditional compilation symbols used to configure CException's + features in its source and header files. See CException documentation + to understand available options. No symbols must be set unless the + defaults are inappropriate for your specific environment. + + **Default**: [] (empty) + + +**unity**: configure symbols used to modify Unity's compiled features + +* `defines`: + + List of conditional compilation symbols used to configure Unity's + features in its source and header files. See Unity documentation to + understand available options. No symbols must be set unless the + defaults are inappropriate for your specific environment. Most Unity + defines can be easily configured through the YAML file. + + **Default**: [] (empty) + +Example [:unity] YAML blurbs +```yaml +:unity: #itty bitty processor & toolchain with limited test execution options + :defines: + - UNITY_INT_WIDTH=16 #16 bit processor without support for 32 bit instructions + - UNITY_EXCLUDE_FLOAT #no floating point unit + +:unity: #great big gorilla processor that grunts and scratches + :defines: + - UNITY_SUPPORT_64 #big memory, big counters, big registers + - UNITY_LINE_TYPE=\"unsigned int\" #apparently we're using really long test files, + - UNITY_COUNTER_TYPE=\"unsigned int\" #and we've got a ton of test cases in those test files + - UNITY_FLOAT_TYPE=\"double\" #you betcha +``` + + +Notes on Unity configuration: + +* **Verification** - Ceedling does no verification of your configuration + values. In a properly configured setup, your Unity configuration + values are processed, collected together with any test define symbols + you specify elsewhere, and then passed to your toolchain during test + compilation. Unity's conditional compilation statements, your + toolchain's preprocessor, and/or your toolchain's compiler will + complain appropriately if your specified configuration values are + incorrect, incomplete, or incompatible. + +* **Routing $stdout** - Unity defaults to using `putchar()` in C's + standard library to display test results. For more exotic environments + than a desktop with a terminal (e.g. running tests directly on a + non-PC target), you have options. For example, you could create a + routine that transmits a character via RS232 or USB. Once you have + that routine, you can replace `putchar()` calls in Unity by overriding + the function-like macro `UNITY_OUTPUT_CHAR`. Consult your toolchain + and shell documentation. Eventhough this can also be defined in the YAML file + most shell environments do not handle parentheses as command line arguments + very well. To still be able to add this functionality all necessary + options can be defined in the `unity_config.h`. Unity needs to be told to look for + the `unity_config.h` in the YAML file, though. + +Example [:unity] YAML blurbs +```yaml +:unity: + :defines: + - UNITY_INCLUDE_CONFIG_H +``` + +Example unity_config.h +``` +#ifndef UNITY_CONFIG_H +#define UNITY_CONFIG_H + +#include "uart_output.h" //Helper library for your custom environment + +#define UNITY_INT_WIDTH 16 +#define UNITY_OUTPUT_START() uart_init(F_CPU, BAUD) //Helperfunction to init UART +#define UNITY_OUTPUT_CHAR(a) uart_putchar(a) //Helperfunction to forward char via UART +#define UNITY_OUTPUT_COMPLETE() uart_complete() //Helperfunction to inform that test has ended + +#endif +``` + + +**tools**: a means for representing command line tools for use under +Ceedling's automation framework + +Ceedling requires a variety of tools to work its magic. By default, +the GNU toolchain (gcc, cpp, as) are configured and ready for +use with no additions to the project configuration YAML file. +However, as most work will require a project-specific toolchain, +Ceedling provides a generic means for specifying / overriding +tools. + +* `test_compiler`: + + Compiler for test & source-under-test code + ${1}: input source ${2}: output object ${3}: optional output list ${4}: optional output dependencies file + + **Default**: gcc + +* `test_linker`: + + Linker to generate test fixture executables + ${1}: input objects ${2}: output binary ${3}: optional output map ${4}: optional library list + + **Default**: gcc + +* `test_fixture`: + + Executable test fixture + ${1}: simulator as executable with ${1} as input binary file argument or native test executable + + **Default**: ${1} + +* `test_includes_preprocessor`: + + Extractor of #include statements + ${1}: input source file + + **Default**: cpp + +* `test_file_preprocessor`: + + Preprocessor of test files (macros, conditional compilation statements) + ${1}: input source file ${2}: preprocessed output source file + + **Default**: gcc + +* `test_dependencies_generator`: + + Discovers deep dependencies of source & test (for incremental builds) + ${1}: input source file ${2}: compiled object filepath ${3}: output dependencies file + + **Default**: gcc + +* `release_compiler`: + + Compiler for release source code + ${1}: input source ${2}: output object ${3}: optional output list ${4}: optional output dependencies file + + **Default**: gcc + +* `release_assembler`: + + Assembler for release assembly code + ${1}: input assembly source file ${2}: output object file + + **Default**: as + +* `release_linker`: + + Linker for release source code + ${1}: input objects ${2}: output binary ${3}: optional output map ${4}: optional library list + + **Default**: gcc + +* `release_dependencies_generator`: + + Discovers deep dependencies of source files (for incremental builds) + ${1}: input source file ${2}: compiled object filepath ${3}: output dependencies file + + **Default**: gcc + + +A Ceedling tool has a handful of configurable elements: + +1. [:executable] (required) - Command line executable having + the form of: + +2. [:arguments] (required) - List of command line arguments + and substitutions + +3. [:name] - Simple name (e.g. "nickname") of tool beyond its + executable name (if not explicitly set then Ceedling will + form a name from the tool's YAML entry name) + +4. [:stderr_redirect] - Control of capturing $stderr messages + {:none, :auto, :win, :unix, :tcsh}. + Defaults to :none if unspecified; create a custom entry by + specifying a simple string instead of any of the available + symbols. + +5. [:background_exec] - Control execution as background process + {:none, :auto, :win, :unix}. + Defaults to :none if unspecified. + + +Tool Element Runtime Substitution +--------------------------------- + +To accomplish useful work on multiple files, a configured tool will most +often require that some number of its arguments or even the executable +itself change for each run. Consequently, every tool's argument list and +executable field possess two means for substitution at runtime. Ceedling +provides two kinds of inline Ruby execution and a notation for +populating elements with dynamically gathered values within the build +environment. + +Tool Element Runtime Substitution: Inline Ruby Execution +-------------------------------------------------------- + +In-line Ruby execution works similarly to that demonstrated for the +[:environment] section except that substitution occurs as the tool is +executed and not at the time the configuration file is first scanned. + +* `#{...}`: + + Ruby string substitution pattern wherein the containing string is + expanded to include the string generated by Ruby code between the + braces. Multiple instances of this expansion can occur within a single + tool element entry string. Note that if this string substitution + pattern occurs at the very beginning of a string in the YAML + configuration the entire string should be enclosed in quotes (see the + [:environment] section for further explanation on this point). + +* `{...} `: + + If an entire tool element string is enclosed with braces, it signifies + that Ceedling should execute the Ruby code contained within those + braces. Say you have a collection of paths on disk and some of those + paths include spaces. Further suppose that a single tool that must use + those paths requires those spaces to be escaped, but all other uses of + those paths requires the paths to remain unchanged. You could use this + Ceedling feature to insert Ruby code that iterates those paths and + escapes those spaces in the array as used by the tool of this example. + +Tool Element Runtime Substitution: Notational Substitution +---------------------------------------------------------- + +A Ceedling tool's other form of dynamic substitution relies on a '$' +notation. These '$' operators can exist anywhere in a string and can be +decorated in any way needed. To use a literal '$', escape it as '\\$'. + +* `$`: + + Simple substitution for value(s) globally available within the runtime + (most often a string or an array). + +* `${#}`: + + When a Ceedling tool's command line is expanded from its configured + representation and used within Ceedling Ruby code, certain calls to + that tool will be made with a parameter list of substitution values. + Each numbered substitution corresponds to a position in a parameter + list. Ceedling Ruby code expects that configured compiler and linker + tools will contain ${1} and ${2} replacement arguments. In the case of + a compiler ${1} will be a C code file path, and ${2} will be the file + path of the resulting object file. For a linker ${1} will be an array + of object files to link, and ${2} will be the resulting binary + executable. For an executable test fixture ${1} is either the binary + executable itself (when using a local toolchain such as gcc) or a + binary input file given to a simulator in its arguments. + + +Example [:tools] YAML blurbs + +```yaml +:tools: + :test_compiler: + :executable: compiler #exists in system search path + :name: 'acme test compiler' + :arguments: + - -I"$": COLLECTION_PATHS_TEST_TOOLCHAIN_INCLUDE #expands to -I search paths + - -I"$": COLLECTION_PATHS_TEST_SUPPORT_SOURCE_INCLUDE_VENDOR #expands to -I search paths + - -D$: COLLECTION_DEFINES_TEST_AND_VENDOR #expands to all -D defined symbols + - --network-license #simple command line argument + - -optimize-level 4 #simple command line argument + - "#{`args.exe -m acme.prj`}" #in-line ruby sub to shell out & build string of arguments + - -c ${1} #source code input file (Ruby method call param list sub) + - -o ${2} #object file output (Ruby method call param list sub) + :test_linker: + :executable: /programs/acme/bin/linker.exe #absolute file path + :name: 'acme test linker' + :arguments: + - ${1} #list of object files to link (Ruby method call param list sub) + - -l$-lib: #inline yaml array substitution to link in foo-lib and bar-lib + - foo + - bar + - -o ${2} #executable file output (Ruby method call param list sub) + :test_fixture: + :executable: tools/bin/acme_simulator.exe #relative file path to command line simulator + :name: 'acme test fixture' + :stderr_redirect: :win #inform Ceedling what model of $stderr capture to use + :arguments: + - -mem large #simple command line argument + - -f "${1}" #binary executable input file to simulator (Ruby method call param list sub) +``` + +Resulting command line constructions from preceding example [:tools] YAML blurbs + + > compiler -I"/usr/include” -I”project/tests” + -I"project/tests/support” -I”project/source” -I”project/include” + -DTEST -DLONG_NAMES -network-license -optimize-level 4 arg-foo + arg-bar arg-baz -c project/source/source.c -o + build/tests/out/source.o + +[notes: (1.) "arg-foo arg-bar arg-baz" is a fabricated example +string collected from $stdout as a result of shell execution +of args.exe +(2.) the -c and -o arguments are +fabricated examples simulating a single compilation step for +a test; ${1} & ${2} are single files] + + > \programs\acme\bin\linker.exe thing.o unity.o + test_thing_runner.o test_thing.o mock_foo.o mock_bar.o -lfoo-lib + -lbar-lib -o build\tests\out\test_thing.exe + +[note: in this scenario ${1} is an array of all the object files +needed to link a test fixture executable] + + > tools\bin\acme_simulator.exe -mem large -f "build\tests\out\test_thing.bin 2>&1” + +[note: (1.) :executable could have simply been ${1} - if we were compiling +and running native executables instead of cross compiling (2.) we're using +$stderr redirection to allow us to capture simulator error messages to +$stdout for display at the run's conclusion] + + +Notes: + +* The upper case names are Ruby global constants that Ceedling + builds + +* "COLLECTION_" indicates that Ceedling did some work to assemble + the list. For instance, expanding path globs, combining multiple + path globs into a convenient summation, etc. + +* At present, $stderr redirection is primarily used to capture + errors from test fixtures so that they can be displayed at the + conclusion of a test run. For instance, if a simulator detects + a memory access violation or a divide by zero error, this notice + might go unseen in all the output scrolling past in a terminal. + +* The preprocessing tools can each be overridden with non-gcc + equivalents. However, this is an advanced feature not yet + documented and requires that the replacement toolchain conform + to the same conventions used by gcc. + +**Ceedling Collection Used in Compilation**: + +* `COLLECTION_PATHS_TEST`: + + All test paths + +* `COLLECTION_PATHS_SOURCE`: + + All source paths + +* `COLLECTION_PATHS_INCLUDE`: + + All include paths + +* `COLLECTION_PATHS_SUPPORT`: + + All test support paths + +* `COLLECTION_PATHS_SOURCE_AND_INCLUDE`: + + All source and include paths + +* `COLLECTION_PATHS_SOURCE_INCLUDE_VENDOR`: + + All source and include paths + applicable vendor paths (e.g. + CException's source path if exceptions enabled) + +* `COLLECTION_PATHS_TEST_TOOLCHAIN_INCLUDE`: + + All test toolchain include paths + +* `COLLECTION_PATHS_TEST_SUPPORT_SOURCE_INCLUDE`: + + All test, source, and include paths + +* `COLLECTION_PATHS_TEST_SUPPORT_SOURCE_INCLUDE_VENDOR`: + + All test, source, include, and applicable vendor paths (e.g. Unity's + source path plus CMock and CException's source paths if mocks and + exceptions are enabled) + +* `COLLECTION_PATHS_RELEASE_TOOLCHAIN_INCLUDE`: + + All release toolchain include paths + +* `COLLECTION_DEFINES_TEST_AND_VENDOR`: + + All symbols specified in [:defines][:test] + symbols defined for + enabled vendor tools - e.g. [:unity][:defines], [:cmock][:defines], + and [:cexception][:defines] + +* `COLLECTION_DEFINES_RELEASE_AND_VENDOR`: + + All symbols specified in [:defines][:release] plus symbols defined by +[:cexception][:defines] if exceptions are ena bled + + +Notes: + +* Other collections exist within Ceedling. However, they are + only useful for advanced features not yet documented. + +* Wherever multiple path lists are combined for use Ceedling prioritizes + path groups as follows: test paths, support paths, source paths, include + paths. + This can be useful, for instance, in certain testing scenarios + where we desire Ceedling or the compiler to find a stand-in header file + before the actual source header file of the same name. + + +**plugins**: Ceedling extensions + +* `load_paths`: + + Base paths to search for plugin subdirectories or extra ruby functionalit + + **Default**: [] (empty) + +* `enabled`: + + List of plugins to be used - a plugin's name is identical to the + subdirectory that contains it (and the name of certain files within + that subdirectory) + + **Default**: [] (empty) + + +Plugins can provide a variety of added functionality to Ceedling. In +general use, it's assumed that at least one reporting plugin will be +used to format test results. However, if no reporting plugins are +specified, Ceedling will print to `$stdout` the (quite readable) raw +test results from all test fixtures executed. + +Example [:plugins] YAML blurb + +```yaml +:plugins: + :load_paths: + - project/tools/ceedling/plugins #home to your collection of plugin directories + - project/support #maybe home to some ruby code your custom plugins share + :enabled: + - stdout_pretty_tests_report #nice test results at your command line + - our_custom_code_metrics_report #maybe you needed line count and complexity metrics, so you + #created a plugin to scan all your code and collect that info +``` + +* `stdout_pretty_tests_report`: + + Prints to $stdout a well-formatted list of ignored and failed tests, + final test counts, and any extraneous output (e.g. printf statements + or simulator memory errors) collected from executing the test + fixtures. Meant to be used with runs at the command line. + +* `stdout_ide_tests_report`: + + Prints to $stdout simple test results formatted such that an IDE + executing test-related Rake tasks can recognize file paths and line + numbers in test failures, etc. Thus, you can click a test result in + your IDE's execution window and jump to the failure (or ignored test) + in your test file (obviously meant to be used with an [IDE like + Eclipse][ide], etc). + + [ide]: http://throwtheswitch.org/white-papers/using-with-ides.html + +* `xml_tests_report`: + + Creates an XML file of test results in the xUnit format (handy for + Continuous Integration build servers or as input to other reporting + tools). Produces a file report.xml in <build root>/artifacts/tests. + +* `bullseye`: + + Adds additional Rake tasks to execute tests with the commercial code + coverage tool provided by [Bullseye][]. See readme.txt inside the bullseye + plugin directory for configuration and use instructions. Note: + Bullseye only works with certain compilers and linkers (healthy list + of supported toolchains though). + + [bullseye]: http://www.bullseye.com + +* `gcov`: + + Adds additional Rake tasks to execute tests with the GNU code coverage + tool [gcov][]. See readme.txt inside the gcov directory for configuration + and use instructions. Only works with GNU compiler and linker. + + [gcov]: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html + +* `warnings_report`: + + Scans compiler and linker `$stdout / $stderr` output for the word + 'warning' (case insensitive). All code warnings (or tool warnings) are + logged to a file warnings.log in the appropriate `<build + root>/artifacts` directory (e.g. test/ for test tasks, `release/` for a + release build, or even `bullseye/` for bullseye runs). + +Module Generator +======================== +Ceedling includes a plugin called module_generator that will create a source, header and test file for you. +There are several possibilities to configure this plugin through your project.yml to suit your project's needs. + +Directory Structure +------------------------------------------- + +The default configuration for directory/project structure is: +```yaml +:module_generator: + :project_root: ./ + :source_root: src/ + :test_root: test/ +``` +You can change these variables in your project.yml file to comply with your project's directory structure. + +If you call `ceedling module:create`, it will create three files: +1. A source file in the source_root +2. A header file in the source_root +3. A test file in the test_root + +If you want your header file to be in another location, +you can specify the ':inc_root:" in your project.yml file: +```yaml +:module_generator: + :inc_root: inc/ +``` +The module_generator will then create the header file in your defined ':inc_root:'. +By default, ':inc_root:' is not defined so the module_generator will use the source_root. + +Sometimes, your project can't be divided into a single src, inc, and test folder. You have several directories +with sources/..., something like this for example: +<project_root> + - myDriver + - src + - inc + - test + - myOtherDriver + - src + - inc + - test + - ... + +Don't worry, you don't have to manually create the source/header/test files. +The module_generator can accept a path to create a source_root/inc_root/test_root folder with your files: +`ceedling module:create[<module_root_path>:<module_name>]` + +F.e., applied to the above project structure: +`ceedling module:create[myOtherDriver:driver]` +This will make the module_generator run in the subdirectory 'myOtherDriver' and generate the module files +for you in that directory. So, this command will generate the following files: +1. A source file 'driver.c' in <project_root>/myOtherDriver/<source_root> +2. A header file 'driver.h' in <project_root>/myOtherDriver/<source_root> (or <inc_root> if specified) +3. A test file 'test_driver.c' in <project_root>/myOtherDriver/<test_root> + +Naming +------------------------------------------- +By default, the module_generator will generate your files in lowercase. +`ceedling module:create[mydriver]` and `ceedling module:create[myDriver]`(note the uppercase) will generate the same files: +1. mydriver.c +2. mydriver.h +3. test_mydriver.c + +You can configure the module_generator to use a differect naming mechanism through the project.yml: +```yaml +:module_generator: + :naming: "camel" +``` +There are other possibilities as well (bumpy, camel, snake, caps). +Refer to the unity module generator for more info (the unity module generator is used under the hood by module_generator). + +Advanced Topics (Coming) +======================== + +Modifying Your Configuration without Modifying Your Project File: Option Files & User Files +------------------------------------------------------------------------------------------- + +Modifying your project file without modifying your project file + +Debugging and/or printf() +------------------------- + +When you gotta get your hands dirty... + +Ceedling Plays Nice with Others - Using Ceedling for Tests Alongside Another Release Build Setup +------------------------------------------------------------------------------------------------ + +You've got options. + +Adding Handy Rake Tasks for Your Project (without Fancy Pants Custom Plugins) +----------------------------------------------------------------------------- + +Simple as snot. + +Working with Non-Desktop Testing Environments +--------------------------------------------- + +For those crazy platforms lacking command line simulators and for which +cross-compiling on the desktop just ain't gonna get it done. + +Creating Custom Plugins +----------------------- + +Oh boy. This is going to take some explaining. diff --git a/tinyusb/test/vendor/ceedling/docs/ThrowTheSwitchCodingStandard.md b/tinyusb/test/vendor/ceedling/docs/ThrowTheSwitchCodingStandard.md new file mode 100755 index 00000000..bf4c099b --- /dev/null +++ b/tinyusb/test/vendor/ceedling/docs/ThrowTheSwitchCodingStandard.md @@ -0,0 +1,206 @@ +# ThrowTheSwitch.org Coding Standard + +Hi. Welcome to the coding standard for ThrowTheSwitch.org. For the most part, +we try to follow these standards to unify our contributors' code into a cohesive +unit (puns intended). You might find places where these standards aren't +followed. We're not perfect. Please be polite where you notice these discrepancies +and we'll try to be polite when we notice yours. + +;) + + +## Why Have A Coding Standard? + +Being consistent makes code easier to understand. We've tried to keep +our standard simple because we also believe that we can only expect someone to +follow something that is understandable. Please do your best. + + +## Our Philosophy + +Before we get into details on syntax, let's take a moment to talk about our +vision for these tools. We're C developers and embedded software developers. +These tools are great to test any C code, but catering to embedded software has +made us more tolerant of compiler quirks. There are a LOT of quirky compilers +out there. By quirky I mean "doesn't follow standards because they feel like +they have a license to do as they wish." + +Our philosophy is "support every compiler we can". Most often, this means that +we aim for writing C code that is standards compliant (often C89... that seems +to be a sweet spot that is almost always compatible). But it also means these +tools are tolerant of things that aren't common. Some that aren't even +compliant. There are configuration options to override the size of standard +types. There are configuration options to force Unity to not use certain +standard library functions. A lot of Unity is configurable and we have worked +hard to make it not TOO ugly in the process. + +Similarly, our tools that parse C do their best. They aren't full C parsers +(yet) and, even if they were, they would still have to accept non-standard +additions like gcc extensions or specifying `@0x1000` to force a variable to +compile to a particular location. It's just what we do, because we like +everything to Just Work™. + +Speaking of having things Just Work™, that's our second philosophy. By that, we +mean that we do our best to have EVERY configuration option have a logical +default. We believe that if you're working with a simple compiler and target, +you shouldn't need to configure very much... we try to make the tools guess as +much as they can, but give the user the power to override it when it's wrong. + + +## Naming Things + +Let's talk about naming things. Programming is all about naming things. We name +files, functions, variables, and so much more. While we're not always going to +find the best name for something, we actually put a bit of effort into +finding *What Something WANTS to be Called*™. + +When naming things, we follow this hierarchy, the first being the +most important to us (but we do all four when possible): +1. Readable +2. Descriptive +3. Consistent +4. Memorable + + +#### Readable + +We want to read our code. This means we like names and flow that are more +naturally read. We try to avoid double negatives. We try to avoid cryptic +abbreviations (sticking to ones we feel are common). + + +#### Descriptive + +We like descriptive names for things, especially functions and variables. +Finding the right name for something is an important endeavor. You might notice +from poking around our code that this often results in names that are a little +longer than the average. Guilty. We're okay with a bit more typing if it +means our code is easier to understand. + +There are two exceptions to this rule that we also stick to as religiously as +possible: + +First, while we realize hungarian notation (and similar systems for encoding +type information into variable names) is providing a more descriptive name, we +feel that (for the average developer) it takes away from readability and is to be avoided. + +Second, loop counters and other local throw-away variables often have a purpose +which is obvious. There's no need, therefore, to get carried away with complex +naming. We find i, j, and k are better loop counters than loopCounterVar or +whatnot. We only break this rule when we see that more description could improve +understanding of an algorithm. + + +#### Consistent + +We like consistency, but we're not really obsessed with it. We try to name our +configuration macros in a consistent fashion... you'll notice a repeated use of +UNITY_EXCLUDE_BLAH or UNITY_USES_BLAH macros. This helps users avoid having to +remember each macro's details. + + +#### Memorable + +Where ever it doesn't violate the above principles, we try to apply memorable +names. Sometimes this means using something that is simply descriptive, but +often we strive for descriptive AND unique... we like quirky names that stand +out in our memory and are easier to search for. Take a look through the file +names in Ceedling and you'll get a good idea of what we are talking about here. +Why use preprocess when you can use preprocessinator? Or what better describes a +module in charge of invoking tasks during releases than release_invoker? Don't +get carried away. The names are still descriptive and fulfill the above +requirements, but they don't feel stale. + + +## C and C++ Details + +We don't really want to add to the style battles out there. Tabs or spaces? +How many spaces? Where do the braces go? These are age-old questions that will +never be answered... or at least not answered in a way that will make everyone +happy. + +We've decided on our own style preferences. If you'd like to contribute to these +projects (and we hope that you do), then we ask if you do your best to follow +the same. It will only hurt a little. We promise. + + +#### Whitespace + +Our C-style is to use spaces and to use 4 of them per indent level. It's a nice +power-of-2 number that looks decent on a wide-screen. We have no more reason +than that. We break that rule when we have lines that wrap (macros or function +arguments or whatnot). When that happens, we like to indent further to line +things up in nice tidy columns. + +```C + if (stuff_happened) + { + do_something(); + } +``` + + +#### Case + +- Files - all lower case with underscores. +- Variables - all lower case with underscores +- Macros - all caps with underscores. +- Typedefs - all caps with underscores. (also ends with _T). +- Functions - camel cased. Usually named ModuleName_FuncName +- Constants and Globals - camel cased. + + +#### Braces + +The left brace is on the next line after the declaration. The right brace is +directly below that. Everything in between in indented one level. If you're +catching an error and you have a one-line, go ahead and to it on the same line. + +```C + while (blah) + { + //Like so. Even if only one line, we use braces. + } +``` + + +#### Comments + +Do you know what we hate? Old-school C block comments. BUT, we're using them +anyway. As we mentioned, our goal is to support every compiler we can, +especially embedded compilers. There are STILL C compilers out there that only +support old-school block comments. So that is what we're using. We apologize. We +think they are ugly too. + + +## Ruby Details + +Is there really such thing as a Ruby coding standard? Ruby is such a free form +language, it seems almost sacrilegious to suggest that people should comply to +one method! We'll keep it really brief! + + +#### Whitespace + +Our Ruby style is to use spaces and to use 2 of them per indent level. It's a +nice power-of-2 number that really grooves with Ruby's compact style. We have no +more reason than that. We break that rule when we have lines that wrap. When +that happens, we like to indent further to line things up in nice tidy columns. + + +#### Case + +- Files - all lower case with underscores. +- Variables - all lower case with underscores +- Classes, Modules, etc - Camel cased. +- Functions - all lower case with underscores +- Constants - all upper case with underscores + + +## Documentation + +Egad. Really? We use mark down and we like pdf files because they can be made to +look nice while still being portable. Good enough? + + +*Find The Latest of This And More at [ThrowTheSwitch.org](https://throwtheswitch.org)* diff --git a/tinyusb/test/vendor/ceedling/docs/UnityAssertionsCheatSheetSuitableforPrintingandPossiblyFraming.pdf b/tinyusb/test/vendor/ceedling/docs/UnityAssertionsCheatSheetSuitableforPrintingandPossiblyFraming.pdf Binary files differnew file mode 100755 index 00000000..28f0c321 --- /dev/null +++ b/tinyusb/test/vendor/ceedling/docs/UnityAssertionsCheatSheetSuitableforPrintingandPossiblyFraming.pdf diff --git a/tinyusb/test/vendor/ceedling/docs/UnityAssertionsReference.md b/tinyusb/test/vendor/ceedling/docs/UnityAssertionsReference.md new file mode 100755 index 00000000..eb855f3c --- /dev/null +++ b/tinyusb/test/vendor/ceedling/docs/UnityAssertionsReference.md @@ -0,0 +1,779 @@ +# Unity Assertions Reference + +## Background and Overview + +### Super Condensed Version + +- An assertion establishes truth (i.e. boolean True) for a single condition. +Upon boolean False, an assertion stops execution and reports the failure. +- Unity is mainly a rich collection of assertions and the support to gather up +and easily execute those assertions. +- The structure of Unity allows you to easily separate test assertions from +source code in, well, test code. +- Unity's assertions: +- Come in many, many flavors to handle different C types and assertion cases. +- Use context to provide detailed and helpful failure messages. +- Document types, expected values, and basic behavior in your source code for +free. + + +### Unity Is Several Things But Mainly It's Assertions + +One way to think of Unity is simply as a rich collection of assertions you can +use to establish whether your source code behaves the way you think it does. +Unity provides a framework to easily organize and execute those assertions in +test code separate from your source code. + + +### What's an Assertion? + +At their core, assertions are an establishment of truth - boolean truth. Was this +thing equal to that thing? Does that code doohickey have such-and-such property +or not? You get the idea. Assertions are executable code (to appreciate the big +picture on this read up on the difference between +[link:Dynamic Verification and Static Analysis]). A failing assertion stops +execution and reports an error through some appropriate I/O channel (e.g. +stdout, GUI, file, blinky light). + +Fundamentally, for dynamic verification all you need is a single assertion +mechanism. In fact, that's what the [assert() macro in C's standard library](http://en.wikipedia.org/en/wiki/Assert.h) +is for. So why not just use it? Well, we can do far better in the reporting +department. C's `assert()` is pretty dumb as-is and is particularly poor for +handling common data types like arrays, structs, etc. And, without some other +support, it's far too tempting to litter source code with C's `assert()`'s. It's +generally much cleaner, manageable, and more useful to separate test and source +code in the way Unity facilitates. + + +### Unity's Assertions: Helpful Messages _and_ Free Source Code Documentation + +Asserting a simple truth condition is valuable, but using the context of the +assertion is even more valuable. For instance, if you know you're comparing bit +flags and not just integers, then why not use that context to give explicit, +readable, bit-level feedback when an assertion fails? + +That's what Unity's collection of assertions do - capture context to give you +helpful, meaningful assertion failure messages. In fact, the assertions +themselves also serve as executable documentation about types and values in your +source code. So long as your tests remain current with your source and all those +tests pass, you have a detailed, up-to-date view of the intent and mechanisms in +your source code. And due to a wondrous mystery, well-tested code usually tends +to be well designed code. + + +## Assertion Conventions and Configurations + +### Naming and Parameter Conventions + +The convention of assertion parameters generally follows this order: + + TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} ) + +The very simplest assertion possible uses only a single "actual" parameter (e.g. +a simple null check). + +"Actual" is the value being tested and unlike the other parameters in an +assertion construction is the only parameter present in all assertion variants. +"Modifiers" are masks, ranges, bit flag specifiers, floating point deltas. +"Expected" is your expected value (duh) to compare to an "actual" value; it's +marked as an optional parameter because some assertions only need a single +"actual" parameter (e.g. null check). +"Size/count" refers to string lengths, number of array elements, etc. + +Many of Unity's assertions are clear duplications in that the same data type +is handled by several assertions. The differences among these are in how failure +messages are presented. For instance, a `_HEX` variant of an assertion prints +the expected and actual values of that assertion formatted as hexadecimal. + + +#### TEST_ASSERT_X_MESSAGE Variants + +_All_ assertions are complemented with a variant that includes a simple string +message as a final parameter. The string you specify is appended to an assertion +failure message in Unity output. + +For brevity, the assertion variants with a message parameter are not listed +below. Just tack on `_MESSAGE` as the final component to any assertion name in +the reference list below and add a string as the final parameter. + +_Example:_ + + TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} ) + +becomes messageified like thus... + + TEST_ASSERT_X_MESSAGE( {modifiers}, {expected}, actual, {size/count}, message ) + +Notes: +- The `_MESSAGE` variants intentionally do not support `printf` style formatting + since many embedded projects don't support or avoid `printf` for various reasons. + It is possible to use `sprintf` before the assertion to assemble a complex fail + message, if necessary. +- If you want to output a counter value within an assertion fail message (e.g. from + a loop) , building up an array of results and then using one of the `_ARRAY` + assertions (see below) might be a handy alternative to `sprintf`. + + +#### TEST_ASSERT_X_ARRAY Variants + +Unity provides a collection of assertions for arrays containing a variety of +types. These are documented in the Array section below. These are almost on par +with the `_MESSAGE`variants of Unity's Asserts in that for pretty much any Unity +type assertion you can tack on `_ARRAY` and run assertions on an entire block of +memory. + + TEST_ASSERT_EQUAL_TYPEX_ARRAY( expected, actual, {size/count} ) + +"Expected" is an array itself. +"Size/count" is one or two parameters necessary to establish the number of array +elements and perhaps the length of elements within the array. + +Notes: +- The `_MESSAGE` variant convention still applies here to array assertions. The +`_MESSAGE` variants of the `_ARRAY` assertions have names ending with +`_ARRAY_MESSAGE`. +- Assertions for handling arrays of floating point values are grouped with float +and double assertions (see immediately following section). + + +### TEST_ASSERT_EACH_EQUAL_X Variants + +Unity provides a collection of assertions for arrays containing a variety of +types which can be compared to a single value as well. These are documented in +the Each Equal section below. these are almost on par with the `_MESSAGE` +variants of Unity's Asserts in that for pretty much any Unity type assertion you +can inject _EACH_EQUAL and run assertions on an entire block of memory. + + TEST_ASSERT_EACH_EQUAL_TYPEX( expected, actual, {size/count} ) + +"Expected" is a single value to compare to. +"Actual" is an array where each element will be compared to the expected value. +"Size/count" is one of two parameters necessary to establish the number of array +elements and perhaps the length of elements within the array. + +Notes: +- The `_MESSAGE` variant convention still applies here to Each Equal assertions. +- Assertions for handling Each Equal of floating point values are grouped with +float and double assertions (see immediately following section). + + +### Configuration + +#### Floating Point Support Is Optional + +Support for floating point types is configurable. That is, by defining the +appropriate preprocessor symbols, floats and doubles can be individually enabled +or disabled in Unity code. This is useful for embedded targets with no floating +point math support (i.e. Unity compiles free of errors for fixed point only +platforms). See Unity documentation for specifics. + + +#### Maximum Data Type Width Is Configurable + +Not all targets support 64 bit wide types or even 32 bit wide types. Define the +appropriate preprocessor symbols and Unity will omit all operations from +compilation that exceed the maximum width of your target. See Unity +documentation for specifics. + + +## The Assertions in All Their Blessed Glory + +### Basic Fail and Ignore + +##### `TEST_FAIL()` + +This fella is most often used in special conditions where your test code is +performing logic beyond a simple assertion. That is, in practice, `TEST_FAIL()` +will always be found inside a conditional code block. + +_Examples:_ +- Executing a state machine multiple times that increments a counter your test +code then verifies as a final step. +- Triggering an exception and verifying it (as in Try / Catch / Throw - see the +[CException](https://github.com/ThrowTheSwitch/CException) project). + +##### `TEST_IGNORE()` + +Marks a test case (i.e. function meant to contain test assertions) as ignored. +Usually this is employed as a breadcrumb to come back and implement a test case. +An ignored test case has effects if other assertions are in the enclosing test +case (see Unity documentation for more). + +### Boolean + +##### `TEST_ASSERT (condition)` + +##### `TEST_ASSERT_TRUE (condition)` + +##### `TEST_ASSERT_FALSE (condition)` + +##### `TEST_ASSERT_UNLESS (condition)` + +A simple wording variation on `TEST_ASSERT_FALSE`.The semantics of +`TEST_ASSERT_UNLESS` aid readability in certain test constructions or +conditional statements. + +##### `TEST_ASSERT_NULL (pointer)` + +##### `TEST_ASSERT_NOT_NULL (pointer)` + + +### Signed and Unsigned Integers (of all sizes) + +Large integer sizes can be disabled for build targets that do not support them. +For example, if your target only supports up to 16 bit types, by defining the +appropriate symbols Unity can be configured to omit 32 and 64 bit operations +that would break compilation (see Unity documentation for more). Refer to +Advanced Asserting later in this document for advice on dealing with other word +sizes. + +##### `TEST_ASSERT_EQUAL_INT (expected, actual)` + +##### `TEST_ASSERT_EQUAL_INT8 (expected, actual)` + +##### `TEST_ASSERT_EQUAL_INT16 (expected, actual)` + +##### `TEST_ASSERT_EQUAL_INT32 (expected, actual)` + +##### `TEST_ASSERT_EQUAL_INT64 (expected, actual)` + +##### `TEST_ASSERT_EQUAL (expected, actual)` + +##### `TEST_ASSERT_NOT_EQUAL (expected, actual)` + +##### `TEST_ASSERT_EQUAL_UINT (expected, actual)` + +##### `TEST_ASSERT_EQUAL_UINT8 (expected, actual)` + +##### `TEST_ASSERT_EQUAL_UINT16 (expected, actual)` + +##### `TEST_ASSERT_EQUAL_UINT32 (expected, actual)` + +##### `TEST_ASSERT_EQUAL_UINT64 (expected, actual)` + + +### Unsigned Integers (of all sizes) in Hexadecimal + +All `_HEX` assertions are identical in function to unsigned integer assertions +but produce failure messages with the `expected` and `actual` values formatted +in hexadecimal. Unity output is big endian. + +##### `TEST_ASSERT_EQUAL_HEX (expected, actual)` + +##### `TEST_ASSERT_EQUAL_HEX8 (expected, actual)` + +##### `TEST_ASSERT_EQUAL_HEX16 (expected, actual)` + +##### `TEST_ASSERT_EQUAL_HEX32 (expected, actual)` + +##### `TEST_ASSERT_EQUAL_HEX64 (expected, actual)` + + +### Masked and Bit-level Assertions + +Masked and bit-level assertions produce output formatted in hexadecimal. Unity +output is big endian. + + +##### `TEST_ASSERT_BITS (mask, expected, actual)` + +Only compares the masked (i.e. high) bits of `expected` and `actual` parameters. + + +##### `TEST_ASSERT_BITS_HIGH (mask, actual)` + +Asserts the masked bits of the `actual` parameter are high. + + +##### `TEST_ASSERT_BITS_LOW (mask, actual)` + +Asserts the masked bits of the `actual` parameter are low. + + +##### `TEST_ASSERT_BIT_HIGH (bit, actual)` + +Asserts the specified bit of the `actual` parameter is high. + + +##### `TEST_ASSERT_BIT_LOW (bit, actual)` + +Asserts the specified bit of the `actual` parameter is low. + +### Integer Less Than / Greater Than + +These assertions verify that the `actual` parameter is less than or greater +than `threshold` (exclusive). For example, if the threshold value is 0 for the +greater than assertion will fail if it is 0 or less. + +##### `TEST_ASSERT_GREATER_THAN (threshold, actual)` + +##### `TEST_ASSERT_GREATER_THAN_INT (threshold, actual)` + +##### `TEST_ASSERT_GREATER_THAN_INT8 (threshold, actual)` + +##### `TEST_ASSERT_GREATER_THAN_INT16 (threshold, actual)` + +##### `TEST_ASSERT_GREATER_THAN_INT32 (threshold, actual)` + +##### `TEST_ASSERT_GREATER_THAN_UINT (threshold, actual)` + +##### `TEST_ASSERT_GREATER_THAN_UINT8 (threshold, actual)` + +##### `TEST_ASSERT_GREATER_THAN_UINT16 (threshold, actual)` + +##### `TEST_ASSERT_GREATER_THAN_UINT32 (threshold, actual)` + +##### `TEST_ASSERT_GREATER_THAN_HEX8 (threshold, actual)` + +##### `TEST_ASSERT_GREATER_THAN_HEX16 (threshold, actual)` + +##### `TEST_ASSERT_GREATER_THAN_HEX32 (threshold, actual)` + +##### `TEST_ASSERT_LESS_THAN (threshold, actual)` + +##### `TEST_ASSERT_LESS_THAN_INT (threshold, actual)` + +##### `TEST_ASSERT_LESS_THAN_INT8 (threshold, actual)` + +##### `TEST_ASSERT_LESS_THAN_INT16 (threshold, actual)` + +##### `TEST_ASSERT_LESS_THAN_INT32 (threshold, actual)` + +##### `TEST_ASSERT_LESS_THAN_UINT (threshold, actual)` + +##### `TEST_ASSERT_LESS_THAN_UINT8 (threshold, actual)` + +##### `TEST_ASSERT_LESS_THAN_UINT16 (threshold, actual)` + +##### `TEST_ASSERT_LESS_THAN_UINT32 (threshold, actual)` + +##### `TEST_ASSERT_LESS_THAN_HEX8 (threshold, actual)` + +##### `TEST_ASSERT_LESS_THAN_HEX16 (threshold, actual)` + +##### `TEST_ASSERT_LESS_THAN_HEX32 (threshold, actual)` + + +### Integer Ranges (of all sizes) + +These assertions verify that the `expected` parameter is within +/- `delta` +(inclusive) of the `actual` parameter. For example, if the expected value is 10 +and the delta is 3 then the assertion will fail for any value outside the range +of 7 - 13. + +##### `TEST_ASSERT_INT_WITHIN (delta, expected, actual)` + +##### `TEST_ASSERT_INT8_WITHIN (delta, expected, actual)` + +##### `TEST_ASSERT_INT16_WITHIN (delta, expected, actual)` + +##### `TEST_ASSERT_INT32_WITHIN (delta, expected, actual)` + +##### `TEST_ASSERT_INT64_WITHIN (delta, expected, actual)` + +##### `TEST_ASSERT_UINT_WITHIN (delta, expected, actual)` + +##### `TEST_ASSERT_UINT8_WITHIN (delta, expected, actual)` + +##### `TEST_ASSERT_UINT16_WITHIN (delta, expected, actual)` + +##### `TEST_ASSERT_UINT32_WITHIN (delta, expected, actual)` + +##### `TEST_ASSERT_UINT64_WITHIN (delta, expected, actual)` + +##### `TEST_ASSERT_HEX_WITHIN (delta, expected, actual)` + +##### `TEST_ASSERT_HEX8_WITHIN (delta, expected, actual)` + +##### `TEST_ASSERT_HEX16_WITHIN (delta, expected, actual)` + +##### `TEST_ASSERT_HEX32_WITHIN (delta, expected, actual)` + +##### `TEST_ASSERT_HEX64_WITHIN (delta, expected, actual)` + + +### Structs and Strings + +##### `TEST_ASSERT_EQUAL_PTR (expected, actual)` + +Asserts that the pointers point to the same memory location. + + +##### `TEST_ASSERT_EQUAL_STRING (expected, actual)` + +Asserts that the null terminated (`'\0'`)strings are identical. If strings are +of different lengths or any portion of the strings before their terminators +differ, the assertion fails. Two NULL strings (i.e. zero length) are considered +equivalent. + + +##### `TEST_ASSERT_EQUAL_MEMORY (expected, actual, len)` + +Asserts that the contents of the memory specified by the `expected` and `actual` +pointers is identical. The size of the memory blocks in bytes is specified by +the `len` parameter. + + +### Arrays + +`expected` and `actual` parameters are both arrays. `num_elements` specifies the +number of elements in the arrays to compare. + +`_HEX` assertions produce failure messages with expected and actual array +contents formatted in hexadecimal. + +For array of strings comparison behavior, see comments for +`TEST_ASSERT_EQUAL_STRING` in the preceding section. + +Assertions fail upon the first element in the compared arrays found not to +match. Failure messages specify the array index of the failed comparison. + +##### `TEST_ASSERT_EQUAL_INT_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_INT8_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_INT16_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_INT32_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_INT64_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_UINT_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_UINT8_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_UINT16_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_UINT32_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_UINT64_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_HEX_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_HEX8_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_HEX16_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_HEX32_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_HEX64_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_PTR_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_STRING_ARRAY (expected, actual, num_elements)` + +##### `TEST_ASSERT_EQUAL_MEMORY_ARRAY (expected, actual, len, num_elements)` + +`len` is the memory in bytes to be compared at each array element. + + +### Each Equal (Arrays to Single Value) + +`expected` are single values and `actual` are arrays. `num_elements` specifies +the number of elements in the arrays to compare. + +`_HEX` assertions produce failure messages with expected and actual array +contents formatted in hexadecimal. + +Assertions fail upon the first element in the compared arrays found not to +match. Failure messages specify the array index of the failed comparison. + +#### `TEST_ASSERT_EACH_EQUAL_INT (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_INT8 (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_INT16 (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_INT32 (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_INT64 (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_UINT (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_UINT8 (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_UINT16 (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_UINT32 (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_UINT64 (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_HEX (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_HEX8 (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_HEX16 (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_HEX32 (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_HEX64 (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_PTR (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_STRING (expected, actual, num_elements)` + +#### `TEST_ASSERT_EACH_EQUAL_MEMORY (expected, actual, len, num_elements)` + +`len` is the memory in bytes to be compared at each array element. + + +### Floating Point (If enabled) + +##### `TEST_ASSERT_FLOAT_WITHIN (delta, expected, actual)` + +Asserts that the `actual` value is within +/- `delta` of the `expected` value. +The nature of floating point representation is such that exact evaluations of +equality are not guaranteed. + + +##### `TEST_ASSERT_EQUAL_FLOAT (expected, actual)` + +Asserts that the ?actual?value is "close enough to be considered equal" to the +`expected` value. If you are curious about the details, refer to the Advanced +Asserting section for more details on this. Omitting a user-specified delta in a +floating point assertion is both a shorthand convenience and a requirement of +code generation conventions for CMock. + + +##### `TEST_ASSERT_EQUAL_FLOAT_ARRAY (expected, actual, num_elements)` + +See Array assertion section for details. Note that individual array element +float comparisons are executed using T?EST_ASSERT_EQUAL_FLOAT?.That is, user +specified delta comparison values requires a custom-implemented floating point +array assertion. + + +##### `TEST_ASSERT_FLOAT_IS_INF (actual)` + +Asserts that `actual` parameter is equivalent to positive infinity floating +point representation. + + +##### `TEST_ASSERT_FLOAT_IS_NEG_INF (actual)` + +Asserts that `actual` parameter is equivalent to negative infinity floating +point representation. + + +##### `TEST_ASSERT_FLOAT_IS_NAN (actual)` + +Asserts that `actual` parameter is a Not A Number floating point representation. + + +##### `TEST_ASSERT_FLOAT_IS_DETERMINATE (actual)` + +Asserts that ?actual?parameter is a floating point representation usable for +mathematical operations. That is, the `actual` parameter is neither positive +infinity nor negative infinity nor Not A Number floating point representations. + + +##### `TEST_ASSERT_FLOAT_IS_NOT_INF (actual)` + +Asserts that `actual` parameter is a value other than positive infinity floating +point representation. + + +##### `TEST_ASSERT_FLOAT_IS_NOT_NEG_INF (actual)` + +Asserts that `actual` parameter is a value other than negative infinity floating +point representation. + + +##### `TEST_ASSERT_FLOAT_IS_NOT_NAN (actual)` + +Asserts that `actual` parameter is a value other than Not A Number floating +point representation. + + +##### `TEST_ASSERT_FLOAT_IS_NOT_DETERMINATE (actual)` + +Asserts that `actual` parameter is not usable for mathematical operations. That +is, the `actual` parameter is either positive infinity or negative infinity or +Not A Number floating point representations. + + +### Double (If enabled) + +##### `TEST_ASSERT_DOUBLE_WITHIN (delta, expected, actual)` + +Asserts that the `actual` value is within +/- `delta` of the `expected` value. +The nature of floating point representation is such that exact evaluations of +equality are not guaranteed. + + +##### `TEST_ASSERT_EQUAL_DOUBLE (expected, actual)` + +Asserts that the `actual` value is "close enough to be considered equal" to the +`expected` value. If you are curious about the details, refer to the Advanced +Asserting section for more details. Omitting a user-specified delta in a +floating point assertion is both a shorthand convenience and a requirement of +code generation conventions for CMock. + + +##### `TEST_ASSERT_EQUAL_DOUBLE_ARRAY (expected, actual, num_elements)` + +See Array assertion section for details. Note that individual array element +double comparisons are executed using `TEST_ASSERT_EQUAL_DOUBLE`.That is, user +specified delta comparison values requires a custom implemented double array +assertion. + + +##### `TEST_ASSERT_DOUBLE_IS_INF (actual)` + +Asserts that `actual` parameter is equivalent to positive infinity floating +point representation. + + +##### `TEST_ASSERT_DOUBLE_IS_NEG_INF (actual)` + +Asserts that `actual` parameter is equivalent to negative infinity floating point +representation. + + +##### `TEST_ASSERT_DOUBLE_IS_NAN (actual)` + +Asserts that `actual` parameter is a Not A Number floating point representation. + + +##### `TEST_ASSERT_DOUBLE_IS_DETERMINATE (actual)` + +Asserts that `actual` parameter is a floating point representation usable for +mathematical operations. That is, the ?actual?parameter is neither positive +infinity nor negative infinity nor Not A Number floating point representations. + + +##### `TEST_ASSERT_DOUBLE_IS_NOT_INF (actual)` + +Asserts that `actual` parameter is a value other than positive infinity floating +point representation. + + +##### `TEST_ASSERT_DOUBLE_IS_NOT_NEG_INF (actual)` + +Asserts that `actual` parameter is a value other than negative infinity floating +point representation. + + +##### `TEST_ASSERT_DOUBLE_IS_NOT_NAN (actual)` + +Asserts that `actual` parameter is a value other than Not A Number floating +point representation. + + +##### `TEST_ASSERT_DOUBLE_IS_NOT_DETERMINATE (actual)` + +Asserts that `actual` parameter is not usable for mathematical operations. That +is, the `actual` parameter is either positive infinity or negative infinity or +Not A Number floating point representations. + + +## Advanced Asserting: Details On Tricky Assertions + +This section helps you understand how to deal with some of the trickier +assertion situations you may run into. It will give you a glimpse into some of +the under-the-hood details of Unity's assertion mechanisms. If you're one of +those people who likes to know what is going on in the background, read on. If +not, feel free to ignore the rest of this document until you need it. + + +### How do the EQUAL assertions work for FLOAT and DOUBLE? + +As you may know, directly checking for equality between a pair of floats or a +pair of doubles is sloppy at best and an outright no-no at worst. Floating point +values can often be represented in multiple ways, particularly after a series of +operations on a value. Initializing a variable to the value of 2.0 is likely to +result in a floating point representation of 2 x 20,but a series of +mathematical operations might result in a representation of 8 x 2-2 +that also evaluates to a value of 2. At some point repeated operations cause +equality checks to fail. + +So Unity doesn't do direct floating point comparisons for equality. Instead, it +checks if two floating point values are "really close." If you leave Unity +running with defaults, "really close" means "within a significant bit or two." +Under the hood, `TEST_ASSERT_EQUAL_FLOAT` is really `TEST_ASSERT_FLOAT_WITHIN` +with the `delta` parameter calculated on the fly. For single precision, delta is +the expected value multiplied by 0.00001, producing a very small proportional +range around the expected value. + +If you are expecting a value of 20,000.0 the delta is calculated to be 0.2. So +any value between 19,999.8 and 20,000.2 will satisfy the equality check. This +works out to be roughly a single bit of range for a single-precision number, and +that's just about as tight a tolerance as you can reasonably get from a floating +point value. + +So what happens when it's zero? Zero - even more than other floating point +values - can be represented many different ways. It doesn't matter if you have +0 x 20 or 0 x 263.It's still zero, right? Luckily, if you +subtract these values from each other, they will always produce a difference of +zero, which will still fall between 0 plus or minus a delta of 0. So it still +works! + +Double precision floating point numbers use a much smaller multiplier, again +approximating a single bit of error. + +If you don't like these ranges and you want to make your floating point equality +assertions less strict, you can change these multipliers to whatever you like by +defining UNITY_FLOAT_PRECISION and UNITY_DOUBLE_PRECISION. See Unity +documentation for more. + + +### How do we deal with targets with non-standard int sizes? + +It's "fun" that C is a standard where something as fundamental as an integer +varies by target. According to the C standard, an `int` is to be the target's +natural register size, and it should be at least 16-bits and a multiple of a +byte. It also guarantees an order of sizes: + +```C +char <= short <= int <= long <= long long +``` + +Most often, `int` is 32-bits. In many cases in the embedded world, `int` is +16-bits. There are rare microcontrollers out there that have 24-bit integers, +and this remains perfectly standard C. + +To make things even more interesting, there are compilers and targets out there +that have a hard choice to make. What if their natural register size is 10-bits +or 12-bits? Clearly they can't fulfill _both_ the requirement to be at least +16-bits AND the requirement to match the natural register size. In these +situations, they often choose the natural register size, leaving us with +something like this: + +```C +char (8 bit) <= short (12 bit) <= int (12 bit) <= long (16 bit) +``` + +Um... yikes. It's obviously breaking a rule or two... but they had to break SOME +rules, so they made a choice. + +When the C99 standard rolled around, it introduced alternate standard-size types. +It also introduced macros for pulling in MIN/MAX values for your integer types. +It's glorious! Unfortunately, many embedded compilers can't be relied upon to +use the C99 types (Sometimes because they have weird register sizes as described +above. Sometimes because they don't feel like it?). + +A goal of Unity from the beginning was to support every combination of +microcontroller or microprocessor and C compiler. Over time, we've gotten really +close to this. There are a few tricks that you should be aware of, though, if +you're going to do this effectively on some of these more idiosyncratic targets. + +First, when setting up Unity for a new target, you're going to want to pay +special attention to the macros for automatically detecting types +(where available) or manually configuring them yourself. You can get information +on both of these in Unity's documentation. + +What about the times where you suddenly need to deal with something odd, like a +24-bit `int`? The simplest solution is to use the next size up. If you have a +24-bit `int`, configure Unity to use 32-bit integers. If you have a 12-bit +`int`, configure Unity to use 16 bits. There are two ways this is going to +affect you: + +1. When Unity displays errors for you, it's going to pad the upper unused bits +with zeros. +2. You're going to have to be careful of assertions that perform signed +operations, particularly `TEST_ASSERT_INT_WITHIN`.Such assertions might wrap +your `int` in the wrong place, and you could experience false failures. You can +always back down to a simple `TEST_ASSERT` and do the operations yourself. + + +*Find The Latest of This And More at [ThrowTheSwitch.org](https://throwtheswitch.org)* diff --git a/tinyusb/test/vendor/ceedling/docs/UnityConfigurationGuide.md b/tinyusb/test/vendor/ceedling/docs/UnityConfigurationGuide.md new file mode 100755 index 00000000..dace20c5 --- /dev/null +++ b/tinyusb/test/vendor/ceedling/docs/UnityConfigurationGuide.md @@ -0,0 +1,433 @@ +# Unity Configuration Guide + +## C Standards, Compilers and Microcontrollers + +The embedded software world contains its challenges. Compilers support different +revisions of the C Standard. They ignore requirements in places, sometimes to +make the language more usable in some special regard. Sometimes it's to simplify +their support. Sometimes it's due to specific quirks of the microcontroller they +are targeting. Simulators add another dimension to this menagerie. + +Unity is designed to run on almost anything that is targeted by a C compiler. It +would be awesome if this could be done with zero configuration. While there are +some targets that come close to this dream, it is sadly not universal. It is +likely that you are going to need at least a couple of the configuration options +described in this document. + +All of Unity's configuration options are `#defines`. Most of these are simple +definitions. A couple are macros with arguments. They live inside the +unity_internals.h header file. We don't necessarily recommend opening that file +unless you really need to. That file is proof that a cross-platform library is +challenging to build. From 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. + + +### Using These Options + +It doesn't matter if you're using a target-specific compiler and a simulator or +a native compiler. In either case, you've got a couple choices for configuring +these options: + +1. 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. +2. You can create a custom `unity_config.h` configuration file (present in your +toolchain's search paths). 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. + + +## The Options + +### Integer Types + +If you've been a C developer for long, you probably already know that C's +concept of an integer varies from target to target. The C Standard has rules +about the `int` matching the register size of the target microprocessor. It has +rules about the `int` and how its size relates to other integer types. An `int` +on one target might be 16 bits while on another target it might be 64. There are +more specific types in compilers compliant with C99 or later, but that's +certainly not every compiler you are likely to encounter. Therefore, Unity has a +number of features for helping to adjust itself to match your required integer +sizes. It starts off by trying to do it automatically. + + +##### `UNITY_EXCLUDE_STDINT_H` + +The first thing that Unity does to guess your types is check `stdint.h`. +This file includes defines like `UINT_MAX` that Unity can use to +learn a lot about your system. It'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`. If that's the case, you're going to want to define this. +That way, Unity will know to skip the inclusion of this file and you won't +be left with a compiler error. + +_Example:_ + #define UNITY_EXCLUDE_STDINT_H + + +##### `UNITY_EXCLUDE_LIMITS_H` + +The second attempt to guess your types is to check `limits.h`. Some compilers +that don't support `stdint.h` could include `limits.h` instead. If you don't +want Unity to check this file either, define this to make it skip the inclusion. + +_Example:_ + #define UNITY_EXCLUDE_LIMITS_H + + +If you've disabled both of the automatic options above, you're going to have to +do the configuration yourself. Don't worry. Even 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. + + +##### `UNITY_INT_WIDTH` + +Define this to be the number of bits an `int` takes up on your system. The +default, if not autodetected, is 32 bits. + +_Example:_ + #define UNITY_INT_WIDTH 16 + + +##### `UNITY_LONG_WIDTH` + +Define this to be the number of bits a `long` takes up on your system. The +default, if not autodetected, is 32 bits. This is used to figure out what kind +of 64-bit support your system can handle. Does it need to specify a `long` or a +`long long` to get a 64-bit value. On 16-bit systems, this option is going to be +ignored. + +_Example:_ + #define UNITY_LONG_WIDTH 16 + + +##### `UNITY_POINTER_WIDTH` + +Define this to be the number of bits a pointer takes up on your system. The +default, if not autodetected, is 32-bits. If you're getting ugly compiler +warnings about casting from pointers, this is the one to look at. + +_Example:_ + #define UNITY_POINTER_WIDTH 64 + + +##### `UNITY_SUPPORT_64` + +Unity will automatically include 64-bit support if it auto-detects it, or if +your `int`, `long`, or pointer widths are greater than 32-bits. Define this to +enable 64-bit support if none of the other options already did it for you. There +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. + +_Example:_ + #define UNITY_SUPPORT_64 + + +### Floating Point Types + +In 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. We are able to guess integer sizes on the fly because integers +are always available in at least one size. Floating point, on the other hand, is +sometimes not available at all. Trying to include `float.h` on these platforms +would result in an error. This leaves manual configuration as the only option. + + +##### `UNITY_INCLUDE_FLOAT` + +##### `UNITY_EXCLUDE_FLOAT` + +##### `UNITY_INCLUDE_DOUBLE` + +##### `UNITY_EXCLUDE_DOUBLE` + +By default, Unity guesses that you will want single precision floating point +support, but not double precision. It's easy to change either of these using the +include and exclude options here. You may include neither, either, or both, as +suits your needs. For features that are enabled, the following floating point +options also become available. + +_Example:_ + + //what manner of strange processor is this? + #define UNITY_EXCLUDE_FLOAT + #define UNITY_INCLUDE_DOUBLE + + +##### `UNITY_EXCLUDE_FLOAT_PRINT` + +Unity aims for as small of a footprint as possible and avoids most standard +library calls (some embedded platforms don’t have a standard library!). Because +of this, its routines for printing integer values are minimalist and hand-coded. +Therefore, the display of floating point values during a failure are optional. +By default, Unity will print the actual results of floating point assertion +failure (e.g. ”Expected 4.56 Was 4.68”). To 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”. If you would like verbose failure messages for floating +point assertions, use these options to give more explicit failure messages. + +_Example:_ + #define UNITY_EXCLUDE_FLOAT_PRINT + + +##### `UNITY_FLOAT_TYPE` + +If enabled, Unity assumes you want your `FLOAT` asserts to compare standard C +floats. If your compiler supports a specialty floating point type, you can +always override this behavior by using this definition. + +_Example:_ + #define UNITY_FLOAT_TYPE float16_t + + +##### `UNITY_DOUBLE_TYPE` + +If enabled, Unity assumes you want your `DOUBLE` asserts to compare standard C +doubles. If you would like to change this, you can specify something else by +using this option. For example, defining `UNITY_DOUBLE_TYPE` to `long double` +could enable gargantuan floating point types on your 64-bit processor instead of +the standard `double`. + +_Example:_ + #define UNITY_DOUBLE_TYPE long double + + +##### `UNITY_FLOAT_PRECISION` + +##### `UNITY_DOUBLE_PRECISION` + +If 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. "Close enough" is controlled by these precision +configuration options. If 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. They are both set to give you approximately 1 significant bit in either +direction. The float precision is 0.00001 while the double is 10-12. +For further details on how this works, see the appendix of the Unity Assertion +Guide. + +_Example:_ + #define UNITY_FLOAT_PRECISION 0.001f + + +### Toolset Customization + +In 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. It 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. These macros will help in those +situations. + + +##### `UNITY_OUTPUT_CHAR(a)` + +##### `UNITY_OUTPUT_FLUSH()` + +##### `UNITY_OUTPUT_START()` + +##### `UNITY_OUTPUT_COMPLETE()` + +By default, Unity prints its results to `stdout` as it runs. This works +perfectly fine in most situations where you are using a native compiler for +testing. It works on some simulators as well so long as they have `stdout` +routed back to the command line. There are times, however, where the simulator +will lack support for dumping results or you will want to route results +elsewhere for other reasons. In these cases, you should define the +`UNITY_OUTPUT_CHAR` macro. This 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). You may replace this with whatever function call you like. + +_Example:_ +Say you are forced to run your test suite on an embedded processor with no +`stdout` option. You decide to route your test result output to a custom serial +`RS232_putc()` function you wrote like thus: + #include "RS232_header.h" + ... + #define UNITY_OUTPUT_CHAR(a) RS232_putc(a) + #define UNITY_OUTPUT_START() RS232_config(115200,1,8,0) + #define UNITY_OUTPUT_FLUSH() RS232_flush() + #define UNITY_OUTPUT_COMPLETE() RS232_close() + +_Note:_ +`UNITY_OUTPUT_FLUSH()` can be set to the standard out flush function simply by +specifying `UNITY_USE_FLUSH_STDOUT`. No other defines are required. + + +##### `UNITY_WEAK_ATTRIBUTE` + +##### `UNITY_WEAK_PRAGMA` + +##### `UNITY_NO_WEAK` + +For some targets, Unity can make the otherwise required setUp() and tearDown() +functions optional. This is a nice convenience for test writers since setUp and +tearDown don’t often actually do anything. If you’re using gcc or clang, this +option is automatically defined for you. Other compilers can also support this +behavior, if they support a C feature called weak functions. A weak function is +a function that is compiled into your executable unless a non-weak version of +the same function is defined elsewhere. If a non-weak version is found, the weak +version is ignored as if it never existed. If your compiler supports this feature, +you can let Unity know by defining UNITY_WEAK_ATTRIBUTE or UNITY_WEAK_PRAGMA as +the function attributes that would need to be applied to identify a function as +weak. If your compiler lacks support for weak functions, you will always need to +define setUp and tearDown functions (though they can be and often will be just +empty). You can also force Unity to NOT use weak functions by defining +UNITY_NO_WEAK. The most common options for this feature are: + +_Example:_ + #define UNITY_WEAK_ATTRIBUTE weak + #define UNITY_WEAK_ATTRIBUTE __attribute__((weak)) + #define UNITY_WEAK_PRAGMA + #define UNITY_NO_WEAK + + +##### `UNITY_PTR_ATTRIBUTE` + +Some compilers require a custom attribute to be assigned to pointers, like +`near` or `far`. In these cases, you can give Unity a safe default for these by +defining this option with the attribute you would like. + +_Example:_ + #define UNITY_PTR_ATTRIBUTE __attribute__((far)) + #define UNITY_PTR_ATTRIBUTE near + + +##### `UNITY_PRINT_EOL` + +By default, Unity outputs \n at the end of each line of output. This is easy +to parse by the scripts, by Ceedling, etc, but it might not be ideal for YOUR +system. Feel free to override this and to make it whatever you wish. + +_Example:_ + #define UNITY_PRINT_EOL { UNITY_OUTPUT_CHAR('\r'); UNITY_OUTPUT_CHAR('\n') } + + + +##### `UNITY_EXCLUDE_DETAILS` + +This is an option for if you absolutely must squeeze every byte of memory out of +your system. Unity stores a set of internal scratchpads which are used to pass +extra detail information around. It's used by systems like CMock in order to +report which function or argument flagged an error. If you're not using CMock and +you're not using these details for other things, then you can exclude them. + +_Example:_ + #define UNITY_EXCLUDE_DETAILS + + + +##### `UNITY_EXCLUDE_SETJMP` + +If your embedded system doesn't support the standard library setjmp, you can +exclude Unity's reliance on this by using this define. This dropped dependence +comes at a price, though. You will be unable to use custom helper functions for +your tests, and you will be unable to use tools like CMock. Very 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. + +_Example:_ + #define UNITY_EXCLUDE_SETJMP + +##### `UNITY_OUTPUT_COLOR` + +If you want to add color using ANSI escape codes you can use this define. +t +_Example:_ + #define UNITY_OUTPUT_COLOR + + + +## Getting Into The Guts + +There will be cases where the options above aren't quite going to get everything +perfect. They are likely sufficient for any situation where you are compiling +and executing your tests with a native toolchain (e.g. clang on Mac). These +options may even get you through the majority of cases encountered in working +with a target simulator run from your local command line. But especially if you +must run your test suite on your target hardware, your Unity configuration will +require special help. This special help will usually reside in one of two +places: the `main()` function or the `RUN_TEST` macro. Let's look at how these +work. + + +##### `main()` + +Each test module is compiled and run on its own, separate from the other test +files in your project. Each test file, therefore, has a `main` function. This +`main` function will need to contain whatever code is necessary to initialize +your system to a workable state. This 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. + +A simple main function looks something like this: + + int main(void) { + UNITY_BEGIN(); + RUN_TEST(test_TheFirst); + RUN_TEST(test_TheSecond); + RUN_TEST(test_TheThird); + return UNITY_END(); + } + +You can see that our main function doesn't bother taking any arguments. For our +most barebones case, we'll never have arguments because we just run all the +tests each time. Instead, we start by calling `UNITY_BEGIN`. We run each test +(in whatever order we wish). Finally, we call `UNITY_END`, returning its return +value (which is the total number of failures). + +It should be easy to see that you can add code before any test cases are run or +after all the test cases have completed. This allows you to do any needed +system-wide setup or teardown that might be required for your special +circumstances. + + +##### `RUN_TEST` + +The `RUN_TEST` macro is called with each test case function. Its job is to +perform whatever setup and teardown is necessary for executing a single test +case function. This includes catching failures, calling the test module's +`setUp()` and `tearDown()` functions, and calling `UnityConcludeTest()`. If +using CMock or test coverage, there will be additional stubs in use here. A +simple minimalist RUN_TEST macro looks something like this: + + #define RUN_TEST(testfunc) \ + UNITY_NEW_TEST(#testfunc) \ + if (TEST_PROTECT()) { \ + setUp(); \ + testfunc(); \ + } \ + if (TEST_PROTECT() && (!TEST_IS_IGNORED)) \ + tearDown(); \ + UnityConcludeTest(); + +So that's quite a macro, huh? It gives you a glimpse of what kind of stuff Unity +has to deal with for every single test case. For each test case, we declare that +it is a new test. Then we run `setUp` and our test function. These are run +within a `TEST_PROTECT` block, the function of which is to handle failures that +occur during the test. Then, assuming our test is still running and hasn't been +ignored, we run `tearDown`. No matter what, our last step is to conclude this +test before moving on to the next. + +Let'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. You could easily insert this after your +`UnityConcludeTest` call. Maybe you want to write an xml tag before and after +each result set. Again, you could do this by adding lines to this macro. Updates +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. + + +## Happy Porting + +The defines and macros in this guide should help you port Unity to just about +any C target we can imagine. If you run into a snag or two, don't be afraid of +asking for help on the forums. We love a good challenge! + + +*Find The Latest of This And More at [ThrowTheSwitch.org](https://throwtheswitch.org)* diff --git a/tinyusb/test/vendor/ceedling/docs/UnityGettingStartedGuide.md b/tinyusb/test/vendor/ceedling/docs/UnityGettingStartedGuide.md new file mode 100755 index 00000000..5e4427ce --- /dev/null +++ b/tinyusb/test/vendor/ceedling/docs/UnityGettingStartedGuide.md @@ -0,0 +1,192 @@ +# Unity - Getting Started + +## Welcome + +Congratulations. You're now the proud owner of your very own pile of bits! What +are you going to do with all these ones and zeros? This document should be able +to help you decide just that. + +Unity is a unit test framework. The goal has been to keep it small and +functional. The core Unity test framework is three files: a single C file and a +couple header files. These team up to provide functions and macros to make +testing easier. + +Unity was designed to be cross-platform. It works hard to stick with C standards +while still providing support for the many embedded C compilers that bend the +rules. Unity has been used with many compilers, including GCC, IAR, Clang, +Green Hills, Microchip, and MS Visual Studio. It's not much work to get it to +work with a new target. + + +### Overview of the Documents + +#### Unity Assertions reference + +This document will guide you through all the assertion options provided by +Unity. This is going to be your unit testing bread and butter. You'll spend more +time with assertions than any other part of Unity. + + +#### Unity Assertions Cheat Sheet + +This document contains an abridged summary of the assertions described in the +previous document. It's perfect for printing and referencing while you +familiarize yourself with Unity's options. + + +#### Unity Configuration Guide + +This document is the one to reference when you are going to use Unity with a new +target or compiler. It'll guide you through the configuration options and will +help you customize your testing experience to meet your needs. + + +#### Unity Helper Scripts + +This document describes the helper scripts that are available for simplifying +your testing workflow. It describes the collection of optional Ruby scripts +included in the auto directory of your Unity installation. Neither Ruby nor +these scripts are necessary for using Unity. They are provided as a convenience +for those who wish to use them. + + +#### Unity License + +What's an open source project without a license file? This brief document +describes the terms you're agreeing to when you use this software. Basically, we +want it to be useful to you in whatever context you want to use it, but please +don't blame us if you run into problems. + + +### Overview of the Folders + +If you have obtained Unity through Github or something similar, you might be +surprised by just how much stuff you suddenly have staring you in the face. +Don't worry, Unity itself is very small. The rest of it is just there to make +your life easier. You can ignore it or use it at your convenience. Here's an +overview of everything in the project. + +- `src` - This is the code you care about! This folder contains a C file and two +header files. These three files _are_ Unity. +- `docs` - You're reading this document, so it's possible you have found your way +into this folder already. This is where all the handy documentation can be +found. +- `examples` - This contains a few examples of using Unity. +- `extras` - These are optional add ons to Unity that are not part of the core +project. If you've reached us through James Grenning's book, you're going to +want to look here. +- `test` - This is how Unity and its scripts are all tested. If you're just using +Unity, you'll likely never need to go in here. If you are the lucky team member +who gets to port Unity to a new toolchain, this is a good place to verify +everything is configured properly. +- `auto` - Here you will find helpful Ruby scripts for simplifying your test +workflow. They are purely optional and are not required to make use of Unity. + + +## How to Create A Test File + +Test files are C files. Most often you will create a single test file for each C +module that you want to test. The test file should include unity.h and the +header for your C module to be tested. + +Next, a test file will include a `setUp()` and `tearDown()` function. The setUp +function can contain anything you would like to run before each test. The +tearDown function can contain anything you would like to run after each test. +Both functions accept no arguments and return nothing. You may leave either or +both of these blank if you have no need for them. If you're using a compiler +that is configured to make these functions optional, you may leave them off +completely. Not sure? Give it a try. If you compiler complains that it can't +find setUp or tearDown when it links, you'll know you need to at least include +an empty function for these. + +The majority of the file will be a series of test functions. Test functions +follow the convention of starting with the word "test_" or "spec_". You don't HAVE +to name them this way, but it makes it clear what functions are tests for other +developers. Also, the automated scripts that come with Unity or Ceedling will default +to looking for test functions to be prefixed this way. Test functions take no arguments +and return nothing. All test accounting is handled internally in Unity. + +Finally, at the bottom of your test file, you will write a `main()` function. +This function will call `UNITY_BEGIN()`, then `RUN_TEST` for each test, and +finally `UNITY_END()`.This is what will actually trigger each of those test +functions to run, so it is important that each function gets its own `RUN_TEST` +call. + +Remembering to add each test to the main function can get to be tedious. If you +enjoy using helper scripts in your build process, you might consider making use +of our handy generate_test_runner.rb script. This will create the main function +and all the calls for you, assuming that you have followed the suggested naming +conventions. In this case, there is no need for you to include the main function +in your test file at all. + +When you're done, your test file will look something like this: + +```C +#include "unity.h" +#include "file_to_test.h" + +void setUp(void) { + // set stuff up here +} + +void tearDown(void) { + // clean stuff up here +} + +void test_function_should_doBlahAndBlah(void) { + //test stuff +} + +void test_function_should_doAlsoDoBlah(void) { + //more test stuff +} + +int main(void) { + UNITY_BEGIN(); + RUN_TEST(test_function_should_doBlahAndBlah); + RUN_TEST(test_function_should_doAlsoDoBlah); + return UNITY_END(); +} +``` + +It's possible that you will need more customization than this, eventually. +For that sort of thing, you're going to want to look at the configuration guide. +This should be enough to get you going, though. + + +## How to Build and Run A Test File + +This is the single biggest challenge to picking up a new unit testing framework, +at least in a language like C or C++. These languages are REALLY good at getting +you "close to the metal" (why is the phrase metal? Wouldn't it be more accurate +to say "close to the silicon"?). While this feature is usually a good thing, it +can make testing more challenging. + +You have two really good options for toolchains. Depending on where you're +coming from, it might surprise you that neither of these options is running the +unit tests on your hardware. +There are many reasons for this, but here's a short version: +- On hardware, you have too many constraints (processing power, memory, etc), +- On hardware, you don't have complete control over all registers, +- On hardware, unit testing is more challenging, +- Unit testing isn't System testing. Keep them separate. + +Instead of running your tests on your actual hardware, most developers choose to +develop them as native applications (using gcc or MSVC for example) or as +applications running on a simulator. Either is a good option. Native apps have +the advantages of being faster and easier to set up. Simulator apps have the +advantage of working with the same compiler as your target application. The +options for configuring these are discussed in the configuration guide. + +To get either to work, you might need to make a few changes to the file +containing your register set (discussed later). + +In either case, a test is built by linking unity, the test file, and the C +file(s) being tested. These files create an executable which can be run as the +test set for that module. Then, this process is repeated for the next test file. +This flexibility of separating tests into individual executables allows us to +much more thoroughly unit test our system and it keeps all the test code out of +our final release! + + +*Find The Latest of This And More at [ThrowTheSwitch.org](https://throwtheswitch.org)* diff --git a/tinyusb/test/vendor/ceedling/docs/UnityHelperScriptsGuide.md b/tinyusb/test/vendor/ceedling/docs/UnityHelperScriptsGuide.md new file mode 100755 index 00000000..12d68d30 --- /dev/null +++ b/tinyusb/test/vendor/ceedling/docs/UnityHelperScriptsGuide.md @@ -0,0 +1,260 @@ +# Unity Helper Scripts + +## With a Little Help From Our Friends + +Sometimes what it takes to be a really efficient C programmer is a little non-C. +The Unity project includes a couple of Ruby scripts for making your life just a tad +easier. They are completely optional. If you choose to use them, you'll need a +copy of Ruby, of course. Just install whatever the latest version is, and it is +likely to work. You can find Ruby at [ruby-lang.org](https://ruby-labg.org/). + + +### `generate_test_runner.rb` + +Are you tired of creating your own `main` function in your test file? Do you +keep forgetting to add a `RUN_TEST` call when you add a new test case to your +suite? Do you want to use CMock or other fancy add-ons but don't want to figure +out how to create your own `RUN_TEST` macro? + +Well then we have the perfect script for you! + +The `generate_test_runner` script processes a given test file and automatically +creates a separate test runner file that includes ?main?to execute the test +cases within the scanned test file. All you do then is add the generated runner +to your list of files to be compiled and linked, and presto you're done! + +This script searches your test file for void function signatures having a +function name beginning with "test" or "spec". It treats each of these +functions as a test case and builds up a test suite of them. For example, the +following includes three test cases: + +```C +void testVerifyThatUnityIsAwesomeAndWillMakeYourLifeEasier(void) +{ + ASSERT_TRUE(1); +} +void test_FunctionName_should_WorkProperlyAndReturn8(void) { + ASSERT_EQUAL_INT(8, FunctionName()); +} +void spec_Function_should_DoWhatItIsSupposedToDo(void) { + ASSERT_NOT_NULL(Function(5)); +} +``` + +You can run this script a couple of ways. The first is from the command line: + +```Shell +ruby generate_test_runner.rb TestFile.c NameOfRunner.c +``` + +Alternatively, if you include only the test file parameter, the script will copy +the name of the test file and automatically append "_Runner" to the name of the +generated file. The example immediately below will create TestFile_Runner.c. + +```Shell +ruby generate_test_runner.rb TestFile.c +``` + +You can also add a [YAML](http://www.yaml.org/) file to configure extra options. +Conveniently, this YAML file is of the same format as that used by Unity and +CMock. So if you are using YAML files already, you can simply pass the very same +file into the generator script. + +```Shell +ruby generate_test_runner.rb TestFile.c my_config.yml +``` + +The contents of the YAML file `my_config.yml` could look something like the +example below. If you're wondering what some of these options do, you're going +to love the next section of this document. + +```YAML +:unity: + :includes: + - stdio.h + - microdefs.h + :cexception: 1 + :suit_setup: "blah = malloc(1024);" + :suite_teardown: "free(blah);" +``` + +If you would like to force your generated test runner to include one or more +header files, you can just include those at the command line too. Just make sure +these are _after_ the YAML file, if you are using one: + +```Shell +ruby generate_test_runner.rb TestFile.c my_config.yml extras.h +``` + +Another option, particularly if you are already using Ruby to orchestrate your +builds - or more likely the Ruby-based build tool Rake - is requiring this +script directly. Anything that you would have specified in a YAML file can be +passed to the script as part of a hash. Let's push the exact same requirement +set as we did above but this time through Ruby code directly: + +```Ruby +require "generate_test_runner.rb" +options = { + :includes => ["stdio.h", "microdefs.h"], + :cexception => 1, + :suite_setup => "blah = malloc(1024);", + :suite_teardown => "free(blah);" +} +UnityTestRunnerGenerator.new.run(testfile, runner_name, options) +``` + +If you have multiple files to generate in a build script (such as a Rakefile), +you might want to instantiate a generator object with your options and call it +to generate each runner afterwards. Like thus: + +```Ruby +gen = UnityTestRunnerGenerator.new(options) +test_files.each do |f| + gen.run(f, File.basename(f,'.c')+"Runner.c" +end +``` + +#### Options accepted by generate_test_runner.rb: + +The following options are available when executing `generate_test_runner`. You +may pass these as a Ruby hash directly or specify them in a YAML file, both of +which are described above. In the `examples` directory, Example 3's Rakefile +demonstrates using a Ruby hash. + + +##### `:includes` + +This option specifies an array of file names to be `#include`'d at the top of +your runner C file. You might use it to reference custom types or anything else +universally needed in your generated runners. + + +##### `:suite_setup` + +Define this option with C code to be executed _before any_ test cases are run. + +Alternatively, if your C compiler supports weak symbols, you can leave this +option unset and instead provide a `void suiteSetUp(void)` function in your test +suite. The linker will look for this symbol and fall back to a Unity-provided +stub if it is not found. + + +##### `:suite_teardown` + +Define this option with C code to be executed _after all_ test cases have +finished. An integer variable `num_failures` is available for diagnostics. +The code should end with a `return` statement; the value returned will become +the exit code of `main`. You can normally just return `num_failures`. + +Alternatively, if your C compiler supports weak symbols, you can leave this +option unset and instead provide a `int suiteTearDown(int num_failures)` +function in your test suite. The linker will look for this symbol and fall +back to a Unity-provided stub if it is not found. + + +##### `:enforce_strict_ordering` + +This option should be defined if you have the strict order feature enabled in +CMock (see CMock documentation). This generates extra variables required for +everything to run smoothly. If you provide the same YAML to the generator as +used in CMock's configuration, you've already configured the generator properly. + +##### `:mock_prefix` and `:mock_suffix` + +Unity automatically generates calls to Init, Verify and Destroy for every file +included in the main test file that starts with the given mock prefix and ends +with the given mock suffix, file extension not included. By default, Unity +assumes a `Mock` prefix and no suffix. + +##### `:plugins` + +This option specifies an array of plugins to be used (of course, the array can +contain only a single plugin). This is your opportunity to enable support for +CException support, which will add a check for unhandled exceptions in each +test, reporting a failure if one is detected. To enable this feature using Ruby: + +```Ruby +:plugins => [ :cexception ] +``` + +Or as a yaml file: + +```YAML +:plugins: + -:cexception +``` + +If you are using CMock, it is very likely that you are already passing an array +of plugins to CMock. You can just use the same array here. This script will just +ignore the plugins that don't require additional support. + + +### `unity_test_summary.rb` + +A Unity test file contains one or more test case functions. Each test case can +pass, fail, or be ignored. Each test file is run individually producing results +for its collection of test cases. A given project will almost certainly be +composed of multiple test files. Therefore, the suite of tests is comprised of +one or more test cases spread across one or more test files. This script +aggregates individual test file results to generate a summary of all executed +test cases. The output includes how many tests were run, how many were ignored, +and how many failed. In addition, the output includes a listing of which +specific tests were ignored and failed. A good example of the breadth and +details of these results can be found in the `examples` directory. Intentionally +ignored and failing tests in this project generate corresponding entries in the +summary report. + +If you're interested in other (prettier?) output formats, check into the +Ceedling build tool project (ceedling.sourceforge.net) that works with Unity and +CMock and supports xunit-style xml as well as other goodies. + +This script assumes the existence of files ending with the extensions +`.testpass` and `.testfail`.The contents of these files includes the test +results summary corresponding to each test file executed with the extension set +according to the presence or absence of failures for that test file. The script +searches a specified path for these files, opens each one it finds, parses the +results, and aggregates and prints a summary. Calling it from the command line +looks like this: + +```Shell +ruby unity_test_summary.rb build/test/ +``` + +You can optionally specify a root path as well. This is really helpful when you +are using relative paths in your tools' setup, but you want to pull the summary +into an IDE like Eclipse for clickable shortcuts. + +```Shell +ruby unity_test_summary.rb build/test/ ~/projects/myproject/ +``` + +Or, if you're more of a Windows sort of person: + +```Shell +ruby unity_test_summary.rb build\teat\ C:\projects\myproject\ +``` + +When configured correctly, you'll see a final summary, like so: + +```Shell +-------------------------- +UNITY IGNORED TEST SUMMARY +-------------------------- +blah.c:22:test_sandwiches_should_HaveBreadOnTwoSides:IGNORE + +------------------------- +UNITY FAILED TEST SUMMARY +------------------------- +blah.c:87:test_sandwiches_should_HaveCondiments:FAIL:Expected 1 was 0 +meh.c:38:test_soda_should_BeCalledPop:FAIL:Expected "pop" was "coke" + +-------------------------- +OVERALL UNITY TEST SUMMARY +-------------------------- +45 TOTAL TESTS 2 TOTAL FAILURES 1 IGNORED +``` + +How convenient is that? + + +*Find The Latest of This And More at [ThrowTheSwitch.org](https://throwtheswitch.org)* |