clang-wrap

A wrapper tool for clang/clang++ that automatically generates and manages LLVM IR files during compilation and linking.

Overview

clang-wrap wraps the clang/clang++ compiler and related tools (ar, cp, mv, ln, install, strip) to automatically:

• Generate LLVM IR (.bc files) during compilation
• Merge LLVM IR files during linking using llvm-link
• Synchronize LLVM IR files when performing file operations (copy, move, link, install)
• Handle static library creation with LLVM IR merging

SPDX License Information

SPDX-FileCopyrightText: (C) 2026 Institute of Software, Chinese Academy of Sciences (ISCAS)
SPDX-FileCopyrightText: (C) 2026 openRuyi Project Contributors
SPDX-FileContributor: YunQiang Su <yunqiang@isrc.iscas.ac.cn>
SPDX-License-Identifier: MulanPSL-2.0

Components

Core Wrappers

• clang-wrap (src/main.rs): Main clang/clang++ wrapper
  • Generates LLVM IR during compilation
  • Invokes llvm-link during linking to merge LLVM IR files

Tool Wrappers

• ar-wrap (src/bin/ar-wrap.rs): ar/llvm-ar wrapper

  • Merges LLVM IR files when creating static libraries

• cp-wrap (src/bin/cp-wrap.rs): cp wrapper

  • Copies corresponding LLVM IR files when copying binaries

• mv-wrap (src/bin/mv-wrap.rs): mv wrapper

  • Moves corresponding LLVM IR files when moving binaries

• ln-wrap (src/bin/ln-wrap.rs): ln wrapper

  • Creates links for corresponding LLVM IR files

• install-wrap (src/bin/install-wrap.rs): install wrapper

  • Installs LLVM IR files to appropriate locations

• strip-wrap (src/bin/strip-wrap.rs): strip wrapper

  • Handles LLVM IR file copying during strip operations

Common Library

• lib.rs (src/lib.rs): Shared functionality including:
  • Debug logging
  • PATH executable finding
  • Environment variable reading
  • LLVM IR path computation
  • Auxiliary file handling (_log, _cmd, _verscript)

Environment Variables

• EMIT_LLVMIR: Enable LLVM IR generation (set to non-empty, non-zero value)
• LLVM_IR_DIR: Output directory for LLVM IR files (default: ~/tmp/llvmir)
• CLANG_WRAP_DEBUG: Enable debug logging (set to non-empty, non-zero value)

Output Files

For each compiled/linked artifact, clang-wrap generates:

• .bc file: LLVM bitcode
• _cmd file: Shell script for re-linking LLVM bitcode
• _log file: Log of llvm-link command
• _verscript file: Version script (if applicable)

Building

cargo build --release

Installation

The compiled binaries should be placed in PATH before the actual tools they wrap, so they intercept calls to clang, ar, cp, etc.

Usage

Once installed, the wrappers work transparently. Set EMIT_LLVMIR=1 to enable LLVM IR generation:

EMIT_LLVMIR=1 make

License

This project is licensed under the MulanPSL-2.0 license.

Copyright

Copyright (C) 2026 Institute of Software, Chinese Academy of Sciences (ISCAS)

Copyright (C) 2026 openRuyi Project Contributors