mohitmishra786/low-level-dev-skills

include-what-you-use

Include What You Use (IWYU) skill for optimizing C/C++ header includes.

Vedi sorgente

Come usare

  1. Copia il comando e controlla il pacchetto prima di installarlo nel tuo ambiente agente.
  2. Controlla strumenti, credenziali e ambienti richiesti nel documento originale.
  3. Descrivi input e risultato desiderato; confronta l’output con le fonti.
npx skills add https://github.com/mohitmishra786/low-level-dev-skills --skill include-what-you-use

Prima di iniziare

  • L’installazione non include abbonamenti, quote API o accesso ai file.
  • Stelle e installazioni indicano attività, non un test indipendente di qualità o sicurezza.
Documento Skill originale

Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.

Include What You Use (IWYU)

Purpose

Guide agents through using IWYU to reduce unnecessary #include directives, interpret IWYU reports and mapping files, decide between forward declarations and full includes, and integrate IWYU into CMake builds to reduce compilation cascades in large codebases.

Triggers

  • "How do I use include-what-you-use?"
  • "How do I reduce my C++ compilation times by fixing includes?"
  • "How do I interpret IWYU output?"
  • "Should I use a forward declaration or include?"
  • "How do I integrate IWYU with CMake?"
  • "What is a compilation cascade and how do I avoid it?"

Workflow

1. Install and run IWYU

bash
# Install
apt-get install iwyu              # Ubuntu/Debian
brew install include-what-you-use # macOS

# Run on a single file
iwyu -Xiwyu --error main.cpp 2>&1

# Run via compile_commands.json
iwyu_tool.py -p build/ src/main.cpp 2>&1 | tee iwyu.log

# Run on entire project
iwyu_tool.py -p build/ 2>&1 | tee iwyu.log

2. CMake integration

cmake
# CMakeLists.txt — use IWYU as include checker during build
find_program(IWYU_PROGRAM NAMES include-what-you-use iwyu)
if(IWYU_PROGRAM)
    set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE
        ${IWYU_PROGRAM}
        -Xiwyu --mapping_file=${CMAKE_SOURCE_DIR}/iwyu.imp
        -Xiwyu --no_comments
    )
endif()
bash
# Build with IWYU analysis
cmake -S . -B build -DCMAKE_CXX_COMPILER=clang++
cmake --build build 2>&1 | tee iwyu.log

3. Interpreting IWYU output

text
main.cpp should add these lines:
#include <string>   // for std::string
#include "mylib/widget.h"  // for Widget

main.cpp should remove these lines:
- #include <vector>  // lines 5-5
- #include "internal/detail.h"  // lines 8-8

The full include-list for main.cpp:
#include <iostream>  // for std::cout
#include <string>    // for std::string
#include "mylib/widget.h"  // for Widget
---

Reading the output:

  • should add: headers providing symbols used but not yet included
  • should remove: headers included but whose symbols aren't used directly
  • The full include-list: what the final header list should look like

4. Apply IWYU fixes automatically

bash
# fix_include script (comes with IWYU)
fix_include < iwyu.log

# Options
fix_include --nosafe_headers < iwyu.log    # more aggressive — also removes system headers
fix_include --comments < iwyu.log          # preserve // comments in includes
fix_include --dry_run < iwyu.log           # preview changes without applying

# Limit to specific files
fix_include --only_re='src/.*\.cpp' < iwyu.log

# Run and apply in one pipeline
iwyu_tool.py -p build/ 2>&1 | fix_include

5. Forward declarations vs full includes

IWYU prefers forward declarations (class/struct declarations without definition) when the full type isn't needed:

cpp
// full_include.h — DON'T include this if only a pointer is used
#include "widget.h"      // full definition: Widget members, vtable, etc.

// forward_decl.h — OK when Widget* or Widget& is sufficient
class Widget;            // forward declaration
void process(Widget *w); // pointer: forward decl is enough

// When forward declaration is sufficient:
// - Pointer or reference parameter: Widget*, Widget&
// - Return type as pointer: Widget*
// - Base class declared elsewhere (but defined in .cpp)

// When full include is required:
// - Inheriting from Widget: class MyWidget : public Widget
// - Accessing Widget members: w.field, w.method()
// - Creating Widget instances: Widget w;
// - Sizeof(Widget)
// - Template instantiation: std::vector<Widget>
cpp
// IWYU-friendly header
#pragma once
class Widget;            // forward declare (saves downstream compilation)

