[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