1
2VERSION
3--------------------------------------------------------------------------------
4spirv-remap 0.97
5
6INTRO:
7--------------------------------------------------------------------------------
8spirv-remap is a utility to improve compression of SPIR-V binary files via
9entropy reduction, plus optional stripping of debug information and
10load/store optimization. It transforms SPIR-V to SPIR-V, remapping IDs. The
11resulting modules have an increased ID range (IDs are not as tightly packed
12around zero), but will compress better when multiple modules are compressed
13together, since compressor's dictionary can find better cross module
14commonality.
15
16Remapping is accomplished via canonicalization. Thus, modules can be
17compressed one at a time with no loss of quality relative to operating on
18many modules at once. The command line tool operates on multiple modules
19only in the trivial repetition sense, for ease of use. The remapper API
20only accepts a single module at a time.
21
22There are two modes of use: command line, and a C++11 API. Both are
23described below.
24
25spirv-remap is currently in an alpha state. Although there are no known
26remapping defects, it has only been exercised on one real world game shader
27workload.
28
29
30FEEDBACK
31--------------------------------------------------------------------------------
32Report defects, enhancements requests, code improvements, etc to:
33 [email protected]
34
35
36COMMAND LINE USAGE:
37--------------------------------------------------------------------------------
38Examples are given with a verbosity of one (-v), but more verbosity can be
39had via -vv, -vvv, etc, or an integer parameter to --verbose, such as
40"--verbose 4". With no verbosity, the command is silent and returns 0 on
41success, and a positive integer error on failure.
42
43Pre-built binaries for several OSs are available. Examples presented are
44for Linux. Command line arguments can be provided in any order.
45
461. Basic ID remapping
47
48Perform ID remapping on all shaders in "*.spv", writing new files with
49the same basenames to /tmp/out_dir.
50
51 spirv-remap -v --map all --input *.spv --output /tmp/out_dir
52
532. Perform all possible size reductions
54
55 spirv-remap-linux-64 -v --do-everything --input *.spv --output /tmp/out_dir
56
57Note that --do-everything is a synonym for:
58
59 --map all --dce all --opt all --strip all
60
61API USAGE:
62--------------------------------------------------------------------------------
63
64The public interface to the remapper is defined in SPIRV/SPVRemapper.h as follows:
65
66namespace spv {
67
68class spirvbin_t
69{
70public:
71 enum Options { ... };
72 spirvbin_t(int verbose = 0); // construct
73
74 // remap an existing binary in memory
75 void remap(std::vector<std::uint32_t>& spv, std::uint32_t opts = DO_EVERYTHING);
76
77 // Type for error/log handler functions
78 typedef std::function<void(const std::string&)> errorfn_t;
79 typedef std::function<void(const std::string&)> logfn_t;
80
81 // Register error/log handling functions (can be c/c++ fn, lambda fn, or functor)
82 static void registerErrorHandler(errorfn_t handler) { errorHandler = handler; }
83 static void registerLogHandler(logfn_t handler) { logHandler = handler; }
84};
85
86} // namespace spv
87
88The class definition is in SPVRemapper.cpp.
89
90remap() accepts an std::vector of SPIR-V words, modifies them per the
91request given in 'opts', and leaves the 'spv' container with the result.
92It is safe to instantiate one spirvbin_t per thread and process a different
93SPIR-V in each.
94
95The "opts" parameter to remap() accepts a bit mask of desired remapping
96options. See REMAPPING AND OPTIMIZATION OPTIONS.
97
98On error, the function supplied to registerErrorHandler() will be invoked.
99This can be a standard C/C++ function, a lambda function, or a functor.
100The default handler simply calls exit(5); The error handler is a static
101member, so need only be set up once, not once per spirvbin_t instance.
102
103Log messages are supplied to registerLogHandler(). By default, log
104messages are eaten silently. The log handler is also a static member.
105
106BUILD DEPENDENCIES:
107--------------------------------------------------------------------------------
108 1. C++11 compatible compiler
109 2. cmake
110 3. glslang
111
112
113BUILDING
114--------------------------------------------------------------------------------
115The standalone remapper is built along side glslang through its
116normal build process.
117
118
119REMAPPING AND OPTIMIZATION OPTIONS
120--------------------------------------------------------------------------------
121API:
122 These are bits defined under spv::spirvbin_t::, and can be
123 bitwise or-ed together as desired.
124
125 MAP_TYPES = canonicalize type IDs
126 MAP_NAMES = canonicalize named data
127 MAP_FUNCS = canonicalize function bodies
128 DCE_FUNCS = remove dead functions
129 DCE_VARS = remove dead variables
130 DCE_TYPES = remove dead types
131 OPT_LOADSTORE = optimize unneeded load/stores
132 MAP_ALL = (MAP_TYPES | MAP_NAMES | MAP_FUNCS)
133 DCE_ALL = (DCE_FUNCS | DCE_VARS | DCE_TYPES)
134 OPT_ALL = (OPT_LOADSTORE)
135 ALL_BUT_STRIP = (MAP_ALL | DCE_ALL | OPT_ALL)
136 DO_EVERYTHING = (STRIP | ALL_BUT_STRIP)
137
138
README.md
1
2
3[](https://securityscorecards.dev/viewer/?uri=github.com/KhronosGroup/glslang)
4
5# News
6
71. `OGLCompiler` and `HLSL` stub libraries have been fully removed from the build.
8
92. `OVERRIDE_MSVCCRT` has been removed in favor of `CMAKE_MSVC_RUNTIME_LIBRARY`
10
11Users are encouraged to utilize the standard approach via [CMAKE_MSVC_RUNTIME_LIBRARY](https://cmake.org/cmake/help/latest/variable/CMAKE_MSVC_RUNTIME_LIBRARY.html).
12
13# Glslang Components and Status
14
15There are several components:
16
17### Reference Validator and GLSL/ESSL -> AST Front End
18
19An OpenGL GLSL and OpenGL|ES GLSL (ESSL) front-end for reference validation and translation of GLSL/ESSL into an internal abstract syntax tree (AST).
20
21**Status**: Virtually complete, with results carrying similar weight as the specifications.
22
23### HLSL -> AST Front End
24
25An HLSL front-end for translation of an approximation of HLSL to glslang's AST form.
26
27**Status**: Partially complete. Semantics are not reference quality and input is not validated.
28This is in contrast to the [DXC project](https://github.com/Microsoft/DirectXShaderCompiler), which receives a much larger investment and attempts to have definitive/reference-level semantics.
29
30See [issue 362](https://github.com/KhronosGroup/glslang/issues/362) and [issue 701](https://github.com/KhronosGroup/glslang/issues/701) for current status.
31
32### AST -> SPIR-V Back End
33
34Translates glslang's AST to the Khronos-specified SPIR-V intermediate language.
35
36**Status**: Virtually complete.
37
38### Reflector
39
40An API for getting reflection information from the AST, reflection types/variables/etc. from the HLL source (not the SPIR-V).
41
42**Status**: There is a large amount of functionality present, but no specification/goal to measure completeness against. It is accurate for the input HLL and AST, but only approximate for what would later be emitted for SPIR-V.
43
44### Standalone Wrapper
45
46`glslang` is command-line tool for accessing the functionality above.
47
48Status: Complete.
49
50Tasks waiting to be done are documented as GitHub issues.
51
52## Other References
53
54Also see the Khronos landing page for glslang as a reference front end:
55
56https://www.khronos.org/opengles/sdk/tools/Reference-Compiler/
57
58The above page, while not kept up to date, includes additional information regarding glslang as a reference validator.
59
60# How to Use Glslang
61
62## Execution of Standalone Wrapper
63
64To use the standalone binary form, execute `glslang`, and it will print
65a usage statement. Basic operation is to give it a file containing a shader,
66and it will print out warnings/errors and optionally an AST.
67
68The applied stage-specific rules are based on the file extension:
69* `.vert` for a vertex shader
70* `.tesc` for a tessellation control shader
71* `.tese` for a tessellation evaluation shader
72* `.geom` for a geometry shader
73* `.frag` for a fragment shader
74* `.comp` for a compute shader
75
76For ray tracing pipeline shaders:
77* `.rgen` for a ray generation shader
78* `.rint` for a ray intersection shader
79* `.rahit` for a ray any-hit shader
80* `.rchit` for a ray closest-hit shader
81* `.rmiss` for a ray miss shader
82* `.rcall` for a callable shader
83
84There is also a non-shader extension:
85* `.conf` for a configuration file of limits, see usage statement for example
86
87## Building (CMake)
88
89Instead of building manually, you can also download the binaries for your
90platform directly from the [main-tot release][main-tot-release] on GitHub.
91Those binaries are automatically uploaded by the buildbots after successful
92testing and they always reflect the current top of the tree of the main
93branch.
94
95### Dependencies
96
97* A C++17 compiler.
98 (For MSVS: use 2019 or later.)
99* [CMake][cmake]: for generating compilation targets.
100* make: _Linux_, ninja is an alternative, if configured.
101* [Python 3.x][python]: for executing SPIRV-Tools scripts. (Optional if not using SPIRV-Tools and the 'External' subdirectory does not exist.)
102* [bison][bison]: _optional_, but needed when changing the grammar (glslang.y).
103* [googletest][googletest]: _optional_, but should use if making any changes to glslang.
104
105### Build steps
106
107The following steps assume a Bash shell. On Windows, that could be the Git Bash
108shell or some other shell of your choosing.
109
110#### 1) Check-Out this project
111
112```bash
113cd <parent of where you want glslang to be>
114git clone https://github.com/KhronosGroup/glslang.git
115```
116
117#### 2) Check-Out External Projects
118
119```bash
120./update_glslang_sources.py
121```
122
123#### 3) Configure
124
125Assume the source directory is `$SOURCE_DIR` and the build directory is
126`$BUILD_DIR`. First ensure the build directory exists, then navigate to it:
127
128```bash
129mkdir -p $BUILD_DIR
130cd $BUILD_DIR
131```
132
133For building on Linux:
134
135```bash
136cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="$(pwd)/install" $SOURCE_DIR
137# "Release" (for CMAKE_BUILD_TYPE) could also be "Debug" or "RelWithDebInfo"
138```
139
140For building on Android:
141```bash
142cmake $SOURCE_DIR -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX="$(pwd)/install" -DANDROID_ABI=arm64-v8a -DCMAKE_BUILD_TYPE=Release -DANDROID_STL=c++_static -DANDROID_PLATFORM=android-24 -DCMAKE_SYSTEM_NAME=Android -DANDROID_TOOLCHAIN=clang -DANDROID_ARM_MODE=arm -DCMAKE_MAKE_PROGRAM=$ANDROID_NDK_HOME/prebuilt/linux-x86_64/bin/make -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake
143# If on Windows will be -DCMAKE_MAKE_PROGRAM=%ANDROID_NDK_HOME%\prebuilt\windows-x86_64\bin\make.exe
144# -G is needed for building on Windows
145# -DANDROID_ABI can also be armeabi-v7a for 32 bit
146```
147
148For building on Windows:
149
150```bash
151cmake $SOURCE_DIR -DCMAKE_INSTALL_PREFIX="$(pwd)/install"
152# The CMAKE_INSTALL_PREFIX part is for testing (explained later).
153```
154
155The CMake GUI also works for Windows (version 3.4.1 tested).
156
157Also, consider using `git config --global core.fileMode false` (or with `--local`) on Windows
158to prevent the addition of execution permission on files.
159
160#### 4) Build and Install
161
162```bash
163# for Linux:
164make -j4 install
165
166# for Windows:
167cmake --build . --config Release --target install
168# "Release" (for --config) could also be "Debug", "MinSizeRel", or "RelWithDebInfo"
169```
170
171If using MSVC, after running CMake to configure, use the
172Configuration Manager to check the `INSTALL` project.
173
174If you want to enable testing via CMake set `GLSLANG_TESTS=ON` when configuring the build.
175
176`GLSLANG_TESTS` is off by default to streamline the packaging / Vulkan SDK process.
177
178### Building (GN)
179
180glslang can also be built with the [GN build system](https://gn.googlesource.com/gn/).
181
182#### 1) Install `depot_tools`
183
184Download [depot_tools.zip](https://storage.googleapis.com/chrome-infra/depot_tools.zip),
185extract to a directory, and add this directory to your `PATH`.
186
187#### 2) Synchronize dependencies and generate build files
188
189This only needs to be done once after updating `glslang`.
190
191With the current directory set to your `glslang` checkout, type:
192
193```bash
194./update_glslang_sources.py
195gclient sync --gclientfile=standalone.gclient
196gn gen out/Default
197```
198
199#### 3) Build
200
201With the current directory set to your `glslang` checkout, type:
202
203```bash
204cd out/Default
205ninja
206```
207
208### If you need to change the GLSL grammar
209
210The grammar in `glslang/MachineIndependent/glslang.y` has to be recompiled with
211bison if it changes, the output files are committed to the repo to avoid every
212developer needing to have bison configured to compile the project when grammar
213changes are quite infrequent. For windows you can get binaries from
214[GnuWin32][bison-gnu-win32].
215
216The command to rebuild is:
217
218```bash
219bison --defines=MachineIndependent/glslang_tab.cpp.h
220 -t MachineIndependent/glslang.y
221 -o MachineIndependent/glslang_tab.cpp
222```
223
224The above command is also available in the bash script in `updateGrammar`,
225when executed from the glslang subdirectory of the glslang repository.
226
227### Building to WASM for the Web and Node
228### Building a standalone JS/WASM library for the Web and Node
229
230Use the steps in [Build Steps](#build-steps), with the following notes/exceptions:
231* `emsdk` needs to be present in your executable search path, *PATH* for
232 Bash-like environments:
233 + [Instructions located here](https://emscripten.org/docs/getting_started/downloads.html#sdk-download-and-install)
234* Wrap cmake call: `emcmake cmake`
235* Set `-DENABLE_OPT=OFF`.
236* Set `-DENABLE_HLSL=OFF` if HLSL is not needed.
237* For a standalone JS/WASM library, turn on `-DENABLE_GLSLANG_JS=ON`.
238* To get a fully minimized build, make sure to use `brotli` to compress the .js
239 and .wasm files
240
241Example:
242
243```sh
244emcmake cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_GLSLANG_JS=ON \
245 -DENABLE_HLSL=OFF -DENABLE_OPT=OFF ..
246```
247
248## Building glslang - Using vcpkg
249
250You can download and install glslang using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
251
252 git clone https://github.com/Microsoft/vcpkg.git
253 cd vcpkg
254 ./bootstrap-vcpkg.sh
255 ./vcpkg integrate install
256 ./vcpkg install glslang
257
258The glslang port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
259
260## Testing
261
262Right now, there are two test harnesses existing in glslang: one is [Google
263Test](gtests/), one is the [`runtests` script](Test/runtests). The former
264runs unit tests and single-shader single-threaded integration tests, while
265the latter runs multiple-shader linking tests and multi-threaded tests.
266
267Tests may erroneously fail or pass if using `ALLOW_EXTERNAL_SPIRV_TOOLS` with
268any commit other than the one specified in `known_good.json`.
269
270### Running tests
271
272The [`runtests` script](Test/runtests) requires compiled binaries to be
273installed into `$BUILD_DIR/install`. Please make sure you have supplied the
274correct configuration to CMake (using `-DCMAKE_INSTALL_PREFIX`) when building;
275otherwise, you may want to modify the path in the `runtests` script.
276
277Running Google Test-backed tests:
278
279```bash
280cd $BUILD_DIR
281
282# for Linux:
283ctest
284
285# for Windows:
286ctest -C {Debug|Release|RelWithDebInfo|MinSizeRel}
287
288# or, run the test binary directly
289# (which gives more fine-grained control like filtering):
290<dir-to-glslangtests-in-build-dir>/glslangtests
291```
292
293Running `runtests` script-backed tests:
294
295```bash
296cd $SOURCE_DIR/Test && ./runtests
297```
298
299If some tests fail with validation errors, there may be a mismatch between the
300version of `spirv-val` on the system and the version of glslang. In this
301case, it is necessary to run `update_glslang_sources.py`. See "Check-Out
302External Projects" above for more details.
303
304### Contributing tests
305
306Test results should always be included with a pull request that modifies
307functionality.
308
309If you are writing unit tests, please use the Google Test framework and
310place the tests under the `gtests/` directory.
311
312Integration tests are placed in the `Test/` directory. It contains test input
313and a subdirectory `baseResults/` that contains the expected results of the
314tests. Both the tests and `baseResults/` are under source-code control.
315
316Google Test runs those integration tests by reading the test input, compiling
317them, and then compare against the expected results in `baseResults/`. The
318integration tests to run via Google Test is registered in various
319`gtests/*.FromFile.cpp` source files. `glslangtests` provides a command-line
320option `--update-mode`, which, if supplied, will overwrite the golden files
321under the `baseResults/` directory with real output from that invocation.
322For more information, please check `gtests/` directory's
323[README](gtests/README.md).
324
325For the `runtests` script, it will generate current results in the
326`localResults/` directory and `diff` them against the `baseResults/`.
327When you want to update the tracked test results, they need to be
328copied from `localResults/` to `baseResults/`. This can be done by
329the `bump` shell script.
330
331You can add your own private list of tests, not tracked publicly, by using
332`localtestlist` to list non-tracked tests. This is automatically read
333by `runtests` and included in the `diff` and `bump` process.
334
335## Programmatic Interfaces
336
337Another piece of software can programmatically translate shaders to an AST
338using one of two different interfaces:
339* A new C++ class-oriented interface, or
340* The original C functional interface
341
342The `main()` in `StandAlone/StandAlone.cpp` shows examples using both styles.
343
344### C++ Class Interface (new, preferred)
345
346This interface is in roughly the last 1/3 of `ShaderLang.h`. It is in the
347glslang namespace and contains the following, here with suggested calls
348for generating SPIR-V:
349
350```cxx
351const char* GetEsslVersionString();
352const char* GetGlslVersionString();
353bool InitializeProcess();
354void FinalizeProcess();
355
356class TShader
357 setStrings(...);
358 setEnvInput(EShSourceHlsl or EShSourceGlsl, stage, EShClientVulkan or EShClientOpenGL, 100);
359 setEnvClient(EShClientVulkan or EShClientOpenGL, EShTargetVulkan_1_0 or EShTargetVulkan_1_1 or EShTargetOpenGL_450);
360 setEnvTarget(EShTargetSpv, EShTargetSpv_1_0 or EShTargetSpv_1_3);
361 bool parse(...);
362 const char* getInfoLog();
363
364class TProgram
365 void addShader(...);
366 bool link(...);
367 const char* getInfoLog();
368 Reflection queries
369```
370
371For just validating (not generating code), substitute these calls:
372
373```cxx
374 setEnvInput(EShSourceHlsl or EShSourceGlsl, stage, EShClientNone, 0);
375 setEnvClient(EShClientNone, 0);
376 setEnvTarget(EShTargetNone, 0);
377```
378
379See `ShaderLang.h` and the usage of it in `StandAlone/StandAlone.cpp` for more
380details. There is a block comment giving more detail above the calls for
381`setEnvInput, setEnvClient, and setEnvTarget`.
382
383### C Functional Interface (original)
384
385This interface is in roughly the first 2/3 of `ShaderLang.h`, and referred to
386as the `Sh*()` interface, as all the entry points start `Sh`.
387
388The `Sh*()` interface takes a "compiler" call-back object, which it calls after
389building call back that is passed the AST and can then execute a back end on it.
390
391The following is a simplified resulting run-time call stack:
392
393```c
394ShCompile(shader, compiler) -> compiler(AST) -> <back end>
395```
396
397In practice, `ShCompile()` takes shader strings, default version, and
398warning/error and other options for controlling compilation.
399
400### C Functional Interface (new)
401
402This interface is located `glslang_c_interface.h` and exposes functionality similar to the C++ interface. The following snippet is a complete example showing how to compile GLSL into SPIR-V 1.5 for Vulkan 1.2.
403
404```c
405#include <glslang/Include/glslang_c_interface.h>
406
407// Required for use of glslang_default_resource
408#include <glslang/Public/resource_limits_c.h>
409
410typedef struct SpirVBinary {
411 uint32_t *words; // SPIR-V words
412 int size; // number of words in SPIR-V binary
413} SpirVBinary;
414
415SpirVBinary compileShaderToSPIRV_Vulkan(glslang_stage_t stage, const char* shaderSource, const char* fileName) {
416 const glslang_input_t input = {
417 .language = GLSLANG_SOURCE_GLSL,
418 .stage = stage,
419 .client = GLSLANG_CLIENT_VULKAN,
420 .client_version = GLSLANG_TARGET_VULKAN_1_2,
421 .target_language = GLSLANG_TARGET_SPV,
422 .target_language_version = GLSLANG_TARGET_SPV_1_5,
423 .code = shaderSource,
424 .default_version = 100,
425 .default_profile = GLSLANG_NO_PROFILE,
426 .force_default_version_and_profile = false,
427 .forward_compatible = false,
428 .messages = GLSLANG_MSG_DEFAULT_BIT,
429 .resource = glslang_default_resource(),
430 };
431
432 glslang_shader_t* shader = glslang_shader_create(&input);
433
434 SpirVBinary bin = {
435 .words = NULL,
436 .size = 0,
437 };
438 if (!glslang_shader_preprocess(shader, &input)) {
439 printf("GLSL preprocessing failed %s\n", fileName);
440 printf("%s\n", glslang_shader_get_info_log(shader));
441 printf("%s\n", glslang_shader_get_info_debug_log(shader));
442 printf("%s\n", input.code);
443 glslang_shader_delete(shader);
444 return bin;
445 }
446
447 if (!glslang_shader_parse(shader, &input)) {
448 printf("GLSL parsing failed %s\n", fileName);
449 printf("%s\n", glslang_shader_get_info_log(shader));
450 printf("%s\n", glslang_shader_get_info_debug_log(shader));
451 printf("%s\n", glslang_shader_get_preprocessed_code(shader));
452 glslang_shader_delete(shader);
453 return bin;
454 }
455
456 glslang_program_t* program = glslang_program_create();
457 glslang_program_add_shader(program, shader);
458
459 if (!glslang_program_link(program, GLSLANG_MSG_SPV_RULES_BIT | GLSLANG_MSG_VULKAN_RULES_BIT)) {
460 printf("GLSL linking failed %s\n", fileName);
461 printf("%s\n", glslang_program_get_info_log(program));
462 printf("%s\n", glslang_program_get_info_debug_log(program));
463 glslang_program_delete(program);
464 glslang_shader_delete(shader);
465 return bin;
466 }
467
468 glslang_program_SPIRV_generate(program, stage);
469
470 bin.size = glslang_program_SPIRV_get_size(program);
471 bin.words = malloc(bin.size * sizeof(uint32_t));
472 glslang_program_SPIRV_get(program, bin.words);
473
474 const char* spirv_messages = glslang_program_SPIRV_get_messages(program);
475 if (spirv_messages)
476 printf("(%s) %s\b", fileName, spirv_messages);
477
478 glslang_program_delete(program);
479 glslang_shader_delete(shader);
480
481 return bin;
482}
483```
484
485## Basic Internal Operation
486
487* Initial lexical analysis is done by the preprocessor in
488 `MachineIndependent/Preprocessor`, and then refined by a GLSL scanner
489 in `MachineIndependent/Scan.cpp`. There is currently no use of flex.
490
491* Code is parsed using bison on `MachineIndependent/glslang.y` with the
492 aid of a symbol table and an AST. The symbol table is not passed on to
493 the back-end; the intermediate representation stands on its own.
494 The tree is built by the grammar productions, many of which are
495 offloaded into `ParseHelper.cpp`, and by `Intermediate.cpp`.
496
497* The intermediate representation is very high-level, and represented
498 as an in-memory tree. This serves to lose no information from the
499 original program, and to have efficient transfer of the result from
500 parsing to the back-end. In the AST, constants are propagated and
501 folded, and a very small amount of dead code is eliminated.
502
503 To aid linking and reflection, the last top-level branch in the AST
504 lists all global symbols.
505
506* The primary algorithm of the back-end compiler is to traverse the
507 tree (high-level intermediate representation), and create an internal
508 object code representation. There is an example of how to do this
509 in `MachineIndependent/intermOut.cpp`.
510
511* Reduction of the tree to a linear byte-code style low-level intermediate
512 representation is likely a good way to generate fully optimized code.
513
514* There is currently some dead old-style linker-type code still lying around.
515
516* Memory pool: parsing uses types derived from C++ `std` types, using a
517 custom allocator that puts them in a memory pool. This makes allocation
518 of individual container/contents just few cycles and deallocation free.
519 This pool is popped after the AST is made and processed.
520
521 The use is simple: if you are going to call `new`, there are three cases:
522
523 - the object comes from the pool (its base class has the macro
524 `POOL_ALLOCATOR_NEW_DELETE` in it) and you do not have to call `delete`
525
526 - it is a `TString`, in which case call `NewPoolTString()`, which gets
527 it from the pool, and there is no corresponding `delete`
528
529 - the object does not come from the pool, and you have to do normal
530 C++ memory management of what you `new`
531
532* Features can be protected by version/extension/stage/profile:
533 See the comment in `glslang/MachineIndependent/Versions.cpp`.
534
535[cmake]: https://cmake.org/
536[python]: https://www.python.org/
537[bison]: https://www.gnu.org/software/bison/
538[googletest]: https://github.com/google/googletest
539[bison-gnu-win32]: http://gnuwin32.sourceforge.net/packages/bison.htm
540[main-tot-release]: https://github.com/KhronosGroup/glslang/releases/tag/main-tot
541