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 | 144467 -> 0 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, 0 insertions, 4825 deletions
diff --git a/tinyusb/test/vendor/ceedling/docs/CException.md b/tinyusb/test/vendor/ceedling/docs/CException.md deleted file mode 100755 index c3718191..00000000 --- a/tinyusb/test/vendor/ceedling/docs/CException.md +++ /dev/null @@ -1,292 +0,0 @@ - -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 deleted file mode 100755 index 87f9c00b..00000000 --- a/tinyusb/test/vendor/ceedling/docs/CMock_Summary.md +++ /dev/null @@ -1,603 +0,0 @@ -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 deleted file mode 100755 index 88cd0202..00000000 --- a/tinyusb/test/vendor/ceedling/docs/CeedlingPacket.md +++ /dev/null @@ -1,2060 +0,0 @@ -[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 deleted file mode 100755 index bf4c099b..00000000 --- a/tinyusb/test/vendor/ceedling/docs/ThrowTheSwitchCodingStandard.md +++ /dev/null @@ -1,206 +0,0 @@ -# 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 differdeleted file mode 100755 index 28f0c321..00000000 --- a/tinyusb/test/vendor/ceedling/docs/UnityAssertionsCheatSheetSuitableforPrintingandPossiblyFraming.pdf +++ /dev/null diff --git a/tinyusb/test/vendor/ceedling/docs/UnityAssertionsReference.md b/tinyusb/test/vendor/ceedling/docs/UnityAssertionsReference.md deleted file mode 100755 index eb855f3c..00000000 --- a/tinyusb/test/vendor/ceedling/docs/UnityAssertionsReference.md +++ /dev/null @@ -1,779 +0,0 @@ -# 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 deleted file mode 100755 index dace20c5..00000000 --- a/tinyusb/test/vendor/ceedling/docs/UnityConfigurationGuide.md +++ /dev/null @@ -1,433 +0,0 @@ -# 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 deleted file mode 100755 index 5e4427ce..00000000 --- a/tinyusb/test/vendor/ceedling/docs/UnityGettingStartedGuide.md +++ /dev/null @@ -1,192 +0,0 @@ -# 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 deleted file mode 100755 index 12d68d30..00000000 --- a/tinyusb/test/vendor/ceedling/docs/UnityHelperScriptsGuide.md +++ /dev/null @@ -1,260 +0,0 @@ -# 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)* |