Apache Celix 常用 CLI 命令与工具详解

目标：把 Apache Celix 2.4.0 日常用到的命令与工具讲透——启动器 celix 的每个选项、嵌入框架的 celix_launcher C API、CMake/Make 构建命令、zip/ldd 辅助工具，每条命令配真实回显，已在 Ubuntu 22.04（x86_64）实测通过。

一、环境信息

本节交代命令实测所用的环境与关键路径。以下为本篇全部回显的运行环境：

操作系统：Ubuntu 22.04.5 LTS（x86_64）
编译器/构建工具：GCC 11.4.0、GNU Make 4.3、CMake 3.22.1
目标组件：Apache Celix 2.4.0
安装前缀：/opt/celix（启动器 /opt/celix/bin/celix，头文件 /opt/celix/include/celix，库 /opt/celix/lib）
源码构建目录：/opt/src/celix-2.4.0/build
实测运行时目录：/opt/celix-demo/runtime（属性文件 config.properties，加载 hello_bundle.zip）
嵌入示例：/opt/celix-demo/embed/embed.c

💡 说明：Celix 是 C/C++ 版 OSGi 框架，构建用 CMake + Make，运行用启动器 celix。它是纯 C/C++ 工程；本篇只讲真实可用的 C/C++ 工具链。

二、工具概览

本节先给一张工具清单，让读者知道每个工具做什么、何时用。

工具	类型	用途	实测可用性
`celix`	可执行文件（`/opt/celix/bin/celix`）	启动/停止框架，加载 bundle，查看属性	已安装
`celix_launcher`	C API（`/opt/celix/include/celix/framework/celix_launcher.h`）	把框架嵌入自己的 C/C++ 程序	已随库安装
`cmake`	构建命令行	配置、编译、安装 Celix 及 bundle	3.22.1
`make`	构建命令行	CMake 生成的底层构建后端	4.3
`zip`	打包命令行	打包 bundle 归档（`.zip`）	3.0
`ldd`	依赖查看	检查可执行文件的共享库解析	系统自带

关键解读：本篇重点在 celix（运行期）与 celix_launcher（嵌入），cmake/make 是构建期主工具，zip/ldd 为排障辅助。

三、前置条件

本节说明复现本篇命令的前提：

已编译安装 Celix 2.4.0 到 /opt/celix（安装方法见两篇安装指南）。
已存在一个可加载的 bundle，本篇沿用实测工程 /opt/celix-demo/hello_bundle（构建产物含 hello_bundle.zip）。
运行前导出库路径：

export LD_LIBRARY_PATH=/opt/celix/lib:$LD_LIBRARY_PATH

验证可执行文件可见：

ls -l /opt/celix/bin/celix

回显：

-rwxr-xr-x 1 root root 16096 Oct 13 17:47 /opt/celix/bin/celix

四、celix 启动器详解

本节逐个讲解启动器 celix 的选项，每个选项都给命令与回显。

4.1 `-h` / `--help`：查看用法

/opt/celix/bin/celix --help

回显：

Usage:
  celix [-h|-p] [path/to/runtime/config.properties]
Options:
        -h | --help: Show this message.
        -p | --props: Show the embedded and runtime properties for this Celix runtime and exit.
        -c | --create-bundle-cache: Create the bundle cache for this Celix runtime and exit.
        --embedded_bundles: Show the embedded bundles for this Celix runtime and exit.

解读：celix 的用法形态是 celix [-h|-p] [属性文件路径]。除 -h/-p 两个短选项外还有 -c 与 --embedded_bundles 两个长/短选项，最后的位置参数是可选属性文件。

4.2 `-p` / `--props`：查看生效属性

-p 打印嵌入属性、运行时属性文件内容与合并后的最终值。

cd /opt/celix-demo/runtime
export LD_LIBRARY_PATH=/opt/celix/lib:$LD_LIBRARY_PATH
/opt/celix/bin/celix -p ./config.properties

回显：

Embedded properties:
|- Empty!

Runtime properties (input ./config.properties):
|- CELIX_AUTO_START_1=hello_bundle.zip
|- CELIX_BUNDLES_PATH=/opt/celix-demo/hello_bundle/build

Resolved (env, runtime and embedded) properties:
|- CELIX_AUTO_START_1=hello_bundle.zip (source runtime)
|- CELIX_BUNDLES_PATH=/opt/celix-demo/hello_bundle/build (source runtime)

解读：三组分别对应「编译期嵌入」「属性文件」「合并后」。source runtime 表示该值来自属性文件；若来自环境变量则标 source env。排障「属性改了没生效」时优先看 Resolved 分组的来源。

4.3 `-c` / `--create-bundle-cache`：预建 bundle 缓存

-c 在不真正启动框架的情况下，按属性文件预先创建 bundle 缓存目录（框架随后启动更快）。

