mob-sakai/CSharpCompilerSettingsForUnity

C# Compiler Settings For Unity

:warning: NOTE: Do not use the obsolete tags and branches to reference the package. They will be removed in near future. :warning:

Change the C# compiler (csc) used on your Unity project, as you like!

<< Description | Installation | Usage | Contributing >>

Description

A good news! Unity 2020.2.0a12 or later now supports C# 8.0!

Many developers (including you!) have been eagerly awaiting support for C# 8.0.
C# 8.0 includes some features and some useful syntax-sugars:

• Readonly members
• Default interface methods
• Pattern matching enhancements:
  • Switch expressions
  • Property patterns
  • Tuple patterns
  • Positional patterns
• Using declarations
• Static local functions
• Disposable ref structs
• Nullable reference types
• Asynchronous streams
• Asynchronous disposable
• Indices and ranges
• Null-coalescing assignment
• Unmanaged constructed types
• Stackalloc in nested expressions
• Enhancement of interpolated verbatim strings

However, unfortunately, there are no plans to backport to Unity 2020.1 or earlier...

This package changes the C# compiler (csc) used on your Unity project, to support C# 8.0, C# 9.0 and more.
Let's enjoy new C# features with your Unity project!

Features

• Easy to use.
  • This package is out of the box!
• Change the C# compiler (csc) used on your Unity project.
  • Change the nuget package name.
    • Microsoft.Net.Compilers: Official compiler (default in legacy Unity, run on Unity built-in mono)
    • Microsoft.Net.Compilers.Toolset: Official compiler (default in modern Uniity, run on dotnet)
      • Resolve the issue #2
    • OpenSesame.Net.Compilers: Allows access to internals/privates in other assemblies (run on Unity built-in mono)
    • OpenSesame.Net.Compilers.Toolset: Allows access to internals/privates in other assemblies (run on dotnet)
      • Resolve the issue #2
    • Or, your custom nuget package
  • Change the nuget package version.
    • 3.4.0: C# 8.0 Supported.
    • 3.5.0: C# 8.0 Supported. (default in Unity 2020.2.0)
    • 3.6.0: C# 8.0 Supported.
    • 3.7.0: C# 8.0 Supported.
    • 3.8.0 (preview): C# 9.0 Supported.
    • 3.9.0: C# 9.0 Supported. (default in Unity 2021.2.0)
    • 3.10.0: C# 9.0 Supported.
    • 3.11.0: C# 9.0 Supported.
    • 4.0.1: C# 10.0 Supported.
    • For other versions, see the nuget package page above.
  • Change the C# language version.
    • 7.0
    • 7.1
    • 7.2
    • 7.3
    • 8.0 (default in Unity 2020.2.0)
    • 9.0 (default in Unity 2021.2.0)
    • 10.0 (latest)
• Add the scripting define symbols based on language version on compiling.
  • e.g. CSHARP_7_3_OR_LATER, CSHARP_8_OR_LATER, CSHARP_9_OR_LATER ...
• Change the C# compiler settings for each *.asmdef file.
  • Portability: The assembly works even in the projects that do not have this package installed.
    • The best option when distributing as a package.
  • Publish as Dll: Published dll works without this package.
  • Modify the scripting define symbols for each *.asmdef file.
    • Add/Remove specific symbols separated with semicolons (';') or commas (',').
    • The symbols starting with '!' will be removed.
    • e.g. SYMBOL_TO_ADD;!SYMBOL_TO_REMOVE;...
