Add spirv-lesspipe.sh

Idea suggested by @steve-lunarg in issue 359.

diff --git a/CHANGES b/CHANGES
index 9406356..be8fcde 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -7,6 +7,7 @@ v2016.3-dev 2016-08-11
  - Add spirv-cfg, an experimental tool to dump the control flow graph
    as a GraphiViz "dot" graph
  - Add optimization pass: Eliminate dead constants.
+ - Add spirv-lesspipe.sh filter utility
  - Fixes issues:
    #288: Check def-use dominance rules for OpPhi (variable,parent) operands
    #340: Avoid race on mkdir during build

diff --git a/README.md b/README.md
index 3362099..7008a69 100644 (file)
--- a/README.md
+++ b/README.md
@@ -234,6 +234,26 @@ This is experimental.
 * `spirv-cfg` - the control flow graph dumper
   * `<spirv-dir>/tools/cfg`
 
+### Utility filters
+
+* `spirv-lesspipe.sh` - Automatically disassembles `.spv` binary files for the
+  `less` program, on compatible systems.  For example, set the `LESSOPEN`
+  environment variable as follows, assuming both `spirv-lesspipe.sh` and
+  `spirv-dis` are on your executable search path:
+  ```
+   export LESSOPEN='| spirv-lesspipe.sh "%s"'
+  ```
+  Then you page through a disassembled module as follows:
+  ```
+  less foo.spv
+  ```
+  * The `spirv-lesspipe.sh` script will pass through any extra arguments to
+    `spirv-dis`.  So, for example, you can turn off colours and friendly ID
+    naming as follows:
+    ```
+    export LESSOPEN='| spirv-lesspipe.sh "%s" --no-color --raw-id'
+    ```
+
 ### Tests
 
 Tests are only built when googletest is found.

diff --git a/tools/CMakeLists.txt b/tools/CMakeLists.txt
index dbc218b..1e2ee69 100644 (file)
--- a/tools/CMakeLists.txt
+++ b/tools/CMakeLists.txt
@@ -24,6 +24,8 @@
 # TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 # MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
 
+add_subdirectory(lesspipe)
+
 # Add a SPIR-V Tools command line tool. Signature:
 #   add_spvtools_tool(
 #     TARGET target_name

diff --git a/tools/lesspipe/CMakeLists.txt b/tools/lesspipe/CMakeLists.txt
new file mode 100644 (file)
index 0000000..6d30db1
--- /dev/null
+++ b/tools/lesspipe/CMakeLists.txt
@@ -0,0 +1,38 @@
+# Copyright (c) 2016 Google Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and/or associated documentation files (the
+# "Materials"), to deal in the Materials without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Materials, and to
+# permit persons to whom the Materials are furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Materials.
+#
+# MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS
+# KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS
+# SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT
+#    https://www.khronos.org/registry/
+#
+# THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
+
+# Install a script for use with the LESSOPEN of less(1).
+# For example, after installation into /usr/local do:
+#    export LESSOPEN='|/usr/local/bin "%s"'
+#    less -R foo.spv
+#
+# See https://github.com/KhronosGroup/SPIRV-Tools/issues/359
+
+# The script will be installed with everyone having read and execute
+# permissions.
+# We have a .sh extension because Windows users often configure
+# executable settings via filename extension.
+install(PROGRAMS spirv-lesspipe.sh DESTINATION bin)

diff --git a/tools/lesspipe/spirv-lesspipe.sh b/tools/lesspipe/spirv-lesspipe.sh
new file mode 100644 (file)
index 0000000..05831d1
--- /dev/null
+++ b/tools/lesspipe/spirv-lesspipe.sh
@@ -0,0 +1,40 @@
+#!/bin/bash
+
+# Copyright (c) 2016 The Khronos Group Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and/or associated documentation files (the
+# "Materials"), to deal in the Materials without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Materials, and to
+# permit persons to whom the Materials are furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Materials.
+#
+# MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS
+# KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS
+# SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT
+#    https://www.khronos.org/registry/
+#
+# THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
+
+# A script for automatically disassembling a .spv file
+# for less(1).  This assumes spirv-dis is on our PATH.
+#
+# See https://github.com/KhronosGroup/SPIRV-Tools/issues/359
+
+case "$1" in
+    *.spv) spirv-dis "$@" 2>/dev/null;;
+    *) exit 1;;
+esac
+
+exit $?
+