Dantali0n 1b837766f0 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 <info@dantalion.nl>
Change-Id: I3b11db441d14d2e8d792a22de2bd17fe5c2389fd
Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/6798
Community-CI: Mellanox Build Bot
Reviewed-by: Ben Walker <benjamin.walker@intel.com>
Reviewed-by: Aleksey Marchuk <alexeymar@mellanox.com>
Tested-by: SPDK CI Jenkins <sys_sgci@intel.com>

2021-03-18 14:37:46 +00:00

2.2 KiB

Raw Blame History

Linking SPDK applications with pkg-config

The SPDK build system generates pkg-config files to facilitate linking applications with the correct set of SPDK and DPDK libraries. Using pkg-config in your build system will ensure you do not need to make modifications when SPDK adds or modifies library dependencies.

If your application is using the SPDK nvme library, you would use the following to get the list of required SPDK libraries:

PKG_CONFIG_PATH=/path/to/spdk/build/lib/pkgconfig pkg-config --libs spdk_nvme

To get the list of required SPDK and DPDK libraries to use the DPDK-based environment layer:

PKG_CONFIG_PATH=/path/to/spdk/build/lib/pkgconfig pkg-config --libs spdk_env_dpdk

When linking with static libraries, the dependent system libraries must also be specified. To get the list of required system libraries:

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. 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
SPDK_LIB := $(shell PKG_CONFIG_PATH="$(PKG_CONFIG_PATH)" pkg-config --libs spdk_nvme
DPDK_LIB := $(shell PKG_CONFIG_PATH="$(PKG_CONFIG_PATH)" pkg-config --libs spdk_env_dpdk

app:
	$(CC) -o app app.o -pthread -Wl,--no-as-needed $(SPDK_LIB) $(DPDK_LIB) -Wl,--as-needed

If using the SPDK nvme static library:

PKG_CONFIG_PATH = $(SPDK_DIR)/build/lib/pkgconfig
SPDK_LIB := $(shell PKG_CONFIG_PATH="$(PKG_CONFIG_PATH)" pkg-config --libs spdk_nvme
DPDK_LIB := $(shell PKG_CONFIG_PATH="$(PKG_CONFIG_PATH)" pkg-config --libs spdk_env_dpdk
SYS_LIB := $(shell PKG_CONFIG_PATH="$(PKG_CONFIG_PATH)" pkg-config --libs --static spdk_syslibs

app:
	$(CC) -o app app.o -pthread -Wl,--whole-archive $(SPDK_LIB) $(DPDK_LIB) -Wl,--no-whole-archive \
		$(SYS_LIB)

2.2 KiB Raw Blame History

Linking SPDK applications with pkg-config

2.2 KiB

Raw Blame History