From 4cecfe6e9d9e9216d9235feec25460c4011bf65f 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: a65cd2c4c062d4ae388191b9d6708b4fadffaa3f)

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(-)

(limited to 'documentation')

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 0dddb8b3bb..00741ee456 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -2349,7 +2349,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
@@ -2389,6 +2389,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>
@@ -2401,13 +2402,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>
@@ -2417,7 +2420,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
@@ -2780,6 +2792,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 5403f20b6f..f9bbddd724 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -428,6 +428,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