From c1b94791e6ed9f04ac111da86aa7cd576d185567 Mon Sep 17 00:00:00 2001
From: Scott Rifenbark <srifenbark@gmail.com>
Date: Thu, 17 Oct 2019 12:09:17 -0700
Subject: ref-manual, dev-manual: Added CMake toolchain files.

Fixes [YOCTO #12760]

Updated the cmake.bbclass description to tell what directory
to insall custom CMake toolchain files into.  Also, updated
the two areas in the "Writing a New Recipe" section that
mention CMake.  Placed a couple notes there concerning the
same directory stuff.

(From yocto-docs rev: cacdedf4e1186a96ce00f94e0f42817dfb724ac7)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 .../dev-manual/dev-manual-common-tasks.xml         | 26 +++++++++++++++++++---
 documentation/ref-manual/ref-classes.xml           |  8 +++++++
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index a97c96619d..c64914a304 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -2348,7 +2348,7 @@
                 Most software provides some means of setting build-time
                 configuration options before compilation.
                 Typically, setting these options is accomplished by running a
-                configure script with some options, or by modifying a build
+                configure script with options, or by modifying a build
                 configuration file.
                 <note>
                     As of Yocto Project Release 1.7, some of the core recipes
@@ -2388,6 +2388,7 @@
                         software is built using Autotools.
                         If this is the case, you just need to worry about
                         modifying the configuration.</para>
+
                         <para>When using Autotools, your recipe needs to inherit
                         the
                         <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
@@ -2400,13 +2401,15 @@
                         or
                         <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
                         to pass any needed configure options that are specific
-                        to the recipe.</para></listitem>
+                        to the recipe.
+                        </para></listitem>
                     <listitem><para><emphasis>CMake:</emphasis>
                         If your source files have a
                         <filename>CMakeLists.txt</filename> file, then your
                         software is built using CMake.
                         If this is the case, you just need to worry about
                         modifying the configuration.</para>
+
                         <para>When you use CMake, your recipe needs to inherit
                         the
                         <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
@@ -2416,7 +2419,16 @@
                         You can make some adjustments by setting
                         <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
                         to pass any needed configure options that are specific
-                        to the recipe.</para></listitem>
+                        to the recipe.
+                        <note>
+                            If you need to install one or more custom CMake
+                            toolchain files that are supplied by the
+                            application you are building, install the files to
+                            <filename>${D}${datadir}/cmake/</filename> Modules
+                            during
+                            <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>.
+                        </note>
+                        </para></listitem>
                     <listitem><para><emphasis>Other:</emphasis>
                         If your source files do not have a
                         <filename>configure.ac</filename> or
@@ -2779,6 +2791,14 @@
                         <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
                         for additional information.
                         </para></listitem>
+                    <listitem><para>
+                        If you need to install one or more custom CMake
+                        toolchain files that are supplied by the
+                        application you are building, install the files to
+                        <filename>${D}${datadir}/cmake/</filename> Modules
+                        during
+                        <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>.
+                        </para></listitem>
                 </itemizedlist>
             </note>
         </section>
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index ece47e757b..76ae334b24 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -445,6 +445,14 @@
         variable to specify additional configuration options to be passed
         using the <filename>cmake</filename> command line.
     </para>
+
+    <para>
+        On the occasion that you would be installing custom CMake toolchain
+        files supplied by the application being built, you should install them
+        to the preferred CMake Module directory:
+        <filename>${D}${datadir}/cmake/</filename> Modules during
+        <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>.
+    </para>
 </section>
 
 <section id='ref-classes-cml1'>
-- 
cgit v1.2.3-54-g00ecf