diff --git a/documentation/best_practices/cmake.rst b/documentation/best_practices/cmake.rst new file mode 100644 index 0000000..00eb834 --- /dev/null +++ b/documentation/best_practices/cmake.rst @@ -0,0 +1,94 @@ +*************************** +CMake with Bitbake recipes +*************************** + +Example of using CMake with Bitbake recipes. + +Please find the example here: +`CMake Yocto Example `_. + + +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 ``/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 +`. + + + +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 +`. + + + +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 + diff --git a/documentation/best_practices/index.rst b/documentation/best_practices/index.rst new file mode 100644 index 0000000..91375cc --- /dev/null +++ b/documentation/best_practices/index.rst @@ -0,0 +1,13 @@ + +============================== +Belden CoreOS Best Practices +============================== + +| + +.. toctree:: + :caption: Table of Contents + :numbered: + + overview + cmake diff --git a/documentation/best_practices/overview.rst b/documentation/best_practices/overview.rst new file mode 100644 index 0000000..312944c --- /dev/null +++ b/documentation/best_practices/overview.rst @@ -0,0 +1,6 @@ +************************ +Best Practices Overview +************************ + +To ease the support and developement of CoreOS on multiple plateform, +some examples were made to show developers good practices when working with yocto. diff --git a/documentation/index.rst b/documentation/index.rst index b437414..1be8c50 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -32,6 +32,7 @@ same structures. Reference Manual Boot Concepts + Best Practices .. toctree:: :maxdepth: 1 diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index 769f48d..966b8fc 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst @@ -13,7 +13,7 @@ provided by OpenEmbedded-Core are documented in the ``coreos-efi-secureboot.bbclass`` ================================= -The ``coreos-efi-secureboot`` class is a class made to be ihnerited in a global +The ``coreos-efi-secureboot`` class is a class made to be inherited in a global configuration file. On the CoreOS distribution, this class is inherited inside the CoreOS distrubtion configuration file.