Issues with 'HandleLLVMOptions' and 'LLVM_DEFINITIONS'

[christopherbate]

TLDR:

• Some projects use the sequence find_project(LLVM) ; include(HandleLLVMOptions) to set directory-scoped cMake compilation options based on CMake variables provided by LLVMConfig.cmake. This includes compiler options, linker options, and compiler definitions.
• HandleLLVMOptions will then also set LLVM_DEFINITIONS to the set of definitions in the top-level CMake scope.
• Downstream projects are also invoking add_definitions(${LLVM_DEFINITIONS}) but they are unaware that a) LLVM_DEFINITIONS is a space-separated list and needs to be pre-processed and b) has different effects depending on ordering with HandleLLVMOptions and c) can cause duplication of compiler definitions

[christopherbate]

Clarification on the issue after some investigation:

What is recommended by the docs at https://llvm.org/docs/CMake.html#embedding-llvm-in-your-project is to invoke

  find_package(LLVM CONFIG REQUIRED)

  include_directories(${LLVM_INCLUDE_DIRS})
  separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})
  add_definitions(${LLVM_DEFINITIONS_LIST})

The find_package defines LLVM_DEFINITIONS by way of the installed or configured LLVMConfig.cmake file.

However, what MLIR projects are doing is (as recommended in MLIR Standalone example)

  find_package(MLIR CONFIG REQUIRED) # implicitly also does find_package(LLVM ...)
  
  include(HandleLLVMOptions)

  include_directories(${LLVM_INCLUDE_DIRS})
  separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})
  add_definitions(${LLVM_DEFINITIONS_LIST})

The HandleLLVMOptions call is overriding LLVM_DEFINITIONS with a new value. Behavior is different depending on placement of include(HandleLLVMOptions).

So I think either HandleLLVMOptions was not intended to be used out-of-tree, but many projects are using it. Perhaps guidance should be updated to below:

If building against installed/pre-packaged LLVM

  find_package(LLVM CONFIG REQUIRED)

  include_directories(${LLVM_INCLUDE_DIRS})
  separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})
  add_definitions(${LLVM_DEFINITIONS_LIST})

  # Optional, if wanting to use LLVM-style CMake compilation flags in your project (e.g. LLVM_USE_LINKER, LLVM_USE_SANITIZER, etc)
 # Must come AFTER any uses of `LLVM_DEFINITIONS` since
 # this will override it.
 # This likely will cause  some duplication of compiler definitions.
  include(HandleLLVMOptions)

If embedding LLVM as a sub-project

  add_subdirectory(${LLVM_PROJECT_SRC_DIR}/llvm ${LLVM_BINARY_DIR})

  find_package(LLVM CONFIG REQUIRED 
    HINTS ${LLVM_BINARY_DIR}/lib/cmake/llvm
  )
  
  # These are only needed for targets that depend on LLVM targets.
  include_directories(${LLVM_INCLUDE_DIRS})
  separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})
  add_definitions(${LLVM_DEFINITIONS_LIST})
  
  # Optional, if wanting to use LLVM-style CMake compilation flags in your project (e.g. LLVM_USE_LINKER, LLVM_USE_SANITIZER, etc)
 # Must come AFTER any uses of `LLVM_DEFINITIONS` since
 # this will override it.
 # This likely will cause  some duplication of compiler definitions.
  include(HandleLLVMOptions)