Commit 1b837766 authored by Dantali0n's avatar Dantali0n Committed by Tomasz Zawadzki
Browse files

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: default avatarDantali0n <info@dantalion.nl>
Change-Id: I3b11db441d14d2e8d792a22de2bd17fe5c2389fd
Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/6798


Community-CI: Mellanox Build Bot
Reviewed-by: default avatarBen Walker <benjamin.walker@intel.com>
Reviewed-by: default avatarAleksey Marchuk <alexeymar@mellanox.com>
Tested-by: default avatarSPDK CI Jenkins <sys_sgci@intel.com>
parent 360fd2cc

doc/libraries.md

+20 −0
Original line number Diff line number Diff line
@@ -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

~~~

doc/pkgconfig.md

+4 −3
Original line number Diff line number Diff line
@@ -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