cd /opt/celix-demo/runtime
/opt/celix/bin/celix -c ./config.properties 2>&1 | head

回显：

[2026-10-13T17:51:23] [   info] [celix_framework] [celix_bundleCache_createBundleArchivesCache:361] Deleted bundle cache directory .cache
[2026-10-13T17:51:23] [   info] [celix_framework] [celix_bundleCache_createBundleArchivesForSpaceSeparatedList:327] Created bundle cache '.cache/bundle1/resources' for bundle archive hello_bundle (bndId=1).

验证缓存已生成：

find .cache -maxdepth 2

回显：

.cache
.cache/bundle1
.cache/bundle1/resources
.cache/bundle1/bundle_state.properties
.cache/bundle1/storage

4.4 `--embedded_bundles`：查看内嵌 bundle

/opt/celix/bin/celix --embedded_bundles

回显：

Embedded bundles:
|- no embedded bundles

解读：若构建时把 bundle 嵌入到启动器内，这里会列出；用默认配置编译的启动器没有内嵌 bundle，故显示 no embedded bundles。

4.5 无选项启动框架并加载 bundle

不带 -h/-p/-c 而直接给出属性文件路径时，启动框架并按属性文件安装、启动 bundle。

cd /opt/celix-demo/runtime
timeout 4 /opt/celix/bin/celix ./config.properties 2>&1 | head

回显：

[hello_bundle] started, bundle id = 1
[2026-10-13T17:49:15] [   info] [celix_framework] [framework_start:476] Celix framework started
[hello_bundle] stopped, bundle id = 1

解读：启动器会一直前台运行直到收到退出信号（本篇用 timeout 限时演示）。中间出现 [hello_bundle] started，说明 CELIX_AUTO_START_1 指定的 bundle 已按级别 1 启动。

⚠️ 注意：交互式 shell 界面（celix_shell_tui.zip）需要 tty。非交互环境下不会激活，实测回显为：

[2026-10-13T17:55:17] [   info] [celix_framework] [Shell TUI] no tty connected. Shell TUI will not activate.

如需交互式 shell，请在带终端的会话中启动。

五、celix_launcher 嵌入 C API 详解

本节说明如何把框架嵌入到自己的 C/C++ 程序中。注意：celix_launcher 在本版本中不是可执行命令，而是一组 C API（头文件 celix_launcher.h），随 libcelix_framework 一起安装。

查看头文件导出的函数（实测省略许可注释后的内容）：

grep -vE '^ \*|^/\*|^#|^$' /opt/celix/include/celix/framework/celix_launcher.h

回显：

extern "C" {
CELIX_FRAMEWORK_EXPORT int celixLauncher_launchAndWaitForShutdown(int argc, char *argv[], celix_properties_t *embeddedConfig);
CELIX_FRAMEWORK_EXPORT int celixLauncher_launchWithArgv(int argc, char *argv[], celix_properties_t* embeddedConfig, celix_framework_t** framework);
CELIX_FRAMEWORK_EXPORT int celixLauncher_launch(const char *configFile, celix_framework_t **framework);
CELIX_FRAMEWORK_EXPORT int celixLauncher_launchWithStream(FILE *config, celix_framework_t **framework);
CELIX_FRAMEWORK_EXPORT int celixLauncher_launchWithProperties(celix_properties_t *config, celix_framework_t **framework);
CELIX_FRAMEWORK_EXPORT void celixLauncher_waitForShutdown(celix_framework_t *framework);
CELIX_FRAMEWORK_EXPORT void celixLauncher_stop(celix_framework_t *framework);
CELIX_FRAMEWORK_EXPORT void celixLauncher_destroy(celix_framework_t *framework);
}

逐项说明：

celixLauncher_launchAndWaitForShutdown：接收 argc/argv，启动框架并阻塞等待退出——celix 可执行文件内部就是这么调的。
celixLauncher_launch：按属性文件路径启动，返回框架句柄。
celixLauncher_launchWithStream / launchWithProperties：分别从文件流、属性对象启动。
celixLauncher_waitForShutdown / stop / destroy：等待退出 / 主动停止 / 释放框架。

下面写一个最小嵌入程序 /opt/celix-demo/embed/embed.c：

#include <stdio.h>
#include <celix_launcher.h>

int main(int argc, char *argv[]) {
    printf("[embed] embedding Celix framework\n");
    return celixLauncher_launchAndWaitForShutdown(argc, argv, NULL);
}

编译（指定头文件目录与库，并写入运行时库搜索路径）：

cd /opt/celix-demo/embed
gcc embed.c -o embed \
  -I/opt/celix/include/celix/framework -I/opt/celix/include/celix/utils \
  -L/opt/celix/lib -Wl,-rpath,/opt/celix/lib \
  -lcelix_framework -lcelix_utils -lcurl -luuid -lpthread
