Projects.md

Project files and compiler configuration using dsconfig.xml

A "project" is a collection of Dassie source files that are all compiled into a single assembly. The Dassie project system is based on the central project file dsconfig.xml that lies in the root directory of every project and is used to configure compiler settings. The content of such a file looks like this:

<?xml version="1.0" encoding="utf-8"?>
<DassieConfig FormatVersion="1.0">
  <!--Settings, references and build profiles, see below-->
</DassieConfig>

The following documentation is about format version 1.0, which is the most recent version. Once the format is updated, the documentation for old versions will be archived in this repository.

Table of contents
General settings
Build profiles
Debug profiles
Ignoring compiler messages
References
Resources
Version information
Macros
Importing project files

General settings

These settings are at the top level of the XML tree and configure the behavior of the compiler as well as resources associated with the project.

Name	Possible values	Description	Notes
AdvancedErrorMessages	true or false	If true, every error message will visually display the code section where it originated.
ApplicationType	Console, WinExe, Installer or Library	Sets the application type and required subsystem of the program.
AssemblyFileName	Any string	Sets the file name of the generated assembly.
AssemblyManifest	Any string	The path to a manifest file that contains Windows-specific configuration.
BuildDirectory	Any string	Sets the directory containing build output files.
BuildProfiles	See below	Contains custom build profiles. See below for more info.
CacheSourceFiles	true or false	If true, caches source files to enable some incremental build capabilities.	Not yet finished.
CodeAnalyzers		A list of code analyzers that are run during the build.	Not yet supported.
CompilerMessageRedirectionFile	Any string	Sets the file the compiler writes logs and error messages to.
Configuration	Debug or Release	Determines which build configuration should be used.
DebugProfiles	See below	Contains custom debug profiles. See below for more info.	The Dassie compiler itself does not have any debugging capabilties. This setting is used by integrated development environments.
EmitPdb	true or false	Determines wheter to emit symbol information.
EnableMessageTimestamps	true or false	If true, all compiler messages include a timestamp.
EnableTips	true or false	If true, some errors and warnings will display additional information to help resolve the issue.
GenerateILFiles	true or false	If true, the compiler outputs human-readable .NET Intermediate Language (.il) files.
IgnoreAllMessages	true or false	Determines if all compiler messages (not warnings or errors) should be ignored.
IgnoreAllWarnings	true or false	Determines if all compiler warnings should be ignored.
IgnoredMessages	See below	A list of compiler messages and warnings that are ignored and will never be emitted. See below for more details.
IlOptimizations	true or false	Determines wheter to optimize generated IL (intermediate language).
ImplicitImports	true or false	Determines wheter or not the Dassie core library (Dassie.Core) and some modules such as stdout are implicitly imported into every file. true by default.
ImplicitTypeAliases	true or false	Determines wheter or not to enable default type aliases for primitive types (such as int32 for System.Int32). true by default.
IncludeDependencies	true or false	If true, all dependencies of the program are statically linked into a single file.
KeepIntermediateFiles	true or false	Determines wheter or not to delete intermediate source files, which are generated by the compiler as it rewrites high-level language constructs to a lower-level representation.
MacroDefinitions	See below	Sets user-defined macros. See below for more details.
MeasureElapsedTime	true or false	If true, the compilation time (in milliseconds) will be displayed after a build.
PersistentResourceFile	true or false	The Dassie compiler generates a .res file containing all native resources contained in the program. By default, this file is deleted after the build. When this setting is enabled, it is kept.
PrintExceptionInfo	true or false	If true, prints the whole stack trace of an exception when one occurs in the compiler.
References	See below	Used to configure dependencies. See below for more details.
Resources	See below	Used to configure native and managed resources. See below for more details.
RootNamespace	Any string	Sets the root namespace (determined by the export keyword) of the project. If empty, it is set to the project name.
Runtime	Jit or Aot	Determines which runtime to use for the execution of the generated executables. If this property is set to Aot, the compiler generates native executables for the current system and platform that are compiled ahead of time, along with regular .NET assemblies.	AOT compilation is currently only supported for Windows.
TreatWarningsAsErrors	true or false	If true, all compiler warnings are treated like errors.
Verbosity	0, 1 or 2	Sets the level of detail for compiler messages. At level 0, the only compiler messages are errors, warnings and code suggestions. At level 1, the compiler displays more advanced information about the build process. At level 2, the compiler provides in-depth diagnostic information.
VersionInfo	See below	Sets version information for the program. See below for more details.

