CMake
=====

config.cmake
------------

CMake configuration file(s) defining a cross compiler toolchain and installation
directories. They can also optionally define extra assembly, C, C++ or linker
flag arguments to the cross and/or native compilers. To create a new
configuration file from the template invoke the pyedev config command::

    pyedev config --new NAME

The defined variables in this file are made available to CMakeLists.txt files
(when using the pyedev build command) using the following include::

    include("${PYEDEV_CONFIG}")

build.cmake
-----------

CMake function definitions for use by CMake build targets files. These are made
available to CMakeLists.txt files (when using the pyedev build command) using
the following include::

    include("${PYEDEV_BUILD}")

Includes build tools for cross compiling static library archives and
application binaries, and for natively compiling executable test suites.

The functions available are documented below.

pyedev_build_util_configure_files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Function to configure list of files where <file>.in exists::

    pyedev_build_util_configure_files([file1, ...])

Wrapper to CMake configure_file, iterates over list of files and if file
with .in extension exists it is configured to produce file output.

The arguments are:

``[file1, ...]``
    Input file list without .in extension.

pyedev_build_util_build_number
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Function to get a build number from file::

    pyedev_build_util_build_number(<file> <out_no>)

Uses regex to get build number from file, or return a default value of 1.

The arguments are:

``<file>``
    Build number file path.

``<out_no>``
    Output build number variable.

pyedev_build_util_arch_flags
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Function to get architecture specific compiler and linker flags::

    pyedev_build_util_arch_flags(<arch> <out_compiler_flags> <out_ld_flags>)

Will set the output variable names to architecture specific compiler and
linker flags for use during compilation. Currently supports: ``cortex-m0``,
``cortex-m4``, ``cortex-m7``.

The arguments are:

``<arch>``
    Architecture string.

``<out_compiler_flags>``
    Output compiler flags variable.

``<out_ld_flags>``
    Output linker flags variable.

pyedev_build_target_library_headers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Function to install library headers::

    pyedev_build_target_library_headers(<target> <headers> <install_dir>
                                        <out_target>)

Library headers will be installed the specified installation subdirectory,
which can be used to structure the library includes installation directory.

The arguments are:

``<target>``
    Unique name for library headers target.

``<headers>``
    Headers file list.

``<install_dir>``
    Installation location for target output, this should be a relative path
    inside the library includes install directory defined in configuration file.

``<out_target>``
    Output target variable.

pyedev_build_target_library
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Function to create a static library build target::

    pyedev_build_target_library(<target> <arch> <compiler_flags> <inc> <src>
                                <depends> <build_file> <out_target>)

``<target>``
    Unique name for library target.

``<arch>``
    Architecture string.

``<compiler_flags>``
    General compiler flags.

``<inc>``
    Include directories list.

``<src>``
    Source files list.

``<depends>``
    Target dependencies list.

``<build_file>``
    Build file path (increments build number).

``<out_target>``
    Output target variable.

pyedev_build_target_application
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Function to create a application binary build target::

    pyedev_build_target_application(<target> <arch> <compiler_flags> <ld_script>
                                    <ld_flags> <inc> <src> <libs> <depends>
                                    <install_dir> <build_file> <out_target>)

Application sources will be compiled to produce elf, map and binary output
files for the target architecture. Target files will be copied to the
install directory and output target variable will be set.

Target is built when platform type is ``cross``.

The arguments are:

``<target>``
    Unique name for application target.

``<arch>``
    Architecture string.

``<compiler_flags>``
    General compiler flags.

``<ld_script>``
    Linker script file path.

``<ld_flags>``
    Linker flags.

``<inc>``
    Include directories list.

``<src>``
    Source files list.

``<libs>``
    Linked libraries list.

``<depends>``
    Target dependencies list.

``<install_dir>``
    Installation location for target outputs, this should be a relative path
    inside the application install directory defined in configuration file.

``<build_file>``
    Build file path (increments build number).

``<out_target>``
    Output target variable.

pyedev_build_target_utility
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Function to create a utility executable build target::

    pyedev_build_target_utility(<target> <compiler_flags> <inc> <src> <depends>
                                <install_dir> <out_target>)

Utility sources will be compiled to produce executable binary.

Target is built when platform type is ``native``.

``<target>``
    Unique name for utility target.

``<compiler_flags>``
    General compiler flags.

``<inc>``
    Include directories list.

``<src>``
    Source files list.

``<depends>``
    Target dependencies list.

``<install_dir>``
    Installation location for target output, this should be a relative path
    inside the binary install directory defined in configuration file.

``<out_target>``
    Output target variable.

pyedev_build_target_test
~~~~~~~~~~~~~~~~~~~~~~~~

Function to create a test executable build target::

    pyedev_build_target_test(<target> <compiler_flags> <inc> <src> <depends>
                             <install_dir> <out_target>)

Test sources will be compiled to produce executable binary. Output file will
be copied to the install directory and executed.

Target is built when platform type is ``native``.

``<target>``
    Unique name for test target.

``<compiler_flags>``
    General compiler flags.

``<inc>``
    Include directories list.

``<src>``
    Source files list.

``<depends>``
    Target dependencies list.

``<install_dir>``
    Installation location for target output, this should be a relative path
    inside the tests install directory defined in configuration file.

``<out_target>``
    Output target variable.

pyedev_build_target_doxygen
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Function to create a documentation generation target using Doxygen::

    pyedev_build_target_doxygen(<target> <doxyfile> <output_dir> <install_dir>)

Doxygen will be invoked with the doxyfile configuration file. HTML produced
in the output directory will be copied to the install directory.

Target is built when platform type is ``none``.

The arguments are:

``<target>``
    Unique name for Doxygen target.

``<doxyfile>``
    Input Doxygen configuration file.

``<output_dir>``
    Directory location of Doxygen output, this should be a relative path
    inside the CMake build directory such as "doxygen" and match the
    variable ``OUTPUT_DIRECTORY`` in the doxyfile.

``<install_dir>``
    Installation location for Doxygen html output, this should be a relative
    path inside the documentation install directory defined in configuration
    file.