docs: Updates for Linux loader /usr/local search paths.

Change-Id: I899c55815ef51efd141c22a5ce37b0800c2a8430

diff --git a/BUILD.md b/BUILD.md
index dc5e8d6..00f6e4b 100644 (file)
--- 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 (file)
--- 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.