| |
| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1"> |
| <meta name="description" content=""> |
| <meta name="author" content=""> |
| |
| <title>CMake Commands / Apache Celix</title> |
| |
| |
| <link rel="icon" href="/assets/img/favicon.ico"> |
| |
| |
| <link href="/assets/css/bootstrap.min.css" rel="stylesheet"> |
| |
| |
| <link href="/assets/css/style.css" rel="stylesheet"> |
| |
| <style> |
| |
| |
| .card-body img { |
| max-width: 100%; |
| width: 100%; |
| height: auto; |
| } |
| |
| |
| .card-body img + em { |
| text-decoration: underline; |
| } |
| </style> |
| |
| |
| <script> |
| var _paq = window._paq = window._paq || []; |
| |
| _paq.push(['disableCookies']); |
| |
| _paq.push(['trackPageView']); |
| _paq.push(['enableLinkTracking']); |
| (function() { |
| var u="https://analytics.apache.org/"; |
| _paq.push(['setTrackerUrl', u+'matomo.php']); |
| _paq.push(['setSiteId', '9']); |
| var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; |
| g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s); |
| })(); |
| </script> |
| |
| |
| </head> |
| <body class="light-grey"> |
| |
| <a href="https://github.com/apache/celix" class="github-ribbon"> |
| <img src="/assets/img/forkme_right_red_aa0000.png" alt="Fork me on GitHub"> |
| </a> |
| |
| |
| <nav class="navbar navbar-expand-lg navbar-dark bg-primary fixed-top"> |
| <div class="container"> |
| <a class="navbar-brand" href="/"> |
| <img src="/assets/img/celix-white.svg" height="40" class="d-inline-block align-top" alt="Celix Logo"> |
| </a> |
| <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarResponsive" aria-controls="navbarResponsive" aria-expanded="false" aria-label="Toggle navigation"> |
| <span class="navbar-toggler-icon"></span> |
| </button> |
| <div class="collapse navbar-collapse" id="navbarResponsive"> |
| <ul class="navbar-nav ml-auto"> |
| <li class="nav-item"> |
| <a class="nav-link" href="/">Home</a> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="/download.cgi">Download</a> |
| </li> |
| <li class="nav-item dropdown active"> |
| <a class="nav-link dropdown-toggle" href="#" id="ddDocs" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> |
| Docs |
| </a> |
| <div class="dropdown-menu" aria-labelledby="ddDocs"> |
| <a class="dropdown-item" href="/docs/2.4.0/docs.html">2.4.0 (latest)</a> |
| <a class="dropdown-item" href="/docs/2.3.0/docs.html">2.3.0</a> |
| <a class="dropdown-item" href="/docs/2.2.1/docs.html">2.2.1</a> |
| <a class="dropdown-item" href="/docs/2.1.0/docs.html">2.1.0</a> |
| </div> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" id="ddContributing" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> |
| Contributing |
| </a> |
| <div class="dropdown-menu" aria-labelledby="ddContributing"> |
| <a class="dropdown-item" href="/contributing/youatcelix.html">You at Celix</a> |
| <a class="dropdown-item" href="/contributing/submitting-patches.html">Submitting patches</a> |
| <a class="dropdown-item" href="/contributing/source-and-builds.html">Source code and builds</a> |
| <hr> |
| <a class="dropdown-item" href="/contributing/releasing.html">Releasing</a> |
| <a class="dropdown-item" href="/contributing/volunteers.html">Volunteers</a> |
| <a class="dropdown-item" href="https://whimsy.apache.org/board/minutes/Celix.html">Board Reports</a> |
| </div> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" id="ddSupport" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> |
| Support |
| </a> |
| <div class="dropdown-menu" aria-labelledby="ddSupport"> |
| <a class="dropdown-item" href="/support/mailing-list.html">Mailing Lists</a> |
| <a class="dropdown-item" href="/support/issue-tracking.html">Issue Tracking</a> |
| </div> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" id="ddFoundation" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> |
| ASF |
| </a> |
| <div class="dropdown-menu" aria-labelledby="ddFoundation"> |
| <a class="dropdown-item" href="https://www.apache.org/">ASF Home</a> |
| <a class="dropdown-item" href="https://www.apache.org/foundation/how-it-works.html">How it works</a> |
| <a class="dropdown-item" href="https://www.apache.org/licenses/">License</a> |
| <a class="dropdown-item" href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| <a class="dropdown-item" href="https://www.apache.org/foundation/thanks.html">Thanks</a> |
| <a class="dropdown-item" href="https://www.apache.org/security/">Security</a> |
| <a class="dropdown-item" href="https://www.apache.org/foundation/policies/conduct">Code of Conduct</a> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </nav> |
| |
| |
| <div class="section"> |
| <div class="container"> |
| <div class="row py-4"> |
| <div class="col-sm-12 card"> |
| <div class="card-body pt-5"> |
| |
| |
| |
| |
| <a class="edit-on-gh" href="https://github.com/apache/celix/edit/master/documents/cmake_commands/README.md" title="Edit this page on GitHub">Edit on GitHub</a> |
| |
| |
| |
| |
| |
| <a href="/docs/2.4.0/docs.html" title="back to documentation"><< back to documentation</a> |
| |
| |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <h1 id="apache-celix---cmake-commands">Apache Celix - CMake Commands</h1> |
| <p>For Apache Celix several cmake command are added to be able to work with Apache Celix bundles and deployments.</p> |
| <h1 id="bundles">Bundles</h1> |
| <p>A bundle is a dynamically loadable collection of shared libraries, configuration files and optional an activation entry |
| that can be dynamically installed and started in a Celix framework.</p> |
| <h2 id="add_celix_bundle">add_celix_bundle</h2> |
| <p>Add a Celix bundle to the project.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">add_celix_bundle</span>(<span style="color:#b44"><bundle_target_name></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">SOURCES</span> <span style="color:#b44">source1</span> <span style="color:#b44">source2</span> <span style="color:#b44">...</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[NAME</span> <span style="color:#b44">bundle_name]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[SYMBOLIC_NAME</span> <span style="color:#b44">bundle_symbolic_name]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[DESCRIPTION</span> <span style="color:#b44">bundle_description]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[GROUP</span> <span style="color:#b44">bundle_group]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[VERSION</span> <span style="color:#b44">bundle_version]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[FILENAME</span> <span style="color:#b44">bundle_filename]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[PRIVATE_LIBRARIES</span> <span style="color:#b44">private_lib1</span> <span style="color:#b44">private_lib2</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[HEADERS</span> <span style="color:#b44">"header1: header1_value"</span> <span style="color:#b44">"header2: header2_value"</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[DO_NOT_CONFIGURE_SYMBOL_VISIBILITY]</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">add_celix_bundle</span>(<span style="color:#b44"><bundle_target_name></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">ACTIVATOR</span> <span style="color:#b44"><activator_lib></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[NAME</span> <span style="color:#b44">bundle_name]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[SYMBOLIC_NAME</span> <span style="color:#b44">bundle_symbolic_name]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[DESCRIPTION</span> <span style="color:#b44">bundle_description]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[GROUP</span> <span style="color:#b44">bundle_group]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[VERSION</span> <span style="color:#b44">bundle_version]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[FILENAME</span> <span style="color:#b44">bundle_filename]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[PRIVATE_LIBRARIES</span> <span style="color:#b44">private_lib1</span> <span style="color:#b44">private_lib2</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[HEADERS</span> <span style="color:#b44">"header1: header1_value"</span> <span style="color:#b44">"header2: header2_value"</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[DO_NOT_CONFIGURE_SYMBOL_VISIBILITY]</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">add_celix_bundle</span>(<span style="color:#b44"><bundle_target_name></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">NO_ACTIVATOR</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[NAME</span> <span style="color:#b44">bundle_name]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[SYMBOLIC_NAME</span> <span style="color:#b44">bundle_symbolic_name]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[DESCRIPTION</span> <span style="color:#b44">bundle_description]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[GROUP</span> <span style="color:#b44">bundle_group]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[VERSION</span> <span style="color:#b44">bundle_version]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[FILENAME</span> <span style="color:#b44">bundle_filename]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[PRIVATE_LIBRARIES</span> <span style="color:#b44">private_lib1</span> <span style="color:#b44">private_lib2</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[HEADERS</span> <span style="color:#b44">"header1: header1_value"</span> <span style="color:#b44">"header2: header2_value"</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[DO_NOT_CONFIGURE_SYMBOL_VISIBILITY]</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><p>Example:</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">add_celix_bundle</span>(<span style="color:#b44">my_bundle</span> <span style="color:#b44">SOURCES</span> <span style="color:#b44">src/my_activator.c</span>)<span style=""> |
| </span></span></span></code></pre></div><p>There are three variants:</p> |
| <ul> |
| <li>With SOURCES the bundle will be created using a list of sources files as input for the bundle activator library.</li> |
| <li>With ACTIVATOR the bundle will be created using the library target or absolute path to existing library as activator library.</li> |
| <li>With the NO_ACTIVATOR option will create a bundle without a activator (i.e. a pure resource bundle).</li> |
| </ul> |
| <p>Optional arguments are:</p> |
| <ul> |
| <li>NAME: The (human readable) name of the bundle. This will be used as Bundle-Name manifest entry. Default is the <bundle_target_name>.</li> |
| <li>SYMBOLIC_NAME: The symbolic name of the bundle. This will be used as Bundle-SymbolicName manifest entry. Default is the <bundle_target_name>.</li> |
| <li>DESCRIPTION: The description of the bundle. This will be used as Bundle-Description manifest entry. Default this is empty.</li> |
| <li>GROUP: The group the bundle is part of. This will be used as Bundle-Group manifest entry. Default this is empty (no group).</li> |
| <li>VERSION: The bundle version. This will be used for the Bundle-Version manifest entry. In combination with SOURCES the version will also be used to set the activator library target property VERSION and SOVERSION. |
| For SOVERSION only the major part is used. Expected scheme is “<major>.<minor>.<path>”. Default version is “0.0.0”</li> |
| <li>FILENAME: The filename of the bundle file, without extension. Default is <bundle_target_name>. Together with the BUILD_TYPE, this will result in a filename like “bundle_target_name_Debug.zip</li> |
| <li>PRIVATE_LIBRARIES: private libraries to be included in the bundle. Specified libraries are added to the “Private-Library” manifest statement and added in the root of the bundle. libraries can be cmake library targets or absolute paths to existing libraries.</li> |
| <li>HEADERS: Additional headers values that are appended to the bundle manifest.</li> |
| <li>DO_NOT_CONFIGURE_SYMBOL_VISIBILITY: By default the bundle library will be build with symbol visibility configuration preset set to hidden. This can be disabled by providing this option.</li> |
| </ul> |
| <h2 id="celix_bundle_private_libs">celix_bundle_private_libs</h2> |
| <p>Add libraries to a bundle.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_bundle_private_libs</span>(<span style="color:#b44"><bundle_target></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">lib1</span> <span style="color:#b44">lib2</span> <span style="color:#b44">...</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><p>Example:</p> |
| <pre tabindex="0"><code>celix_bundle_private_libs(my_bundle my_lib1 my_lib2) |
| </code></pre><p>A library should be a cmake library target or an absolute path to existing library. |
| The libraries will be copied into the bundle zip and activator library will be linked (PRIVATE) against them.</p> |
| <p>Apache Celix uses dlopen with RTLD_LOCAL to load the activator library in a bundle. |
| It is important to note that dlopen will always load the activator library, |
| but not always load the libraries the bundle activator library is linked against. |
| If the activator library is linked against a library which is already loaded, the already loaded library will be used. |
| More specifically dlopen will decide this based on the NEEDED header in the activator library |
| and the SO_NAME headers of the already loaded libraries.</p> |
| <p>For example installing in order:</p> |
| <ul> |
| <li>Bundle A with a private library libfoo (SONAME=libfoo.so) and</li> |
| <li>Bundle B with a private library libfoo (SONAME=libfoo.so). |
| Will result in Bundle B also using libfoo loaded from the cache dir in Bundle A.</li> |
| </ul> |
| <p>This also applies if multiple Celix frameworks are created in the same process. For example installed in order:</p> |
| <ul> |
| <li>Bundle A with a private library libfoo (SONAME=libfoo.so) in Celix Framework A and</li> |
| <li>The same Bundle A in Celix Framework B. |
| Will result in Bundle A from Framework B to use the libfoo loaded from the cache dir of Bundle A in framework A.</li> |
| </ul> |
| <h2 id="celix_bundle_files">celix_bundle_files</h2> |
| <p>Add files to the target bundle.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_bundle_files</span>(<span style="color:#b44"><bundle_target></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">files...</span> <span style="color:#b44">DESTINATION</span> <span style="color:#b44"><dir></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[FILE_PERMISSIONS</span> <span style="color:#b44">permissions...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[DIRECTORY_PERMISSIONS</span> <span style="color:#b44">permissions...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[NO_SOURCE_PERMISSIONS]</span> <span style="color:#b44">[USE_SOURCE_PERMISSIONS]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[FILES_MATCHING]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[PATTERN</span> <span style="color:#b44"><pattern></span> <span style="color:#b44">|</span> <span style="color:#b44">REGEX</span> <span style="color:#b44"><regex>]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[EXCLUDE]</span> <span style="color:#b44">[PERMISSIONS</span> <span style="color:#b44">permissions...]</span> <span style="color:#b44">[...]</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><p>Example:</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_bundle_files</span>(<span style="color:#b44">my_bundle</span> <span style="color:#666">${</span><span style="color:#b8860b">CMAKE_CURRENT_LIST_DIR</span><span style="color:#666">}</span><span style="color:#b44">/resources/my_file.txt</span> <span style="color:#b44">DESTINATION</span> <span style="color:#b44">META-INF/subdir</span>)<span style=""> |
| </span></span></span></code></pre></div><p>DESTINATION is relative to the bundle archive root. |
| The rest of the command is based on the file(COPY …) cmake command. |
| See cmake file(COPY …) command for more info.</p> |
| <p>Note with celix_bundle_files, files are copied cmake generation time. Updates are not copied !!</p> |
| <h2 id="celix_bundle_add_dir">celix_bundle_add_dir</h2> |
| <p>Copy to the content of a directory to a bundle.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_bundle_add_dir</span>(<span style="color:#b44"><bundle_target></span> <span style="color:#b44"><input_dir></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[DESTINATION</span> <span style="color:#b44"><relative_path_in_bundle>]</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><p>Example:</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_bundle_add_dir</span>(<span style="color:#b44">my_bundle</span> <span style="color:#b44">bundle_resources/</span> <span style="color:#b44">DESTINATION</span> <span style="color:#b44">"resources"</span>)<span style=""> |
| </span></span></span></code></pre></div><p>Optional arguments:</p> |
| <ul> |
| <li>DESTINATION: Destination of the files, relative to the bundle archive root. Default is “.”.</li> |
| </ul> |
| <p>Note celix_bundle_add_dir copies the dir and can track changes.</p> |
| <h2 id="celix_bundle_add_files">celix_bundle_add_files</h2> |
| <p>Copy to the content of a directory to a bundle.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_bundle_add_files</span>(<span style="color:#b44"><bundle_target></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[FILES</span> <span style="color:#b44"><file1></span> <span style="color:#b44"><file2></span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[DESTINATION</span> <span style="color:#b44"><relative_path_in_bundle>]</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><p>Example:</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_bundle_add_files</span>(<span style="color:#b44">my_bundle</span> <span style="color:#b44">FILES</span> <span style="color:#b44">my_file1.txt</span> <span style="color:#b44">my_file2.txt</span> <span style="color:#b44">DESTINATION</span> <span style="color:#b44">"resources"</span>)<span style=""> |
| </span></span></span></code></pre></div><p>Optional arguments:</p> |
| <ul> |
| <li>FILES: Which files to copy to the the bundle.</li> |
| <li>DESTINATION: Destination of the files, relative to the bundle archive root. Default is “.”.</li> |
| </ul> |
| <p>Note celix_bundle_add_files copies the files and can track changes.</p> |
| <h2 id="celix_bundle_headers">celix_bundle_headers</h2> |
| <p>Append the provided headers to the target bundle manifest.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_bundle_headers</span>(<span style="color:#b44"><bundle_target></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">"header1: header1_value"</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">"header2: header2_value"</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">...</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><h2 id="celix_bundle_symbolic_name">celix_bundle_symbolic_name</h2> |
| <p>Set bundle symbolic name</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_bundle_symbolic_name</span>(<span style="color:#b44"><bundle_target></span> <span style="color:#b44">symbolic_name</span>)<span style=""> |
| </span></span></span></code></pre></div><h2 id="celix_get_bundle_symbolic_name">celix_get_bundle_symbolic_name</h2> |
| <p>Get bundle symbolic name from a (imported) bundle target.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_get_bundle_symbolic_name</span>(<span style="color:#b44"><bundle_target></span> <span style="color:#b44">VARIABLE_NAME</span>)<span style=""> |
| </span></span></span></code></pre></div><p>Example: <code>celix_get_bundle_symbolic_name(Celix::shell SHELL_BUNDLE_SYMBOLIC_NAME)</code></p> |
| <h2 id="celix_bundle_name">celix_bundle_name</h2> |
| <p>Set bundle name</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_bundle_name</span>(<span style="color:#b44"><bundle_target></span> <span style="color:#b44">name</span>)<span style=""> |
| </span></span></span></code></pre></div><h2 id="celix_bundle_version">celix_bundle_version</h2> |
| <p>Set bundle version</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_bundle_version</span>(<span style="color:#b44"><bundle_target></span> <span style="color:#b44">version</span>)<span style=""> |
| </span></span></span></code></pre></div><h2 id="celix_bundle_description">celix_bundle_description</h2> |
| <p>Set bundle description</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_bundle_description</span>(<span style="color:#b44"><bundle_target></span> <span style="color:#b44">description</span>)<span style=""> |
| </span></span></span></code></pre></div><h2 id="celix_bundle_group">celix_bundle_group</h2> |
| <p>Set bundle group.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_bundle_group</span>(<span style="color:#b44"><bundle_target></span> <span style="color:#b44">bundle</span> <span style="color:#b44">group</span>)<span style=""> |
| </span></span></span></code></pre></div><h2 id="celix_get_bundle_filename">celix_get_bundle_filename</h2> |
| <p>Get bundle filename from a (imported) bundle target taking into account the |
| used CMAKE_BUILD_TYPE and available bundle configurations.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_get_bundle_filename</span>(<span style="color:#b44"><bundle_target></span> <span style="color:#b44">VARIABLE_NAME</span>)<span style=""> |
| </span></span></span></code></pre></div><p>Example:</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_get_bundle_filename</span>(<span style="color:#b44">Celix::shell</span> <span style="color:#b44">SHELL_BUNDLE_FILENAME</span>)<span style=""> |
| </span></span></span></code></pre></div><h2 id="celix_get_bundle_file">celix_get_bundle_file</h2> |
| <p>Get bundle file (absolute path to a bundle) from a (imported) bundle |
| target taking into account the used CMAKE_BUILD_TYPE and available |
| bundle configurations.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_get_bundle_file</span>(<span style="color:#b44"><bundle_target></span> <span style="color:#b44">VARIABLE_NAME</span>)<span style=""> |
| </span></span></span></code></pre></div><p>Example:</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_get_bundle_file</span>(<span style="color:#b44">Celix::shell</span> <span style="color:#b44">SHELL_BUNDLE_FILE</span>)<span style=""> |
| </span></span></span></code></pre></div><h2 id="install_celix_bundle">install_celix_bundle</h2> |
| <p>Install bundle when ‘make install’ is executed.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">install_celix_bundle</span>(<span style="color:#b44"><bundle_target></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[EXPORT]</span> <span style="color:#b44">export_name</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[PROJECT_NAME]</span> <span style="color:#b44">project_name</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[BUNDLE_NAME]</span> <span style="color:#b44">bundle_name</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[HEADERS</span> <span style="color:#b44">header_file1</span> <span style="color:#b44">header_file2</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[RESOURCES</span> <span style="color:#b44">resource1</span> <span style="color:#b44">resource2</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><p>Bundles are installed at <code><install-prefix>/share/<project_name>/bundles</code>. |
| Headers are installed at <code><install-prefix>/include/<project_name>/<bundle_name></code> |
| Resources are installed at <code><install-prefix>/shared/<project_name>/<bundle_name></code></p> |
| <p>Optional arguments:</p> |
| <ul> |
| <li>EXPORT: Associates the installed bundle with a export_name. |
| The export name can be used to generate a CelixTargets.cmake file (see install_celix_bundle_targets)</li> |
| <li>PROJECT_NAME: The project name for installing. Default is the cmake project name.</li> |
| <li>BUNDLE_NAME: The bundle name used when installing headers/resources. Default is the bundle target name.</li> |
| <li>HEADERS: A list of headers to install for the bundle.</li> |
| <li>RESOURCES: A list of resources to install for the bundle.</li> |
| </ul> |
| <h2 id="install_celix_targets">install_celix_targets</h2> |
| <p>Generate and install a Celix Targets cmake file which contains CMake commands to create imported targets for the bundles |
| install using the provided <export_name>. These imported CMake targets can be used in CMake projects using the installed |
| bundles.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">install_celix_targets</span>(<span style="color:#b44"><export_name></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">NAMESPACE</span> <span style="color:#b44"><namespace></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[FILE</span> <span style="color:#b44"><celix_target_filename>]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[PROJECT_NAME</span> <span style="color:#b44"><project_name>]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[DESTINATION</span> <span style="color:#b44"><celix_targets_destination>]</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><p>Example:</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">install_celix_targets</span>(<span style="color:#b44">celix</span> <span style="color:#b44">NAMESPACE</span> <span style="color:#b44">Celix::</span> <span style="color:#b44">DESTINATION</span> <span style="color:#b44">share/celix/cmake</span> <span style="color:#b44">FILE</span> <span style="color:#b44">CelixTargets</span>)<span style=""> |
| </span></span></span></code></pre></div><p>Optional Arguments:</p> |
| <ul> |
| <li>FILE: The Celix Targets cmake filename to used, without the cmake extension. Default is <export_name>BundleTargets</li> |
| <li>PROJECT_NAME: The project name to used for the share location. Default is the cmake project name.</li> |
| <li>DESTINATION: The (relative) location to install the Celix Targets cmake file to. Default is share/<PROJECT_NAME>/cmake.</li> |
| </ul> |
| <h1 id="celix-containers">Celix Containers</h1> |
| <p>Celix containers are executables preconfigured to start a Celix framework with a set of configuration properties |
| and a set of bundles to install or install and start.</p> |
| <h2 id="add_celix_container">add_celix_container</h2> |
| <p>Add a Celix container, consisting out of a selection of bundles and a Celix launcher. |
| Celix containers can be used to start a Celix framework together with a selection of bundles.</p> |
| <p>A Celix container will be build in <code><cmake_build_dir>/deploy[/<group_name>]/<celix_container_name></code>. |
| Use the <code><celix_container_name></code> executable to run the containers.</p> |
| <p>There are three variants of ‘add_celix_container’:</p> |
| <ul> |
| <li>If no launcher is specified a custom Celix launcher will be generated. This launcher also contains the configured properties.</li> |
| <li>If a LAUNCHER_SRC is provided a Celix launcher will be build using the provided sources. Additional sources can be added with the |
| CMake ’target_sources’ command.</li> |
| <li>If a LAUNCHER (absolute path to a executable of CMake <code>add_executable</code> target) is provided that will be used as Celix launcher.</li> |
| </ul> |
| <p>Creating a Celix containers using ‘add_celix_container’ will lead to a CMake executable target (expect if a LAUNCHER is used). |
| These targets can be used to run/debug Celix containers from a IDE (if the IDE supports CMake).</p> |
| <p>Optional Arguments:</p> |
| <ul> |
| <li>COPY: With this option the bundles used in the container will be copied in and configured for a bundles directory |
| next to the container executable. Only one of the COPY or NO_COPY options can be provided. |
| Default is COPY.</li> |
| <li>NO_COPY: With this option the bundles used in the container will be configured using absolute paths to the bundles |
| zip files. Only one of the COPY or NO_COPY options can be provided. |
| Default is COPY.</li> |
| <li>CXX: With this option the generated Celix launcher (if used) will be a C++ source. |
| This ensures that the Celix launcher is linked against stdlibc++. Only one of the C or CXX options can be provided. |
| Default is CXX</li> |
| <li>C: With this option the generated Celix launcher (if used) will be a C source. Only one of the C or CXX options can |
| be provided. |
| Default is CXX</li> |
| <li>FAT: With this option only embedded bundles are allowed to be added to the container. Ensuring a container executable |
| this is not dependent on external bundle zip files. |
| Note that this option does not change anything to the container, it just ensure that all added bundles are embedded |
| bundles.</li> |
| <li>USE_CONFIG: With this option the config properties are generated in a ‘config.properties’ instead of embedded in |
| the Celix launcher.</li> |
| <li>GROUP: If configured the build location will be prefixed the GROUP. Default is empty.</li> |
| <li>NAME: The name of the executable. Default is <celix_container_name>. Only useful for generated/LAUNCHER_SRC |
| Celix launchers.</li> |
| <li>DIR: The base build directory of the Celix container. Default is <code><cmake_build_dir>/deploy</code>.</li> |
| <li>BUNDLES: A list of bundles for the Celix container to install and start. |
| These bundle will be configured for run level 3. See ‘celix_container_bundles’ for more info.</li> |
| <li>INSTALL_BUNDLES: A list of bundles for the Celix container to install (but not start).</li> |
| <li>EMBEDDED_BUNDLES: A list of bundles to embed in the Celix container (inject as binary in the executable) and |
| to install and start for the Celix container. |
| See <code>celix_target_embedded_bundle</code> for more info about embedded bundles.</li> |
| <li>INSTALL_EMBEDDED_BUNDLES: A list of bundles to embed in the Celix container (inject as binary in the executable) and |
| to install (but not start) for the Celix container. |
| See <code>celix_target_embedded_bundle</code> for more info about embedded bundles.</li> |
| <li>PROPERTIES: A list of configuration properties, these can be used to configure the Celix framework and/or bundles. |
| Normally this will be EMBEDED_PROPERTIES, but if the USE_CONFIG option is used this will be RUNTIME_PROPERTIES. |
| See the framework library or bundles documentation about the available configuration options.</li> |
| <li>EMBEDDED_PROPERTIES: A list of configuration properties which will be used in the generated Celix launcher.</li> |
| <li>RUNTIME_PROPERTIES: A list of configuration properties which will be used in the generated config.properties file.</li> |
| </ul> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">add_celix_container</span>(<span style="color:#b44"><celix_container_name></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[COPY]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[NO_COPY]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[CXX]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[C]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[FAT]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[USE_CONFIG]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[GROUP</span> <span style="color:#b44">group_name]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[NAME</span> <span style="color:#b44">celix_container_name]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[DIR</span> <span style="color:#b44">dir]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[BUNDLES</span> <span style="color:#b44"><bundle1></span> <span style="color:#b44"><bundle2></span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[INSTALL_BUNDLES</span> <span style="color:#b44"><bundle1></span> <span style="color:#b44"><bundle2></span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[EMBEDDED_BUNDLES</span> <span style="color:#b44"><bundle1></span> <span style="color:#b44"><bundle2></span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[INSTALL_EMBEDDED_BUNDLES</span> <span style="color:#b44"><bundle1></span> <span style="color:#b44"><bundle2></span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[PROPERTIES</span> <span style="color:#b44">"prop1=val1"</span> <span style="color:#b44">"prop2=val2"</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[EMBEDDED_PROPERTIES</span> <span style="color:#b44">"prop1=val1"</span> <span style="color:#b44">"prop2=val2"</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[RUNTIME_PROPERTIES</span> <span style="color:#b44">"prop1=val1"</span> <span style="color:#b44">"prop2=val2"</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">add_celix_container</span>(<span style="color:#b44"><celix_container_name></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">LAUNCHER</span> <span style="color:#b44">launcher</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[COPY]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[NO_COPY]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[CXX]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[C]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[FAT]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[USE_CONFIG]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[GROUP</span> <span style="color:#b44">group_name]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[NAME</span> <span style="color:#b44">celix_container_name]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[DIR</span> <span style="color:#b44">dir]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[BUNDLES</span> <span style="color:#b44"><bundle1></span> <span style="color:#b44"><bundle2></span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[INSTALL_BUNDLES</span> <span style="color:#b44"><bundle1></span> <span style="color:#b44"><bundle2></span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[EMBEDDED_BUNDLES</span> <span style="color:#b44"><bundle1></span> <span style="color:#b44"><bundle2></span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[INSTALL_EMBEDDED_BUNDLES</span> <span style="color:#b44"><bundle1></span> <span style="color:#b44"><bundle2></span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[PROPERTIES</span> <span style="color:#b44">"prop1=val1"</span> <span style="color:#b44">"prop2=val2"</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[EMBEDDED_PROPERTIES</span> <span style="color:#b44">"prop1=val1"</span> <span style="color:#b44">"prop2=val2"</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[RUNTIME_PROPERTIES</span> <span style="color:#b44">"prop1=val1"</span> <span style="color:#b44">"prop2=val2"</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">add_celix_container</span>(<span style="color:#b44"><celix_container_name></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">LAUNCHER_SRC</span> <span style="color:#b44">launcher_src</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[COPY]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[NO_COPY]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[CXX]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[C]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[FAT]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[USE_CONFIG]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[GROUP</span> <span style="color:#b44">group_name]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[NAME</span> <span style="color:#b44">celix_container_name]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[DIR</span> <span style="color:#b44">dir]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[BUNDLES</span> <span style="color:#b44"><bundle1></span> <span style="color:#b44"><bundle2></span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[INSTALL_BUNDLES</span> <span style="color:#b44"><bundle1></span> <span style="color:#b44"><bundle2></span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[EMBEDDED_BUNDLES</span> <span style="color:#b44"><bundle1></span> <span style="color:#b44"><bundle2></span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[INSTALL_EMBEDDED_BUNDLES</span> <span style="color:#b44"><bundle1></span> <span style="color:#b44"><bundle2></span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[PROPERTIES</span> <span style="color:#b44">"prop1=val1"</span> <span style="color:#b44">"prop2=val2"</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[EMBEDDED_PROPERTIES</span> <span style="color:#b44">"prop1=val1"</span> <span style="color:#b44">"prop2=val2"</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[RUNTIME_PROPERTIES</span> <span style="color:#b44">"prop1=val1"</span> <span style="color:#b44">"prop2=val2"</span> <span style="color:#b44">...]</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><p>Examples:</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#080;font-style:italic">#Creates a Celix container in ${CMAKE_BINARY_DIR}/deploy/simple_container which starts 3 bundles located at |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic">#${CMAKE_BINARY_DIR}/deploy/simple_container/bundles. |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span><span style="color:#a2f">add_celix_container</span>(<span style="color:#b44">simple_container</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">BUNDLES</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">Celix::shell</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">Celix::shell_tui</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">Celix::log_admin</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">PROPERTIES</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">CELIX_LOGGING_DEFAULT_ACTIVE_LOG_LEVEL=debug</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#080;font-style:italic">#Creates a "fat" Celix container in ${CMAKE_BINARY_DIR}/deploy/simple_fat_container which starts 3 bundles embedded |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic">#in the container executable. |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span><span style="color:#a2f">add_celix_container</span>(<span style="color:#b44">simple_fat_container</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">FAT</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">EMBEDDED_BUNDLES</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">Celix::shell</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">Celix::shell_tui</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">Celix::log_admin</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">PROPERTIES</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">CELIX_LOGGING_DEFAULT_ACTIVE_LOG_LEVEL=debug</span> |
| </span></span><span style="display:flex;"><span> )<span style=""> |
| </span></span></span></code></pre></div><h2 id="celix_container_bundles">celix_container_bundles</h2> |
| <p>Add a selection of bundles to the Celix container.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_container_bundles</span>(<span style="color:#b44"><celix_container_target_name></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[COPY]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[NO_COPY]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[LEVEL</span> (<span style="color:#b44">0..6</span>)<span style="color:#b44">]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[INSTALL]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">bundle1</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">bundle2</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">...</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><p>Example:</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_container_bundles</span>(<span style="color:#b44">my_container</span> <span style="color:#b44">Celix::shell</span> <span style="color:#b44">Celix::shell_tui</span>)<span style=""> |
| </span></span></span></code></pre></div><p>The selection of bundles are (if configured) copied to the container build dir and |
| are added to the configuration properties so that they are installed and started when the Celix container is executed.</p> |
| <p>The Celix framework supports 7 (0 - 6) run levels. Run levels can be used to control the start and stop order of bundles. |
| Bundles in run level 0 are started first and bundles in run level 6 are started last. |
| When stopping bundles in run level 6 are stopped first and bundles in run level 0 are stopped last. |
| Within a run level the order of configured decides the start order; bundles added earlier are started first.</p> |
| <p>Optional Arguments:</p> |
| <ul> |
| <li>LEVEL: The run level for the added bundles. Default is 3.</li> |
| <li>INSTALL: If this option is present, the bundles will only be installed instead of the default install and start. |
| The bundles will be installed after all bundle in LEVEL 0..6 are installed and started.</li> |
| <li>COPY: If this option is present, the bundles will be copied to the container build dir. This option overrides the |
| NO_COPY option used in the add_celix_container call.</li> |
| <li>NO_COPY: If this option is present, the install/start bundles will be configured using a absolute path to the |
| bundle. This option overrides optional COPY option used in the add_celix_container call.</li> |
| </ul> |
| <h2 id="celix_container_embedded_bundles">celix_container_embedded_bundles</h2> |
| <p>Embed a selection of bundles to the Celix container.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_container_embedded_bundles</span>(<span style="color:#b44"><celix_container_target_name></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[LEVEL</span> (<span style="color:#b44">0..6</span>)<span style="color:#b44">]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[INSTALL]</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">bundle1</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">bundle2</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">...</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><p>Example:</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_container_embedded_bundles</span>(<span style="color:#b44">my_container</span> <span style="color:#b44">Celix::shell</span> <span style="color:#b44">Celix::shell_tui</span>)<span style=""> |
| </span></span></span></code></pre></div><p>The selection of bundles are embedded in the container executable using the |
| <code>celix_target_embedded_bundle</code> Celix CMake command and are added to the configuration properties so that they are |
| installed and started when the Celix container is executed.</p> |
| <p>See <code>celix_target_embedded_bundle</code> for how bundle is embedded in a executable.</p> |
| <p>The Celix framework supports 7 (0 - 6) run levels. Run levels can be used to control the start and stop order of bundles. |
| Bundles in run level 0 are started first and bundles in run level 6 are started last. |
| When stopping bundles in run level 6 are stopped first and bundles in run level 0 are stopped last. |
| Within a run level the order of configured decides the start order; bundles added earlier are started first.</p> |
| <p>Optional Arguments:</p> |
| <ul> |
| <li>LEVEL: The run level for the added bundles. Default is 3.</li> |
| <li>INSTALL: If this option is present, the bundles will only be installed instead of the default install and start. |
| The bundles will be installed after all bundle in LEVEL 0..6 are installed and started.</li> |
| </ul> |
| <h2 id="celix_container_properties">celix_container_properties</h2> |
| <p>Add the provided properties to the target Celix container config properties. |
| If the USE_CONFIG option is used these configuration properties will be added to the ‘config.properties’ file else they |
| will be added to the generated Celix launcher.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_container_properties</span>(<span style="color:#b44"><celix_container_target_name></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">"prop1=val1"</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">"prop2=val2"</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">...</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><h2 id="celix_container_embedded_properties">celix_container_embedded_properties</h2> |
| <p>Add the provided properties to the target Celix container config properties. |
| These properties will be embedded into the generated Celix launcher.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_container_embedded_properties</span>(<span style="color:#b44"><celix_container_target_name></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">"prop1=val1"</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">"prop2=val2"</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">...</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><h2 id="celix_container_runtime_properties">celix_container_runtime_properties</h2> |
| <p>Add the provided properties to the target Celix container config properties. |
| These properties will be added to the config.properties in the container build dir.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_container_runtime_properties</span>(<span style="color:#b44"><celix_container_target_name></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">"prop1=val1"</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">"prop2=val2"</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">...</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><h1 id="celix-cmake-commands-for-generic-cmake-targets">Celix CMake commands for generic CMake targets</h1> |
| <p>Celix provides several CMake commands that operate on the generic CMake targets (executable, shared library, etc).</p> |
| <p>Celix CMake commands for generic CMake target will always use the keyword signature (<code>PRIVATE</code>, <code>PUBLIC</code>, <code>INTERFACE</code>) |
| version for linking, adding sources, etc. This means that these command will not work on targets created with |
| an “all-plain” CMake version command.</p> |
| <h2 id="add_celix_bundle_dependencies">add_celix_bundle_dependencies</h2> |
| <p>Add bundles as dependencies to a cmake target, so that the bundle zip files will be created before the cmake target.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">add_celix_bundle_dependencies</span>(<span style="color:#b44"><cmake_target></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">bundles...</span> |
| </span></span><span style="display:flex;"><span>)<span style=""> |
| </span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">add_celix_bundle_dependencies</span>(<span style="color:#b44">my_exec</span> <span style="color:#b44">my_bundle1</span> <span style="color:#b44">my_bundle2</span>)<span style=""> |
| </span></span></span></code></pre></div><h2 id="celix_target_embedded_bundle">celix_target_embedded_bundle</h2> |
| <p>Embeds a Celix bundle into a CMake target.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_target_embedded_bundle</span>(<span style="color:#b44"><cmake_target></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">BUNDLE</span> <span style="color:#b44"><bundle></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[NAME</span> <span style="color:#b44"><name>]</span> |
| </span></span><span style="display:flex;"><span> )<span style=""> |
| </span></span></span></code></pre></div><p>Example:</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_target_embedded_bundle</span>(<span style="color:#b44">my_executable</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">BUNDLE</span> <span style="color:#b44">Celix::shell</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">NAME</span> <span style="color:#b44">celix_shell</span> |
| </span></span><span style="display:flex;"><span> )<span style=""> |
| </span></span></span><span style="display:flex;"><span><span style=""></span><span style="color:#080;font-style:italic"># result in the symbols: |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"># - celix_embedded_bundle_celix_shell_start |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"># - celix_embedded_bundle_celix_shell_end |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"># - celix_embedded_bundles = "embedded://celix_shell" |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"># to be added to `my_executable` |
| </span></span></span></code></pre></div><p>The Celix bundle will be embedded into the CMake target between the symbols: <code>celix_embedded_bundle_${NAME}_start</code> and |
| <code>celix_embedded_bundle_${NAME}_end</code>.</p> |
| <p>Also a <code>const char * const</code> symbol with the name <code>celix_embedded_bundles</code> will be added or updated containing a <code>,</code> |
| seperated list of embedded Celix bundle urls. The url will be: <code>embedded://${NAME}</code>.</p> |
| <p>For Linux the linking flag <code>--export-dynamic</code> is added to ensure that the previous mentioned symbols can be retrieved |
| using <code>dlsym</code>.</p> |
| <p>Mandatory Arguments:</p> |
| <ul> |
| <li>BUNDLE: The bundle target or bundle file (absolute path) to embed in the CMake target.</li> |
| </ul> |
| <p>Optional Arguments:</p> |
| <ul> |
| <li>NAME: The name to use when embedding the Celix bundle. This name is used in the _start and _end symbol, but also |
| for the embedded bundle url. |
| For a bundle CMake target the default is the bundle symbolic name and for a bundle file the default is the |
| bundle filename without extension. The NAME must be a valid C identifier.</li> |
| </ul> |
| <p>Bundles embedded in an executable can be installed/started using the bundle url: “embedded://${NAME}” in |
| combination with <code>celix_bundleContext_installBundle</code> (C) or <code>celix::BundleContext::installBundle</code> (C++). |
| All embedded bundle can be installed using the framework utils function |
| <code>celix_framework_utils_installEmbeddedBundles</code> (C) or <code>celix::installEmbeddedBundles</code> (C++).</p> |
| <h2 id="celix_target_embedded_bundles">celix_target_embedded_bundles</h2> |
| <p>Embed multiple Celix bundles into a CMake target.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_target_embedded_bundles</span>(<span style="color:#b44"><cmake_target></span> <span style="color:#b44">[<bundle1></span> <span style="color:#b44"><bundle2></span> <span style="color:#b44">...]</span>)<span style=""> |
| </span></span></span></code></pre></div><p>Example:</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_target_embedded_bundles</span>(<span style="color:#b44">my_executable</span> <span style="color:#b44">Celix::shell</span> <span style="color:#b44">Celix::shell_tui</span>)<span style=""> |
| </span></span></span></code></pre></div><p>The bundles will be embedded using their symbolic name if the bundle is a CMake target or their filename (without |
| extension) if the bundle is a file (absolute path).</p> |
| <h2 id="celix_target_bundle_set_definition">celix_target_bundle_set_definition</h2> |
| <p>Add a compile-definition with a set of comma seperated bundles paths to a target and also adds the bundles as |
| dependency to the target.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_target_bundle_set_definition</span>(<span style="color:#b44"><cmake_target></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">NAME</span> <span style="color:#b44"><set_name></span> |
| </span></span><span style="display:flex;"><span> <span style="color:#b44">[<bundle1></span> <span style="color:#b44"><bundle2>..]</span> |
| </span></span><span style="display:flex;"><span> )<span style=""> |
| </span></span></span></code></pre></div><p>Example:</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_target_bundle_set_definition</span>(<span style="color:#b44">test_example</span> <span style="color:#b44">NAME</span> <span style="color:#b44">TEST_BUNDLES</span> <span style="color:#b44">Celix::shell</span> <span style="color:#b44">Celix::shell_tui</span>)<span style=""> |
| </span></span></span></code></pre></div><p>The compile-definition will have the name <code>${NAME}</code> and will contain a <code>,</code> separated list of bundle paths. |
| The bundle set can be installed using the Celix framework util function <code>celix_framework_utils_installBundleSet</code> (C) |
| or <code>celix::installBundleSet</code> (C++).</p> |
| <p>Adding a compile-definition with a set of bundles can be useful for testing purpose.</p> |
| <h2 id="celix_target_hide_symbols">celix_target_hide_symbols</h2> |
| <p>Configure the symbol visibility preset of the provided target to hidden.</p> |
| <p>This is done by setting the target properties C_VISIBILITY_PRESET to hidden, the CXX_VISIBILITY_PRESET to hidden and |
| VISIBILITY_INLINES_HIDDEN to ON.</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_target_hide_symbols</span>(<span style="color:#b44"><cmake_target></span> <span style="color:#b44">[RELEASE]</span> <span style="color:#b44">[DEBUG]</span> <span style="color:#b44">[RELWITHDEBINFO]</span> <span style="color:#b44">[MINSIZEREL]</span>)<span style=""> |
| </span></span></span></code></pre></div><p>Optional arguments are:</p> |
| <ul> |
| <li>RELEASE: hide symbols for the release build type</li> |
| <li>DEBUG: hide symbols for the debug build type</li> |
| <li>RELWITHDEBINFO: hide symbols for the relwithdebinfo build type</li> |
| <li>MINSIZEREL: hide symbols for the minsizerel build type</li> |
| </ul> |
| <p>If no optional arguments are provided, the symbols are hidden for all build types.</p> |
| <p>Example:</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-CMake" data-lang="CMake"><span style="display:flex;"><span><span style="color:#a2f">celix_target_hide_symbols</span>(<span style="color:#b44">my_bundle</span> <span style="color:#b44">RELEASE</span> <span style="color:#b44">MINSIZEREL</span>)<span style=""> |
| </span></span></span></code></pre></div> |
| |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| |
| <footer class="py-3 bg-secondary"> |
| <div class="container"> |
| <div class="row"> |
| <div class="col-md-8 text-center"> |
| <p class="m-0 text-white"> |
| Copyright © 2024 The Apache Software Foundation, Licensed under |
| the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>. |
| <br> |
| Apache Celix, Celix, Apache, the Apache feather logo and the Apache Celix logo are trademarks of The Apache Software Foundation. |
| </p> |
| </div> |
| <div class="col-md-4 text-center"> |
| <a href="https://www.apache.org/events/current-event.html" target="_blank"> |
| <img src="https://www.apache.org/events/current-event-234x60.png" title="Apache Event" width="234" height="60" border="0"> |
| </a> |
| </div> |
| </div> |
| </div> |
| </footer> |
| |
| |
| <script src="/assets/js/jquery.min.js"></script> |
| <script src="/assets/js/bootstrap.bundle.min.js"></script> |
| |
| |
| </body> |
| </html> |
