Code-X Processor

How to download and run

Go to the Public Downloads and get this executable:

  • codex.exe

The executable is self-contained and can be run without prior installation.

The Code-X Processor tool is contained in the Tinman 3D SDK as the codex component. It analyzes the C# source code of Code-X compliant libraries and then generates source code for other programming languages, for example C++, HLSL or GLSL.

For details on this workflow, please refer to Code-X Framework.

The following sections explain the command line and project file syntax that are required to run a Code-X workflow.

CAUTION

Running a Code-X workflow can cause lots of file modifications in the local filesystem.

It is strongly recommended to have a version control system in place (e.g. Git or SVN), to be able to review all changes that have actually happened and to undo them, if necessary.

This particularly applies to the time when authoring a Code-X project file, where - for example - it is possible to have all output files accidentally deleted by adding a single incorrect exclude filter (which would also delete all native code blocks).

Command Line

To perform a Code-X workflow, run the codex tool and point it to a Code-X Project File.

The codex tool requires a Development licence key, which must be specified with an environment variable:
TINMAN_3D_LICENCEKEY= ...
Command-line invocation of codex tool
> codex <task> (1)
1 The command-line task to perform.
Grammar of a command-line task
!task         := api | check | process | generate | run ; (1)
api           := 'api' ;
check         := 'check' project-file ;
generate      := 'generate' targets? project-file ;
process       := 'process' project-file ;
run           := 'run' targets? project-file ;

!project-file := ws path ; (2)

!language     := @'cs' | @'cpp' | @'java' | @'hlsl' | @'glsl' ; (3)
language-list := language .. ',' ;
targets       := '[' language-list ']'   (4)
               | ']' language-list '[' ; (5)

ws            := [\t ]+ ;
1 Chooses the task to perform: api, check, process, generate or run
2 Chooses the Code-X Project File, as an absolute or relative file path.
3 Specifies a single target programming language.
4 Selects only the specified target programming languages.
5 Selects all target programming languages except the specified ones.

Status messages that are intended for human consumption are output to the standard output stream in an unspecified format and may be discarded without loosing any relevant information about the Code-X workflow.

Errors, warnings and hints regarding the Code-X workflow are output to the standard error stream in a well-defined format and are supposed to be consumed by human beings or machines, see Message Format.

The process exit codes may be used when integrating a Code-X workflow invocation into a build pipeline.

Table 1. Process exit codes
Code Meaning

0

The Code-X workflow has completed successfully.

No syntax errors have been reported.

No semantic problems have been reported.

No semantic hints have been reported.

1

The Code-X workflow has completed successfully.

No syntax errors have been reported.

No semantic problems have been reported.

At least one semantic hint has been generated.

2

The Code-X workflow has completed successfully.

No syntax errors have been reported.

No semantic errors have been reported.

At least one semantic warning has been generated.

3

The Code-X workflow has failed with errors.

At least one syntax error or semantic error has been generated.

-1

The Code-X workflow did not run.

The command-line arguments are incorrect or the licence key is missing.

-2

The Code-X workflow has crashed.

An unexpected internal error has occurred and status messages have been output to provide additional information.

api

This task scans the current directory for *.psi and *.api files and outputs the <project-id/> values for each one to the standard output stream.

Use this task to gather the information that is required for adding <external/> and <dependency/> elements to the Code-X Project File.

check

Example command-line invocation
> codex check my-project.xml

This task parses the Code-X compliant input source code files and collects the native code blocks (see CxStatementCode and CodeX::NativeAttribute) of each target programming language, by scanning the output source code files. If there are syntax errors, the task reports them and then terminates.

If there are no syntax errors, the task inspects the parsed input source code files and the collected native code blocks. If there are semantic problems, the task reports them and then terminates.

This task does not modify the filesystem.

process

Example command-line invocation
> codex process my-project.xml

This task first runs check and terminates if there are any errors or problems. Upon success, it writes the .psi and .api files for each project.

The .psi files contain the full code model as well as the content of all native code regions.

The .api files only contain those parts of the full code model which are required for use as external libraries.

This task modifies the filesystem.

generate

Example command-line invocation
> codex generate @ cpp my-project.xml

This task uses the .psi files of each project and thus requires that process has been run before. It generates the output source code for the chosen target programming languages.

This task modifies the filesystem.

run

Example command-line invocation
> codex run my-project.xml

This task runs process and terminates if there are any errors or problems. Upon success, runs generate.

