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

[Dan Liew]

On 23 July 2014 16:36, Brad King <brad.king at kitware.com> wrote:
> 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();

Oh I never new that. This clearly is something that should be
documented in LLVM because I can't find anything about "components".

Given that llvm_map_components_to_libnames() seems to be the way of
doing things it seemed pointless to keep the deprecated documentation
that used llvm_map_components_to_libraries() (it's so similar) so I've
dropped that.

Given that now all the client of LLVM sees is a different function
name wouldn't it make more sense for the implementation of
llvm_map_components_to_libraries() to just call
llvm_map_components_to_libnames()? They seem to have the same
signature and doing that would mean that current users of LLVM using
CMake don't have to change their own CMakeLists.txt files.

>> 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.

Done.

New patches are attached.
-- 
Dan Liew
PhD Student - Imperial College London
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-Document-the-new-LLVM-CMake-interface-for-building-a.patch
Type: text/x-patch
Size: 8121 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140723/33e8ff35/attachment.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0002-Emit-a-warning-if-llvm_map_components_to_libraries-n.patch
Type: text/x-patch
Size: 1475 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140723/33e8ff35/attachment-0001.bin>