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 Things left to do:  See `Todo.txt`
  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 The integration tests to run via the `runtests` script is registered
 181 via various `Test/test-*` text files and `Test/testlist`.
 182 When you want to update the tracked test results, they need to be
 183 copied from `localResults/` to `baseResults/`.  This can be done by
 184 the `bump` shell script.
 185
 186 The list of files tested comes from `testlist`, and lists input shaders
 187 in this directory, which must all be public for this to work.  However,
 188 you can add your own private list of tests, not tracked here, by using
 189 `localtestlist` to list non-tracked tests.  This is automatically read
 190 by `runtests` and included in the `diff` and `bump` process.
 191
 192 Programmatic Interfaces
 193 -----------------------
 194
 195 Another piece of software can programmatically translate shaders to an AST
 196 using one of two different interfaces:
 197 * A new C++ class-oriented interface, or
 198 * The original C functional interface
 199
 200 The `main()` in `StandAlone/StandAlone.cpp` shows examples using both styles.
 201
 202 ### C++ Class Interface (new, preferred)
 203
 204 This interface is in roughly the last 1/3 of `ShaderLang.h`.  It is in the
 205 glslang namespace and contains the following.
 206
 207 ```cxx
 208 const char* GetEsslVersionString();
 209 const char* GetGlslVersionString();
 210 bool InitializeProcess();
 211 void FinalizeProcess();
 212
 213 class TShader
 214     bool parse(...);
 215     void setStrings(...);
 216     const char* getInfoLog();
 217
 218 class TProgram
 219     void addShader(...);
 220     bool link(...);
 221     const char* getInfoLog();
 222     Reflection queries
 223 ```
 224
 225 See `ShaderLang.h` and the usage of it in `StandAlone/StandAlone.cpp` for more
 226 details.
 227
 228 ### C Functional Interface (orignal)
 229
 230 This interface is in roughly the first 2/3 of `ShaderLang.h`, and referred to
 231 as the `Sh*()` interface, as all the entry points start `Sh`.
 232
 233 The `Sh*()` interface takes a "compiler" call-back object, which it calls after
 234 building call back that is passed the AST and can then execute a backend on it.
 235
 236 The following is a simplified resulting run-time call stack:
 237
 238 ```c
 239 ShCompile(shader, compiler) -> compiler(AST) -> <back end>
 240 ```
 241
 242 In practice, `ShCompile()` takes shader strings, default version, and
 243 warning/error and other options for controlling compilation.
 244
 245 Basic Internal Operation
 246 ------------------------
 247
 248 * Initial lexical analysis is done by the preprocessor in
 249   `MachineIndependent/Preprocessor`, and then refined by a GLSL scanner
 250   in `MachineIndependent/Scan.cpp`.  There is currently no use of flex.
 251
 252 * Code is parsed using bison on `MachineIndependent/glslang.y` with the
 253   aid of a symbol table and an AST.  The symbol table is not passed on to
 254   the back-end; the intermediate representation stands on its own.
 255   The tree is built by the grammar productions, many of which are
 256   offloaded into `ParseHelper.cpp`, and by `Intermediate.cpp`.
 257
 258 * The intermediate representation is very high-level, and represented
 259   as an in-memory tree.   This serves to lose no information from the
 260   original program, and to have efficient transfer of the result from
 261   parsing to the back-end.  In the AST, constants are propogated and
 262   folded, and a very small amount of dead code is eliminated.
 263
 264   To aid linking and reflection, the last top-level branch in the AST
 265   lists all global symbols.
 266
 267 * The primary algorithm of the back-end compiler is to traverse the
 268   tree (high-level intermediate representation), and create an internal
 269   object code representation.  There is an example of how to do this
 270   in `MachineIndependent/intermOut.cpp`.
 271
 272 * Reduction of the tree to a linear byte-code style low-level intermediate
 273   representation is likely a good way to generate fully optimized code.
 274
 275 * There is currently some dead old-style linker-type code still lying around.
 276
 277 * Memory pool: parsing uses types derived from C++ `std` types, using a
 278   custom allocator that puts them in a memory pool.  This makes allocation
 279   of individual container/contents just few cycles and deallocation free.
 280   This pool is popped after the AST is made and processed.
 281
 282   The use is simple: if you are going to call `new`, there are three cases:
 283
 284   - the object comes from the pool (its base class has the macro
 285     `POOL_ALLOCATOR_NEW_DELETE` in it) and you do not have to call `delete`
 286
 287   - it is a `TString`, in which case call `NewPoolTString()`, which gets
 288     it from the pool, and there is no corresponding `delete`
 289
 290   - the object does not come from the pool, and you have to do normal
 291     C++ memory management of what you `new`
 292
 293
 294 [cmake]: https://cmake.org/
 295 [bison]: https://www.gnu.org/software/bison/
 296 [googletest]: https://github.com/google/googletest
 297 [bison-gnu-win32]: http://gnuwin32.sourceforge.net/packages/bison.htm