This task modifies the filesystem.

MSBuild

The Code-X processor can be invoked from the Microsoft Build Engine (MSBuild).

Although MSBuild can run arbitrary command-line tools (and thus the codex tool), using a build task eases setup and provides better feedback for errors, warnings and notices, with out-of-the box integration in IDEs.

The codex task requires a Development licence key, which must be specified with an environment variable:
TINMAN_3D_LICENCEKEY= ...

To add the Code-X processor to a project, insert a <UsingTask/> element to the project file, which will register the processor task with the build engine.

Register processor task
<UsingTask
  TaskName="CodeX.Processor.Task"
  AssemblyFile="codex-task.dll"/> (1)
1 Path to the processor task binary, see lib/win.any/ or Preview (Web) / Tools.

Once the processor task has been registered, build targets may be defined by adding <Target/> elements to the project file.

Build target using the processor task
<Target
  Name="MyTaskName" BeforeTargets="Build"> (1)
  <CodeX.Processor.Task
    Arguments="check codex.xml"
    Directory="$(ProjectDir)"
    FailOnErrors="true"
    FailOnNotices="false"
    FailOnWarnings="false"/>
</Target>
1 Choose these according to your build pipeline.

The processor task properties are described by the subsequent sections.

​Arguments

Default Value

"check codex.xml"

The command-line arguments for the Code-X processor, see Command Line.

If not specified, runs check on the default project file.

​Directory

Default Value

"$(ProjectDir)"

The base directory to use for resolving relative paths that are present in Arguments.

If not specified, the directory of the project file that has called this task is used.

​Fail​On​Errors

Default Value

"true"

Shall the build fail on syntax and semantic errors?

​Fail​On​Notices

Default Value

"false"

Shall the build fail on semantic notices?

​Fail​On​Warnings

Default Value

"false"

Shall the build fail on semantic warnings?

Message Format

The Code-X workflow outputs messages in a well-defined format, as described by the subsequent sections.

Syntax Errors

A syntax error indicates that an input source file does match the grammar for Code-X code units (see CxCodeUnit).

All errors must be fixed before the Code-X workflow can succeed.