ls -l embed

回显：

-rw-r--r-- 1 root root 12349 Oct 13 17:59 embed

运行（传入与 celix 相同的属性文件）：

cd /opt/celix-demo/runtime
export LD_LIBRARY_PATH=/opt/celix/lib:$LD_LIBRARY_PATH
timeout 4 /opt/celix-demo/embed/embed ./config.properties 2>&1 | head

回显：

[embed] embedding Celix framework
[hello_bundle] started, bundle id = 1
[2026-10-13T17:59:28] [   info] [celix_framework] [framework_start:476] Celix framework started
[hello_bundle] stopped, bundle id = 1

解读：自写程序成功嵌入框架并加载了 bundle，效果与直接调用 celix 等价。

六、cmake 构建命令详解

本节讲构建 Celix 与 bundle 时用到的 CMake 子命令。

6.1 版本与总用法

cmake --version
cmake --help | head -14

回显：

cmake version 3.22.1

CMake suite maintained and supported by Kitware (kitware.com/cmake).
Usage

  cmake [options] <path-to-source>
  cmake [options] <path-to-existing-build>
  cmake [options] -S <path-to-source> -B <path-to-build>

Specify a source directory to (re-)generate a build system for it in the

解读：cmake -S <源码> -B <构建> 是源码外构建的标准写法；配置阶段用 -D<变量>=<值> 传参。

6.2 `cmake --build` 用法

cd /opt/src/celix-2.4.0
cmake --build 2>&1 | head -20

回显（不加目录时打印用法）：

Usage: cmake --build <dir>             [options] [-- [native-options]]
       cmake --build --preset <preset> [options] [-- [native-options]]
Options:
  <dir>          = Project binary directory to be built.
  --preset <preset>, --preset=<preset>
                 = Specify a build preset.
  --target <tgt>..., -t <tgt>...
                 = Build <tgt> instead of default targets.
  --config <cfg> = For multi-configuration tools, choose <cfg>.
  --clean-first  = Build target 'clean' first, then build.
  --verbose, -v  = Enable verbose output - if supported - including
                   the build commands to be executed.

解读：常用组合是 cmake --build build（编译默认目标）、cmake --build build --target install（仅跑安装目标）、cmake --build build -j$(nproc)（并行）。

实测配置与编译：

cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/opt/celix -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

回显（输出节选，实测首尾）：

-- Configuring done
-- Generating done
-- Build files have been written to: /opt/src/celix-2.4.0/build
...
[100%] Built target SimpleServicesExample
[100%] Built target depman_example_cxx

安装：

cmake --install build

回显（输出节选，实测首尾）：

-- Installing: /opt/celix/share/celix/cmake/cmake_celix/UseCelix.cmake
...
-- Installing: /opt/celix/lib/cmake/Celix/CelixConfigVersion.cmake

6.3 `cmake -L` 查看缓存变量

cd /opt/src/celix-2.4.0
cmake -L -N build | grep -E 'CMAKE_INSTALL_PREFIX|CMAKE_BUILD_TYPE|ENABLE_TESTING|ZIP_COMMAND'

回显：

CMAKE_BUILD_TYPE:STRING=Release
CMAKE_INSTALL_PREFIX:PATH=/opt/celix
ENABLE_TESTING:BOOL=OFF
ZIP_COMMAND:FILEPATH=/usr/bin/zip

解读：-L 列出缓存变量，-N 表示只看不改；排查「某参数当前是什么值」时最直接。

七、make 构建命令详解

本节讲 CMake 生成的底层 Make 后端用法。

make --version | head -1
make --help | head -14

回显：

GNU Make 4.3
Usage: make [options] [target] ...
Options:
  -b, -m                      Ignored for compatibility.
  -B, --always-make           Unconditionally make all targets.
  -C DIRECTORY, --directory=DIRECTORY
                              Change to DIRECTORY before doing anything.
  -d                          Print lots of debugging information.
  -e, --environment-overrides
                              Environment variables override makefiles.
  -f FILE, --file=FILE, --makefile=FILE
                              Read FILE as a makefile.
  -h, --help                  Print this message and exit.
  -j [N], --jobs[=N]          Allow N jobs at once; infinite jobs with no arg.

解读：进入构建目录后，make 等价于 cmake --build .；make -j$(nproc) 并行编译；make install 走安装目标。用 cmake --build 包裹可屏蔽不同后端（Make/Ninja）差异。

实测在构建目录内直接调用 make：

cd /opt/src/celix-2.4.0/build
make help 2>&1 | head -12

回显（输出节选，实测首尾；列出可构建的目标）：

The following are some of the valid targets for this Makefile:
... all (the default if no target is provided)
... clean
... depend
... edit_cache
... install
... install/local
... install/strip
... list_install_components
... rebuild_cache

八、辅助命令

本节讲两个排障辅助工具。

