libMy

Short description

Search and replace all occurrences (in files and file names) of

• libMy (complete name of the library)
• libmy (folder name of the library)
• my (C++ namespace matching folder name)

At a minimum:

1. Modify cicd/platformio.ini adding the library dependencies of libMy
2. Synchronize those with libmy/library.json at the dependencies keys
3. Customize and synchronize libmy/examples/sdkconfig.defaults and tests/sdkconfig.defaults.
   Do do use flags to enable/disable ESP features.
4. Synchronize libmy/examples/platformio.ini and tests/platformio.ini.sample to have the correct configuration for running tests and compiling your library. They will be identical to cicd/platformio.ini except some CI-specific options (e.g. pins of the test machine)
5. Rename the namespace libmy/{include, src}/my in terms of folder and file content.
6. Update libmy/library.json with the correct URLs and author information.
7. Appropriately change the symlink to ../../libmy at tests/lib/libmy,
8. Write your tests in tests/src/main.cpp
9. Update .gitlab-ci.yml with the correct PIO_LIB_FOLDER variable
10. Setup the CI/CD settings with the correct PLATFORMIO_ORG variable for publishing
11. Write extra documentation in docs/src/*.md
12. Remove unnecessary keys from .gitlab-ci.yml, if you do not have actual unit tests or examples.

Good luck!

Developer guide

Folder structure

Important folders:

• libmy/
  Library source code, divided in headers, source code, examples.
  • libmy/{include, src, examples}/my/
    All sources are placed in the subfolders my. This reflects the namespace in which all the objects are located, and keeps the includes clean.
  • libmy/examples/sdkconfig.defaults
    This is the default ESP-IDF SDK config file that should be used when building the examples.
    
• tests/
  Subfolder containing the unit test project.
  • tests/lib/libmy/
    Symlink to libmy/, to allow the unit tests to pick up the local library folder
  • tests/test/.keep
    We need to keep this folder for PlatformIO to believe we are providing unit test in our own custom entry point.

Secondary folders:

• cicd/ Helper files needed by CI/CD
• docs/ Doxygen config and additional doxygen sources
• misc/ Helper files needed for setting up development, logos, non-source material.

Setting up development

0. Install PlatformIO CLI.

1. Prepare tests/platformio.ini. You can, for example
   • Customize tests/platformio.ini.sample to your board and setup, or
   • Copy cicd/platformio.ini, the file used by CI/CD
2. Generate a compilation database for your IDE of choice using

   $> ./misc/gen-compiledb.py tests/platformio.ini       

   You have to regenerate this when a new file is added.
3. You are now using the unit test project to "host" the library (so you will see all usages of instantiated templates, for example).
4. Use the provided .clang-format file to format the source, e.g. by

   $> clang-format --style file -i libmy/src/my/my_file.cpp

Running the tests

Note on the test project structure. We set up the unit test project in such a way that we can use both pio run and pio test to run the unit tests. The two commands are similar but different enough that some commands are available for one and not the other (for example, the compilation database is generated for pio run but not pio test). We work around this by providing a test transport (similar to the one provided by pio test), our own app_main() function and building sources and tests together.

0. Make sure you have setup your tests/platformio.ini as above.

1. Change directory and use either pio test or pio run, as follows:

   $> cd tests/
   $> pio run -t upload -t monitor  # or
   $> pio test

Building the documentation

1. Install Doxygen (or run through Docker), and run

   $> doxygen ./doxygen.conf

2. The documentation can be seen at ./docs/_build/html/index.html.