class Container {
    Widget *head_;       // pointer: forward decl is enough
public:
    void add(Widget *w);
    Widget *get(int idx);
};
// Container.cpp includes "widget.h" — only .cpp pays the compile cost

6. Mapping files for third-party headers

IWYU mapping files teach IWYU about indirect includes (where #include <vector> is provided by some internal STL header):

python
# iwyu.imp — IWYU mapping file
[
  # Map internal LLVM headers to public ones
  { "include": ["<llvm/ADT/StringRef.h>", "private",
                 "<llvm/ADT/StringRef.h>", "public"] },

  # Map system headers to POSIX equivalents
  { "include": ["<bits/types.h>", "private", "<sys/types.h>", "public"] },
  { "include": ["<bits/socket.h>", "private", "<sys/socket.h>", "public"] },

  # Symbol → header mappings
  { "symbol": ["std::string", "private", "<string>", "public"] },
  { "symbol": ["NULL",        "private", "<cstddef>", "public"] },
]
bash
# Use mapping file
iwyu -Xiwyu --mapping_file=iwyu.imp main.cpp

# IWYU ships with common mappings
ls /usr/share/include-what-you-use/
# gcc.stl.headers.imp, boost-1.62.imp, libcxx.imp, etc.

iwyu -Xiwyu --mapping_file=/usr/share/include-what-you-use/gcc.stl.headers.imp

7. What IWYU does not do

IWYU has limits — be aware:

bash
# IWYU may give wrong advice for:
# - Macros from headers (hard to track)
# - Template specializations in included headers
# - Headers required for correct ODR linking

# Safe iterative workflow:
# 1. Run IWYU
# 2. Apply fixes with fix_include
# 3. Rebuild and run tests
# 4. Revert any changes that break the build
# 5. Repeat until clean

# Check for compilation cascade: how many TUs include a header
grep -rl '#include "expensive.h"' src/ | wc -l

Related skills

  • Use skills/build-systems/build-acceleration for ccache and other compile speed techniques
  • Use skills/build-systems/cmake for CMake integration of build analysis tools
  • Use skills/compilers/cpp-modules for C++20 modules as a long-term solution to include bloat

Correlati per attività

dallo stesso repository

Altri Skills

Tutti gli Skills
mohitmishra786
Community

low-power-embedded

Low-power embedded skill for sleep modes and energy optimization. Use when configuring MCU sleep/stop/standby, peripheral clock gating, wake-up sources, or measuring firmware current draw. Activates on queries about WFI, STOP mode, STM32 PWR, nRF sleep, wake-up EXTI, or reducing embedded power consumption.

Installazioni / 1h
1
GitHub Stars
296
Aggiornato
20 nov
mohitmishra786
Community

core-dumps

Core dump analysis skill for production crash triage. Use when loading core files in GDB or LLDB, enabling core dump generation on Linux/macOS, mapping symbols with debuginfo or debuginfod, or extracting backtraces from crashes without re-running the program. Activates on queries about core files, ulimit, coredumpctl, debuginfod, crash triage, or analyzing segfaults from production binaries.

Installazioni / 1h
2
GitHub Stars
267
Aggiornato
27 giu
mohitmishra786
Community

custom-allocators

Custom allocator skill for memory allocation strategies. Use when implementing pool/slab/arena allocators, tuning jemalloc/mimalloc, writing Rust GlobalAlloc, or benchmarking allocator performance. Activates on queries about jemalloc, mimalloc, tcmalloc, arena allocator, GlobalAlloc, or fragmentation.

Installazioni / 1h
2
GitHub Stars
267
Aggiornato
27 giu
mohitmishra786
Community

ebpf

eBPF skill for Linux observability and networking. Use when writing eBPF programs with libbpf or bpftrace, attaching kprobes/tracepoints/XDP hooks, debugging verifier errors, working with eBPF maps, or achieving CO-RE portability across kernel versions. Activates on queries about eBPF, bpftool, bpftrace, XDP programs, libbpf, verifier errors, eBPF maps, or kernel tracing with BPF.

Installazioni / 1h
2
GitHub Stars
267
Aggiornato
27 giu