8.1 zip：打包 bundle

zip -v 2>&1 | head -6

回显：

Copyright (c) 1990-2008 Info-ZIP - Type 'zip "-L"' for software license.
This is Zip 3.0 (July 5th 2008), by Info-ZIP.
Currently maintained by E. Gordon.  Please send bug reports to
the authors using the web page at www.info-zip.org; see README for details.

解读：Celix 打包 bundle 需要 jar 或 zip 之一，纯 C 环境装 zip 即可；若 zip 缺失，CMake 配置阶段会直接报 A jar or zip command is needed to jar/zip bundles。

8.2 ldd：检查运行时依赖

export LD_LIBRARY_PATH=/opt/celix/lib:$LD_LIBRARY_PATH
ldd /opt/celix/bin/celix | head -6

回显：

        linux-vdso.so.1 (0x00007fff8dfe2000)
        libcelix_framework.so.2 => /opt/celix/lib/libcelix_framework.so.2 (0x000078fcee33e000)
        libcurl.so.4 => /lib/x86_64-linux-gnu/libcurl.so.4 (0x000078fcee293000)
        libcelix_utils.so.2 => /opt/celix/lib/libcelix_utils.so.2 (0x000078fcee274000)
        libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x000078fcee04b000)
        libuuid.so.1 => /lib/x86_64-linux-gnu/libuuid.so.1 (0x000078fcee042000)

解读：若某行显示 not found，即为该共享库未解析——通常是 LD_LIBRARY_PATH 未含 /opt/celix/lib。

九、注意事项

路径：LD_LIBRARY_PATH=/opt/celix/lib:$LD_LIBRARY_PATH 是每次运行前的基本动作；持久化见安装指南第七节。
交互 shell 需 tty，非交互场景用属性文件驱动 bundle 更稳妥。
celix 前台阻塞运行，脚本中请配合 timeout 或后台运行 + 信号控制。
嵌入程序编译时若出现 undefined reference to celix_utils_*，说明漏链了 -lcelix_utils（及其依赖 -lcurl -luuid -lpthread），按第五节链接参数补齐。

十、常见问题（FAQ）

Q1：celix --help 里看到的选项只有四个，够用吗？

现象：选项很少。定位：celix 是框架启动器，本身只负责进程入口与属性装载，交互能力由 shell bundle 提供。解决：需要交互式命令时加载 celix_shell.zip + celix_shell_tui.zip 并在带 tty 的终端运行。

Q2：非交互环境启动含 shell 的运行时看不到命令行界面？

现象：日志出现 Shell TUI will not activate。定位：TUI 组件检测到无 tty。解决：改用带终端的会话，或在属性文件中仅加载业务 bundle、用日志观察运行状态。

Q3：cmake --build 报 Error: ./--help is not a directory？

现象：把 --help 传给了 cmake --build。定位：CMake 3.22 的 cmake --build 不把 --help 当选项，而是当作目录参数。解决：不带参数直接运行 cmake --build，它会打印用法（见 6.2）。

Q4：嵌入程序编译报 undefined reference to celix_properties_size 等？

现象：链接失败。定位：只链了 -lcelix_framework，未链其依赖库。解决：补齐 -lcelix_utils -lcurl -luuid -lpthread 并加 -Wl,-rpath,/opt/celix/lib（见第五节实测命令）。

十一、参考链接

Apache Celix 官网：https://celix.apache.org/
源码发布目录（本版本实测）：https://downloads.apache.org/celix/celix-2.4.0/
启动器与嵌入 API 头文件（源码内）：/opt/celix/include/celix/framework/celix_launcher.h
官方构建说明（源码内 BUILDING 文件）：/opt/src/celix-2.4.0/BUILDING
GitHub 仓库：https://github.com/apache/celix

Apache Celix 常用 CLI 命令与工具详解

Apache Celix 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、celix 启动器详解

4.1 -h / --help：查看用法

4.2 -p / --props：查看生效属性

4.3 -c / --create-bundle-cache：预建 bundle 缓存

4.4 --embedded_bundles：查看内嵌 bundle

4.5 无选项启动框架并加载 bundle

五、celix_launcher 嵌入 C API 详解

六、cmake 构建命令详解

6.1 版本与总用法

6.2 cmake --build 用法

6.3 cmake -L 查看缓存变量

七、make 构建命令详解

八、辅助命令

8.1 zip：打包 bundle

8.2 ldd：检查运行时依赖

九、注意事项

十、常见问题（FAQ）

十一、参考链接

4.1 `-h` / `--help`：查看用法

4.2 `-p` / `--props`：查看生效属性

4.3 `-c` / `--create-bundle-cache`：预建 bundle 缓存

4.4 `--embedded_bundles`：查看内嵌 bundle

6.2 `cmake --build` 用法

6.3 `cmake -L` 查看缓存变量