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