NOELLE Offers Empowering LLVM Extensions

• Description
• Version
• Status
• Prerequisites
• Building and Installing
• Testing
• Uninstalling
• Repository structure
• NOELLE as an external project
• Projects built upon NOELLE
• Contributing
• License

Description

NOELLE provides abstractions to help build advanced code analyses and transformations for LLVM IR code. It is built upon SVF, SCAF, and LLVM.

We released NOELLE's source code in the hope of enriching the resources available to the research community and compiler developers. You are kindly asked to acknowledge usage of the tool by citing the following paper:

@inproceedings{NOELLE,
    title={{NOELLE} {O}ffers {E}mpowering {LL}VM {E}xtensions},
    author={Angelo Matni and Enrico Armenio Deiana and Yian Su and Lukas Gross and Souradip Ghosh and Sotiris Apostolakis and Ziyang Xu and Zujun Tan and Ishita Chaturvedi and David I. August and Simone Campanoni},
    booktitle={International Symposium on Code Generation and Optimization, 2022. CGO 2022.},
    year={2022}
}

The following material compose the documentation currently available:

• An introductory video
• The CGO 2022 Paper
• The slides used during Advanced Topics in Compilers at Northwestern
• The Github Wiki of the project
• Comments in the source code

Version

The latest stable version is 14.1.0 (tag = v14.1.0).

Version Numbering Scheme

The version number is in the form of [v Major.Minor.Revision ]

• Major: Each major version matches a specific LLVM version (e.g., version 9 matches LLVM 9, version 11 matches LLVM 11)
• Minor: Starts from 0, each minor version represents either one or more API replacements/removals that might impact the users OR a forced update every six months (the minimum minor update frequency)
• Revision: Starts from 0; each revision version may include bug fixes or incremental improvements

Update Frequency

• Major: Matches the LLVM releases on a best-effort basis
• Minor: At least once per six months, at most once per month (1/month ~ 2/year)
• Revision: At least once per month, at most twice per week (2/week ~ 1/month)

Status

This is the status of NOELLE for different LLVM versions.

LLVM	NOELLE's branch	SVF included	SCAF included	Unit tests failed out of 35 tests	Latest version	Maintained
18.1.8	v18	❌	❌	35		✅
14.0.6	master	✅	✅	13	14.1.0	✅
9.0.0	v9	✅	✅	13	9.17.0	❌

Prerequisites

• LLVM 14.0.6
• Z3 4.8.8 or newer

Northwestern users

Those who have access to the Zythos cluster at Northwestern can source LLVM 14.0.6 and Z3 4.13.0 from any node of the cluster with:

source /project/extra/llvm/14.0.6/enable
source /project/extra/z3/4.13.0/enable

Building and Installing

To build and install NOELLE you need to configure it first, unless the default configuration is satisfactory. From the root directory:

make menuconfig     # to customize the installation
make                # set the number of jobs with JOBS=8 (default is 16)

To build with any other generator, e.g. Ninja, use make GENERATOR=Ninja.

Testing

To run all tests, invoke the following commands:

cd tests
make clean    # optional but recommended
make

Uninstalling

To uninstall NOELLE, please run the following commands:

Run make uninstall to uninstall without cleaning the build files.

Run make clean to reset the repository to its initial state. For generality, the install directory is not removed.

Repository structure

• bin contains the scripts through which the user will run all analyses and transformations
• doc contains the documentation
• examples contains examples of how to build LLVM pass that rely on NOELLE
• src contains the C++ source of the framework
• src/core contains all the main abstractions
• src/tools contains a set of tools built on top of the core. All tools are independent from one another
• tests contains unit tests

NOELLE as an external project

NOELLE can be easily integrated your project with ExternalProject and FetchContent.

By using ExternalProject, cmake will download, compile and install the repository at build time. By the time you compile your project, NOELLE will be already installed.

include(ExternalProject)
ExternalProject_Add(
    noelle
    GIT_REPOSITORY  "https://github.com/arcana-lab/noelle.git"
    GIT_TAG         v14.1.0
    BUILD_COMMAND   ${CMAKE_COMMAND} --build . -j16
    INSTALL_COMMAND ${CMAKE_COMMAND} --install .
    CMAKE_ARGS
        -DCMAKE_INSTALL_PREFIX=${CMAKE_CURRENT_BINARY_DIR}/noelle
        -DNOELLE_SVF=OFF
        -DNOELLE_SCAF=OFF
)
include_directories(${CMAKE_CURRENT_BINARY_DIR}/noelle/include)

By using FetchContent, the repository will be made available as soon as cmake is run. your project and noelle will then be compiled as a single project.

include(FetchContent)
FetchContent_Declare(
    noelle
    GIT_REPOSITORY  "https://github.com/arcana-lab/noelle.git"
    GIT_TAG         v14.1.0
)
set(NOELLE_SVF OFF)
set(NOELLE_SCAF OFF)
FetchContent_MakeAvailable(noelle)
FetchContent_GetProperties(noelle)

# at this point noelle is available but NOT installed
include_directories(${noelle_SOURCE_DIR}/src/core/alloc_aa/include) # for example

Projects built upon NOELLE

Several projects have already been built successfully upon NOELLE. These projects are (in no particular order):

• Gino
• MemOIR
• HBC
• CPF
• CARMOT
• Alaska
• TrackFM
• SPLENDID
• WARIO
• CCK
• Compiler-based timing
• PRV Jeeves
• CARAT
• STATS
• Time squeezer

Contributing

We welcome contributions from the community to improve this framework and evolve it to cater for more users.

NOELLE uses clang-format to ensure uniform styling across the project's source code. To format all .cpp and .hpp files in the repository run make format from the root. clang-format is run automatically as a pre-commit git hook, meaning that when you commit a file clang-format is automatically run on the file in-place.

Since git doesn't allow for git hooks to be installed when you clone the repository, cmake will install the pre-commit git hook upon installation.

If you have any trouble using this framework feel free to reach out to us for help (contact simone.campanoni@northwestern.edu).

License

NOELLE is licensed under the MIT License.