[RFC] Factor out repetitive cmake patterns for llvm-style projects

[stephenneuendorffer]

Summary

New projects (particularly out of tree) have a tendency to hijack the existing
llvm configuration options and build targets (add_llvm_library,
add_llvm_tool). This can lead to some confusion.

1. When querying a configuration variable, do we care about how LLVM was

configured, or how these options were configured for the out of tree project?

2. LLVM has lots of defaults, which are easy to miss

(e.g. LLVM_BUILD_TOOLS=ON). These options all need to be duplicated in the
CMakeLists.txt for the project.

In addition, with LLVM Incubators coming online, we need better ways for these
incubators to do things the "LLVM way" without alot of futzing. Ideally, this
would happen in a way that eases importing into the LLVM monorepo when
projects mature.

This patch creates some generic infrastructure in llvm/cmake/modules and
refactors MLIR to use this infrastructure. This should expand to include
add_xxx_library, which is by far the most complicated bit of building a
project correctly, since it has to deal with lots of shared library
configuration bits. (MLIR currently hijacks the LLVM infrastructure for
building libMLIR.so, so this needs to get refactored anyway.)

[mehdi_amini]

Something you don't make very explicit in the description of this patch is that beyond a "refactoring" this is also changing the behavior by *duplicating* the options for each subproject.
For example building with -DLLVM_INCLUDE_EXAMPLES won't be enough to include the examples in MLIR, the user must also provide -DMLIR_INCLUDE_EXAMPLES. Same for every other options.

I can see how this provide more flexibility to the user configuring the build, but this flexibility comes also with a more complex surface. For example when building LLVM+MLIR, passing -DLLVM_INSTALL_TOOLCHAIN_ONLY=ON isn't enough and you need also -DMLIR_INSTALL_TOOLCHAIN_ONLY=ON.

[tstellar]

llvm/cmake/modules/LLVMProjectOptions.cmake

52

Are there any of these that we can remove from LLVM, so we don't have to duplicate them for other projects? It seems to be that we could drop all the INCLUDE_* options. I'm guessing they exist, so that things like examples are buildable, but aren't added to the all target? To me it seems better to automatically add everything to all, and users that want to build less then all can just specify the targets that they want to build. Having both BUILD_* and INCLUDE_* options is very confusing.

[stephenneuendorffer]

In D85140#2191271, @mehdi_amini wrote:

Something you don't make very explicit in the description of this patch is that beyond a "refactoring" this is also changing the behavior by *duplicating* the options for each subproject.
For example building with -DLLVM_INCLUDE_EXAMPLES won't be enough to include the examples in MLIR, the user must also provide -DMLIR_INCLUDE_EXAMPLES. Same for every other options.

I can see how this provide more flexibility to the user configuring the build, but this flexibility comes also with a more complex surface. For example when building LLVM+MLIR, passing -DLLVM_INSTALL_TOOLCHAIN_ONLY=ON isn't enough and you need also -DMLIR_INSTALL_TOOLCHAIN_ONLY=ON.

That's true. My thinking was that these should get defaults from LLVM, like MLIR_INCLUDE_DOCS already did.

[stephenneuendorffer]

llvm/cmake/modules/LLVMProjectOptions.cmake

52

I'm all for simplification, but I think it's somewhat orthogonal with what I'm trying to achieve here. I agree with the general sentiment that there are just too many configuration options.

[mehdi_amini]

In D85140#2191323, @stephenneuendorffer wrote:

That's true. My thinking was that these should get defaults from LLVM, like MLIR_INCLUDE_DOCS already did.

Seems like a good idea!

[stephenneuendorffer]

llvm/cmake/modules/LLVMProjectOptions.cmake

52

I think part of the reason why the INCLUDE configurations exists is to speed up the project generation time. However, I don't know how much of a problem this is in practice. I suspect that for most people compilation still takes longer than configuration.

[stellaraccident]

I am supportive of this cleanup (I have found this awkward in out of tree projects particularly). However, I am probably also not the right person for a detailed review compared to the existing CMake boiler-plate.

[stephenneuendorffer]

Anyone have any concerns with this patch landing? I'd be particularly interested if there are opinions about better ways to structure llvm/cmake/modules/LLVMProjectOptions.cmake or llvm/cmake/modules/LLVMProjectTargets.cmake

[phosek]

In D85140#2309107, @stephenneuendorffer wrote:

Anyone have any concerns with this patch landing? I'd be particularly interested if there are opinions about better ways to structure llvm/cmake/modules/LLVMProjectOptions.cmake or llvm/cmake/modules/LLVMProjectTargets.cmake

I'm mostly concerned about this change being too MLIR specific. Not everything in add_llvm_project_options and add_llvm_project_targets makes sense for every LLVM project and I'd preferred if this was broken down into smaller pieces that could be used independently rather than having this all-or-nothing functions.

Also a styling nit, this should have been cmake/Modules, not cmake/modules. The former is used only by LLVM and is a historic relic, all other projects use cmake/Modules which is more common in CMake-based builds.