• Modify langversion property in *.csproj file.
• If dotnet is required, it will be installed automatically.
• CompilerType.BuiltIn compiler option to disable this plugin.
• Enable Logging option to display compilation log.
• Nullable option to enable Nullable reference types (C# 8.0).
  • enable: The nullable annotation context is enabled. The nullable warning context is enabled.
    • Variables of a reference type, string for example, are non-nullable. All nullability warnings are enabled.
  • warnings: The nullable annotation context is disabled. The nullable warning context is enabled.
    • Variables of a reference type are oblivious. All nullability warnings are enabled.
  • annotations: The nullable annotation context is enabled. The nullable warning context is disabled.
    • Variables of a reference type, string for example, are non-nullable. All nullability warnings are disabled.
  • disable: The nullable annotation context is disabled. The nullable warning context is disabled.
    • Variables of a reference type are oblivious, just like earlier versions of C#. All nullability warnings are disabled.
• Analyzer/Source Generator Packages option to analyze/generate your code on compile.

Feature plans

• Show package description.

NOTE: Please do so at your own risk!

https://forum.unity.com/threads/unity-c-8-support.663757/page-2#post-5738029

Unity doesn't support using your own C# compiler. While this is possible, it is not something I would recommend, as we've not tested customer C# compiler versions with Unity.

Installation

Requirement

• Unity 2018.3 or later

via OpenUPM

This package is available on OpenUPM.
After installing openupm-cli, run the following command

openupm add com.coffee.csharp-compiler-settings

via Package Manager

Find the manifest.json file in the Packages directory in your project and edit it to look like this:

{
  "dependencies": {
    "com.coffee.csharp-compiler-settings": "https://github.com/mob-sakai/CSharpCompilerSettingsForUnity.git",
    ...
  },
}

To update the package, change suffix #{version} to the target version.

• e.g. "com.coffee.csharp-compiler-settings": "https://github.com/mob-sakai/CSharpCompilerSettingsForUnity.git#1.0.0",

Or, use UpmGitExtension to install and update the package.

Usage

Configure C# compiler settings for the project

1. Open project setting window. (Edit > Project Settings)
   
2. Select C# Compiler tab
3. Set Compiler Type to Custom Package, to use custom compiler package.
   
4. Input Package Name, Package Version, Language Version for compilation.
   • See features section.
5. Press Apply button to save settings.
6. It will automatically request a recompilation.
   The selected nuget package will be used for compilation.
7. Enjoy!

The project setting asset for C# Compiler will be saved in ProjectSettings/CSharpCompilerSettings.asset.

Configure C# compiler settings for *.asmodef file

1. Select a *.asmodef file
2. Turn on Enable C# Compilier Settings to configure.
   
3. Set Compiler Type to Custom Package, to use custom compiler package.
4. Input Package Name, Package Version, Language Version and Modify Symbols for compilation.
   • See features section.
5. Press Apply button to save settings.

Reload: Reload C# compiler settings dll for the assembly.
Publish as dll: Publish the assembly as dll to the parent directory.

For C# 8.0 features

C# 8.0 features
samples

If you want to use the C# 8.0 features, set it up as follows:

• Package Name: Microsoft.Net.Compilers
• Package Version: 3.5.0 or later
• Language Version: latest or CSharp_8

Some features required external library.

• Async stream -> UniTask v2
  • Install to project.
• Indices and ranges -> IndexRange
  • Download nuget package and extract it.
  • Import lib/netstandard2.0/IndexRange.dll to project.
• Stackalloc in nested expressions -> System.Memory
  • Download nuget package and extract it.
  • Import lib/netstandard2.0/System.Memory.dll to project.

NOTE: Default interface methods feature is not available. It requires .Net Standard 2.1.

For C# 9.0 features

C# 9.0 features
samples

If you want to use the C# 9.0 features, set it up as follows:

• Package Name: Microsoft.Net.Compilers
• Package Version: 3.9.0 or later
• Language Version: latest or CSharp_9

NOTE: Some features is not available. It requires .Net 5.

For C# 10.0 features

C# 10.0 features
samples

If you want to use the C# 10.0 features, set it up as follows:

• Package Name: Microsoft.Net.Compilers.Toolset
• Package Version: 4.0.1 or later
• Language Version: latest or CSharp_10

NOTE: Some features is not available. It requires .Net 6.

Development Notes

How to update CSharpCompilerSettings

• See installation section to update package
• Click Project Settings > C# Compoler > Reload to reload all CSharpCompilerSettings_*.dll assemblies

For Unity 2021.1 or later

In Unity 2021.1 or later, the compile flow has changed significantly. (#11) The source code must pass both the built-in compiler and the custom compiler. Please use the CUSTOM_COMPILE directive as follows:

using System;
using NUnit.Framework;

namespace IgnoreAccessibility
{
    public class IgnoreAccessibilityContent
    {
        private int privateNumber = 999;
    }

    public class IgnoreAccessibilityTest
    {
        [Test]
        public void GetPrivateField()
        {
#if CUSTOM_COMPILE
            Assert.AreEqual(new IgnoreAccessibilityContent().privateNumber, 999);
#else
            throw new NotImplementedException();
#endif
        }
    }
}

How to include the asmdef in Packages directory

By default, asmdefs under Packages and Assets/Standard Assets/ are NOT compiled with the custom compiler package.
This is to prevent unintended compiler changes and to minimize the impact of compiler changes.
Packages (and store assets) should essentially be compiled with the default compiler.

If you want to compile an embedded package or your custom package with a custom compiler, set Packages/your_package_name/ instead of !Packages/.
See #12 for details.

Contributing

Issues

Issues are very valuable to this project.

• Ideas are a valuable source of contributions others can make
• Problems show where this project is lacking
• With a question you show where contributors can improve the user experience

Pull Requests

Pull requests are, a great way to get your ideas into this repository.
See CONTRIBUTING.md and sandbox branch.

Support

This is an open source project that I am developing in my spare time.
If you like it, please support me.
With your support, I can spend more time on development. :)

License

• MIT

Author

• mob-sakai

See Also

• GitHub page : https://github.com/mob-sakai/CSharpCompilerSettingsForUnity
• Releases : https://github.com/mob-sakai/CSharpCompilerSettingsForUnity/releases
• Issue tracker : https://github.com/mob-sakai/CSharpCompilerSettingsForUnity/issues
• Change log : https://github.com/mob-sakai/CSharpCompilerSettingsForUnity/blob/master/CHANGELOG.md
• Test Space : https://mob-sakai.testspace.com/spaces/130862/current