{"id":18009858,"url":"https://github.com/kekyo/ilcompose","last_synced_at":"2025-03-26T14:31:35.812Z","repository":{"id":84090138,"uuid":"491375328","full_name":"kekyo/ILCompose","owner":"kekyo","description":"Compose partially implementation both .NET language and IL assembler into a single assembly.","archived":false,"fork":false,"pushed_at":"2023-11-18T05:30:34.000Z","size":298,"stargazers_count":17,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-21T23:22:21.268Z","etag":null,"topics":["cil","compose","ilasm","ilsupport","inline-asm","mixin","msil"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kekyo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-12T05:24:40.000Z","updated_at":"2025-02-25T23:45:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"64eaafe7-461e-4a5d-ab14-cfa3a0f94622","html_url":"https://github.com/kekyo/ILCompose","commit_stats":null,"previous_names":[],"tags_count":61,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kekyo%2FILCompose","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kekyo%2FILCompose/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kekyo%2FILCompose/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kekyo%2FILCompose/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kekyo","download_url":"https://codeload.github.com/kekyo/ILCompose/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245670739,"owners_count":20653413,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cil","compose","ilasm","ilsupport","inline-asm","mixin","msil"],"created_at":"2024-10-30T02:11:18.670Z","updated_at":"2025-03-26T14:31:35.797Z","avatar_url":"https://github.com/kekyo.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ILCompose\n\n![ILCompose](Images/ILCompose.100.png)\n\n[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)\n[![NuGet ILCompose](https://img.shields.io/nuget/v/ILCompose.svg?style=flat)](https://www.nuget.org/packages/ILCompose)\n[![CI build (main)](https://github.com/kekyo/ILCompose/workflows/.NET/badge.svg?branch=main)](https://github.com/kekyo/ILCompose/actions?query=branch%3Amain)\n\n----\n\n## What is this?\n\nCompose partially implementation both .NET language and IL assembler.\nAn improved implementation of the principles of [ILSupport](https://github.com/ins0mniaque/ILSupport).\nIf you are looking for an inline assembler for CIL/MSIL, here is a realistic solution.\n\nIn sample.cs:\n\n```csharp\nnamespace IL2C.BasicTypes\n{\n    public class System_Boolean\n    {\n        // Refer IL assembly\n        [MethodImpl(MethodImplOptions.ForwardRef)]\n        public static extern void ValueTypeTest();\n    }\n}\n```\n\nIn sample.il:\n```\n.class public IL2C.BasicTypes.System_Boolean\n{\n    .method public static void ValueTypeTest() cil managed\n    {\n        .maxstack 2\n        ldc.i4.s 123\n        box bool\n\n        ; ...\n\n        ret\n    }\n}\n```\n\nThese source code compose into one assembly by ILCompose.\nSemantically, it is similar to the C# partial class definition, but it does this at the CIL level.\n\n![Diagram](Images/diagram.png)\n\nAll CIL assemble source code (*.il) are automatically assembled by official dotnet IL assembler `ILAsm`.\n\nOnly you have to do install the NuGet package [ILCompose](https://www.nuget.org/packages/ILCompose) and ready to use!\n\n----\n\n## Environments\n\nSupported target platforms:\n\n* .NET 8, 7, 6, 5\n* .NET Core 3.1 to 2.0 (maybe to 1.0)\n* .NET Standard 2.1, 2.0 (maybe to 1.0)\n* .NET Framework 4.8 to 2.0 (maybe to 1.0)\n\nSupported building platforms:\n\n* dotnet SDK 8, 7, 6, 5, 3.1, 2.2 and 2.1 (on Windows and Linux)\n* .NET Framework 4.8 to 4.6.2 on Windows (With dotnet SDK installation)\n\n----\n\n## How to use\n\nIn short example:\n\n```bash\n$ dotnet new console\n$ dotnet add package ILCompose\n\n[Then write your code both *.cs and *.il ...]\n```\n\nSee fully sample code:\n\n* [Basic project](samples/ILCompose.Sample/)\n* [Applied unit test project](samples/ILCompose.UnitTestSample/)\n\n----\n\n## Choose IL assembler\n\nYou can choose IL assembler between:\n\n* [ILAsm.Managed](https://github.com/kekyo/ILAsm.Managed): Defaulted, no need to action.\n* [CoreCLR ILAsm](https://www.nuget.org/packages/Microsoft.NETCore.ILAsm/): Optional, need to set `\u003cILComposeUsingILAsmManaged\u003efalse\u003c/ILComposeUsingILAsmManaged\u003e` into `\u003cPropertyGroup\u003e`.\n* Your own `ilasm.exe`: Optional, need to set `\u003cILComposeILAsmToolPath\u003e` and `\u003cILComposeILAsmToolOptions\u003e`.\n\n### Why ILAsm.Managed is defaulted instead CoreCLR one?\n\nBecause CoreCLR ILAsm package contains many different sub packages included native binary each OS distributions.\nAnd [standard dynamic reference script technique has a problem](https://github.com/dotnet/runtime/blob/ed1595e2b10c32ed076d345567407ba1c081e1dd/src/coreclr/.nuget/Microsoft.NET.Sdk.IL/targets/Microsoft.NET.Sdk.IL.targets#L45),\ncould not effect MSBuild script conditions at running `dotnet restore` and `nuget restore` time except using Visual Studio IDE.\n\nIf you are concerned about the stock ILAsm, and in fact ILAsm.Managed fails to compile,\nyou can accept the above problem and use it.\n\n----\n\n## Insight\n\nILSupport is cumbersome because it requires custom build scripts to be incorporated into the your project.\nHowever, ILCompose is simply installation the NuGet package and builds everything automatically.\n\nWhen you install the NuGet package,\nthe CIL (*.il) file will have the `ILComposeTargetIL` build action set as follows:\n\n![ILComposeTargetIL](Images/vsproperties.png)\n\nBasically, it can be used in the same way as ILSupport.\n\nILSupport is realized using ILDasm and a string substitution technique.\nWhile ILCompose is realized using cecil, so the internal implementations are completely different.\n\nHere is where the problem was in ILSupport.\nThe following C# code with the `forwardref` attribute applied cannot apply the additional custom attributes\n(they must be written on the IL assembly source code side):\n\n```csharp\n// Refer IL assembly, all additional custom attribute will silently remove by ILSupport.\n[MethodImpl(MethodImplOptions.ForwardRef)]\npublic static extern void ValueTypeTest();\n```\n\nIt allows you to apply custom attributes normally, as shown below:\n\n```csharp\n// Refer IL assembly with custom attributes\n[Test]\n[Description(\"A value type test.\")]\n[MethodImpl(MethodImplOptions.ForwardRef)]\npublic static extern void ValueTypeTest();\n```\n\n### Automatic adjusting assembly references.\n\nWhen assembling your loose IL source code with implicit referenced assemblies,\n`ILAsm` will cause these warnings below.\n\nILAsm.Managed:\n\n```\nWarning -- Reference to undeclared extern assembly 'netstandard', adding.\nWarning -- Reference to undeclared extern assembly 'System.Runtime', adding.\nWarning -- Reference to undeclared extern assembly 'mscorlib', adding.\n```\n\nCoreCLR ILAsm:\n\n```\nwarning : Reference to undeclared extern assembly 'netstandard'. Attempting autodetect\nwarning : Reference to undeclared extern assembly 'System.Runtime'. Attempting autodetect\nwarning : Reference to undeclared extern assembly 'mscorlib'. Attempting autodetect\n\n...\n```\n\nSee also: [dotnet/runtime: ilasm cannot compile against different corlib names](https://github.com/dotnet/runtime/issues/7758)\n\nILCompose has no control these warning on `ILAsm`,\nbut ILCompose will resolve these inconsistent references in the final composite assembly.\nFinally, the primary assembly (the original output assembly of the project) is aggregated into referenced assemblies.\nFor example, `mscorlib.dll` for `net48` and `System.Runtime.dll` for `net6.0`.\n\nThis feature is disabled `\u003cILComposeAdjustAssemblyReferences\u003efalse\u003c/ILComposeAdjustAssemblyReferences\u003e` in `\u003cPropertyGroup\u003e` element.\n\n----\n\n## Limitation\n\n* `\u003cDebugType\u003e` `embedded` is not supported.\n* If no corresponding forwardref method is defined for a CIL method on the source code, that CIL method will not be composed.\n\n----\n\n## Background\n\nThis project was created in [IL2C](https://github.com/kekyo/IL2C.git),\nthere was a need for IL code management.\nIn IL2C, CIL unit test code was composed into .NET assemblies using ILSupport, but:\n\n* The portion of [NUnit](https://nunit.org/) that relies on\n  [Custom attributes extensions](https://docs.nunit.org/articles/nunit/extending-nunit/Custom-Attributes.html) has\n  caused problems on the JetBrains Rider's test explorer, and I wanted to eliminate this. I was thinking of stopping the use of custom attributes extensions.\n* In that case, needed to resolve a problem with custom attributes being removed\n  by the `forwardref` attribute in ILSupport.\n* To begin with, the ILSupport script was being used with considerable modifications, which caused maintainability problems.\n\nRelated: [IL2C issue #100: Will upgrade basis environments.](https://github.com/kekyo/IL2C/issues/100)\n\nTherefore, I developed this package as a general-purpose package.\n\n----\n\n## License\n\nCopyright (c) Kouji Matsui (@kozy_kekyo, @kekyo@mastodon.cloud)\n\nLicense under Apache-v2.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkekyo%2Filcompose","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkekyo%2Filcompose","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkekyo%2Filcompose/lists"}