[stephenneuendorffer]

Thanks Petr. Can you point to some example projects where some of these
targets are harmful? Personally I'm willing to accept that some of the
mechanisms here might not be used by all projects in exchange for
simplification and ease of use.

Steve

[phosek]

In D85140#2310962, @stephenneuendorffer wrote:

Thanks Petr. Can you point to some example projects where some of these
targets are harmful? Personally I'm willing to accept that some of the
mechanisms here might not be used by all projects in exchange for
simplification and ease of use.

Steve

I don't think any of these are harmful, they are just not needed in most projects.

• *_INCLUDE_UTILS, *_BUILD_UTILS and *_INSTALL_UTILS is only relevant in LLVM which is the only project that uses this concept.
• *_BUILD_TOOLS is used by Clang, Flang, LLD and LLVM, *_INCLUDE_TOOLS is used by LLVM only.
• *_INSTALL_TOOLCHAIN_ONLY is defined in LLVM and while other projects use this variable, it's used as a global shared variable and it doesn't make sense to define it for each project. Maybe we should rename LLVM_INSTALL_TOOLCHAIN_ONLY to INSTALL_TOOLCHAIN_ONLY?
• *_INCLUDE_EXAMPLES and *_BUILD_EXAMPLES is only used by Clang, LLVM and MLIR.
• While *_BUILD_TESTS is only used by LLVM, *_INCLUDE_TESTS is used by all projects. In some cases, *_BUILD_TESTS might make sense even for projects that don't use them currently. For example, Clang uses add_unittest so whether those are built is controlled by LLVM_BUILD_TESTS, but perhaps there should be CLANG_BUILD_TESTS?
• *_INCLUDE_INTEGRATION_TESTS is only used by MLIR.
• *_INCLUDE_DOCS is used by all projects.

[pawelo12345678]

Does further work on this one have a potential to fix following issues while building MLIR?:

[ 81%] Building CXX object tools/mlir/lib/Conversion/LinalgToLLVM/CMakeFiles/obj.MLIRLinalgToLLVM.dir/LinalgToLLVM.cpp.o
cd /home/pawelo/llvm-project.git/build-shared-release/tools/mlir/lib/Conversion/LinalgToLLVM && /usr/lib/llvm/10/bin/clang++ -DBUILD_EXAMPLES -DGTEST_HAS_RTTI=0 -DMLIR_CUDA_CONVERSIONS_ENABLED=0 -DMLIR_ROCM_CONVERSIONS_ENABLED=0 -D_DEBUG -D_GNU_SOURCE -D__STDC_CONSTANT_MACROS -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_M
ACROS -I/home/pawelo/llvm-project.git/build-shared-release/tools/mlir/lib/Conversion/LinalgToLLVM -I/home/pawelo/llvm-project.git/mlir/lib/Conversion/LinalgToLLVM -I/home/pawelo/llvm-project.git/build-shared-release/include -I/home/pawelo/llvm-project.git/llvm/include -I/home/pawelo/llvm-project.git/mlir/include -I
/home/pawelo/llvm-project.git/build-shared-release/tools/mlir/include -stdlib=libc++ -fPIC -fvisibility-inlines-hidden -Werror=date-time -Werror=unguarded-availability-new -Wall -Wextra -Wno-unused-parameter -Wwrite-strings -Wcast-qual -Wmissing-field-initializers -pedantic -Wno-long-long -Wimplicit-fallthrough -Wc
overed-switch-default -Wno-noexcept-type -Wnon-virtual-dtor -Wdelete-non-virtual-dtor -Wstring-conversion -ffunction-sections -fdata-sections -Werror=global-constructors -O3   -fno-exceptions -fno-rtti -UNDEBUG -std=c++17 -o CMakeFiles/obj.MLIRLinalgToLLVM.dir/LinalgToLLVM.cpp.o -c /home/pawelo/llvm-project.git/mli
r/lib/Conversion/LinalgToLLVM/LinalgToLLVM.cpp
In file included from /home/pawelo/llvm-project.git/mlir/lib/Conversion/LinalgToLLVM/LinalgToLLVM.cpp:21:
/home/pawelo/llvm-project.git/mlir/include/mlir/Dialect/Linalg/Passes.h:67:10: fatal error: 'mlir/Dialect/Linalg/Passes.h.inc' file not found
#include "mlir/Dialect/Linalg/Passes.h.inc"
         ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1 error generated.

...or:

