Using dsc

dsc is a command-line utility that builds D# projects with dependencies on the .net framework. It receives its input as command-line arguments. The meaning of these command-line arguments can either be inferred from there position, as in dsc Flame\Flame.dsc.dsproj, or they can be specified explicitly, as in dsc -source Flame\Flame.dsc.dsproj.

You can grab dsc the dsc binaries from the releases page.

Source files

Source files are passed to dsc by providing their paths as command-line arguments, or passing dsc the path of one or more projects. Said input files are formally given by making them arguments to the -source parameter, but they are usually provided by placing them immediately after the dsc command.

These files can be either .ds source files, or .dsproj projects that reference source files.

Here are some examples:

dsc Vector.ds -platform clr

is equivalent to

dsc -source Vector.ds -platform clr

and

dsc -platform clr -source Vector.ds

However, the following is invalid:

dsc -platform clr Vector.ds

in this scenario, Vector.ds is grouped with -platform clr Vector.ds, instead of being a separate option. dsc will not recognize it as a source file.

Prefix-based arguments

Prefix-based arguments can of course be used as an alternative way to pass typical arguments to the compiler, but they are mostly useful when specifying relatively rare requests and passing data to the back-end. This is a brief yet incomplete list of some of these prefixes:

• -source: defines source files. This is implicitly the first parameter, as described above. Note that invoking dsc with dsc Vector2.ds -platform clr -source VectorMath.ds will compile only VectorMath.ds.
• -target: The output file for the compilation process. If the process does not yield a single output file (which is possible when compiling source code to another programming language), this path is used as a relative path for the output files.
• -platform: The target platform. This is a unique identifier that specifies the compiler's output. Reasonable values that can be provided to this option:
• CLR (default - this target platform is used to build Flame, Flame.Compiler, Flame.Syntax and Flame.DSharp)
• Python (experimental - it is recommended you stick to reference and instance types)
• C++ (experimental - this back-end does not yet support all ICodeGenerator features, and may generate forward references in certain situations)
• contract: generates textual contracts and descriptions for your data structures.
• -make-project: this flag expects no arguments, and creates a .dsproj file based on the given compiler arguments and source file.
• -docs: expects one argument, and instructs the compiler to generate documentation based on the assembly that has been parsed. Allowed argument values are:
• xml/true: generates XML documentation.
• false/no/none/any other value (default): does not generate any documentation.
• -verify: expects one argument. This instructs the compiler to verify the assembly based on the aforementioned argument. Allowed argument values are:
• true (default): verify the assembly
• any other value: do not verify the assembly
• -file: expects no arguments. Indicates that, no matter the extension of the -source path, it must be treated as a single source file.
• -project: expects no arguments. Indicates that, no matter the extension of the -source path, it must be treated as a project file.
• -compileall: instructs the compiler to recompile the entire source assembly to the output path. Possible values are:
• true (default): the default build process is executed
• any other value: the compiler may omit members it does not find any references to.
• -docs-formatter: expects one argument. Defines which documentation comment formatter the back-end should use. This differs form the -docs option in the sense that -docs creates a separate documentation file, whereas -docs-formatter embeds them as comments in the generated source code. This flag is currently only supported by the C++ back-end. Possible values are:
• xml: generates XML documentation comments.
• doxygen: generates Doxygen documentation comments.
• any other value: uses the default, text contract-style formatter.
• default: uses the formatter specified by the back-end.
• -chat: expects one argument. Provides a way of managing the amount of feedback the compiler provides.
• none/zipit: no output except completion/failure messages.
• errors: no output except errors and completion/failure messages.
• warnings/warn: no output except warnings, errors and completion/failure messages.
• messages/silent: outputs messages, warnings and errors, as well as completion/failure notifications.
• loud/any other value (default): outputs all messages, warnings, errors and completion/failure notifications. The compiler's progress and current activity is also printed.

Passes

Passes are prefixed with -f, and operate on the compiler's intermediate representation. They can be turned on or off explicitly, though this should not be necessary: dsc will select passes when appropriate. Some passes included in dsc:

• -flower-yield: lowers yield return and yield break constructs to state machines. This requires a target environment that labels, enumerators and enumerables, and knows how to implement them. On by default when compiling with -platform clr.
• -fdead-code-elimination: eliminates unreachable code. If some of the removed code corresponds to a statement or expression defined by the user, a warning is raised. If a function does not always seem to resume control to the caller (it can do so by using a return, throw or yield break statement), a warning is logged, as well. On by default.

Including build options in .dsproj projects

Some build options, such as -docs, may be specified in the source .dsproj project by using an <Option/> tag.
For example:

<Option Key="docs" Value="xml" />

tells the compiler to generate XML documentation for the project.

Dependencies

dsc does not compile project dependencies automatically. It merely copies the compiled dependencies to its output path.

Examples

Compiling the variables example

VariablesExample.dsproj can easily be compiled to a .Net assembly by invoking dsc with:

dsc VariablesExample.dsproj

It is equally possible, however, to compile the same project to Python or C++ code by invoking dsc with:

dsc VariablesExample.dsproj -platform C++

or

dsc VariablesExample.dsproj -platform Python

respectively.

Compiling Flame

Flame can be compiled (assuming we are in the repository's root directory) by using:

dsc Flame\Flame.dsc.dsproj

More detailed instructions can be found on the Compiling Flame page.