Improving support for CMake-based applications

[Brad King]

Hi Takumi,

Thanks for looking at the series!

On 01/27/2014 11:29 AM, NAKAMURA Takumi wrote:
> I have been playing to tweak to let Clang FindPackage-friendly.
> FYI, my tweaks, working in progress
>   -- https://github.com/chapuni/llvm-project/commits/cmake/sa/trunk

It looks like you're trying to teach tools/clang/CMakeLists.txt to
find_package(LLVM) when built as an outside project.  In fact I have
changes to do that which I used as part of testing this series.  My
approach uses those LLVM_BUILD_* variables to hook up build/source
tree locations automatically when building Clang against the LLVM
build tree.

I plan to submit that as a follow-up series to Clang cfe-commits once
the necessary pieces are in LLVM.  As a preview:

  project(Clang)
  cmake_minimum_required(VERSION 2.8.8)

  # Allow user to optionally override LLVM build tree locations.
  set(LLVM_TOOLS_BINARY_DIR "" CACHE PATH "Path to llvm/bin")
  set(LLVM_LIBRARY_DIR "" CACHE PATH "Path to llvm/lib")
  set(LLVM_MAIN_INCLUDE_DIR "" CACHE PATH "Path to llvm/include")
  set(LLVM_BINARY_DIR "" CACHE PATH "Path to LLVM build tree")
  set(LLVM_MAIN_SRC_DIR "" CACHE PATH "Path to LLVM source tree")

  # Look for LLVM build or install tree.
  find_package(LLVM REQUIRED)
  list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")

  # Load default locations from LLVM build tree when using one.
  foreach(v
      TOOLS_BINARY_DIR
      LIBRARY_DIR
      MAIN_INCLUDE_DIR
      BINARY_DIR
      MAIN_SRC_DIR
      )
    if(LLVM_BUILD_${v} AND NOT LLVM_${v})
      set(LLVM_${v} "${LLVM_BUILD_${v}}")
    endif()
  endforeach()

  # Tell tablegen() macro to use the imported executable by logical name.
  set(LLVM_TABLEGEN_EXE llvm-tblgen)

  ...

> I have a few questions.
> 
>   - Could you introduce me how to write FindPackage-friendly
> cmakefiles for developers?

For the side providing the package, there are tutorials on our Wiki:

 http://www.cmake.org/Wiki/CMake/Tutorials#CMake_Packages

There is also a new "cmake-packages(7)" manual that will be part of
the next CMake release.  It isn't published at a persistent URL
yet but here is link to the version control viewer for the manual
source as of today:

 http://cmake.org/gitweb?p=cmake.git;a=blob;f=Help/manual/cmake-packages.7.rst;hb=d31e68a2

The patch series I've proposed here along with some follow-ups I
will send once this one is merged take care of everything covered
there.

For the side using the package (the application), just

 find_package(LLVM REQUIRED)

should be enough to find LLVM.  To point your local application
build at a specific LLVM, one may set LLVM_DIR to point at the
directory containing the LLVMConfig.cmake file:

 cmake ../myapp -DLLVM_DIR=/path/to/prefix/share/llvm/cmake

or just add the LLVM installation prefix or build tree to the
list of prefixes to search:

 cmake ../myapp -DCMAKE_PREFIX_PATH=/path/to/prefix

>   - Would it be better to add stuff in LLVMConfig.cmake?
>     - list(APPEND CMAKE_MODULE_PATH)
>     - include_directories(${LLVM_INCLUDE_DIRS})
>     - link_directories(${LLVM_LIBRAY_DIRS})

No.  When an application does find_package(LLVM) the resulting
effects should be declarative.  We don't know that the application
actually wants to use the values immediately.  It should be up to
the application to use LLVM_INCLUDE_DIRS, LLVM_LIBRARY_DIRS, and
LLVM_CMAKE_DIR while invoking the above commands itself.

> +set(LLVM_CONFIG_INCLUDE_DIRS
> +  "${LLVM_MAIN_INCLUDE_DIR}"
> +  "${LLVM_INCLUDE_DIR}"
> +  )
> 
> For historical reasons, we prefer to seek build tree at first in INCLUDE_DIRS.
> See also https://github.com/chapuni/llvm-project/commit/8a09aaa4c07fc9fdd1b4a63d7accc8ccf3389032

Yes, I agree.

Thanks,
-Brad