llvm-pycodegen
==============

Copyright (C) 2024 Dmitry Matveev

License: GNU Lesser General Public License v3.0 (LGPLv3)

This project is distributed under the LGPLv3 license. The full license text
can be found in the LICENSE file in the project root.

You are free to use, modify, and distribute this code in accordance with
the terms of LGPLv3. More details: https://www.gnu.org/licenses/lgpl-3.0.html

================================================================================

How to build this

This project supports two build modes:
  1. In-tree build (project inside llvm/tools/)
  2. Out-of-tree build via LLVM_EXTERNAL_PROJECTS (project in separate folder)

Both modes build the module statically from LLVM sources.

--------------------------------------------------------------------------------
Option 1: In-tree build
--------------------------------------------------------------------------------

Place the project in llvm/tools/llvm-pycodegen and run from the llvm-project root:

  cmake -S llvm -B build -G Ninja -C llvm/tools/llvm-pycodegen/release.cmake
  cmake --build ./build --target llvm_pycodegen

--------------------------------------------------------------------------------
Option 2: Out-of-tree build (LLVM_EXTERNAL_PROJECTS)
--------------------------------------------------------------------------------

Directory structure:
  /path/to/
    llvm-project/          # LLVM source tree (or just llvm/ folder)
      llvm/
    llvm-pycodegen/        # This project (separate folder)

Build commands:

  cmake -S /path/to/llvm-project/llvm -B build -G Ninja \
    -C /path/to/llvm-pycodegen/release.cmake \
    -DLLVM_EXTERNAL_PROJECTS=llvm-pycodegen \
    -DLLVM_EXTERNAL_LLVM_PYCODEGEN_SOURCE_DIR=/path/to/llvm-pycodegen

  cmake --build ./build --target llvm_pycodegen

Example with relative paths (when llvm-project and llvm-pycodegen are siblings):

  # From parent directory containing both projects
  cmake -S llvm-project/llvm -B build -G Ninja \
    -C llvm-pycodegen/release.cmake \
    -DLLVM_EXTERNAL_PROJECTS=llvm-pycodegen \
    -DLLVM_EXTERNAL_LLVM_PYCODEGEN_SOURCE_DIR=$(pwd)/llvm-pycodegen

  cmake --build ./build --target llvm_pycodegen

--------------------------------------------------------------------------------
Stub file generation (IDE support)
--------------------------------------------------------------------------------

The build system can generate Python stub files (.pyi) that provide:
  - Autocompletion in VS Code, PyCharm, and other IDEs
  - Static type checking via mypy, pyright, pytype
  - Function signature hints and documentation

Build targets:
  llvm_pycodegen              - Build module only
  llvm_pycodegen_stub         - Generate stubs only (requires module to be built)
  llvm_pycodegen_with_stubs   - Build module AND generate stubs together

Recommended build command (module + stubs):
  cmake --build ./build --target llvm_pycodegen_with_stubs

After building, the following files are generated:
  - llvm_pycodegen.cpython-*.so  (compiled module)
  - llvm_pycodegen.pyi           (type annotations)
  - py.typed                     (PEP 561 marker file)

These files are placed in the same directory as the compiled module.

To disable stub generation:
  cmake ... -DLLVM_PYCODEGEN_GENERATE_STUBS=OFF

Alternative: generate stubs via command line:
  python -m nanobind.stubgen -m llvm_pycodegen

--------------------------------------------------------------------------------
Notes
--------------------------------------------------------------------------------

LLVM must be configured with the following options (already set in release.cmake):
  -DLLVM_ENABLE_RTTI=ON       # Required for nanobind
  -DLLVM_ENABLE_EH=ON         # Required for nanobind
  -DLLVM_TARGETS_TO_BUILD=RISCV