Build profiles

Build profiles are used in combination with the dc build [BuildProfile] command and configure the scope of a build as well as custom settings and build events. Here is an example of a build profile:

<BuildProfiles>
  <BuildProfile Name="BuildAndLog">
    <Arguments>build</Arguments>
    <PostBuildEvents>
      <BuildEvent>
        <Command>echo. >> build.log &amp; echo Build finished at %time% on $(Date). >> build.log</Command>
      </BuildEvent>
    </PostBuildEvents>
  </BuildProfile>
</BuildProfiles>

The above example first launches the compiler with the default arguments and then appends some text to a log file after the build is completed. The following tables list all features supported by build events:

<BuildProfile> object

Name	Type	Allowed values	Description
Name	Attribute	Any string	Sets the name of the build profile.
Arguments	Element	Any string	Sets the arguments with which the compiler is invoked when the build profile is executed.
Settings	Element	Children of the <DassieConfig> object	Allows overriding the compiler settings from the table above.
PreBuildEvents	Element	A list of <BuildEvent>s	A list of build events executed before the project is being built.
PostBuildEvents	Element	A list of <BuildEvent>s	A list of build events executed after the project has been built.

<BuildEvent> object

Name	Type	Allowed values	Description
Critical	Attribute	true or false	If true, the compiler emits an error if the command returns a non-zero exit code. Otherwise, a warning is emitted. true by default.
Hidden	Attribute	true or false	If true, the command is run in the background without a visible output. false by default.
RunAsAdministrator	Attribute	true or false	If true, the command runs with full privileges. false by default.
WaitForExit	Attribute	true or false	If true, the compiler waits for the command to finish execution before continuing. If disabled, no error or warning messages regarding the exit code are emitted. false by default.
Command	Element	Any string	The command that is executed when the build event is run.

Debug profiles

Debug profiles are used by a debugging environment to configure arguments passed to the debuggee. Their markup structure looks like this:

<DebugProfiles>
  <DebugProfile Name="Default">
    <Arguments>file.txt</Arguments>
    <WorkingDirectory>.\child</WorkingDirectory>
  </DebugProfile>
</DebugProfiles>

<DebugProfile> has the following options:

Name	Type	Allowed values	Description
Name	Attribute	Any string	Sets the name of the profile.
Arguments	Attribute	Any string	Sets the command-line arguments passed to the debuggee.
WorkingDirectory	Attribute	Any string	Sets the directory the debuggee is launched in.

Ignoring compiler messages

The <IgnoredMessages> object is used to disable specific compiler error codes. Only information and warning messages can be ignored. To disable a message, add a child node corresponding to the kind of message that is to be disabled (information, warning) containing its error code. A list of error codes can be found here.

<IgnoredMessages>
  <Message>DS0070</Message>
</IgnoredMessages>

References

References are used to declare dependencies on assemblies, other Dassie projects or NuGet packages. Here is an example:

<References>
  <AssemblyReference>C:\libs\sdk.dll</AssemblyReference>
  <ProjectReference>%userprofile%\Projects\Library\dsconfig.xml</ProjectReference>
  <PackageReference Version="2.4.1">Package01</PackageReference>
</References>

The structure of these elements is described below.

<AssemblyReference> object

Name	Type	Allowed values	Description
CopyToOutput	Attribute	true or false	Determines wheter or not to copy the referenced file to the build output directory. true by default.
	Text	Any string	The path to the referenced file.

