ivampiresp/Spdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Improve documentation around linkage requirements

Browse Source 
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>
This commit is contained in:
Dantali0n 2021-03-09 10:37:51 +01:00 committed by Tomasz Zawadzki
parent 360fd2cc5a
commit 1b837766f0
2 changed files with 24 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
doc/libraries.md
View File

@ -191,3 +191,23 @@ shim/implementation library system.
# two libraries # two libraries
gcc -o my_app ./my_app.c -lspdk -lcustom_env_shim -lcustom_env_implementation 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
~~~

7
doc/pkgconfig.md
View File

@ -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 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 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 from the resulting application binary. With shared libraries this is achieved through
shows how to use pkg-config to link an application that uses the SPDK nvme shared the `-Wl,--no-as-needed` parameters while with static libraries `-Wl,--whole-archive`
library: 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 PKG_CONFIG_PATH = $(SPDK_DIR)/build/lib/pkgconfig