[cmake-developers] [PATCH] Better find module developer documentation

Alex Merry alex.merry at kde.org
Mon Mar 31 10:27:54 EDT 2014


On 27/03/14 14:33, Brad King wrote:
> On 03/26/2014 03:02 PM, Alex Merry wrote:
>> I wrote some documentation on how to write a find module for KDE's
>> extra-cmake-modules project, and Stephen suggested upstreaming it.  So
>> attached is a patch that does that.
> 
> Thanks for working on this.  I like the tutorial-style presentation.
> 
> First, a few reST style comments:
> 
> * Paragraphs ending in ": ::" can be simplified to "::".
> 
> * CMake code blocks should use ".. code-block:: cmake" rather
>   than a plain literal block if the code in the block is valid
>   CMake code (as against containing placeholders as in command
>   signature documentation).
> 
> * Indented blocks where the amount of indentation can be chosen
>   should use 2 spaces instead of 1.
> 
>> Note that this changes the recommendations from the Foo_LIBRARIES,
>> Foo_INCLUDES and Foo_DEFINITIONS variables to creating imported targets
>> (which are much easier and less error-prone to use).
> 
> Providing imported targets is nice, and preferred by KDE, but is
> not a requirement for upstream modules.  Most existing modules
> have not been updated to provide them.  Using imported targets
> throughout a project requires additional effort when creating
> package configuration files to ensure dependencies that name
> imported targets have them available.
> 
> The docs should explain both approaches.  Then explain why
> imported targets are preferred but that since the approach
> is newer not all existing modules have been updated.
> 
> We need to maintain the list of example variable names.  The
> difference between Foo_LIBRARY and Foo_LIBRARIES needs to be
> clearly explained, and not just in the sample module section.

Attached patch contains the suggested changes.  I still went with
recommending Foo_VERSION over Foo_VERSION_STRING, because there is
really no purpose served by having two different names for the version
variable, one for packages and one for find modules.  I kept in a note
about Foo_VERSION_STRING, though.

Alex



-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-Rewrite-the-find-module-developer-documentation.patch
Type: text/x-patch
Size: 24986 bytes
Desc: not available
URL: <http://public.kitware.com/pipermail/cmake-developers/attachments/20140331/fa0a098f/attachment-0002.bin>


More information about the cmake-developers mailing list