<ProjectReference> object

Name	Type	Allowed values	Description
CopyToOutput	Attribute	true or false	Determines wheter or not to copy the output of the referenced project to the build output directory. true by default.
	Text	Any string	The project file of the referenced project.

<PackageReference> object

Name	Type	Allowed values	Description
Version	Attribute	Any string	Determines which version of the package to reference.
	Text	Any string	The NuGet package ID of the referenced package.

Resources

There are two kinds of resources which can be included in a .NET assembly: Native (unmanaged) resources, which are stored in the .rsrc section of the PE file and are handled by the operating system, and managed resources that are handled by the .NET runtime. Here is an example:

<Resources>
  <UnmanagedResource>version.res</UnmanagedResource>
  <ManagedResource Name="Painting">image.png</ManagedResource>
</Resources>

These two types of resources have the following options:

<UnmanagedResource> object

Name	Type	Allowed values	Description
	Text	Any string	The path to the resource file.

<ManagedResource> object

Name	Type	Allowed values	Description
Name	Attribute	Any string	An alias that identifies the resource inside the program.
	Text	Any string	The path to the resource file.

Version information

Version information is used to display metadata about the program. It is visible in the 'Details' tab of a file's properties in Windows.

<VersionInfo>
  <Description>My program</Description>
  <Copyright>(C) 2024 My company</Copyright>
</VersionInfo>

These fields are supported by the <VersionInfo> object:

Name	Description
Description	A short description of the application.
Product	The product name of the application.
InternalName	The internal name of the application.
Company	The author of the application.
Copyright	A copyright string.
Trademark	Trademarks owned by the company.
Version	The product version of the application.
FileVersion	The file version of the application.

Macros

Macros are identifiers that are replaced with a specific value by the compiler before the start of the compilation. In addition to a set of predefined macros, a project file can contain custom macro declarations. Macro names are always case-insensitive. Here is an example of how macros are used:

<VersionInfo>
  <!--Assuming the year is 2024, this will be expanded to "(C) 2024 My company".-->
  <Copyright>(C) $(Year) My company</Copyright>
</VersionInfo>

Predefined macros

Macro name	Description
$(Time)	The current time at the start of the build, formatted as HH:mm.
$(TimeExact)	The current time at the start of the build, formatted as HH:mm:ss.ffff.
$(Date)	The current date.
$(Year)	The current year.
$(CompilerDirectory)	The path to the directory containing the Dassie Compiler executable.
$(CompilerPath)	The path to the Dassie Compiler executable (dc.dll).
$(ProjectDir)	The absolute path to the root directory of the current project.
$(ProjectName)	The name of the current project.
$(OutputDir)	The absolute path to the build output directory of the current project.

Important

Be careful when using the $(Time) and $(TimeExact) macros inside build events. Since all macros are evaluated before the build starts, the value of these macros will stay the same between pre-build and post-build events. On Windows, you can use the %time% variable to accurately retrieve the current time instead.

Custom macros

Custom macros are contained in the <MacroDefinitions> tag. Here is an example of how to use them:

<MacroDefinitions>
  <Define Macro="Author">My company</Define>
</MacroDefinitions>

<VersionInfo>
  <Company>$(Author)</Company>
</VersionInfo>

Importing project files

The Import attribute can be used on the <DassieConfig> object to specify a configuration file to inherit settings from. When the compiler encounters this attribute, it loads the specified configuration file and applies all settings to the current configuration file. If the current file already contains a setting that is set by the imported configuration file, the inherited value is overwritten.

<!--measurements.xml-->
<DassieConfig>
  <MeasureElapsedTime>true</MeasureElapsedTime>
</DassieConfig>

<!--dsconfig.xml-->
<DassieConfig Import="measurements.xml">
  <ApplicationType>Library</ApplicationType>
  <!--...-->
</DassieConfig>

Besides configuration files, the Import attribute also supports configuration providers from compiler extensions.