***************************
CMake with Bitbake recipes
***************************

Example of using CMake with Bitbake recipes. 

Please find the example here:
`CMake Yocto Example <https://bitbucket.gad.local/projects/ICO/repos/coreos/browse/layers/meta-belden-coreos-demo/recipes-demo/cmake-demo/cmake-demo_0.1.bb>`_.

.. warning::
   This simple example has the code in the same repo as the recipe. However, it is recommended to have the code in a separate git repo.
   To use remote git repo, it's necessary to have settings as follows:
   
   * SRC_URI = "git://github.com/<link to your repo>"
   * S="${WORKDIR}/git


BitBake recipe
===============

Bitbake recipe inherits the cmake class and then ``CMakeLists.txt`` file can be used for building and installing.
``CMakeLists.txt`` is expected at top of the sources tree pointed by ``SRC_URI``. 
Usually this file is fetched using git or by downloading a tarball (.tar.gz).
If this file is created locally it should be placed somewhere in path (usually ``<Package Name>/files``). Files that are going to be used in 
package need to be included using ``SRC_URI +=``, files need to be included with paths relative to files directory.
Installation of generated files can also be done using native CMake install command (which is recommended), 
but in case something specific is needed, developer can override CMake installation with a BitBake ``do_install`` function.

.. warning::
   When using CMake for installation of some files, and using Bitbake recipe 
   for installing other files. Bitbake's ``do_install`` will override the CMake 
   installation, therefore, one should use ``do_install:append``.



``CMakeLists.txt`` file
========================
When building binaries and libraries in the same package, it's a good idea to keep ``CMakeLists.txt`` 
files split up over all source directories with top ``CMakeLists.txt`` to keep common info:

* ``cmake_minimum_required`` - Defines minimum version of CMake required for desired build. Please check what version is supported by installed Yocto.
* ``project`` - Defines project name and version.
* ``add_subdirectory`` - If the package uses multiple ``CMakeLists.txt`` files, their directories should be included using this command.

optional: ``set(CMAKE_VERBOSE_MAKEFILE ON)`` - can be used for debugging



Helloworld - Simple binary example
===================================

This method shows a simple "Hello world" program written in C, 
that uses CMake for building and installing the binary in Yocto.

Additional information about this topic can be found in official 
documentation: :external:ref:`Yocto Project - CMake
<ref-classes-cmake>`. 



CMake file - explanation
-------------------------
``CMakeLists.txt`` inherits top ``CMakeLists.txt``, so only minimal information is defined in this file:

* ``add_executable`` - Creating binary file
* ``install`` - Installing binary file




Hello service - Simple binary is started in systemd
====================================================

A simple service that starts binary on boot is created. Service 
file is installed using Bitbake method, as using CMake can be 
avoided in this case (no need to build).




Libdemo - Simple library example
=================================

Demo library with one function is built and installed using CMake.
An include file is also installed.

Further information about building different types of libraries can 
be found on official CMake page: :external:ref:`Yocto Project Library documentation 
<dev-manual/common-tasks:working with libraries>`.



CMake file - explanation
-------------------------

``CMakeLists.txt`` inherits top ``CMakeLists.txt``, but this ``CMakeLists.txt`` is somewhat different compared to Helloworld:

* ``add_library`` - declare the library target.
* ``set_target_properties`` - define different properties that are useful for creating library (e.g. defining include files)
* ``set_target_properties`` - installing files to desired locations