[ 70%] Building CXX object tools/mlir/lib/Dialect/LLVMIR/CMakeFiles/obj.MLIRLLVMIR.dir/IR/LLVMDialect.cpp.o
cd /home/pawelo/llvm-project.git/build-shared-release/tools/mlir/lib/Dialect/LLVMIR && /usr/lib/llvm/10/bin/clang++ -DBUILD_EXAMPLES -DGTEST_HAS_RTTI=0 -DMLIR_CUDA_CONVERSIONS_ENABLED=0 -DMLIR_ROCM_CONVERSIONS_ENABLED=0 -D_DEBUG -D_GNU_SOURCE -D__STDC_CONSTANT_MACROS -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -I/
home/pawelo/llvm-project.git/build-shared-release/tools/mlir/lib/Dialect/LLVMIR -I/home/pawelo/llvm-project.git/mlir/lib/Dialect/LLVMIR -I/home/pawelo/llvm-project.git/build-shared-release/include -I/home/pawelo/llvm-project.git/llvm/include -I/home/pawelo/llvm-project.git/mlir/include -I/home/pawelo/llvm-project.g
it/build-shared-release/tools/mlir/include -stdlib=libc++ -fPIC -fvisibility-inlines-hidden -Werror=date-time -Werror=unguarded-availability-new -Wall -Wextra -Wno-unused-parameter -Wwrite-strings -Wcast-qual -Wmissing-field-initializers -pedantic -Wno-long-long -Wimplicit-fallthrough -Wcovered-switch-default -Wno-
noexcept-type -Wnon-virtual-dtor -Wdelete-non-virtual-dtor -Wstring-conversion -ffunction-sections -fdata-sections -Werror=global-constructors -O3   -fno-exceptions -fno-rtti -UNDEBUG -std=c++17 -o CMakeFiles/obj.MLIRLLVMIR.dir/IR/LLVMDialect.cpp.o -c /home/pawelo/llvm-project.git/mlir/lib/Dialect/LLVMIR/IR/LLVMDia
lect.cpp
In file included from /home/pawelo/llvm-project.git/mlir/lib/Dialect/LLVMIR/IR/LLVMDialect.cpp:13:
In file included from /home/pawelo/llvm-project.git/mlir/include/mlir/Dialect/LLVMIR/LLVMDialect.h:18:
/home/pawelo/llvm-project.git/mlir/include/mlir/Dialect/OpenMP/OpenMPDialect.h:19:10: fatal error: 'mlir/Dialect/OpenMP/OpenMPOpsDialect.h.inc' file not found
#include "mlir/Dialect/OpenMP/OpenMPOpsDialect.h.inc"
         ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1 error generated.

It occurs on every build since June/July. I guess it's because I'm using plain cmake, not ninja.

[stephenneuendorffer]

In D85140#2318940, @pawelo12345678 wrote:

Does further work on this one have a potential to fix following issues while building MLIR?:
It occurs on every build since June/July. I guess it's because I'm using plain cmake, not ninja.

That's a separate dependence problem. I'll take a look

[smeenai]

In D85140#2310910, @phosek wrote:

Also a styling nit, this should have been cmake/Modules, not cmake/modules. The former is used only by LLVM and is a historic relic, all other projects use cmake/Modules which is more common in CMake-based builds.

FWIW, a bunch of other LLVM subprojects (Clang, LLD, MLIR, Flang, etc.) all appear to use modules. Modules appears to be used primarily by the runtimes (compiler-rt, libcxx, etc.)

llvm/cmake/modules/LLVMProjectOptions.cmake

+# LLVM-style projects generally have the same directory structure.  This file
+# provides some bolierplate cmake support for projects that supports this
+# directory structure.  Note that generally speaking, projects should prefer
+# to use their own rules for these rather than relying on the core llvm build
+# targets.
+
+# Generally name should be lower case.
+function(add_llvm_project_options name)
+  string(TOUPPER "${name}" uppername)
+
+  # Define options to control the inclusion and default build behavior for
+  # components which may not strictly be necessary (tools, examples, and tests).
+  #
+  # This is primarily to support building smaller or faster project files.
+  option(${uppername}_INCLUDE_TOOLS
+    "Generate build targets for the ${uppername} tools."
+    ${LLVM_INCLUDE_TOOLS})
+  option(${uppername}_BUILD_TOOLS
+    "Build the ${uppername} tools. If OFF, just generate build targets."
+    ${LLVM_BUILD_TOOLS})
+
+  option(${uppername}_INCLUDE_UTILS
+    "Generate build targets for the ${uppername} utils."
+    ${LLVM_INCLUDE_UTILS})
+  option(${uppername}_BUILD_UTILS
+    "Build ${uppername} utility binaries. If OFF, just generate build targets."
+    ${LLVM_BUILD_UTILS})
+  option(${uppername}_INSTALL_UTILS
+    "Include utility binaries in the 'install' target."
+    ${LLVM_INSTALL_UTILS})
+
+  # i.e. Don't install headers, for instance.
+  option(${uppername}_INSTALL_TOOLCHAIN_ONLY
+    "Only include toolchain files in the 'install' target."
+    ${LLVM_INSTALL_TOOLCHAIN_ONLY})
+
+  option(${uppername}_BUILD_EXAMPLES
+    "Build the ${uppername} example programs. If OFF, just generate build targets."
+    ${LLVM_BUILD_EXAMPLES})
+  option(${uppername}_INCLUDE_EXAMPLES
+    "Generate build targets for the ${uppername} examples"
+    ${LLVM_INCLUDE_EXAMPLES})
+  if(${uppername}_BUILD_EXAMPLES)
+    add_definitions(-DBUILD_EXAMPLES)
+  endif(${uppername}_BUILD_EXAMPLES)
+
+  option(${uppername}_BUILD_TESTS
+    "Build ${uppername} unit tests. If OFF, just generate build targets."
+    ${LLVM_BUILD_TESTS})
+  option(${uppername}_INCLUDE_TESTS
+    "Generate build targets for the ${uppername} unit tests."
+    ${LLVM_INCLUDE_TESTS})
+  if (${uppername}_INCLUDE_TESTS)
+    add_definitions(-D${uppername}_INCLUDE_TESTS)
+  endif()
+
+  option(${uppername}_INCLUDE_INTEGRATION_TESTS
+    "Generate build targets for the ${uppername} integration tests."
+    ${LLVM_INCLUDE_INTEGRATION_TESTS})
+  if (${uppername}_INCLUDE_INTEGRATION_TESTS)
+    add_definitions(-D${uppername}_INCLUDE_INTEGRATION_TESTS)
+  endif()
+
+  option(${uppername}_INCLUDE_DOCS
+    "Generate build targets for the ${uppername} docs."
+    ${LLVM_INCLUDE_DOCS})
+
+endfunction(add_llvm_project_options)

