espressif_tinyusb/test/unit-test/vendor/ceedling/plugins/dependencies/README.md

ceedling-dependencies

Plugin for supporting release dependencies. It's rare for an embedded project to be built completely free of other libraries and modules. Some of these may be standard internal libraries. Some of these may be 3rd party libraries. In either case, they become part of the project's ecosystem.

This plugin is intended to make that relationship easier. It allows you to specify a source for dependencies. If required, it will automatically grab the appropriate version of that dependency.

Most 3rd party libraries have a method of building already in place. While we'd love to convert the world to a place where everything downloads with a test suite in Ceedling, that's not likely to happen anytime soon. Until then, this plugin will allow the developer to specify what calls Ceedling should make to oversee the build process of those third party utilities. Are they using Make? CMake? A custom series of scripts that only a mad scientist could possibly understand? No matter. Ceedling has you covered. Just specify what should be called, and Ceedling will make it happen whenever it notices that the output artifacts are missing.

Output artifacts? Sure! Things like static and dynamic libraries, or folders containing header files that might want to be included by your release project.

So how does all this magic work?

First, you need to add the :dependencies plugin to your list. Then, we'll add a new section called :dependencies. There, you can list as many dependencies as you desire. Each has a series of fields which help Ceedling to understand your needs. Many of them are optional. If you don't need that feature, just don't include it! In the end, it'll look something like this:

