[PATCH] Document new LLVM CMake interface and emit warning when using llvm_map_components_to_libraries

[Brad King]

On 07/23/2014 11:04 AM, Dan Liew wrote:
>>  llvm_map_components_to_libnames(llvm_libs native option bitreader)
>>  target_link_libraries(simple-tool ${llvm_libs})
> 
> Is it ever the case that a component does not directly map to a single library?

Yes, and they can map to multiple libraries.  Target architecture
names are transformed, for example.  I have one project that does:

 llvm_map_components_to_libnames(llvm_libs native option bitreader
                                 ${LLVM_TARGETS_TO_BUILD})

and the resulting list has many libraries for each target arch.
It is needed to link tools that do

  llvm::InitializeAllTargets();
  llvm::InitializeAllTargetMCs();
  llvm::InitializeAllAsmPrinters();
  llvm::InitializeAllAsmParsers();

> CMAKE_PREFIX_PATH. I've not used it before and based on reading its
> documentation (man cmake-variables) it globally effects what find_XXX
> directives do. This does not seem like a good idea. Imagine if user's
> application uses ``find_package(Boost)`` but also uses
> ``find_package(LLVM REQUIRED CONFIG)``.

CMAKE_PREFIX_PATH can be a list of prefixes:

 "-DCMAKE_PREFIX_PATH=/path/to/Boost;/path/to/LLVM"

It was originally created for users that have a bunch of stuff installed
in a custom installation prefix, but can be used for this too.

I'm fine with not mentioning it here though.

> Although looking at documentation for find_package() the search order
> is quite complicated so I'm probably wrong. It is also not obvious
> where using <package>_DIR is in that order from the documentation.

It says "A cache entry called ``<package>_DIR`` is created to
hold the directory containing the file".  In other words, if
the value is set to a valid location then there is no search
done at all.

> +``LLVM_INCLUDE_DIRS``
> +  The path to the LLVM header files directory.

This should be documented as a list so projects do not use it
expecting it to always be one value.

Thanks,
-Brad