llvm/cmake/modules/LLVMProjectTargets.cmake

+# For project foo, this function generates:
+# add_foo_tool(name)     (An executable installed by default)
+# add_foo_utility(name)  (An executable *not* installed by default)
+# add_foo_example(name)  (An executable which is built, but never installed)
+# add_foo_example_library(name)  (A library to go along with an example)
+
+# It also assumes the following configuration environment variables
+# (see LLVMProjectOptions.cmake)
+# FOO_TOOLS_INSTALL_DIR
+# FOO_BUILD_TOOLS
+# FOO_BUILD_UTILS
+# FOO_INSTALL_UTILS
+# FOO_BUILD_EXAMPLES
+# FOO_HAS_EXPORTS
+# FOO_INSTALL_TOOLCHAIN_ONLY
+
+function(add_llvm_project_targets projectname)
+  string(TOUPPER "${name}" upperprojectname)
+
+  macro(add_${projectname}_tool name)
+    if( NOT ${upperprojectname}_BUILD_TOOLS )
+      set(EXCLUDE_FROM_ALL ON)
+    endif()
+    add_llvm_executable(${name} ${ARGN})
+
+    if ( ${name} IN_LIST LLVM_TOOLCHAIN_TOOLS OR NOT ${upperprojectname}_INSTALL_TOOLCHAIN_ONLY)
+      if( ${upperprojectname}_BUILD_TOOLS )
+        set(export_to_${projectname}exports)
+        if(${name} IN_LIST LLVM_DISTRIBUTION_COMPONENTS OR
+            NOT LLVM_DISTRIBUTION_COMPONENTS)
+          set(export_to_${projectname}exports EXPORT ${upperprojectname}Exports)
+          set_property(GLOBAL PROPERTY ${upperprojectname}_HAS_EXPORTS True)
+        endif()
+
+        install(TARGETS ${name}
+          ${export_to_${projectname}exports}
+          RUNTIME DESTINATION ${${upperprojectname}_TOOLS_INSTALL_DIR}
+          COMPONENT ${name})
+
+        if (NOT LLVM_ENABLE_IDE)
+          add_llvm_install_targets(install-${name}
+            DEPENDS ${name}
+            COMPONENT ${name})
+        endif()
+      endif()
+    endif()
+    if( ${upperprojectname}_BUILD_TOOLS )
+      set_property(GLOBAL APPEND PROPERTY ${upperprojectname}_EXPORTS ${name})
+    endif()
+    set_target_properties(${name} PROPERTIES FOLDER "Tools")
+  endmacro(add_${projectname}_tool name)
+
+  macro(add_${projectname}_example name)
+    if( NOT ${upperprojectname}_BUILD_EXAMPLES )
+      set(EXCLUDE_FROM_ALL ON)
+    endif()
+    add_llvm_executable(${name} ${ARGN})
+    if( ${upperprojectname}_BUILD_EXAMPLES )
+      install(TARGETS ${name} RUNTIME DESTINATION examples)
+    endif()
+    set_target_properties(${name} PROPERTIES FOLDER "Examples")
+  endmacro(add_${projectname}_example name)
+
+  macro(add_${projectname}_example_library name)
+    if( NOT ${upperprojectname}_BUILD_EXAMPLES )
+      set(EXCLUDE_FROM_ALL ON)
+      add_llvm_library(${name} BUILDTREE_ONLY ${ARGN})
+    else()
+      add_llvm_library(${name} ${ARGN})
+    endif()
+
+    set_target_properties(${name} PROPERTIES FOLDER "Examples")
+  endmacro(add_${projectname}_example_library name)
+
+  # This is a macro that is used to create targets for executables that are needed
+  # for development, but that are not intended to be installed by default.
+  macro(add_${projectname}_utility name)
+    if ( NOT ${upperprojectname}_BUILD_UTILS )
+      set(EXCLUDE_FROM_ALL ON)
+    endif()
+
+    add_llvm_executable(${name} DISABLE_LLVM_LINK_LLVM_DYLIB ${ARGN})
+    set_target_properties(${name} PROPERTIES FOLDER "Utils")
+    if (NOT ${upperprojectname}_INSTALL_TOOLCHAIN_ONLY)
+      if (${upperprojectname}_INSTALL_UTILS AND ${upperprojectname}_BUILD_UTILS)
+        set(export_to_${projectname}exports)
+        if (${name} IN_LIST LLVM_DISTRIBUTION_COMPONENTS OR
+            NOT LLVM_DISTRIBUTION_COMPONENTS)
+          set(export_to_${projectname}exports EXPORT ${upperprojectname}Exports)
+          set_property(GLOBAL PROPERTY ${upperprojectname}_HAS_EXPORTS True)
+        endif()
+
+        install(TARGETS ${name}
+          ${export_to_${projectname}exports}
+          RUNTIME DESTINATION ${LLVM_UTILS_INSTALL_DIR}
+          COMPONENT ${name})
+
+        if (NOT LLVM_ENABLE_IDE)
+          add_llvm_install_targets(install-${name}
+            DEPENDS ${name}
+            COMPONENT ${name})
+        endif()
+        set_property(GLOBAL APPEND PROPERTY ${upperprojectname}_EXPORTS ${name})
+      elseif(${upperprojectname}_BUILD_UTILS)
+        set_property(GLOBAL APPEND PROPERTY ${upperprojectname}_EXPORTS_BUILDTREE_ONLY ${name})
+      endif()
+    endif()
+  endmacro(add_${projectname}_utility name)
+endfunction(add_llvm_project_targets)

