• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..--

.github/25-Apr-2025-619548

External/25-Apr-2025-7873

SPIRV/25-Apr-2025-28,61622,211

StandAlone/25-Apr-2025-2,9492,226

Test/25-Apr-2025-568,745548,100

build_overrides/25-Apr-2025-117109

glslang/25-Apr-2025-100,91976,308

gtests/25-Apr-2025-5,8884,303

kokoro/25-Apr-2025-1,051615

ndk_test/25-Apr-2025-599

.clang-formatD25-Apr-2025379 1413

.gitattributesD25-Apr-2025523 1815

.gitignoreD25-Apr-2025252 2623

.gnD25-Apr-20251.7 KiB4037

.mailmapD25-Apr-2025219 43

Android.bpD25-Apr-20257.2 KiB249234

BUILD.gnD25-Apr-202510.9 KiB347312

CHANGES.mdD25-Apr-20258.2 KiB251194

CMakeLists.txtD25-Apr-202514.5 KiB393343

CODE_OF_CONDUCT.mdD25-Apr-2025280 21

DEPSD25-Apr-20252.8 KiB8372

LICENSED25-Apr-20255.3 KiB10992

LICENSE.txtD25-Apr-202553.4 KiB1,017836

METADATAD25-Apr-2025321 1412

MODULE_LICENSE_BSDD25-Apr-20250

OWNERSD25-Apr-202539 21

README-spirv-remap.txtD25-Apr-20255 KiB138100

README.mdD25-Apr-202519.8 KiB541389

SECURITY.mdD25-Apr-2025319 74

_config.ymlD25-Apr-202527 21

build_info.h.tmplD25-Apr-20252.9 KiB6355

build_info.pyD25-Apr-20257.6 KiB227160

gen_extension_headers.pyD25-Apr-20253.6 KiB9964

known_good.jsonD25-Apr-2025681 2625

known_good_khr.jsonD25-Apr-2025632 2625

license-checker.cfgD25-Apr-20251.7 KiB6156

parse_version.cmakeD25-Apr-20251.9 KiB4240

standalone.gclientD25-Apr-20251.7 KiB4341

update_glslang_sources.pyD25-Apr-20254.9 KiB153101

README-spirv-remap.txt

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![Continuous Integration](https://github.com/KhronosGroup/glslang/actions/workflows/continuous_integration.yml/badge.svg)
2![Continuous Deployment](https://github.com/KhronosGroup/glslang/actions/workflows/continuous_deployment.yml/badge.svg)
3[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/KhronosGroup/glslang/badge)](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