io.extendreality.malimbe

Malimbe

A collection of tools to simplify writing public API components in Unity.

Introduction

Malimbe is a collection of tools to simplify writing public API components in Unity.

By taking the assemblies that are created by build tools and changing the assembly itself, repetetive boilerplate can be reduced, new functionality can be introduced and logic written as part of the source code can be altered. This process is called Intermediate Language (IL) weaving and Malimbe uses Fody to do it.

Malimbe helps running Fody and Fody addins without MSBuild or Visual Studio and additionally offers running them inside Unity by integrating with Unity's compilation and build pipeline. Multiple weavers come with Malimbe to help with boilerplate one has to write when creating Unity components that are intended for public consumption. This includes a form of "serialized properties", getting rid of duplicated documentation through XML documentation and the [Tooltip] attribute as well as weavers that help with ensuring the API is able to be called from UnityEvents.

Releases

Branch	Version	Explanation
latest		Stable, production-ready
next		Experimental, not production-ready

Releases follow the Semantic Versioning (SemVer) system.

Getting Started

Please follow these steps to install the package using a local location until Unity's Package Manager (UPM) allows third parties to publish packages to the UPM feed:

1. Download a release from the Releases page and extract it into your folder you use to keep your packages. It is recommended to make that folder part of your project and therefore version controlled.
2. Open your Unity (>= 2018.3) project and follow Unity's instructions on how to add the package to your project using UPM.
3. Anywhere in your Unity project add a FodyWeavers.xml file.
4. Configure the various weavers Malimbe offers, e.g.:

   <?xml version="1.0" encoding="utf-8"?>
   
   <Weavers>
     <Malimbe.FodyRunner>
       <LogLevel>Error</LogLevel>
     </Malimbe.FodyRunner>
     <Malimbe.SerializedProperty/>
     <Malimbe.ClearPropertyMethod>
       <NamespaceFilter>^My.Namespace.Example</NamespaceFilter>
     </Malimbe.ClearPropertyMethod>
     <Malimbe.ValidatePropertiesMethod>
       <NamespaceFilter>^My.Namespace.Example</NamespaceFilter>
     </Malimbe.ValidatePropertiesMethod>
     <Malimbe.XmlDocumentationToFieldTooltip>
       <NamespaceFilter>^My.Namespace.Example</NamespaceFilter>
     </Malimbe.XmlDocumentationToFieldTooltip>
   </Weavers>
   

   As with any Fody weaver configuration the order of weavers is important in case a weaver should be applying to the previous weaver's changes.

Additional weavers are supported. To allow Malimbe's Unity integration to find the weavers' assemblies they have to be included anywhere in the Unity project or in one of the UPM packages the project uses.

What's in the Box

Malimbe is a collection of tools. Each project represents a solution to a specific issue:

• FodyRunner: A standalone library that allows running Fody without MSBuild or Visual Studio.

  • Use the XML element LogLevel to specify which log messages should be sent to the logger instance. Valid values are

    • None (or don't specify LogLevel)
    • Debug
    • Info
    • Warning
    • Error
    • All

    Separate multiple levels by using multiple XML elements or separate inside an XML element by using any form of whitespace including newlines or commas.

• FodyRunner.UnityIntegration: Weaves assemblies in the Unity Editor after Unity compiled them as well as builds. The weaving is done by utilizing FodyRunner.
  • There is no need to manually run the weaving process. The library just needs to be part of a Unity project (configured to only run in the Editor) to be used. It hooks into the various callbacks Unity offers and automatically weaves any assembly on startup as well as when they change.
  • Once the library is loaded in the Editor a menu item Tools/Malimbe/Weave All Assemblies allows to manually trigger the weaving process for all assemblies in the current project. This is useful when a FodyWeavers.xml file was changed.
• SerializedProperty.Fody: A Unity-specific weaver. Ensures the backing field for a property annotated with [SerializedProperty] is serialized. If a T SetPropertyName(T, T) method exists it will be used in the property's setter before existing instructions.
  • Annotate a property with [SerializedProperty] to use this. Note that the attribute's constructor allows specifying whether the backing field should be hidden in the Unity inspector (false by default). Hiding the property from the inspector (e.g. in the UnityEvent listener picker) is not supported by Unity.
  • Optionally write T SetPropertyName(T, T) methods that act as a setter addition on the same type that declares the property (of type T). A call to this method will be added to the start of the existing setter. The accessibility level of the method doesn't matter and the name lookup is case insensitive.
  • If the property's backing field doesn't use [SerializeField] it will be added.
  • If the property is an auto-implemented property the backing field will be renamed to match the property's name for viewing in the Unity inspector. Since C# doesn't allow multiple members of a type to share a name the backing field's name will differ in the first character's case. E.g.:
    • int Counter { get; set; } will use a backing field called counter.
    • bool isValid { get; private set; } will use a backing field called IsValid.
• ClearPropertyMethod.Fody: A generic weaver. Creates ClearProperty() methods for any property that is of reference type and has a setter. Sets the property via its setter to null in this new method.
  • The weaver only runs on types that match a namespace. Specify the namespaces to act on via (multiple) XML elements called NamespaceFilter. The elements' values are used as (.NET Standard's) regular expressions.
  • In case the method already exists the additional instructions will be weaved into the end of the method. The method name lookup is case insensitive.