mlir/CMakeLists.txt

 add_custom_target(mlir-generic-headers)
 set_target_properties(mlir-generic-headers PROPERTIES FOLDER "Misc")
 # mlir-headers may be dialect-dependent.
 add_custom_target(mlir-headers)
 set_target_properties(mlir-headers PROPERTIES FOLDER "Misc")
 add_dependencies(mlir-headers mlir-generic-headers)
 add_custom_target(mlir-doc)
 
+# Get a bunch of LLVM-style default options.
+include(LLVMProjectOptions)
+add_llvm_project_options(mlir)
+
 # Build the CUDA conversions and run according tests if the NVPTX backend
 # is available
 if ("NVPTX" IN_LIST LLVM_TARGETS_TO_BUILD)
   set(MLIR_CUDA_CONVERSIONS_ENABLED 1)
 else()
   set(MLIR_CUDA_CONVERSIONS_ENABLED 0)
 endif()
 # TODO: we should use a config.h file like LLVM does
 add_definitions(-DMLIR_CUDA_CONVERSIONS_ENABLED=${MLIR_CUDA_CONVERSIONS_ENABLED})
 
 # Build the ROCm conversions and run according tests if the AMDGPU backend
 # is available
 if ("AMDGPU" IN_LIST LLVM_TARGETS_TO_BUILD)
   set(MLIR_ROCM_CONVERSIONS_ENABLED 1)
 else()
   set(MLIR_ROCM_CONVERSIONS_ENABLED 0)
 endif()
 add_definitions(-DMLIR_ROCM_CONVERSIONS_ENABLED=${MLIR_ROCM_CONVERSIONS_ENABLED})
 
 set(MLIR_CUDA_RUNNER_ENABLED 0 CACHE BOOL "Enable building the mlir CUDA runner")
 set(MLIR_ROCM_RUNNER_ENABLED 0 CACHE BOOL "Enable building the mlir ROCm runner")
 set(MLIR_VULKAN_RUNNER_ENABLED 0 CACHE BOOL "Enable building the mlir Vulkan runner")
 
-option(MLIR_INCLUDE_TESTS
-       "Generate build targets for the MLIR unit tests."
-       ${LLVM_INCLUDE_TESTS})
-
-option(MLIR_INCLUDE_INTEGRATION_TESTS
-       "Generate build targets for the MLIR integration tests.")
-
 #-------------------------------------------------------------------------------
 # Python Bindings Configuration
 # Requires:
 #   The pybind11 library can be found (set with -DPYBIND_DIR=...)
 #   The python executable is correct (set with -DPYTHON_EXECUTABLE=...)
 #
 # Version locking
 # ---------------
if(MLIR_BINDINGS_PYTHON_ENABLED)
   message(STATUS "Found ppython libraries: ${PYTHON_LIBRARIES}")
   find_package(pybind11 CONFIG REQUIRED)
   message(STATUS "Found pybind11 v${pybind11_VERSION}: ${pybind11_INCLUDE_DIRS}")
   message(STATUS "Python prefix = '${PYTHON_MODULE_PREFIX}', "
                  "suffix = '${PYTHON_MODULE_SUFFIX}', "
                  "extension = '${PYTHON_MODULE_EXTENSION}")
 endif()
 
