header_utils.py

Convert headers to a binder friendly format.

repo: https://github.com/shakfu/header_utils

Features

Header Transformations

Default

• Convert include statements with quotes to pointy brackets.

#include"parent/abc.h" -> <parent/abc.h>

• Convert relative to absolute include path references.

#include"../abc.h" -> <parent/abc.h>

Optional

• Convert #pragma once entries to header guards.

#pragma once

becomes

#ifndef ABC_H
#defineABC_H
...
#endif// ABC_H

Dependency Analysis

• Generate a graphviz (pdf|png|svg) graph of header dependencies.

This requires:

pip install graphviz

and graphviz to be installed on your system. On macOS for example:

brew install graphviz

Usage

A few usage examples (full commandline api is provided below):

Note:

• As a safety measure: header_utils.py does not do in-place transformations. It will always write its transformations to a copy of the input_dir.

• If dry-run mode is active no changes are made, and an output_dir need not be provide. In this mode, graphviz dependency graphs can be generated from the input_dir.

• If dry-run mode is not active, then an output_dir must be provided.

1. Dry-run mode

./header_utils.py --graph=depends.pdf --dry-run include

Print out default transformations in dry-run mode without making any changes. Also generate a pdf graph of header-file dependencies using graphviz.

2. Default Transformations

./header_utils.py -o include-dst include-src

Apply default transformations to headers copied to include-dst.

3. Default Transformations with custom endings filter

./header_utils.py -o include-dst --header-endings .hpp include-src

In this case, only headers with an .hpp suffix will be modified as opposed to the default: any with ['.h', '.hpp', '.hh'] endings.

4. Default Transformations with header-guards option

./header_utils.py -o include-dst --header-guards include-src

Apply default transformations to headers and also convert #pragma once entries to header guards.

Commandline API

usage: header_utils.py [-h] [--output_dir OUTPUT_DIR]
[--header-endings HEADER_ENDINGS [HEADER_ENDINGS ...]]
[--header-guards] [--dry-run] [--force-overwrite]
[--list] [--graph GRAPH]
input_dir
Convert headers to a binder friendly format. (default: ['.h', '.hpp', '.hh'])
positional arguments:
input_dir input include directory containing source headers
optional arguments:
-h, --help show this help message and exit
--output_dir OUTPUT_DIR, -o OUTPUT_DIR
output directory for modified headers (default: None)
--header-endings HEADER_ENDINGS [HEADER_ENDINGS ...], -e HEADER_ENDINGS [HEADER_ENDINGS ...]
--header-guards convert `#pragma once` to header guards (default: False)
--dry-run, -d run in dry-run mode without actual changes (default: False)
--force-overwrite, -f
force overwrite output_dir if it already exists (default: False)
--list, -l list target headers only (default: False)
--graph GRAPH, -g GRAPH
output path for graphviz graph with format suffix
[png|pdf|svg] (default: None)

Testing

To test header_utils.py, ensure you have pytest installed.

Note: this project uses a snapshot of the actual headers from the taskflow project to test its functionality.

pytest

TODO

• add more tests