diff options
Diffstat (limited to 'tinyusb/test/vendor/ceedling/docs/CeedlingPacket.md')
| -rwxr-xr-x | tinyusb/test/vendor/ceedling/docs/CeedlingPacket.md | 2060 |
1 files changed, 0 insertions, 2060 deletions
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. |