From 1b837766f0af8e80d4711804540062246870e850 Mon Sep 17 00:00:00 2001 From: Dantali0n Date: Tue, 9 Mar 2021 10:37:51 +0100 Subject: [PATCH] docs: Improve documentation around linkage requirements The documentation around static linking in doc/libraries.md is improved. This is achieved using examples and explaning the requirements that arise from the use of constructor functions. Additionally, the documentation around the same subject is improved in doc/pkgconfig.md Signed-off-by: Dantali0n Change-Id: I3b11db441d14d2e8d792a22de2bd17fe5c2389fd Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/6798 Community-CI: Mellanox Build Bot Reviewed-by: Ben Walker Reviewed-by: Aleksey Marchuk Tested-by: SPDK CI Jenkins --- doc/libraries.md | 20 ++++++++++++++++++++ doc/pkgconfig.md | 7 ++++--- 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/doc/libraries.md b/doc/libraries.md index a1c4dc36d..6bee7d882 100644 --- a/doc/libraries.md +++ b/doc/libraries.md @@ -191,3 +191,23 @@ shim/implementation library system. # two libraries gcc -o my_app ./my_app.c -lspdk -lcustom_env_shim -lcustom_env_implementation ~~~ + +# SPDK Static Objects {#static_objects} + +SPDK static objects are compiled by default even when no parameters are supplied to the build system. +Unlike SPDK shared objects, the filename does not contain any versioning semantics. Linking against +static objects is similar to shared objects but will always require the use of `-Wl,--whole-archive` +as argument. This is due to the use of constructor functions in SPDK such as those to register +NVMe transports. + +Due to the lack of versioning semantics, it is not recommended to install static libraries system wide. +Instead the path to these static libraries should be added as argument at compile time using +`-L/path/to/static/libs`. The use of static objects instead of shared objects can also be forced +through `-Wl,-Bsatic`, otherwise some compilers might prefer to use the shared objects if both +are available. + +~~~{.sh} + gcc -o my_app ./my_app.c -L/path/to/static/libs -Wl,--whole-archive -Wl,-Bstatic -lpassthru_external + -lspdk_event_bdev -lspdk_bdev -lspdk_bdev_malloc -lspdk_log -lspdk_thread -lspdk_util -lspdk_event + -lspdk_env_dpdk -Wl,--no-whole-archive -Wl,-Bdynamic -pthread -ldpdk +~~~ diff --git a/doc/pkgconfig.md b/doc/pkgconfig.md index 5cde70a17..181b2ea60 100644 --- a/doc/pkgconfig.md +++ b/doc/pkgconfig.md @@ -28,9 +28,10 @@ PKG_CONFIG_PATH=/path/to/spdk/build/lib/pkgconfig pkg-config --libs spdk_syslibs Note that SPDK libraries use constructor functions liberally, so you must surround the library list with extra linker options to ensure these functions are not dropped -from the resulting application binary. Here is an example Makefile snippet that -shows how to use pkg-config to link an application that uses the SPDK nvme shared -library: +from the resulting application binary. With shared libraries this is achieved through +the `-Wl,--no-as-needed` parameters while with static libraries `-Wl,--whole-archive` +is used. Here is an example Makefile snippet that shows how to use pkg-config to link +an application that uses the SPDK nvme shared library: ~~~ PKG_CONFIG_PATH = $(SPDK_DIR)/build/lib/pkgconfig