.. Generated by qibuild/doc/tools/gen_cmake_doc.py
.. DO NOT EDIT

.. highlight:: cmake

Functions to create targets
============================

This is the main qiBuild module. It encapsulates the creation of programs,
scripts and libraries, handling dependencies and install rules,
in an easy, elegant and standard way.

There could be differents targets:

* *bin* : a program
* *lib* : a library
* *script* : a script

.. seealso::

   * :ref:`using-submodules`



.. _qi_create_bin:

qi_create_bin
-------------

.. cmake:function:: qi_create_bin(name [<remaining args> ...] [NO_INSTALL] [NO_RPATH] [EXCLUDE_FROM_ALL] [STAGE] [WIN32] [MACOSX_BUNDLE] [SUBFOLDER <subfolder>] [SRC <src> ...] [DEPENDS <depends> ...] [SUBMODULE <submodule> ...])

    :arg name: the target name
    :arg remaining args: source files, like the SRC group, argn and SRC will be merged
    :arg NO_INSTALL: Do not create install rules for the target
    :arg NO_RPATH: Do not try to fix rpath By default, qibuild runs chrpath on the targets so everything work even when project is intalled to a non-standard location. Use this to prevent chrpath to be run.
    :arg EXCLUDE_FROM_ALL: Do not include the target in the 'all' target, this target will not be build by default, you will have to compile the target explicitly. Warning: you will NOT be able to create install rules for this target.
    :arg STAGE: Stage the binary.
    :arg WIN32: Build an executable with a WinMain entry point on windows.
    :arg MACOSX_BUNDLE: Refer to the add_executable documentation.
    :arg SUBFOLDER: The destination subfolder. The install rules generated will be sdk/bin/<subfolder>
    :arg SRC: The list of source files
    :arg DEPENDS: The list of source files
    :arg SUBMODULE: The list of source files

    Create an executable.
    The target name should be unique.
    
**Example**

.. literalinclude:: /samples/target/CMakeLists.txt
   :language: cmake




.. _qi_create_script:

qi_create_script
----------------

.. cmake:function:: qi_create_script(name source [NO_INSTALL] [STAGE] [SUBFOLDER <subfolder>])

    :arg name: The name of the target script
    :arg source: The source script, that will be copied in the sdk to bin/<name>
    :arg NO_INSTALL: Do not generate install rule for the script
    :arg STAGE: Stage the binary.
    :arg SUBFOLDER: The subfolder in sdk/bin to install the script into. (sdk/bin/<subfolder>) 

    Create a script. This will generate rules to install it in the sdk.
    



.. _qi_create_lib:

qi_create_lib
-------------

.. cmake:function:: qi_create_lib(name [<remaining args> ...] [NO_INSTALL] [EXCLUDE_FROM_ALL] [INTERNAL] [NO_STAGE] [NO_FPIC] [SUBFOLDER <subfolder>] [SRC <src> ...] [SUBMODULE <submodule> ...] [DEP <dep> ...])

    :arg name: the target name
    :arg remaining args: sources files, like the SRC group, argn and SRC will be merged
    :arg NO_INSTALL: Do not create install rules for the target
    :arg EXCLUDE_FROM_ALL: Do not include the target in the 'all' target, This target will not be built by default, you will have to compile the target explicitly. Warning: you will NOT be able to create install rules for this target.
    :arg INTERNAL: By default, the library won't be installed, the headers of the library won't be installed either, and library cmake config file will not be generated, thus it will be impossible to use the library from another project using a package of the project. You can by-pass this behavior by setting QI_INSTALL_INTERNAL to "ON"
    :arg NO_STAGE: Do not stage the library.
    :arg NO_FPIC: Do not set -fPIC on static libraries (will be set for shared lib by CMake anyway)
    :arg SUBFOLDER: The destination subfolder. The install rules generated will be sdk/lib/<subfolder>
    :arg SRC: The list of source files (private headers and sources)
    :arg SUBMODULE: Submodule to include in the lib
    :arg DEP: List of dependencies

    Create a library
    
    The target name should be unique.
    
    If you need your library to be static, use::
    
      qi_create_lib(mylib STATIC SRC ....)
    
    If you need your library to be shared, use::
    
      qi_create_lib(mylib SHARED SRC ....)
    
    If you want to let the user choose, use::
    
       qi_create_lib(mylib SRC ....)
    
    The library will be:
     * built as a shared library on UNIX
     * built as a static library on windows
    
    But the user can set BUILD_SHARED_LIBS=OFF to compile
    everything in static by default.
    
    Warning ! This is quite not the standard CMake behavior
    
**Example**

.. literalinclude:: /samples/target/CMakeLists.txt
   :language: cmake




.. _qi_create_config_h:

qi_create_config_h
------------------

.. cmake:function:: qi_create_config_h(OUT_PATH source dest)

    :arg OUT_PATH: Path to the generated file
    :arg source: The source file
    :arg dest: The destination

    Create a configuration file
    
    Configures a header named ${dest} using the source file from
    ${source} using ``configure_file``
    In addition:
    
     - Make sure the path where the header is generated is
       added to the include path
    
     - Create the necessary install rules
    
    If you need the header to be generated in a subdirectory
    (recommended), simply use something like::
    
      qi_create_config_h(_out config.h.in foo/config.h)