+# Get a bunch of default targets
+include(LLVMProjectTargets)
+add_llvm_project_targets(mlir)
+
 include_directories( "include")
 include_directories( ${MLIR_INCLUDE_DIR})
 
 # Adding tools/mlir-tblgen here as calling add_tablegen sets some variables like
 # MLIR_TABLEGEN_EXE in PARENT_SCOPE which gets lost if that folder is included
 # from another directory like tools
+if (MLIR_INCLUDE_TOOLS)
   add_subdirectory(tools/mlir-tblgen)
+endif()
 
 add_subdirectory(include/mlir)
 add_subdirectory(lib)
 # C API needs all dialects for registration, but should be built before tests.
 add_subdirectory(lib/CAPI)
 if (MLIR_INCLUDE_TESTS)
-  add_definitions(-DMLIR_INCLUDE_TESTS)
   add_subdirectory(unittests)
   add_subdirectory(test)
 endif()
 if (MLIR_INCLUDE_INTEGRATION_TESTS)
-  add_definitions(-DMLIR_INCLUDE_INTEGRATION_TESTS)
   add_subdirectory(integration_test)
 endif()
 # Tools needs to come late to ensure that MLIR_ALL_LIBS is populated.
 # Generally things after this point may depend on MLIR_ALL_LIBS or libMLIR.so.
+if (MLIR_INCLUDE_TOOLS)
   add_subdirectory(tools)
+endif()
 
-if( LLVM_INCLUDE_EXAMPLES )
+if (MLIR_INCLUDE_EXAMPLES)
   add_subdirectory(examples)
 endif()
 
-option(MLIR_INCLUDE_DOCS "Generate build targets for the MLIR docs."
-  ${LLVM_INCLUDE_DOCS})
 if (MLIR_INCLUDE_DOCS)
   add_subdirectory(docs)
 endif()
 
