Commit 6f931ba7 authored by Jim Harris's avatar Jim Harris Committed by Tomasz Zawadzki
Browse files

doc: fix bugs in pkg-config documentation 



Our pkg-config documentation has a couple of bugs:

1) It recommends using separate variables for results from spdk_nvme
   and spdk_env_dpdk. But both of these generate '-lspdk_util' and
   on a static build that ends up with multiple definition link errors.
2) DPDK by default builds both static and shared libraries. The linker
   will prefer shared instead of static if it finds both. But the DPDK
   build directory is not part of LD_LIBRARY_PATH by default.

So fix the docs with the following two changes:

1) Recommend just one pkg-config invocation, passing spdk_nvme and
   spdk_env_dpdk together.
2) Wrap the libraries in the LDFLAGS with -Wl,-Bstatic and -Wl,-Bdynamic.
   This will signal the linker to prefer static instead of shared libraries
   if it finds both, just for those libraries between the two added
   directives.

While here, also add a missing --static argument to the example for
spdk_syslibs.

Fixes issue #3177.

Signed-off-by: default avatarJim Harris <jim.harris@samsung.com>
Change-Id: Ibf1f2f06560e77738cfa040c38346ec0867d5b4b
Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/20558


Reviewed-by: default avatarTomasz Zawadzki <tomasz.zawadzki@intel.com>
Reviewed-by: default avatarKonrad Sztyber <konrad.sztyber@intel.com>
Tested-by: default avatarSPDK CI Jenkins <sys_sgci@intel.com>
parent 3a501549

doc/pkgconfig.md

+12 −18
Original line number Diff line number Diff line
@@ -6,24 +6,18 @@ 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:

to get the list of required SPDK libraries, and the DPDK libraries for the

DPDK-based environment layer:



~~~bash

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:



~~~bash

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

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

~~~



When linking with static libraries, the dependent system libraries must also be

specified. To get the list of required system libraries:



~~~bash

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

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

~~~



Note that SPDK libraries use constructor functions liberally, so you must surround
@@ -35,22 +29,22 @@ an application that uses the SPDK nvme shared library: 


~~~bash

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

SPDK_LIB := $(shell PKG_CONFIG_PATH="$(PKG_CONFIG_PATH)" pkg-config --libs spdk_nvme spdk_env_dpdk



app:

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

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

~~~



If using the SPDK nvme static library:

If using the SPDK nvme static library, you should also wrap with `-Wl,-Bstatic` and

`-Wl,-Bdynamic`. DPDK by default builds both shared and static libraries - these

linker args will ensure that linker uses the static versions:



~~~bash

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

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

	$(CC) -o app app.o -pthread -Wl,--whole-archive -Wl,-Bstatic $(SPDK_LIB) \

		-Wl,-Bdynamic -Wl,--no-whole-archive $(SYS_LIB)

~~~