CMinx Dependencies

This page describes the packages that CMinx depends on, the supported versions, and also why we depend on these packages.

CMake

The dependency on CMake has been thrust upon us by the problem scope. Namely, in order to extract documentation from CMake scripts, and to integrate well with existing CMake workflows, CMinx needs to know about CMake.

The minimum version of CMake required by CMinx is 3.14 on account of needing the FetchContent_MakeAvailable command.

Python

CMinx is a tool meant to be run on existing CMake infrastructure in order to generate human-readable documentation. Conceptually this is a parsing exercise. Python is an ideal language for writing CMinx on account of its developer-friendly nature, and the large number of already-existing open-source packages. In particular, Python packages already exist for a number of parsing and documentation related scenarios. Using these packages will increase the robustness of CMinx, while also cutting down on development time.

Arguably, the main drawback of Python programs are that they tend to be slower than their compiled language analogs. However, we do not envision CMinx being used in performance critical situations. Moreover, we anticipate that I/O will dominate CMinx’s operation. Point being, we anticipate Python to be fast enough for our purposes.

As of 2020, Python 2 is no longer supported, and we have opted to write CMinx in Python 3 for future compatibility purposes. CMinx uses a main signature (in cminx/__init__.py) which is incompatible with Python versions less than 3.9.

Antlr4

Antlr is arguably the de facto tool for generating language parsers. CMinx is ultimately a CMake parser (with the ability to recognize some CMake extensions). We use Antlr to generate the core of CMinx.

The files generated by Antlr live in cminx/parser. These files were generated by Antlr version 4.7.2 and are version-locked to 4.7.2. In turn, CMinx requires Antlr version 4.7.2 exactly. In the future this restriction could be lifted by having the parser be generated as part of the build process.

Confuse

Confuse is a Python library for managing YAML configuration files. CMinx uses it to load default configuration values from cminx/config_default.yml and search system configuration paths such as /etc/cminx/ and ~/.config/cminx/ for config.yaml files. See Search Paths for more details.

Confuse also supports checking the configuration files for malformed or incorrect entries using templating. Templating is accomplished in the cminx.config module.

As of writing, cminx uses the latest version of Confuse, version 1.7.0. Later versions with the same major version should continue to work.

PathSpec

PathSpec is a Python library for matching file paths against .gitignore-style filters. CMinx uses PathSpec to determine whether files in the input path (or in subdirectories thereof) are supposed to be excluded. CMinx’s usage of PathSpec is confined to cminx/__init__.py, in cminx.document().

As of writing, CMinx uses the latest version of PathSpec, version 0.9.0.

CMinx Testing Dependencies

To facilitate testing of CMinx we use a couple of additional packages beyond those needed to simply build CMinx; they are described in this section.

coverage

Coverage.py is used to measure the code coverage of our Python test suite.

docutils

docutils is used to help test the generated restructured text files.

After some manual testing it appears that any version of docutils newer than 0.10 will work. Older versions of docutils do not appear to be compatible with Python 3. The version of docutils used by CMinx is really only relevant for CI, and if developers want to locally test CMinx. As such our CI coverage does not exhaustively consider multiple versions of docutils.

pytest

Used to run the Python test suite.

pytest-cov

A plugin for pytest which aids in generating coverage reports for the Python test suite.

CMinx Documentation Dependencies

Building CMinx’s documentation requires additional packages beyond those needed to build CMinx itself; they are described in this section.

sphinx

Sphinx is a widely used tool for generating static websites.

Under normal circumstances we expect the version of sphinx used by CMinx to only be relevant to CI and have opted to let pip install what ever version it wants. Should the automatically installed version ever end up not being compatible with our documentation, then we will pin the version.

sphinx_rtd_theme

The Read-the-Docs Sphinx theme is one of the most full-featured Sphinx themes around. Of the themes perused, no other theme generated documentation for CMinx which looked as nice. It is probably possible to extend other themes to achieve similar effects, but for simplicity we opted to use the already available Read-the-Docs theme.

Like the sphinx dependency, under normal circumstances we expect the version of the sphinx_rtd_theme used by CMinx to only be relevant to CI and have opted to provide no guidance to pip.