diff --git a/README.md b/README.md index e846f61..ee8a9bd 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,9 @@ Telescope 是一套预编译框架。 +|[中文](README.md)|[English](docs/en-us/README.md)| +|-|-| + 当项目安装 Telescope 了之后,项目中即可开始书写预编译代码。通过执行这些预编译代码,项目可以在编译期间执行一些平时需要在运行时执行的代码。这种方式能够将耗时的运行时代码迁移到编译期执行,大幅度提升运行时性能。 ![](https://github.com/dotnet-campus/Telescope/workflows/.NET%20Core/badge.svg) @@ -93,4 +96,4 @@ internal partial class Program ## 为此项目开发 -非常期望你能加入到 Telescope 的开发中来,请阅读 [如何为 Telescope 贡献代码](/docs/how-to-contribute.md) 了解开发相关的约定和技术要求。 +非常期望你能加入到 Telescope 的开发中来,请阅读 [如何为 Telescope 贡献代码](/docs/zh-hans/how-to-contribute.md) 了解开发相关的约定和技术要求。 diff --git a/docs/en-us/README.md b/docs/en-us/README.md new file mode 100644 index 0000000..7544d53 --- /dev/null +++ b/docs/en-us/README.md @@ -0,0 +1,88 @@ +# Telescope + +Telescope is a pre-compilation framework. + +Once Telescope is installed in a project, you can start writing pre-compilation code in the project. By executing these pre-compilation codes, the project can execute some codes during compilation that usually need to be executed at runtime. This method can migrate time-consuming runtime code to compile-time execution, greatly improving runtime performance. + +## Telescope.SourceGeneratorAnalyzers + +The version of Telescope using SourceGenerator source code generator + +It can be used to export specified types + +### Usage + +Supports multiple different export methods + +#### Partial Method Style + +This is the recommended method + +Define partial methods in the partial class, mark the partial method with the `dotnetCampus.Telescope.TelescopeExportAttribute` attribute, and the return value includes export conditions, as follows + +```csharp +internal partial class Program +{ + [dotnetCampus.Telescope.TelescopeExportAttribute()] + private static partial IEnumerable<(Type type, F1Attribute attribute, Func creator)> ExportFooEnumerable(); +} +``` + +The above code will export all types in the current project that are marked with `F1Attribute` and inherit `Base`. After the Telescope source code generator, the code generated is roughly as follows + +```csharp + [global::System.CodeDom.Compiler.GeneratedCode("dotnetCampus.Telescope.SourceGeneratorAnalyzers", "1.0.0")] + internal partial class Program + { + private static partial IEnumerable<(Type type, F1Attribute attribute, Func creator)> ExportFooEnumerable() + { + yield return (typeof(F2), new F1Attribute() + { + + }, () => new F2()); + yield return (typeof(F3), new F1Attribute() + { + + }, () => new F3()); + } + } +``` + +Advanced usage: + +You can add the IncludeReference attribute to TelescopeExportAttribute to export all types of referenced assemblies that meet the conditions, as follows + +```csharp +internal partial class Program +{ + [dotnetCampus.Telescope.TelescopeExportAttribute(IncludeReference = true)] + private static partial IEnumerable<(Type type, F1Attribute attribute, Func creator)> ExportFooEnumerable(); +} +``` + +It is only recommended to add the `IncludeReference = true` attribute in the entry assembly, because once this attribute is added, any changes to the referenced assembly may cause the source code generator to execute repeatedly, reducing VisualStudio performance + +#### Assembly Marking + +This is the traditional implementation method of Telescope. In the project where you need to export types, mark the `dotnetCampus.Telescope.MarkExportAttribute` attribute, as follows + +```csharp +[assembly: dotnetCampus.Telescope.MarkExportAttribute(typeof(Base), typeof(FooAttribute))] +``` + +After marking, the `dotnetCampus.Telescope.__AttributedTypesExport__` type will be automatically generated, and you can directly use it in the code, as follows + +```csharp + var attributedTypesExport = new __AttributedTypesExport__(); + ICompileTimeAttributedTypesExporter exporter = attributedTypesExport; + foreach (var exportedTypeMetadata in exporter.ExportAttributeTypes()) + { + Console.WriteLine(exportedTypeMetadata.RealType.FullName); + } +``` + +You can also use the `dotnetCampus.Telescope.AttributedTypes` helper class to get all exported types + +## Develop for this project + +We very much hope that you can join the development of Telescope, please read [How to Contribute to Telescope](/docs/how-to-contribute.md) to understand the development related conventions and technical requirements. diff --git a/docs/README.md b/docs/zh-hans/README.md similarity index 100% rename from docs/README.md rename to docs/zh-hans/README.md diff --git a/docs/how-to-contribute.md b/docs/zh-hans/how-to-contribute.md similarity index 100% rename from docs/how-to-contribute.md rename to docs/zh-hans/how-to-contribute.md