(Linux) LD_LIBRARY_PATH not mentioned in capture docs

[MarkY-LunarG]

I saw an issue on discord that a person didn't know they needed to point to the .so files with LD_LIBRARY_PATH. Should probably add a little documentation about that just because not everyone who uses this will be an experienced Linux user.

[bradgrantham-lunarg]

Can I get more clarification on this? Normally my understanding is that a user on Linux only needs to set VK_LAYER_PATH and VK_INSTANCE_LAYERS. What DSO do they need to set LD_LIBRARY_PATH to find?

[MarkY-LunarG]

The library .so for the GfxReconstruct layer. The user was building it himself using this repo, but the SO wasn't loaded because he didn't add it. I would just add a mention that finding the .so may require adding it to the LD_LIBRARY_PATH search.

[bradgrantham-lunarg]

To follow up, it sounds like there are three typical use-cases to cover:

• User installs the SDK including GFXR and uses the setup script to set up LD_LIBRARY_PATH. This should work now and is documented in USAGE_desktop.md.
• User installs GFXR with their distribution and distribution handles putting it in the right place. That's out of the scope of the documentation in GFXR to discuss in detail but is mentioned in passing.
• User uses VK_LAYER_PATH pointing at the directory containing the built JSON and DSO within GFXR. This should work now, but is mostly done by skilled practitioners. That's documented in USAGE_desktop.md as well.

We can put more documentation in USAGE_desktop.md on LD_LIBRARY_PATH but I feel like it could be slightly misleading unless stated very clearly.

So I'm tempted to "wontfix" unless we can learn more about what happened to force the user into a place where they needed to set LD_LIBRARY_PATH.

[bradgrantham-lunarg]

@MarkY-LunarG Do you want to push on this issue or can I close this?

[MarkY-LunarG]

@bradgrantham-lunarg , I can't decide. I still think this is something inexperienced people will stumble with. But I don't know that adding it to USAGE_desktop.md would be any different. This is kind of a corner case where someone is building it themselves, and probably choosing the "install" option without actually installing it. That would cause the library to not be relatively referenced in the JSON file. Is there any indication in our documentation that people should choose the non-install option when building the repo if they don't actually want to install it or put it in a package?

[bradgrantham-lunarg]

@MarkY-LunarG What's "the install option"?

Okay, what I really needed here were steps for reproducing the issue. In the future, please provide that if you can.

I took a minute to build Release gfxreconstruct @ 1e1853aea10c43232c64d8cd572ff1d4b98a7688 (dev as of today) under Ubuntu 20.04 a la BUILD.md:

grantham@grantham-VirtualBox:~/trees/gfxreconstruct$ python3 scripts/build.py --skip-check-code-style --skip-tests
-- Vulkan Header = /home/grantham/trees/gfxreconstruct/external/Vulkan-Headers/include/vulkan/vulkan_core.h
-- Detected Vulkan Version 1.2.189
-- Configuring done
-- Generating done
-- Build files have been written to: /home/grantham/trees/gfxreconstruct/build/linux/x64/cmake_output
[ 19%] Built target gfxrecon_util
[...]
[100%] Built target gfxrecon.py
-- Install configuration: "Release"
-- Installing: /home/grantham/trees/gfxreconstruct/build/linux/x64/output/lib/libVkLayer_gfxreconstruct.so
-- Installing: /home/grantham/trees/gfxreconstruct/build/linux/x64/output/share/vulkan/explicit_layer.d/VkLayer_gfxreconstruct.json
[...]

Looking at the default installation location for scripts/build.py, I understand why a new user would be confused. The .so is not put in the same directory as the manifest.

If a user was to run the commands later in BUILD.md for running cmake by hand, that user would probably succeed, because the install directory is /usr/local/lib, and on Ubuntu that's part of the ldconfig cache.

So it looks like we do need something in BUILD.md that tells a user either:

• Do it through cmakeas described later in the doc, then things will probably go in the right place (as cmake understands it)
• Add the DSO directory to LD_LIBRARY_PATH, like on Linux x64 from the gfxrecon top that would be export $LD_LIBRARY_PATH=$PWD/build/linux/x64/output/lib:$LD_LIBRARY_PATH.
• Use scripts/build.py but set --install-dir to something appropriate of the user's choosing, like $HOME/gfxrecon-install, then add that plus /lib to LD_LIBRARY_PATH, like export $LD_LIBRARY_PATH=$HOME/gfxrecon-install/lib:$LD_LIBRARY_PATH.