ceedling 0.30.0 → 0.31.0

data/vendor/c_exception/vendor/unity/docs/UnityConfigurationGuide.md

@@ -1,398 +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 in order 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 make use of 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
-
-
-##### `UNITY_EXCLUDE_SIZEOF`
-
-The third and final attempt to guess your types is to use the `sizeof()`
-operator. Even if the first two options don't work, this one covers most cases.
-There _is_ a rare compiler or two out there that doesn't support sizeof() in the
-preprocessing stage, though. For these, you have the ability to disable this
-feature as well.
-
-_Example:_
-        #define UNITY_EXCLUDE_SIZEOF
-
-If you've disabled all 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_INCLUDE_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_INCLUDE_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_FLOAT_VERBOSE`
-
-##### `UNITY_DOUBLE_VERBOSE`
-
-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.
-To keep Unity universal, though, we chose to _not_ develop our own floating
-point print routines. Instead, the display of floating point values during a
-failure are optional. By default, Unity will not print the actual results of
-floating point assertion failure. So a failed assertion will produce 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 (e.g. `"Expected 4.56 Was 4.68"`). Note that this feature requires the
-use of `sprintf` so might not be desirable in all cases.
-
-_Example:_
-        #define UNITY_DOUBLE_VERBOSE
-
-
-##### `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 operate 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:
-
-        #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. If you
-specify a custom flush function instead with `UNITY_OUTPUT_FLUSH` directly, it
-will declare an instance of your function by default. If you want to disable
-this behavior, add `UNITY_OMIT_OUTPUT_FLUSH_HEADER_DECLARATION`.
-
-
-##### `UNITY_SUPPORT_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_SUPPORT_WEAK` 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). The most common options for this feature are:
-
-_Example:_
-        #define UNITY_SUPPORT_WEAK weak
-        #define UNITY_SUPPORT_WEAK __attribute__((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
-
-
-## 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)*

data/vendor/c_exception/vendor/unity/docs/UnityGettingStartedGuide.md

@@ -1,191 +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.  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 require 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)*