Syntax errors may be generated for valid C# code, because not all C# language features are supported by Code-X.
Syntax error message
['project.codex\CodeX.Examples.CodeX\Constants.cs'] (1)
45:     public const int SomeNumber = 1x0; (2)
   ___________________________________/\__ (3)
   [Syntax] Mismatch in rule constant, expected this: ';' (4)
   [Syntax] Mismatch in rule expr-add, expected this: [  +- ] | '\n' | ...
   [Syntax] Mismatch in rule expr-assign, expected this: [  = ] | '%=' | ...
   [Syntax] Mismatch in rule expr-cond, expected this: [  ? ] | '\n' | ...
   [Syntax] Mismatch in rule expr-cond-and, expected this: ' ' | '&&' | ...
   [Syntax] Mismatch in rule expr-cond-or, expected this: ' ' | '\n' | ...
   [Syntax] Mismatch in rule expr-equal, expected this: ' ' | '!=' | ...
   [Syntax] Mismatch in rule expr-logic-and, expected this: [  & ] | '\n' | ...
   [Syntax] Mismatch in rule expr-logic-or, expected this: [  | ] | '\n' | ...
   [Syntax] Mismatch in rule expr-logic-xor, expected this: [  ^ ] | '\n' | ...
   [Syntax] Mismatch in rule expr-mul, expected this: [  %*/ ] | '//' | ...
   [Syntax] Mismatch in rule expr-relate, expected this: [  <> ] | '<=' | ...
   [Syntax] Mismatch in rule expr-shift, expected this: ' ' | '<<' | '>>' | ...
   [Syntax] Mismatch in rule expr-suffix, expected this: [  (. ] | '++' | ...
   [Syntax] Mismatch in rule literal-number, expected this: '.' | '0'..'9' | ...
1 Path to the source code file, relative to $(BaseDir)
2 The source code line, including the line number
3 Visual indicator of the syntax error column
4 The grammar rules that were matching the preceding input

Semantic Problems

A semantic problem is a critical error, a non-critical error or a warning, in terms of the Code-X Framework.

All errors must be fixed before the Code-X workflow can succeed.

All warnings should be fixed. The workflow will fail on warnings. By configuring <ignore/> elements in the Code-X Project File, specific warnings can be ignored.

Semantic problem message
[Critical] ConstantDeclaration.MemberType has incomplete / unresolved value! (1)
['project.codex\CodeX.Examples.CodeX\Constants.cs'] (2)
::CodeX.Examples/Constants/SomeString (3)
----  (4)
/// <summary>
///   Summary
/// </summary>
public const string2 SomeString = "Hallo";
----

[Critical] NamedType has incomplete / unresolved value!
::CodeX.Examples/Constants/SomeString
string2 (3)
1 The severity (Critical, Error, Warning or Notice), followed by the message. Will be omitted iff it is identical to the part of the previous message.
2 Path to the source code file, relative to $(BaseDir)
3 A name path that identifies the code element, in the form ::Namespace/Type/Member/Parameter. Will be omitted iff it is identical to the part of the previous message.
4 The source code fragment, will be surrounded by ----, if multi-line.

Semantic Hints

A semantic hint is a notice, in terms of the Code-X Framework.

The format of semantic hints is identical to the format of Semantic Problems.

By configuring <ignore/> elements in the Code-X Project File, specific hints can be silenced.

After adding native code blocks to the input source code, there will be hints stating that code blocks in the output source code are incomplete. Running the Code-X workflow in such a case will create the missing code blocks. The hints will disappear once theses blocks have been filled with code.

Code-X Project File

Regular XML files are used to define Code-X workflows. File paths need to be specified at various places in a project file. This documentation uses the following placeholders to refer to common directories:

$(ProjectFile)

This is the absolute path to the Code-X project file.

$(BaseDir)

The base directory of the Code-X workflow, defined by base of <codex/>.

$(ProjectDir)

The base directory of a project, defined by base of <project/>.

$(OutputDir)

The output directory for generated source code of a <module/> for a specific <target/>.

Code-X project file
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE codex PUBLIC "-//TINMAN//CODEX//EN"
  "https://dtd.tinman3d.com/Code-X.1.dtd"> (1)
<codex format="1"> (2)
  ...
</codex>
1 The Document Type Definition for validation, which also chooses the Code-X project file format version.
2 See <codex/> element.

The following sections contain a documentation block for each XML element, of this style:

<example/>
Parent

<parent-1/>
<parent-2/>

Children

<child-1/> - exactly one
<child-2/> - zero or one
<child-3/> - zero or more

Attributes

attribute-1 - required
attribute-2 - required
attribute-3 - optional
attribute-4 - optional

<example attribute-1="..." attribute-2="..."
         attribute-3="..." attribute-4="...">
  <child-1>...</child-1>
  <child-2>...</child-2>
  <child-3/>
  ...
</example>

The Parent section links to the possible XML parent elements, Children lists the allowed child XML elements and Attributes shows the attributes of the XML element. For each attribute, there is a separate documentation section.

<codex/>

This is the root XML element of a Code-X Project File document.

<codex/>
Children

<global/> - zero or one
<external/> - zero or more
<project/> - zero or more

Attributes

format - optional
base - optional

<codex format="..." base="...">
  <global>...</global>
  <external>...</external>
  ...
  <project>...</project>
  ...
</codex>

format

The file format version of the Code-X project file. If not specified, the format version 1 will be assumed.

Currently, there is only the file format version 1.

base

If absolute, defines $(BaseDir).

If relative, resolves against the directory that contains $(ProjectFile) and then defines $(BaseDir).

If not specified, $(BaseDir) will be identical to the directory that contains $(ProjectFile).

<dictionary/>

Defines the dictionary that will be used for spell-checking when analyzing source code comments.

<dictionary/>
Parent

<global/>

Children

<word-list/> - zero or more

<dictionary>
  <word-list/>
  ...
</dictionary>

<exclude/>

Defines filters for excluding files / types from processing.

<exclude/>
Parent

<global/>
<input/>

Children

<filter/> - zero or more

<exclude>
  <filter/>
  ...
</exclude>

<filter/>

Defines a filter for file paths or fully qualified type names.

<filter/>
Parent

<exclude/>
<include/>

Attributes

prefix - optional
suffix - optional
priority - optional

<filter prefix="..." suffix="..." priority="..."/>

For input files of a <project/>, the <filter/> attributes operate on relative file paths, based on $(ProjectDir). Directory separators are normalized, so / and \ may be used interchangeably.

Example input for file path filter
Relative/Path/To/Input.cs

For input types of a <module/> and <target/>, the <filter/> attributes operate on the fully-qualified C# type name, not including the global:: prefix and omitting any generic type suffixes.

Example input for type name filter
CodeX.Examples.HelloWorld

Input files and types are processed in the following sequence:

  1. <project/>
    Matching input files are parsed, which yields project input types.

  2. <module/>
    Matching project input types are collected as module input types.

  3. <target/>
    Matching module input types are collected as target input types.

prefix

If set, the input must start with the specified prefix.

suffix

If set, the input must end with the specified suffix.

priority

Specifies the priority of this filter. If a filter matches a file / type, it will set the filter result (according to the parent element) only if its priority is greater then the previous match.

If not set, the priority is 0.

<global/>

The elements in the global section define properties for the whole workspace. Some properties may be overridden by elements at lower levels.

<global/>
Parent

<codex/>

Children

<dictionary/> - zero or one
<exclude/> - zero or one
<ignore/> - zero or more

<global>
  <dictionary>...</dictionary>
  <exclude>...</exclude>
  <ignore/>
  ...
</global>

<ignore/>

Defines filters for ignoring non-critical Semantic Problems and Semantic Hints.

Ignored inspection messages a dropped silently, the processor will behave as if the message had not been generated in the first place.

<ignore/>
Parent

<global/>

Attributes

message - optional
message-op - optional
node - optional
node-op - optional

<ignore message="..." message-op="..." node="..." node-op="..."/>

The <ignore/> filter will match if all of the following conditions are true:

  • The message test produces a match.

  • The node test produces a match.

The message-op and node-op attributes depict the matching operator and may be one of the following:

Equal

The match token must be equal to message / node.

Contain

The match token must contain message / node.

Prefix

The match token must start with message / node.

Suffix

The match token must end with message / node.

message

Chooses the message text of an inspection message as the match token (i.e. the first line of text, excluding the tag for the inspection severity).

If empty, all inspection messages will be matched, regardless of message-op.

message-op

The matching operator to use for message.

Defaults to Equal.

node

Chooses the name path of the code element of an inspection message as the match token (i.e. the second line of text).

If empty, all inspection messages will be matched, regardless of node-op.

node-op

The matching operator to use for node.

Defaults to Prefix.

<include/>

Defines filters for including files / types for processing.

<include/>
Parent

<input/>

Children

<filter/> - zero or more

<include>
  <filter/>
  ...
</include>

<input/>

Specifies the files / types that will be used as input for the Code-X workflow.

<input/>
Parent

<project/>
<module/>

Children

<exclude/> - zero or one
<include/> - zero or one

Attributes

default - required

<input default="...">
  <exclude>...</exclude>
  <include>...</include>
</input>

The <exclude/> filters are applied before the <include/> filters, which means that exclusions have higher precedence as inclusions when they have the same priority.

If the <input/> element is not present, all input files / types will be used, as if <input default="Include"/> had been specified.

default

Specifies the initial filter result value. May be one of the following:

Include

Files / types will be included by default and may be excluded by filters.

Exclude

Files / types will be excluded by default and may be included by filters.

<module/>

Defines a module within a <project/>.

<module/>
Parent

<project/>

Children

<options/> - zero or one
<input/> - zero or one

Attributes

name - required
output - required
tag - required
type-prefix - optional
header - optional

<module name="..." output="..." tag="..."
        type-prefix="..." header="...">
  <options>...</options>
  <input/>
</module>

name

Specifies a human-readable name for the module.

This name is used in comments of the generated source code when referring to a module of a project and should thus be plausible.

output

Defines $(OutputDir) as the concatenation (indicated by |) of the following tokens:

$(ProjectDir) | "/" | output | full-source? | path-suffix | "/"

If a <module/> is not obfuscated, the full-source token will not be used.

For obfuscated modules, two output passes are performed: the first pass outputs the obfuscated source code and the second pass output the full (i.e. non-obfuscated) source code. The full-source token is used to generate a distinct $(OutputDir) value for the second pass.

Example 1. Example $(OutputDir)

Given these values:

$(ProjectDir) = "/my-project"
output = "MyModule"
full-source = ".Full"
path-suffix = ".Cpp"

Code for non-obfuscated modules and for the first pass of obfuscated modules is then output to:

$(OutputDir) = "/my-project/MyModule.Cpp"

Code for the second pass of obfuscated modules is output to:

$(OutputDir) = "/my-project/MyModule.Full.Cpp"

tag

Assigns a machine-readable tag to the module, which must be suitable for use as filesystem path element and as a programming language identifier.

type-prefix

Specifies a common type name prefix that depicts which types of are included in the module.

The <input/> of <project/> yields source code files, which are parsed into code units.

Each code unit contains a single type declaration, which has a fully-qualified name.

A code unit belongs to a module iff the fully-qualified type name of its declaration starts with type-prefix.

header

Optional override for the header attribute of the enclosing <project/>.

<option/>

Defines a single option in a set of <options/>.

<option/>
Parent

<options/>

Attributes

name - required
value - required

<option name="..." value="..."/>

name

The option name.

value

The option value.

<options/>

Defines a set of <option/> elements for the Cpu-X and Gpu-X workflows.

<options/>
Parent

<module/>
<target/>

Children

<option/> - zero or more

<options>
  <option/>
  ...
</options>

<project/>

Defines a project for the Code-X workflow.

<project/>
Parent

<codex/>

Children

<project-id/> - exactly one
<dependency/> - zero or more
<target/> - zero or more
<input/> - zero or one
<module/> - zero or more

Attributes

name - required
tag - required
psi - required
base - optional
header - optional

<project name="..." tag="..." psi="..."
         base="..."  header="...">
  <project-id/>
  <dependency/>
  ...
  <target>...</target>
  ...
  <input>...</input>
  <module>...</module>
  ...
</project>

name

Specifies a human-readable name for the project.

This name is used in comments of the generated source code when referring to a project and should thus be plausible.

tag

Assigns a machine-readable tag to the project, which must be suitable for use in filesystem paths.

The tag does not need to be unique, multiple projects may share the same tag.

The generators for the <target/> programming languages use the project tag to construct file paths for the output source code files, so it is important to choose project tags carefully. Otherwise, output files may overwrite each other, which will cause compilation errors.

psi

Path to the .psi file of this project, either absolute or relative to $(ProjectDir).

The .api file of the project will be written into the same directory as the .psi file.

base

If absolute, defines $(ProjectDir).

If relative, resolves against $(BaseDir) and then defines $(ProjectDir).

If not specified, $(ProjectDir) will be identical to $(BaseDir).

header

Path to an optional copyright text file in UTF-8 encoding, either absolute or relative to $(ProjectDir), which will be read and its content be written at the beginning of each generated output source code file.

The file header must be plain text. Depending on the <target/> programming language, it will be wrapped in suitable source code comments. Usually, these will be single-line comments.

Example file header text
Example file header
with two text lines
Example source code file output
// Example file header
// with two text lines
...

The file header text may contain placeholders, which will be expanded, as described below.

Table 2. File header placeholders
Placeholder Replacement Values

{0}

A - B vX.Y

A = <project/>.name
B = <module/>.name
X = <project-id/>.major
Y = <project-id/>.minor

<project-id/>

References a specific project and version.

<project-id/>
Parent

<project/>
<external/>

Attributes

guid - required
name - optional
major - optional
minor - optional

<project-id guid="..." name="..." major="..." minor="..."/>

guid

Defines a unique identifier for the project, in form of a GUID, for example A3252944-2D5D-4010-B0FE-D68DB002A19A.

Usually, a project identifier is assigned once and then never changed again. The Code-X workflow uses the guid in combination with major and minor in order to resolve references between projects.

name

Optional human-readable name to use instead of guid, for better readability.

This name does not have any impact on the Code-X workflow. However, it should correlate with name.

major

Defines the major version number of the project.

Each time the public API of a project (i.e. the contents of the .api file) changes, the major version number must be incremented and the minor version number must be set to 0.

If not specified, the major version number will be 1.

minor

Defines the minor version number of the project.

Each time the implementation of a project (i.e. the contents of the .psi file) changes but the public API remains unchanged (i.e. the contents of the .api file), the minor version number must be incremented.

If not specified, the minor version number will be 0.

<target/>

Defines a target for code generation.

<target/>
Parent

<project/>

Children

<options/> - zero or one

Attributes

language - required
language-tag - optional
path-suffix - optional
full-source - optional

<target language=".." language-tag="..."
        path-suffix=".." full-source="...">
  <options>...</options>
</target>

Native code blocks are collected and stored separately for each defined target language.

When using a single target for a programming language, native code blocks may need to do compile-time branching (e.g. pre-processor #ifdef). By using language tags, separate targets may be defined for the same programming language, which will allow the native code blocks to be separated, as well.

language

Depicts the programming language to generate.

Before generating code, the output directory is cleaned by deleting all files, except certain retained files.

May be one of the following:

CPP

The C++ programming language version 11 for the Cpu-X Workflow.

Retained files:

  • CodeX_System*.h

  • CodeX_System*.cpp

  • *.Test.*

  • *.Native.*

  • stdafx.cpp

  • stdafx.h

  • *.natvis

CS

The C# programming language version 7.3 for the Cpu-X Workflow.

Retained files:

  • AssemblyInfo.cs

  • SafeNativeMethods*.cs

JAVA

The Java programming language version 11 for the Cpu-X Workflow.

Retained files:

  • none

HLSL

The High-Level Shader Language for the Gpu-X Workflow.

Retained files:

  • none

GLSL

The OpenGL Shading Language for the Gpu-X Workflow.

Retained files:

  • none

language-tag

Optional tag to use for discriminating this target against others with the same language.

path-suffix

The output path suffix to use for this language.

full-source

The full-source tag to use for this language.

<word-list/>

Declares a word file that shall be used for spell-checking. Word files are simple text files in UTF-8 encoding, where each line of text defines a single word.

<word-list/>
Parent

<dictionary/>

Attributes

kind - required
path - required

<word-list kind="..." path="..."/>

kind

Defines the usage of the word list. May be one of the following:

Abbreviation

Case-sensitive abbreviations that shall be ignored.

Example 2. Common abbreviations

JSON
WKT
XML

Designation

Case-sensitive names and designations that shall be ignored.

Example 3. Common names

Mercator
Euler
Lambert

Dictionary

Case-insensitive words to use for spell-checking.

Example 4. Common dictionary words

hello
world

Reserved

Reserved identifiers that shall be ignored.

Example 5. Common reserved identifiers

stackalloc
readonly

path

The path of the word file. Will be resolved against $(BaseDir), if relative.

Cpu-X Workflow

This section explains those Code-X Project File elements that belong to the Cpu-X workflow.

<dependency/>

Declares that the enclosing <project/> depends on the project that is specified by this element.

The dependency may be an external library (see <external/>) or another project (see <project/>).

<dependency/>
Parent

<project/>

Attributes

guid - required
name - optional
major - optional
minor - optional

<dependency guid="..." name="..."
            major="..." minor="..."/>

guid

The guid of the referenced <project/>.

name

Optional human-readable name to use instead of guid, for better readability.

This name does not have any impact on the Code-X workflow. However, it should correlate with name.

major

The exact major version number of the referenced <project/>.

The major versions of the dependency and the referenced project must match exactly.

If not specified, the major version number will be 1.

minor

The minimum minor version number of the referenced <project/>.

The minor version of the dependency must be less than or equal to the minor version of the referenced <project/>.

If not specified, the minor version number will be 0.

<external/>

Defines an external library, which is provided as a separate .psi or .api file.

<external/>
Parent

<codex/>

Children

<project-id/> - exactly one

Attributes

path - exactly one

<external path="...">
  <project-id/>
</external>

path

The file path of the .psi or .api file which represents the external library.

If relative, resolves against $(BaseDir).

Since .api files have a smaller file size, the Code-X workflow will finish more quickly. Also, they will not expose any implementation details, as they contain only those parts of the code model which belong to the public API.

<options/>

This section lists the <options/> that may be configured for the Cpu-X Workflow.

Table 3. Allowed option targets for Cpu-X
Option Allowed in <module/> Allowed in <target/> Used by language

"BuggyCode"

yes

yes

any

"Encoding"

yes

yes

any

"IndentChar"

yes

yes

any

"IndentCount"

yes

yes

any

"IndentWidth"

yes

yes

any

"NamingStyle"

yes

no

any

"NoExport"

yes

yes

CPP

"Obfuscate"

yes

yes

any

"PrecompiledHeader"

yes

yes

CPP

Allowed options that are present in <target/> will override options that are present in <module/>.

"BuggyCode"

This custom option enables ("yes") or disables ("no") output of buggy code.

Defaults to "no".

Buggy code is a defined as the modification of functional code:

  • The structural design remains unchanged (namespaces, types and members).

  • The program flow (i.e. statements) remains unchanged.

  • Near-terminal expressions are modified in order to yield non-functional code.

The modifications should be hardly noticeable, so that a reviewer can still make statements about the code quality and structure. Furthermore, the modifications must not cause compiler errors and should not cause additional compiler warnings. This way, a developer can set up a full integration using the buggy code. After shaking off all integration issues, the developer can swap in the functional code.

"Encoding"

Name of the output encoding to use, may be one of the following:

  • "US-ASCII"

  • "ISO-8859-1"

  • "UTF-8"

  • "UTF-16BE"

  • "UTF-16LE"

Specifying a name that does not match any of the above ones (case-insensitively), the fallback "US-ASCII" will be used.

If the encoding has a preamble (for example BOM for Unicode), it will be used when writing generated files.

Defaults to "UTF-8".

"IndentChar"

Specified the indentation character to use.

Default to " " (space).

"IndentCount"

Specified the width of a single indentation level, measured in indentation characters.

Defaults to 2.

"IndentWidth"

Specified the width of a single indentation level, measured in text columns.

Defaults to 2.

"NamingStyle"

Specifies the naming style to use.

May be one of the following values, as indicated by the sub-section captions.

"Default"

This is the default naming style for language CPP and CS.

  • "UpperMixedCase" for type declarations

    • with "I…​" prefix for interface declarations

  • "UpperMixedCase" for public members

  • "lowerMixedCase" for non-public members

"Hungarian"

Based on "Default", adding name prefixes for type declarations and their members.

Name prefixes for type declarations:

  • "C…​" for classes

  • "S…​" for structures

  • "E…​" for enumerations

Name prefixes for members have two parts:

  • "m_" for instance members

  • "s_" for static members

The second prefix part depends on the member type:

"Java"

This is the default naming style for language JAVA.

Based on "Default", using the following rules for naming members:

  • "UPPER_CASE_NAME" for enum items, constants and static readonly fields.

  • "lowerMixedCase" for all other members

"NoExport"

This options disables ("yes") or enables ("no") export of symbols for dynamic linking.

Defaults to "no".

"Obfuscate"

This options enables ("yes") or disables ("no") obfuscation of non-public code.

If specified by <module/>, obfuscation will be configured accordingly.

Otherwise, if specified by <target/>, obfuscation will be configured accordingly.

Otherwise, obfuscation will be disabled.

When obfuscation is enabled, all code elements that are neither public nor protected will / be obfuscated in the following manner:

  • They will be renamed to X_, where X is a randomly chosen identifier.

  • All code comments are removed.

  • All non-significant whitespaces are removed.

Obfuscation will not be performed for local variables with identifiers that end with _keep. Code elements annotated with [Keep] will also not be obfuscated.

"PrecompiledHeader"

Name of the precompiled C++ header file to include at the top of each generated source file.

Defaults to "", i.e. no precompiled header is used.

Gpu-X Workflow

This section explains those Code-X Project File elements that belong to the Gpu-X workflow.

The Gpu-X workflow generates content in the $(OutputDir) according to the following descriptions.

Example 6. Common output structure for GLSL / HLSL
$(OutputDir)/glsl/
$(OutputDir)/hlsl/

Output for the GLSL / HLSL target language is generated in this subdirectory.

$(OutputDir)/glsl/GpuX.glsl
$(OutputDir)/hlsl/GpuX.hlsl

Gpu-X framework file for GLSL / HLSL

$(OutputDir)/glsl/{module}/**/*.glsl
$(OutputDir)/hlsl/{module}/**/*.hlsl

The shared GLSL / HLSL source code for each <module/> is output into this directory, where {module} is the module tag.

$(OutputDir)/glsl.{api}/{module}/*.glsl
$(OutputDir)/hlsl.{api}/{module}/*.hlsl

This is the output for shader entry points for a specific API target, where {api} is a token that has been defined by "APIs" and {module} stands for the module tag.

For the HLSL target language, additional content is generated.

Example 7. Additional output structure for HLSL
{build}/**/*.asm
{build}/**/*.cso

These files are treated as build output files and can optionally be cleaned via "Output.Clean". The {build} path is "Output.Build", resolved against $(ProjectDir), if relative.

{ide}/{api}/{api}.vcxproj
{ide}/{api}/{api}.vcxproj.filters

Visual Studio project files for compiling the HLSL source code are generated in these locations, where {ide} is the "Output.IDE" path (resolved against $(ProjectDir), if relative) and {api} is a token from "APIs".

The HLSL project files for Visual Studio are generated based on a template which has the following structure.

Visual Studio project file for HLSL
<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="Build" ToolsVersion="15.0" xmlns="...">
  <Import Project="[NuGet]\Microsoft.Direct3D.DXC.[Version]\..."
          Condition="..."/> (1)
  ...
  <PropertyGroup>
    <ProjectGuid>{[Guid]}</ProjectGuid> (2)
    <OutDir>$(ProjectDir)..\[Output]\</OutDir> (3)
    ...
  </PropertyGroup>
  <!-- =========================================== -->
  <!-- HLSL shaders (entry points for compilation) -->
  <!-- =========================================== -->
  <ItemGroup>
    <FxCompile Include="[InputFile]" ShaderType="..."
               ObjectFileOutput="[OutputFile1]"
               AssemblerOutputFile="[OutputFile2]"/> (4)
    ...
  </ItemGroup>
  ...
  <!-- =========================================== -->
  <!-- HLSL compiler options -->
  <!-- =========================================== -->
  ...
  <ItemDefinitionGroup>
    <FxCompile>
      <AdditionalOptions>[Options]</AdditionalOptions> (5)
      ...
      <ShaderModel>[Model]</ShaderModel> (6)
      ...
    </FxCompile>
  </ItemDefinitionGroup>
  ...
</Project>
1 [NuGet] locates the NuGet package for the DirectX compiler and may be specified via the "api:Vcxproj.NuGetPackagePath" option.

[Version] chooses the NuGet package version and can be set with "api:Vcxproj.DirectXCompilerVersion".
2 [Guid] is the project identifier and may be chosen arbitrarily, as long as it is unique within the solution. Use "api:Vcxproj.ProjectGuid" to specify it.
3 [Output] is the output directory for compiled shaders. It is derived from $(OutputDir) and "Output.Build".
4 [InputFile] is the path to a generated HLSL source file.
[OutputFile1] is the compiled shader binary.
[OutputFile2] is the shader assembly output.
5 [Options] specifies additional compiler options, see "api:Vcxproj.CompilerOptions"
6 [Model] chooses the Shader Model, see "api:Vcxproj.ShaderModel".

<options/>

This section lists the <options/> that may be configured for the Gpu-X Workflow.

Table 4. Allowed option targets for Gpu-X
Option Allowed in <module/> Allowed in <target/> Used by language

"Output.Build"

yes

no

any

"Output.Clean"

yes

no

any

"Output.IDE"

yes

no

any

"APIs"

no

yes

any

"api:Config[NAME]"

no

yes

any

"api:Vcxproj.CompilerOptions"

no

yes

HLSL

"api:Vcxproj.DirectXCompilerVersion"

no

yes

HLSL

"api:Vcxproj.NuGetPackagePath"

no

yes

HLSL

"api:Vcxproj.ProjectGuid"

no

yes

HLSL

"api:Vcxproj.ShaderModel"

no

yes

HLSL

Allowed options that are present in <target/> will override options that are present in <module/>.

"Output.Build"

Specifies the output directory for compiled shaders.

If not specified, $(OutputDir) is used instead.

"Output.Clean"

Specifies whether to clean compiler output files in "Output.Build" ("yes") or to leave them intact ("no").

Defaults to "no".

"Output.IDE"

Specifies the output directory for project files. Will be resolved against $(ProjectDir) if relative.

"APIs"

Chooses the target APIs for which to generate shader entry points.

Options that have names prefixed with a target API token (see api:*) apply only to that API. Without the prefix, an option applies to all target APIs.

Common values are:

  • dx9 → Direct3D 9

  • dx11 → Direct3D 11

  • dx12 → Direct3D 12

  • gl41 → OpenGL 4.1 Core Profile (or newer)

  • gles30 → OpenGLES 3.0 (or newer)

"api:Config[NAME]"

Specifies a compile-time configuration value, which is provided as a pre-processor macro in the generated source code files.

The Gpu-X compliant C# source accesses the configuration values via classes that are annotated with ConfigurationAttribute.

By setting this option, the default configuration values may be overridden.

"api:Vcxproj.CompilerOptions"

Additional options to pass to the shader compiler.

"api:Vcxproj.DirectXCompilerVersion"

Chooses the DirectX Shader Compiler version.

"api:Vcxproj.NuGetPackagePath"

Defines the location of the NuGet package storage, relative to the generated project file.

Defaults to "..\packages".

"api:Vcxproj.ProjectGuid"

An arbitrary but unique identifier in the form 00000000-0000-0000-0000-000000000000, to be used as the identifier for the generated project file.

"api:Vcxproj.ShaderModel"

Chooses the Direct3D Shader Model / Profile.