• ValidatePropertiesMethod.Fody: A generic weaver (though made for Unity). Ensures there's an public OnValidate() method for any type that has properties with setters. For each property it does Property = Property; in this new method.
  • The weaver only runs on types that match a namespace. Specify the namespaces to act on via (multiple) XML elements called NamespaceFilter. The elements' values are used as (.NET Standard's) regular expressions.
  • Instead of OnValidate the method name can be customized with the XML attribute MethodName, e.g.:

      <Malimbe.ValidatePropertiesMethod MethodName="Validate">
        <NamespaceFilter>^My.Namespace.Example</NamespaceFilter>
      </Malimbe.ValidatePropertiesMethod>
    

  • In case the method already exists the additional instructions will be weaved into the end of the method. The method name lookup is case insensitive.
  • If necessary the method and the base type's method will be adjusted to override the method of the same name. Accessibility levels are also adjusted as needed.
• XmlDocumentationToFieldTooltip.Fody: A generic weaver (though made for Unity). Looks up the XML <summary> documentation for any field that is public or uses [SerializeField] and ensures [Tooltip] is used on that field with that summary.
  • The weaver only runs on types that match a namespace. Specify the namespaces to act on via (multiple) XML elements called NamespaceFilter. The elements' values are used as (.NET Standard's) regular expressions.
  • Instead of TooltipAttribute the attribute can be customized with the XML attribute FullAttributeName, e.g.:

      <Malimbe.XmlDocumentationToFieldTooltip FullAttributeName="Some.Other.Namespace.DocumentationAttribute">
        <NamespaceFilter>^My.Namespace.Example</NamespaceFilter>
      </Malimbe.XmlDocumentationToFieldTooltip>
    

    The attribute needs to have a constructor that takes a string parameter and nothing else. Note that the attribute name has to be the full type name, i.e. prefixed by the namespace.
  • In case the attribute already exists on the field it will be replaced.
• UnityPackaging: Outputs a ready-to-use folder with the appropriate hierarchy to copy into a Unity project's Asset folder. The output includes both the Unity integration libraries as well as all weavers listed above.

Contributing

If you want to raise a bug report or feature request please follow SUPPORT.md.

While we intend to add more features to Malimbe when we identify a need or use case, we're always open to take contributions! Please follow the contribution guidelines found in CONTRIBUTING.md.

Naming

Inspired by Fody's naming the name "Malimbe" comes from the small birds that belong to the weaver family Ploceidae.

Tools and Products Used

• Fody

License

Malimbe is released under the MIT License.

Third-party notices can be found in THIRD_PARTY_NOTICES.md

Changelog

2.0.0 (2019-01-07)

Bug Fixes

• Runner: don't leak for already processed assemblies (159e88a)
• Runner: gracefully fail for unfound assemblies (f0b60f9)
• Runner: prevent access to disposed closure (8ead72b)
• SerializedProperty: help serializing properties, not fields (40b6511)
• UnityIntegration: only weave each assembly once (cbfd2e8)
• UnityIntegration: unnecessary creation of an intermediate list (6d65c74)
• UnityIntegration: weave all assemblies on load (d23bacb)

Features

• UnityIntegration: allow weaving all assemblies manually (b87448b)
• UnityIntegration: show progress when weaving all assemblies (2f1bb4c)

BREAKING CHANGES

• SerializedProperty: Fields can no longer be "changed" into properties. Instead of using a field and annotating it with FieldToPropertyAttribute use a property and annotate it with SerializedPropertyAttribute. Auto-implemented properties as well as regular ones are supported and the only requirement is to have a getter and setter (of any accessibility level).