README.md

   1 Also see the Khronos landing page for glslang as a reference front end:
   2
   3 https://www.khronos.org/opengles/sdk/tools/Reference-Compiler/
   4
   5 The above page includes where to get binaries, and is kept up to date
   6 regarding the feature level of glslang.
   7
   8 glslang
   9 =======
  10
  11 [![Build Status](https://travis-ci.org/KhronosGroup/glslang.svg?branch=master)](https://travis-ci.org/KhronosGroup/glslang)
  12 [![Build status](https://ci.appveyor.com/api/projects/status/q6fi9cb0qnhkla68/branch/master?svg=true)](https://ci.appveyor.com/project/Khronoswebmaster/glslang/branch/master)
  13
  14 An OpenGL and OpenGL ES shader front end and validator.
  15
  16 There are several components:
  17
  18 1. A GLSL/ESSL front-end for reference validation and translation of GLSL/ESSL into an AST.
  19
  20 2. An HLSL front-end for translation of a broad generic HLL into the AST. See [issue 362](https://github.com/KhronosGroup/glslang/issues/362) and [issue 701](https://github.com/KhronosGroup/glslang/issues/701) for current status.
  21
  22 3. A SPIR-V back end for translating the AST to SPIR-V.
  23
  24 4. A standalone wrapper, `glslangValidator`, that can be used as a command-line tool for the above.
  25
  26 How to add a feature protected by a version/extension/stage/profile:  See the
  27 comment in `glslang/MachineIndependent/Versions.cpp`.
  28
  29 Tasks waiting to be done are documented as GitHub issues.
  30
  31 Execution of Standalone Wrapper
  32 -------------------------------
  33
  34 To use the standalone binary form, execute `glslangValidator`, and it will print
  35 a usage statement.  Basic operation is to give it a file containing a shader,
  36 and it will print out warnings/errors and optionally an AST.
  37
  38 The applied stage-specific rules are based on the file extension:
  39 * `.vert` for a vertex shader
  40 * `.tesc` for a tessellation control shader
  41 * `.tese` for a tessellation evaluation shader
  42 * `.geom` for a geometry shader
  43 * `.frag` for a fragment shader
  44 * `.comp` for a compute shader
  45
  46 There is also a non-shader extension
  47 * `.conf` for a configuration file of limits, see usage statement for example
  48
  49 Building
  50 --------
  51
  52 Instead of building manually, you can also download the binaries for your
  53 platform directly from the [master-tot release][master-tot-release] on GitHub.
  54 Those binaries are automatically uploaded by the buildbots after successful
  55 testing and they always reflect the current top of the tree of the master
  56 branch.
  57
  58 ### Dependencies
  59
  60 * [CMake][cmake]: for generating compilation targets.
  61 * [Python 2.7][python]: for executing SPIRV-Tools scripts. (Optional if not using SPIRV-Tools.)
  62 * [bison][bison]: _optional_, but needed when changing the grammar (glslang.y).
  63 * [googletest][googletest]: _optional_, but should use if making any changes to glslang.
  64
  65 ### Build steps
  66
  67 #### 1) Check-Out this project
  68
  69 ```bash
  70 cd <parent of where you want glslang to be>
  71 # If using SSH
  72 git clone git@github.com:KhronosGroup/glslang.git
  73 # Or if using HTTPS
  74 git clone https://github.com/KhronosGroup/glslang.git
  75 ```
  76
  77 #### 2) Check-Out External Projects
  78
  79 ```bash
  80 cd <the directory glslang was cloned to, "External" will be a subdirectory>
  81 git clone https://github.com/google/googletest.git External/googletest
  82 ```
  83
  84 If you wish to assure that SPIR-V generated from HLSL is legal for Vulkan,
  85 or wish to invoke -Os to reduce SPIR-V size from HLSL or GLSL, install
  86 spirv-tools with this:
  87
  88 ```bash
  89 ./update_glslang_sources.py
  90 ```
  91
  92 For running the CMake GUI or Visual Studio with python dependencies, you will,
  93 in addition to python within the cygwin environment, need a Windows [python][python]
  94 installation, including selecting the `PATH` update.
  95
  96 #### 3) Configure
  97
  98 Assume the source directory is `$SOURCE_DIR` and
  99 the build directory is `$BUILD_DIR`:
 100
 101 For building on Linux (assuming using the Ninja generator):
 102
 103 ```bash
 104 cd $BUILD_DIR
 105
 106 cmake -GNinja -DCMAKE_BUILD_TYPE={Debug|Release|RelWithDebInfo} \
 107       -DCMAKE_INSTALL_PREFIX=`pwd`/install $SOURCE_DIR
 108 ```
 109
 110 For building on Windows:
 111
 112 ```bash
 113 cmake $SOURCE_DIR -DCMAKE_INSTALL_PREFIX=`pwd`/install
 114 # The CMAKE_INSTALL_PREFIX part is for testing (explained later).
 115 ```
 116
 117 The CMake GUI also works for Windows (version 3.4.1 tested).
 118
 119 #### 4) Build and Install
 120
 121 ```bash
 122 # for Linux:
 123 ninja install
 124
 125 # for Windows:
 126 cmake --build . --config {Release|Debug|MinSizeRel|RelWithDebInfo} \
 127       --target install
 128 ```
 129
 130 If using MSVC, after running CMake to configure, use the
 131 Configuration Manager to check the `INSTALL` project.
 132
 133 ### If you need to change the GLSL grammar
 134
 135 The grammar in `glslang/MachineIndependent/glslang.y` has to be recompiled with
 136 bison if it changes, the output files are committed to the repo to avoid every
 137 developer needing to have bison configured to compile the project when grammar
 138 changes are quite infrequent. For windows you can get binaries from
 139 [GnuWin32][bison-gnu-win32].
 140
 141 The command to rebuild is:
 142
 143 ```bash
 144 bison --defines=MachineIndependent/glslang_tab.cpp.h
 145       -t MachineIndependent/glslang.y
 146       -o MachineIndependent/glslang_tab.cpp
 147 ```
 148
 149 The above command is also available in the bash script at
 150 `glslang/updateGrammar`.
 151
 152 Testing
 153 -------
 154
 155 Right now, there are two test harnesses existing in glslang: one is [Google
 156 Test](gtests/), one is the [`runtests` script](Test/runtests). The former
 157 runs unit tests and single-shader single-threaded integration tests, while
 158 the latter runs multiple-shader linking tests and multi-threaded tests.
 159
 160 ### Running tests
 161
 162 The [`runtests` script](Test/runtests) requires compiled binaries to be
 163 installed into `$BUILD_DIR/install`. Please make sure you have supplied the
 164 correct configuration to CMake (using `-DCMAKE_INSTALL_PREFIX`) when building;
 165 otherwise, you may want to modify the path in the `runtests` script.
 166
 167 Running Google Test-backed tests:
 168
 169 ```bash
 170 cd $BUILD_DIR
 171
 172 # for Linux:
 173 ctest
 174
 175 # for Windows:
 176 ctest -C {Debug|Release|RelWithDebInfo|MinSizeRel}
 177
 178 # or, run the test binary directly
 179 # (which gives more fine-grained control like filtering):
 180 <dir-to-glslangtests-in-build-dir>/glslangtests
 181 ```
 182
 183 Running `runtests` script-backed tests:
 184
 185 ```bash
 186 cd $SOURCE_DIR/Test && ./runtests
 187 ```
 188
 189 ### Contributing tests
 190
 191 Test results should always be included with a pull request that modifies
 192 functionality.
 193
 194 If you are writing unit tests, please use the Google Test framework and
 195 place the tests under the `gtests/` directory.
 196
 197 Integration tests are placed in the `Test/` directory. It contains test input
 198 and a subdirectory `baseResults/` that contains the expected results of the
 199 tests.  Both the tests and `baseResults/` are under source-code control.
 200
 201 Google Test runs those integration tests by reading the test input, compiling
 202 them, and then compare against the expected results in `baseResults/`. The
 203 integration tests to run via Google Test is registered in various
 204 `gtests/*.FromFile.cpp` source files. `glslangtests` provides a command-line
 205 option `--update-mode`, which, if supplied, will overwrite the golden files
 206 under the `baseResults/` directory with real output from that invocation.
 207 For more information, please check `gtests/` directory's
 208 [README](gtests/README.md).
 209
 210 For the `runtests` script, it will generate current results in the
 211 `localResults/` directory and `diff` them against the `baseResults/`.
 212 When you want to update the tracked test results, they need to be
 213 copied from `localResults/` to `baseResults/`.  This can be done by
 214 the `bump` shell script.
 215
 216 You can add your own private list of tests, not tracked publicly, by using
 217 `localtestlist` to list non-tracked tests.  This is automatically read
 218 by `runtests` and included in the `diff` and `bump` process.
 219
 220 Programmatic Interfaces
 221 -----------------------
 222
 223 Another piece of software can programmatically translate shaders to an AST
 224 using one of two different interfaces:
 225 * A new C++ class-oriented interface, or
 226 * The original C functional interface
 227
 228 The `main()` in `StandAlone/StandAlone.cpp` shows examples using both styles.
 229
 230 ### C++ Class Interface (new, preferred)
 231
 232 This interface is in roughly the last 1/3 of `ShaderLang.h`.  It is in the
 233 glslang namespace and contains the following.
 234
 235 ```cxx
 236 const char* GetEsslVersionString();
 237 const char* GetGlslVersionString();
 238 bool InitializeProcess();
 239 void FinalizeProcess();
 240
 241 class TShader
 242     bool parse(...);
 243     void setStrings(...);
 244     const char* getInfoLog();
 245
 246 class TProgram
 247     void addShader(...);
 248     bool link(...);
 249     const char* getInfoLog();
 250     Reflection queries
 251 ```
 252
 253 See `ShaderLang.h` and the usage of it in `StandAlone/StandAlone.cpp` for more
 254 details.
 255
 256 ### C Functional Interface (orignal)
 257
 258 This interface is in roughly the first 2/3 of `ShaderLang.h`, and referred to
 259 as the `Sh*()` interface, as all the entry points start `Sh`.
 260
 261 The `Sh*()` interface takes a "compiler" call-back object, which it calls after
 262 building call back that is passed the AST and can then execute a backend on it.
 263
 264 The following is a simplified resulting run-time call stack:
 265
 266 ```c
 267 ShCompile(shader, compiler) -> compiler(AST) -> <back end>
 268 ```
 269
 270 In practice, `ShCompile()` takes shader strings, default version, and
 271 warning/error and other options for controlling compilation.
 272
 273 Basic Internal Operation
 274 ------------------------
 275
 276 * Initial lexical analysis is done by the preprocessor in
 277   `MachineIndependent/Preprocessor`, and then refined by a GLSL scanner
 278   in `MachineIndependent/Scan.cpp`.  There is currently no use of flex.
 279
 280 * Code is parsed using bison on `MachineIndependent/glslang.y` with the
 281   aid of a symbol table and an AST.  The symbol table is not passed on to
 282   the back-end; the intermediate representation stands on its own.
 283   The tree is built by the grammar productions, many of which are
 284   offloaded into `ParseHelper.cpp`, and by `Intermediate.cpp`.
 285
 286 * The intermediate representation is very high-level, and represented
 287   as an in-memory tree.   This serves to lose no information from the
 288   original program, and to have efficient transfer of the result from
 289   parsing to the back-end.  In the AST, constants are propogated and
 290   folded, and a very small amount of dead code is eliminated.
 291
 292   To aid linking and reflection, the last top-level branch in the AST
 293   lists all global symbols.
 294
 295 * The primary algorithm of the back-end compiler is to traverse the
 296   tree (high-level intermediate representation), and create an internal
 297   object code representation.  There is an example of how to do this
 298   in `MachineIndependent/intermOut.cpp`.
 299
 300 * Reduction of the tree to a linear byte-code style low-level intermediate
 301   representation is likely a good way to generate fully optimized code.
 302
 303 * There is currently some dead old-style linker-type code still lying around.
 304
 305 * Memory pool: parsing uses types derived from C++ `std` types, using a
 306   custom allocator that puts them in a memory pool.  This makes allocation
 307   of individual container/contents just few cycles and deallocation free.
 308   This pool is popped after the AST is made and processed.
 309
 310   The use is simple: if you are going to call `new`, there are three cases:
 311
 312   - the object comes from the pool (its base class has the macro
 313     `POOL_ALLOCATOR_NEW_DELETE` in it) and you do not have to call `delete`
 314
 315   - it is a `TString`, in which case call `NewPoolTString()`, which gets
 316     it from the pool, and there is no corresponding `delete`
 317
 318   - the object does not come from the pool, and you have to do normal
 319     C++ memory management of what you `new`
 320
 321
 322 [cmake]: https://cmake.org/
 323 [python]: https://www.python.org/
 324 [bison]: https://www.gnu.org/software/bison/
 325 [googletest]: https://github.com/google/googletest
 326 [bison-gnu-win32]: http://gnuwin32.sourceforge.net/packages/bison.htm
 327 [master-tot-release]: https://github.com/KhronosGroup/glslang/releases/tag/master-tot