Maki

An automated macro invocation analysis tool.

If you would like to see the artifact associated with the ICSE 2024 paper, Semantic Analysis of Macro Usage for Portability, please go to this Zenodo link.

Requirements

The following instructions assume an Ubuntu 22.04.4 operating system:

CMake. Follow the instructions on the CMake downloads page.

LLVM and Clang. Run the following commands:

wget -qO- https://apt.llvm.org/llvm-snapshot.gpg.key | sudo tee /etc/apt/trusted.gpg.d/apt.llvm.org.asc
sudo apt install llvm-17 clang-17 libclang-17-dev build-essential cmake

Setting up

Build the Clang plugin, e.g.,

cmake -S . -B build/ -G Ninja
cmake --build build/

Running the Clang Plugin

To easily run the Clang plugin, run its wrapper script like so:

./build/bin/maki filename

where filename is the name of the C file whose macro usage you would like to analyze.

Flags

Maki offers the following flags to modify its behavior:

Flag	Effect	Example invocation
`--builtin-macros`	Maki will analyze macro definitions or invocations of compiler builtin macros (this is the default)	`maki -fplugin-arg-maki---builtin-macros`
`--no-builtin-macros`	Maki will not analyze macro definitions or invocations of compiler builtin macros	`maki -fplugin-arg-maki---no-builtin-macros`
`--system-macros`	Maki will analyze macro definitions or invocations in system headers (this is the default)	`maki -fplugin-arg-maki---system-macros`
`--no-system-macros`	Maki will not analyze macro definitions or invocations in system headers	`maki -fplugin-arg-maki---no-system-macros`
`--invalid-macros`	Maki will analyze macro definitions or invocations at invalid locations, e.g. on the command line (this is the default)	`maki -fplugin-arg-maki---invalid-macros`
`--no-invalid-macros`	Maki will not analyze macro definitions or invocations at invalid locations	`maki -fplugin-arg-maki---no-invalid-macros`

Testing

Maki's test suite is located in the tests/Tests directory and automated with LLVM LIT and FileCheck.

Testing dependencies

The Python lit script from PyPi:
```
python3 -m pip install lit
```
FileCheck as one of LLVM's dev dependencies:
```
sudo apt install llvm-dev
```
jq from your package manager, e.g.,
```
sudo apt install jq
```

Running the test suite

From the project root, run the following command to configure Maki with testing enabled and to run its test suite:

cmake -S . -B build/ \
    -DMAKI_ENABLE_TESTING=ON \
    -DLLVM_EXTERNAL_LIT=<lit_path> \
    -DFILECHECK_PATH=<filecheck_path>
cmake --build build/ -t check-maki --parallel

Where <lit_path> and <filecheck_path> are the paths to your lit Python script and FileCheck binary, respectively.

Using the provided Docker image to test

Build the Docker image with the following command in the project root:

docker build -t maki:1.0 .

Run the Docker image:

docker run -it maki:1.0

Build the plugin:

cmake -S . -B build/ -G Ninja
cmake --build build/

Run the test suite:

cmake -S . -B build/ \
    -DMAKI_ENABLE_TESTING=ON \
    -DLLVM_EXTERNAL_LIT=/usr/local/bin/lit \
    -DFILECHECK_PATH=/lib/llvm-17/bin/FileCheck
cmake --build build/ -t check-maki --parallel

Note: If you are on an AMD64 architecture, please follow these steps:

Add the following line to the beginning of the Dockerfile: #!/bin/bash
Change the now second line of the docker file from: FROM ubuntu:22.04 to: FROM --platform=linux/amd64 ubuntu:22.04
Build the Docker image with the following command: docker build --platform linux/amd64 -t maki:1.0 .
Run the Docker image: docker run --platform linux/amd64 --name maki-container -it maki:1.0

Contributing

Developers must format their code using ClangFormat before committing them for review. Assuming you have already followed the general setup instructions to install LLVM and Clang, you can download ClangFormat with the following command:

sudo apt install clang-format-17

appleseedlab/maki