-if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
+if (NOT MLIR_INSTALL_TOOLCHAIN_ONLY)
   install(DIRECTORY include/mlir include/mlir-c
     DESTINATION include
     COMPONENT mlir-headers
     FILES_MATCHING
     PATTERN "*.def"
     PATTERN "*.h"
     PATTERN "*.inc"
     PATTERN "*.td"

mlir/cmake/modules/AddMLIR.cmake

function(add_mlir_interface interface)
   set(LLVM_TARGET_DEFINITIONS ${interface}.td)
   mlir_tablegen(${interface}.h.inc -gen-op-interface-decls)
   mlir_tablegen(${interface}.cpp.inc -gen-op-interface-defs)
   add_public_tablegen_target(MLIR${interface}IncGen)
   add_dependencies(mlir-generic-headers MLIR${interface}IncGen)
 endfunction()
 
 
-# Generate Documentation
+# Generate Documentation using the mlir-doc rule
+#   doc_filename: the basename of a .td tablegen file
+#   command: the tablegen command to run, typically "-gen-op-doc",
+#            "-gen-pass-doc", or "-gen-dialect-doc"
+#   output_file: the basename of a .md markdown file to be output
+#   output_directory: the directory to place the output
 function(add_mlir_doc doc_filename command output_file output_directory)
   set(LLVM_TARGET_DEFINITIONS ${doc_filename}.td)
   tablegen(MLIR ${output_file}.md ${command} "-I${MLIR_MAIN_INCLUDE_DIR}" "-I${MLIR_INCLUDE_DIR}")
   set(GEN_DOC_FILE ${MLIR_BINARY_DIR}/docs/${output_directory}${output_file}.md)
   add_custom_command(
           OUTPUT ${GEN_DOC_FILE}
           COMMAND ${CMAKE_COMMAND} -E copy
                   ${CMAKE_CURRENT_BINARY_DIR}/${output_file}.md
                   ${GEN_DOC_FILE}
           DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${output_file}.md)
   add_custom_target(${output_file}DocGen DEPENDS ${GEN_DOC_FILE})
   add_dependencies(mlir-doc ${output_file}DocGen)
 endfunction()
 
 # Declare an mlir library which can be compiled in libMLIR.so
-# In addition to everything that llvm_add_librar accepts, this
+# In addition to everything that llvm_add_library accepts, this
 # also has the following option:
 # EXCLUDE_FROM_LIBMLIR
 #   Don't include this library in libMLIR.so.  This option should be used
 #   for test libraries, executable-specific libraries, or rarely used libraries
 #   with large dependencies.
 function(add_mlir_library name)
   cmake_parse_arguments(ARG
     "SHARED;INSTALL_WITH_TOOLCHAIN;EXCLUDE_FROM_LIBMLIR"

mlir/examples/standalone/CMakeLists.txt

 set(LLVM_LIBRARY_OUTPUT_INTDIR ${CMAKE_BINARY_DIR}/lib)
 set(MLIR_BINARY_DIR ${CMAKE_BINARY_DIR})
 
 list(APPEND CMAKE_MODULE_PATH "${MLIR_CMAKE_DIR}")
 list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
 include(TableGen)
 include(AddLLVM)
 include(AddMLIR)
+
+# Get a bunch of LLVM-style default options.
+include(LLVMProjectOptions)
+add_llvm_project_options(standalone)
+
 include(HandleLLVMOptions)
 
+# Get a bunch of default targets
+include(LLVMProjectTargets)
+add_llvm_project_targets(standalone)
+
 include_directories(${LLVM_INCLUDE_DIRS})
 include_directories(${MLIR_INCLUDE_DIRS})
 include_directories(${PROJECT_SOURCE_DIR}/include)
 include_directories(${PROJECT_BINARY_DIR}/include)
 link_directories(${LLVM_BUILD_LIBRARY_DIR})
 add_definitions(${LLVM_DEFINITIONS})
 
 add_subdirectory(include)
 add_subdirectory(lib)
 add_subdirectory(test)
 add_subdirectory(standalone-opt)
 add_subdirectory(standalone-translate)

mlir/examples/standalone/standalone-opt/CMakeLists.txt

 get_property(dialect_libs GLOBAL PROPERTY MLIR_DIALECT_LIBS)
 get_property(conversion_libs GLOBAL PROPERTY MLIR_CONVERSION_LIBS)
 set(LIBS
         ${dialect_libs}
         ${conversion_libs}
         MLIROptLib
         MLIRStandalone
         )
-add_llvm_executable(standalone-opt standalone-opt.cpp)
+add_standalone_tool(standalone-opt standalone-opt.cpp)
 
 llvm_update_compile_flags(standalone-opt)
 target_link_libraries(standalone-opt PRIVATE ${LIBS})
 
 mlir_check_all_link_libraries(standalone-opt)

mlir/examples/standalone/standalone-translate/CMakeLists.txt

 set(LLVM_LINK_COMPONENTS
   Support
   )
 
 get_property(dialect_libs GLOBAL PROPERTY MLIR_DIALECT_LIBS)
 get_property(translation_libs GLOBAL PROPERTY MLIR_TRANSLATION_LIBS)
 
-add_llvm_executable(standalone-translate
+add_standalone_tool(standalone-translate
   standalone-translate.cpp
   )
 llvm_update_compile_flags(standalone-translate)
 target_link_libraries(standalone-translate
   PRIVATE
   ${dialect_libs}
   ${translation_libs}
   MLIRIR
   MLIRParser
   MLIRPass
   MLIRSPIRV
   MLIRTranslation
   MLIRSupport
   )
 
 mlir_check_link_libraries(standalone-translate)

mlir/examples/toy/CMakeLists.txt

 add_custom_target(Toy)
 set_target_properties(Toy PROPERTIES FOLDER Examples)
 
 macro(add_toy_chapter name)
   add_dependencies(Toy ${name})
-  add_llvm_example(${name} ${ARGN})
+  add_mlir_example(${name} ${ARGN})
 endmacro(add_toy_chapter name)
 
 add_subdirectory(Ch1)
 add_subdirectory(Ch2)
 add_subdirectory(Ch3)
 add_subdirectory(Ch4)
 add_subdirectory(Ch5)
 add_subdirectory(Ch6)
 add_subdirectory(Ch7)

mlir/test/Examples/standalone/test.toy

 # RUN: %cmake %mlir_src_root/examples/standalone -DCMAKE_CXX_COMPILER=%host_cxx -DCMAKE_C_COMPILER=%host_cc -DMLIR_DIR=%llvm_lib_dir/cmake/mlir ; %cmake --build . --target check-standalone | tee %t | FileCheck %s
+# RUN: %cmake --build . --target mlir-doc
 
 # CHECK: Passed: 3
 # UNSUPPORTED: windows, android

mlir/tools/mlir-cpu-runner/CMakeLists.txt

 set(LLVM_LINK_COMPONENTS
   Core
   Support
   nativecodegen
   )
 
-add_llvm_tool(mlir-cpu-runner
+add_mlir_tool(mlir-cpu-runner
   mlir-cpu-runner.cpp
   )
 llvm_update_compile_flags(mlir-cpu-runner)
 get_property(dialect_libs GLOBAL PROPERTY MLIR_DIALECT_LIBS)
 target_link_libraries(mlir-cpu-runner PRIVATE
   ${dialect_libs}
   MLIRAnalysis
   MLIREDSC
   MLIRExecutionEngine
   MLIRIR
   MLIRJitRunner
   MLIRLLVMIR
   MLIRParser
   MLIRTargetLLVMIR
   MLIRSupport
   )

mlir/tools/mlir-cuda-runner/CMakeLists.txt

if(MLIR_CUDA_RUNNER_ENABLED)
   llvm_expand_pseudo_components(TARGET_LIBS AllTargetsCodeGens)
   # Prepend LLVM in front of every target, this is how the library
   # are named with CMake
   SET(targets_to_link)
   FOREACH(t ${TARGET_LIBS})
     LIST(APPEND targets_to_link "LLVM${t}")
   ENDFOREACH(t)
 
-  add_llvm_tool(mlir-cuda-runner
+  add_mlir_tool(mlir-cuda-runner
     mlir-cuda-runner.cpp
 
     DEPENDS
     cuda-runtime-wrappers
     )
   target_include_directories(mlir-cuda-runner
     PRIVATE ${CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES}
   )
   llvm_update_compile_flags(mlir-cuda-runner)
   target_link_libraries(mlir-cuda-runner PRIVATE ${LIBS} ${targets_to_link})
 
 endif()

mlir/tools/mlir-linalg-ods-gen/CMakeLists.txt

 set(LLVM_LINK_COMPONENTS
   Core
   Support
   )
-add_llvm_tool(mlir-linalg-ods-gen
+add_mlir_tool(mlir-linalg-ods-gen
   mlir-linalg-ods-gen.cpp
 )
 llvm_update_compile_flags(mlir-linalg-ods-gen)
 target_link_libraries(mlir-linalg-ods-gen PRIVATE
   MLIRSupport
   MLIRIR
   )

mlir/tools/mlir-opt/CMakeLists.txt

add_mlir_library(MLIRMlirOptMain
   mlir-opt.cpp
 
   EXCLUDE_FROM_LIBMLIR
 
   LINK_LIBS PUBLIC
   ${LIBS}
   )
 
-add_llvm_tool(mlir-opt
+add_mlir_tool(mlir-opt
   mlir-opt.cpp
 
   DEPENDS
   ${LIBS}
   )
 target_link_libraries(mlir-opt PRIVATE ${LIBS})
 llvm_update_compile_flags(mlir-opt)
 
 mlir_check_all_link_libraries(mlir-opt)

mlir/tools/mlir-reduce/CMakeLists.txt

set(LIBS
   MLIRParser
   MLIRPass
   MLIRReduce
   MLIRSupport
   MLIRTransforms
   MLIRTransformUtils
   )
 
-add_llvm_tool(mlir-reduce
+add_mlir_tool(mlir-reduce
   OptReductionPass.cpp
   Passes/OpReducer.cpp
   ReductionNode.cpp
   ReductionTreeUtils.cpp
   mlir-reduce.cpp
 
   ADDITIONAL_HEADER_DIRS
   ${MLIR_MAIN_INCLUDE_DIR}/mlir/Reducer

mlir/tools/mlir-rocm-runner/CMakeLists.txt

if(MLIR_ROCM_RUNNER_ENABLED)
   llvm_expand_pseudo_components(TARGET_LIBS AllTargetsCodeGens AllTargetsAsmParsers)
   # Prepend LLVM in front of every target, this is how the library
   # are named with CMake
   SET(targets_to_link)
   FOREACH(t ${TARGET_LIBS})
     LIST(APPEND targets_to_link "LLVM${t}")
   ENDFOREACH(t)
 
-  add_llvm_tool(mlir-rocm-runner
+  add_mlir_tool(mlir-rocm-runner
     mlir-rocm-runner.cpp
 
     DEPENDS
     rocm-runtime-wrappers
     )
   llvm_update_compile_flags(mlir-rocm-runner)
   target_include_directories(mlir-rocm-runner
     PRIVATE
     "${HIP_PATH}/../include"
     "${HIP_PATH}/include"
   )
   target_link_libraries(mlir-rocm-runner PRIVATE ${LIBS} ${targets_to_link})
 
 endif()

mlir/tools/mlir-translate/CMakeLists.txt

 set(LLVM_LINK_COMPONENTS
   Support
   )
 
 get_property(dialect_libs GLOBAL PROPERTY MLIR_DIALECT_LIBS)
 get_property(translation_libs GLOBAL PROPERTY MLIR_TRANSLATION_LIBS)
 
-add_llvm_tool(mlir-translate
+add_mlir_tool(mlir-translate
   mlir-translate.cpp
   )
 llvm_update_compile_flags(mlir-translate)
 target_link_libraries(mlir-translate
   PRIVATE
   ${dialect_libs}
   ${translation_libs}
   ${test_libs}

mlir/tools/mlir-vulkan-runner/CMakeLists.txt

if (MLIR_VULKAN_RUNNER_ENABLED)
   llvm_expand_pseudo_components(TARGET_LIBS AllTargetsCodeGens)
   # Prepend LLVM in front of every target, this is how the library
   # are named with CMake
   SET(targets_to_link)
   FOREACH(t ${TARGET_LIBS})
     LIST(APPEND targets_to_link "LLVM${t}")
   ENDFOREACH(t)
 
-  add_llvm_tool(mlir-vulkan-runner
+  add_mlir_tool(mlir-vulkan-runner
     mlir-vulkan-runner.cpp
   )
   add_dependencies(mlir-vulkan-runner vulkan-runtime-wrappers)
   llvm_update_compile_flags(mlir-vulkan-runner)
   target_link_libraries(mlir-vulkan-runner PRIVATE ${FULL_LINK_LIBS} ${LIBS})
 
 endif()