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