From 70fd6144883aa585977363bc6d28005f38ca3564 Mon Sep 17 00:00:00 2001 From: Karl Schultz Date: Mon, 31 Oct 2016 15:58:21 -0600 Subject: [PATCH] docs: Updates for Linux loader /usr/local search paths. Change-Id: I899c55815ef51efd141c22a5ce37b0800c2a8430 --- BUILD.md | 35 ++++++++++++++++++++--- loader/LoaderAndLayerInterface.md | 58 ++++++++++++++++++++++++++++----------- 2 files changed, 73 insertions(+), 20 deletions(-) diff --git a/BUILD.md b/BUILD.md index dc5e8d6..00f6e4b 100644 --- a/BUILD.md +++ b/BUILD.md @@ -78,7 +78,7 @@ This command installs files to: * `/usr/local/include/vulkan`: Vulkan include files * `/usr/local/lib`: Vulkan loader and layers shared objects * `/usr/local/bin`: vulkaninfo application -* `/etc/vulkan/explicit_layer.d`: Layer JSON files +* `/usr/local/etc/vulkan/explicit_layer.d`: Layer JSON files You may need to run `ldconfig` in order to refresh the system loader search cache on some Linux systems. @@ -89,8 +89,35 @@ You can easily remove the installed files with: cat install_manifest.txt | sudo xargs rm ``` -See the CMake documentation for details on using `DESTDIR` and `CMAKE_INSTALL_PREFIX` to customize -your installation location. +You can further customize the installation location by setting additional CMake variables +to override their defaults. +For example, if you would like to install to `/tmp/build` instead of `/usr/local`, specify: + +``` +-DCMAKE_INSTALL_PREFIX=/tmp/build +-DDEST_DIR=/tmp/build +``` + +on your CMake command line and run `make install` as before. +The install step places the files in `/tmp/build`. + +Using the `CMAKE_INSTALL_PREFIX` to customize the install location also modifies the +loader search paths to include searching for layers in the specified install location. +In this example, setting `CMAKE_INSTALL_PREFIX` to `/tmp/build` causes the loader to +search `/tmp/build/etc/vulkan/explicit_layer.d` and `/tmp/build/share/vulkan/explicit_layer.d` +for the layer JSON files. +The loader also searches the "standard" system locations of `/etc/vulkan/explicit_layer.d` +and `/usr/share/vulkan/explicit_layer.d` after searching the two locations under `/tmp/build`. + +You can further customize the installation directories by using the CMake variables +`CMAKE_INSTALL_SYSCONFDIR` to rename the `etc` directory and `CMAKE_INSTALL_DATADIR` +to rename the `share` directory. + +See the CMake documentation for more details on using these variables +to further customize your installation. + +Also see the `LoaderAndLayerInterface` document in the `loader` folder in this repository for more +information about loader operation. Note that some executables in this repository (e.g., `cube`) use the "rpath" linker directive to load the Vulkan loader from the build directory, `dbuild` in this example. @@ -99,7 +126,7 @@ still use the loader from the build directory. ## Validation Test -The test executables can be found in the dbuild/tests directory. +The test executables can be found in the dbuild/tests directory. Some of the tests that are available: - vk\_layer\_validation\_tests: Test Vulkan layers. diff --git a/loader/LoaderAndLayerInterface.md b/loader/LoaderAndLayerInterface.md index 424fc31..2bffd08 100644 --- a/loader/LoaderAndLayerInterface.md +++ b/loader/LoaderAndLayerInterface.md @@ -205,7 +205,6 @@ layer VK\_LAYER\_LUNARG\_parameter\_validation on Windows or Linux is as follows ``` > $ export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_parameter_validation - ``` #### Implicit vs Explicit Layers @@ -465,9 +464,14 @@ Notice the semi-colon between "C:\\Windows\\System32\\vendorc\_icd.json" and In order to find properly-installed ICDs, the Vulkan loader will scan the files in the following Linux directories: -/usr/share/vulkan/icd.d -/etc/vulkan/icd.d -$HOME/.local/share/vulkan/icd.d + /usr/local/etc/vulkan/icd.d + /usr/local/share/vulkan/icd.d + /etc/vulkan/icd.d + /usr/share/vulkan/icd.d + $HOME/.local/share/vulkan/icd.d + +The "/usr/local/*" directories can be configured to be other directories at build time. +See the `BUILD.md` file in this repository for more information. Where $HOME is the current home directory of the application's user id; this path will be ignored for suid programs. @@ -508,10 +512,15 @@ same shared library). The "api\_version" specifies the major.minor.patch version number of the Vulkan API that the shared library (referenced by "library\_path") was built with. -The "/usr/share/vulkan/icd.d" directory is for ICDs that are installed from -Linux-distribution-provided packages. The "/etc/vulkan/icd.d" directory is for +The "/usr/local/etc/vulkan/icd.d" and "/usr/local/share/vulkan/icd.d" +directories are for locally-built ICDs. + +The "/etc/vulkan/icd.d" directory is for ICDs that are installed from non-Linux-distribution-provided packages. +The "/usr/share/vulkan/icd.d" directory is for ICDs that are installed from +Linux-distribution-provided packages. + There are no rules about the name of the text files (except the .json suffix). There are no rules about the name of the ICD shared library files. For example, @@ -544,7 +553,13 @@ other words, only the ICDs listed in "VK\_ICD\_FILENAMES" will be used. The "VK\_ICD\_FILENAMES" environment variable is a colon-separated list of ICD manifest files, containing the following: -- A filename (e.g. "libvkicd.json") in the "/usr/share/vulkan/icd.d", "/etc/vulkan/icd.d" "$HOME/.local/share/vulkan/icd.d" directories +- A filename (e.g. "libvkicd.json") in the +"/usr/local/etc/vulkan/icd.d", +"/usr/local/share/vulkan/icd.d", +"/etc/vulkan/icd.d", +"/usr/share/vulkan/icd.d", +"$HOME/.local/share/vulkan/icd.d" +directories - A full pathname (e.g. "/my\_build/my\_icd.json") @@ -962,12 +977,19 @@ library file may contain multiple layers/extensions (perhaps even an ICD). The Vulkan loader will scan the files in the following Linux directories: -/usr/share/vulkan/explicit\_layer.d -/usr/share/vulkan/implicit\_layer.d -/etc/vulkan/explicit\_layer.d -/etc/vulkan/implicit\_layer.d -\$HOME/.local/share/vulkan/explicit\_layer.d -\$HOME/.local/share/vulkan/implicit\_layer.d + /usr/local/etc/vulkan/explicit_layer.d + /usr/local/etc/vulkan/implicit_layer.d + /usr/local/share/vulkan/explicit_layer.d + /usr/local/share/vulkan/implicit_layer.d + /etc/vulkan/explicit_layer.d + /etc/vulkan/implicit_layer.d + /usr/share/vulkan/explicit_layer.d + /usr/share/vulkan/implicit_layer.d + $HOME/.local/share/vulkan/explicit_layer.d + $HOME/.local/share/vulkan/implicit_layer.d + +The "/usr/local/*" directories can be configured to be other directories at build time. +See the `BUILD.md` file in this repository for more information. Where $HOME is the current home directory of the application's user id; this path will be ignored for suid programs. @@ -983,11 +1005,15 @@ Implicit layers are enabled automatically, whereas explicit layers must be enabled explicitly. What distinguishes a layer as implicit or explicit is by which directory its layer information file exists in. -The "/usr/share/vulkan/\*\_layer.d" directories are for layers that are -installed from Linux-distribution-provided packages. The -"/etc/vulkan/\*\_layer.d" directories are for layers that are installed from +The "/usr/local/etc/vulkan/\*\_layer.d" and "/usr/local/share/vulkan/\*\_layer.d" +directories are for layers that are installed from locally-built sources. + +The "/etc/vulkan/\*\_layer.d" directories are for layers that are installed from non-Linux-distribution-provided packages. +The "/usr/share/vulkan/\*\_layer.d" directories are for layers that are +installed from Linux-distribution-provided packages. + This manifest file is in the JSON format as shown in the following example. See the section [Layer Library Manifest File](#LayerLibraryManifestFile) for more information about each of the nodes in the JSON file. -- 2.7.4