:dependencies:
  :libraries:
    - :name: WolfSSL
      :source_path:   third_party/wolfssl/source
      :build_path:    third_party/wolfssl/build
      :artifact_path: third_party/wolfssl/install
      :fetch:
        :method: :zip
        :source: \\shared_drive\third_party_libs\wolfssl\wolfssl-4.2.0.zip
      :environment:
        - CFLAGS+=-DWOLFSSL_DTLS_ALLOW_FUTURE
      :build:
        - "autoreconf -i"
        - "./configure --enable-tls13 --enable-singlethreaded"
        - make
        - make install
      :artifacts:
        :static_libraries:
          - lib/wolfssl.a
        :dynamic_libraries:
          - lib/wolfssl.so
        :includes:
          - include/**

Let's take a deeper look at each of these features.

The Starting Dash & Name

Yes, that opening dash tells the dependencies plugin that the rest of these fields belong to our first dependency. If we had a second dependency, we'd have another dash, lined up with the first, and followed by all the fields indented again.

By convention, we use the :name field as the first field for each tool. Ceedling honestly doesn't care which order the fields are given... but as humans, it makes it easier for us to see the name of each dependency with starting dash.

The name field is only used to print progress while we're running Ceedling. You may call the name of the field whatever you wish.

Working Folders

The :source_path field allows us to specify where the source code for each of our dependencies is stored. If fetching the dependency from elsewhere, it will be fetched to this location. All commands to build this dependency will be executed from this location (override this by specifying a :build_path). Finally, the output artifacts will be referenced to this location (override this by specifying a :artifact_path)

If unspecified, the :source_path will be dependencies\dep_name where dep_name is the name specified in :name above (with special characters removed). It's best, though, if you specify exactly where you want your dependencies to live.

If the dependency is directly included in your project (you've specified :none as the :method for fetching), then :source_path should be where your Ceedling can find the source for your dependency in you repo.

All artifacts are relative to the :artifact_path (which defaults to be the same as :source_path)

Fetching Dependencies

The :dependencies plugin supports the ability to automatically fetch your dependencies for you... using some common methods of fetching source. This section contains only a couple of fields:

• :method -- This is the method that this dependency is fetched.
  • :none -- This tells Ceedling that the code is already included in the project.
  • :zip -- This tells Ceedling that we want to unpack a zip file to our source path.
  • :git -- This tells Ceedling that we want to clone a git repo to our source path.
  • :svn -- This tells Ceedling that we want to checkout a subversion repo to our source path.
  • :custom -- This tells Ceedling that we want to use a custom command or commands to fetch the code.
• :source -- This is the path or url to fetch code when using the zip or git method.
• :tag/:branch -- This is the specific tag or branch that you wish to retrieve (git only. optional).
• :hash -- This is the specific SHA1 hash you want to fetch (git only. optional, requires a deep clone).
• :revision -- This is the specific revision you want to fetch (svn only. optional).
• :executable -- This is a list of commands to execute when using the :custom method

Environment Variables

Many build systems support customization through environment variables. By specifying an array of environment variables, Ceedling will customize the shell environment before calling the build process.

Environment variables may be specified in three ways. Let's look at one of each:

  :environment:
    - ARCHITECTURE=ARM9
    - CFLAGS+=-DADD_AWESOMENESS
    - CFLAGS-=-DWASTE

In the first example, you see the most straightforward method. The environment variable ARCHITECTURE is set to the value ARM9. That's it. Simple.

The next two options modify an existing symbol. In the first one, we use +=, which tells Ceedling to add the define ADD_AWESOMENESS to the environment variable CFLAGS. The second tells Ceedling to remove the define WASTE from the same environment variable.

There are a couple of things to note here.

First, when adding to a variable, Ceedling has no way of knowing what delimiter you are expecting. In this example you can see we manually added some whitespace. If we had been modifying PATH instead, we might have had to use a : on a unux or ; on Windows.

Second, removing an argument will have no effect on the argument if that argument isn't found precisely. It's case sensitive and the entire string must match. If symbol doesn't already exist, it WILL after executing this command... however it will be assigned to nothing.

Building Dependencies

The heart of the :dependencies plugin is the ability for you, the developer, to specify the build process for each of your dependencies. You will need to have any required tools installed before using this feature.

The steps are specified as an array of strings. Ceedling will execute those steps in the order specified, moving from step to step unless an error is encountered. By the end of the process, the artifacts should have been created by your process... otherwise an error will be produced.

Artifacts

These are the outputs of the build process. There are there types of artifacts. Any dependency may have none or some of these. Calling out these files tells Ceedling that they are important. Your dependency's build process may produce many other files... but these are the files that Ceedling understands it needs to act on.

static_libraries

Specifying one or more static libraries will tell Ceedling where it should find static libraries output by your build process. These libraries are automatically added to the list of dependencies and will be linked with the rest of your code to produce the final release.

If any of these libraries don't exist, Ceedling will trigger your build process in order for it to produce them.

dynamic_libraries

Specifying one or more dynamic libraries will tell Ceedling where it should find dynamic libraries output by your build process. These libraries are automatically copied to the same folder as your final release binary.

If any of these libraries don't exist, Ceedling will trigger your build process in order for it to produce them.

includes

Often when libraries are built, the same process will output a collection of includes so that your release code knows how to interact with that library. It's the public API for that library. By specifying the directories that will contain these includes (don't specify the files themselves, Ceedling only needs the directories), Ceedling is able to automatically add these to its internal include list. This allows these files to be used while building your release code, as well we making them mockable during unit testing.

source

It's possible that your external dependency will just produce additional C files as its output. In this case, Ceedling is able to automatically add these to its internal source list. This allows these files to be used while building your release code.

Tasks

Once configured correctly, the :dependencies plugin should integrate seamlessly into your workflow and you shouldn't have to think about it. In the real world, that doesn't always happen. Here are a number of tasks that are added or modified by this plugin.

ceedling dependencies:clean

This can be issued in order to completely remove the dependency from its source path. On the next build, it will be refetched and rebuilt from scratch. This can also apply to a particular dependency. For example, by specifying dependencies:clean:DepName.

ceedling dependencies:fetch

This can be issued in order to fetch each dependency from its origin. This will have no effect on dependencies that don't have fetch instructions specified. This can also apply to a particular dependency. For example, by specifying dependencies:fetch:DepName.

ceedling dependencies:make

This will force the dependencies to all build. This should happen automatically when a release has been triggered... but if you're just getting your dependency configured at this moment, you may want to just use this feature instead. A single dependency can also be built by specifying its name, like dependencies:make:MyTunaBoat.

ceedling dependencies:deploy

This will force any dynamic libraries produced by your dependencies to be copied to your release build directory... just in case you clobbered them.

paths:include

Maybe you want to verify that all the include paths are correct. If you query Ceedling with this request, it will list all the header file paths that it's found, including those produced by dependencies.

files:include

Maybe you want to take that query further and actually get a list of ALL the header files Ceedling has found, including those belonging to your dependencies.

Testing

Hopefully all your dependencies are fully tested... but we can't always depend on that. In the event that they are tested with Ceedling, you'll probably want to consider using the :subprojects plugin instead of this one. The purpose of this plugin is to pull in third party code for release... and to provide a mockable interface for Ceedling to use during its tests of other modules.

If that's what you're after... you've found the right plugin!

Happy Testing!