From ab36afaeb6c2d81fda2b6d2ccaf8691513103471 Mon Sep 17 00:00:00 2001 From: Ezekiel Warren Date: Mon, 5 Aug 2024 11:25:36 -0700 Subject: [PATCH] feat: codegen docs (#167) * feat: codegen docs * fix: typos --- src/app/app.component.html | 2 +- src/app/docs/BUILD.bazel | 1 + src/app/docs/docs-routing.module.ts | 13 +- src/app/docs/docs.component.html | 9 +- src/app/docs/extend/BUILD.bazel | 17 ++ .../docs/extend/build-recipe.component.html | 3 + src/app/docs/extend/build-recipe.component.ts | 7 + src/app/docs/extend/codegen.component.html | 253 ++++++++++++++++++ src/app/docs/extend/codegen.component.ts | 47 ++++ src/app/docs/extend/extend-routing.module.ts | 23 ++ src/app/docs/overview/overview.component.html | 25 +- src/search/searchable-page-infos.ts | 22 ++ src/tailwind.config.js | 3 + 13 files changed, 421 insertions(+), 4 deletions(-) create mode 100644 src/app/docs/extend/BUILD.bazel create mode 100644 src/app/docs/extend/build-recipe.component.html create mode 100644 src/app/docs/extend/build-recipe.component.ts create mode 100644 src/app/docs/extend/codegen.component.html create mode 100644 src/app/docs/extend/codegen.component.ts create mode 100644 src/app/docs/extend/extend-routing.module.ts diff --git a/src/app/app.component.html b/src/app/app.component.html index 0eda7d8f..40ea6d5b 100644 --- a/src/app/app.component.html +++ b/src/app/app.component.html @@ -33,7 +33,7 @@ Documentation diff --git a/src/app/docs/BUILD.bazel b/src/app/docs/BUILD.bazel index 214052c9..c204cc71 100644 --- a/src/app/docs/BUILD.bazel +++ b/src/app/docs/BUILD.bazel @@ -22,6 +22,7 @@ ng_project( "//:node_modules/@angular/router", "//src/app/docs/cpp-system-impl-wasm", "//src/app/docs/ecs", + "//src/app/docs/extend", "//src/app/docs/implementations", "//src/app/docs/lang", "//src/app/docs/overview", diff --git a/src/app/docs/docs-routing.module.ts b/src/app/docs/docs-routing.module.ts index fdb49b47..be82a89a 100644 --- a/src/app/docs/docs-routing.module.ts +++ b/src/app/docs/docs-routing.module.ts @@ -14,9 +14,13 @@ const routes: Routes = [ component: DocsComponent, children: [ { - path: 'overview', + path: '', component: OverviewComponent, }, + { + path: 'overview', + redirectTo: '', + }, { path: 'lang', component: LangComponent, @@ -84,6 +88,13 @@ const routes: Routes = [ m => m.SystemImplRoutingModule, ), }, + { + path: 'extend', + loadChildren: () => + import('./extend/extend-routing.module').then( + m => m.ExtendRoutingModule, + ), + }, ], }, ]; diff --git a/src/app/docs/docs.component.html b/src/app/docs/docs.component.html index bd79df40..9eb63f1e 100644 --- a/src/app/docs/docs.component.html +++ b/src/app/docs/docs.component.html @@ -1,7 +1,7 @@ Overview + + + Build Recipe + Codegen + diff --git a/src/app/docs/extend/BUILD.bazel b/src/app/docs/extend/BUILD.bazel new file mode 100644 index 00000000..c80dc63b --- /dev/null +++ b/src/app/docs/extend/BUILD.bazel @@ -0,0 +1,17 @@ +load("//tools:ng.bzl", "ng_project") + +package(default_visibility = ["//:__subpackages__"]) + +ng_project( + name = "extend", + srcs = glob([ + "*.ts", + "*.html", + ]), + deps = [ + "//:node_modules/@angular/common", + "//:node_modules/@angular/core", + "//:node_modules/@angular/router", + "//src/components/prism", + ], +) diff --git a/src/app/docs/extend/build-recipe.component.html b/src/app/docs/extend/build-recipe.component.html new file mode 100644 index 00000000..255e1e1c --- /dev/null +++ b/src/app/docs/extend/build-recipe.component.html @@ -0,0 +1,3 @@ +
+
TODO: build recipe docs
+
diff --git a/src/app/docs/extend/build-recipe.component.ts b/src/app/docs/extend/build-recipe.component.ts new file mode 100644 index 00000000..fdf04c63 --- /dev/null +++ b/src/app/docs/extend/build-recipe.component.ts @@ -0,0 +1,7 @@ +import {Component} from '@angular/core'; + +@Component({ + templateUrl: './build-recipe.component.html', + standalone: true, +}) +export class ExtendBuildRecipeComponent {} diff --git a/src/app/docs/extend/codegen.component.html b/src/app/docs/extend/codegen.component.html new file mode 100644 index 00000000..1bbb26ef --- /dev/null +++ b/src/app/docs/extend/codegen.component.html @@ -0,0 +1,253 @@ +
+
+

Ecsact Codegen

+

+ Codegen is a core part of what makes Ecsact possible. It's used for + programming language support, creating database schemas, optimizing + runtime implementations, or collecting general information about your + Ecsact files. +

+ +

How to use Ecsact Codegen

+

+ The typical way Ecsact codegen is used is via game engine integration + and/or the Ecsact CLI coupled with your + programming languages build system, but no matter where codegen is ran it + all boils down to + codegen plugins. +

+ +

Integrations

+

+ Ecsact game engine integrations likely run one or more codegen plugins to + better support Ecsact with the game engine. This can simply be language + wrappers/bindings or more detailed integral support. Typically these + codegen plugins are ran automatically when .ecsact change (if + recognized by the game engine.) +

+

+ For example the Unity integration uses the C# Ecsact codegen plugin to + generate .cs files to make using Ecsact easier with Unity. +

+

+ If you plan on making a custom engine integration please refer to the + custom integration start page. +

+ +

Bazel

+

+ The + rules_ecsact + repository is the official bazel support for Ecsact. The + ecsact_codegen bazel rule is the best way to get started + generating code. More documentation to come. +

+ +

Other Build Systems

+

+ You're likely familiar with some build system for the programming + language you use. Ideally the programming language(s) you use have an + official build system. At this time Ecsact is probably not + supported as a first class citizen, but integrating with your build system + with the Ecsact CLI should be pretty + straight forward. Simply execute the Escact CLI + codegen subcommand with your ecsact files and the plugins you + want: +

+ 

+			ecsact codegen your_ecsact_file.ecsact --plugin=your_plugin
+
+

+ See Ecsact CLI start page for more details. +

+ +

Well Known Codegen Plugins

+

+ The Ecsact core development team maintains various codegen plugins. If you + create a codegen plugin and want it displayed here please open a pull + request or create an issue at our + + open_in_new website repository. +

+ +

+ Available in the Ecsact SDK +

+

+ Plugins available in the Ecsact SDK can be listed with the + Ecsact CLI config subcommand: +

+ 

+			ecsact config builtin_plugins
+
+ + +

Codegen Plugins

+

+ Ecsact codegen plugins are dynamic libraries with 2 exported C functions. + Keep in mind during the development of Ecsact this API is likely to + change. +

+ +

ecsact_plugin_name

+

+ The first is the plugin 'name'. A plugin name is both a name and the + extension of the output file the plugin is responsible for generating. For + example if you had an Ecsact file called + example.ecsact and you generated code with a plugin with the + name my_plugin you would get a file named + example.ecsact.my_plugin. +

+ 
const char* ecsact_plugin_name();
+

+ The return value is a NULL-terminated string with static + storage. In C it simply would be something like this. +

+ 

+			const char* ecsact_plugin_name() {{'{'}}
+				return "my_plugin";
+			{{'}'}}
+
+ +

ecsact_plugin

+

+ The second function is the plugin 'entry point'. The entry point is called + once for every Ecsact package. When implementing your plugin you have + access to all the + meta module functions. + This gives you details about the various components, systems, fields and + more of the package. +

+ 

+			void ecsact_codegen_plugin(
+				ecsact_package_id,
+				ecsact_codegen_write_fn_t,
+				ecsact_codegen_report_fn_t
+			);
+
+

+ There are 2 functions that get passed into your entrypoint. A write + function and a report function. The write function is writes to the file + your generating and the report function is for reporting warnings and + errors to the user. +

+ +

+ The write function takes a pointer to some bytes and the length of those + bytes and returns void. +

+ 

+			void(const char*, int32_t);
+
+ +

+ The report function is similar to the write function except it also takes + a report type enum as the first parameter. +

+ 

+			void(ecsact_codegen_report_type, const char*, int32_t);
+
+ +

+ The report types mean different things. There is some wiggle room on what + they mean so it may vary depending on the environment you're codegen + plugin is running in. +

+ + + + + + + + + + + + + + + + + + + + + + + +
Report TypeDescription
ECSACT_CODEGEN_REPORT_INFO + Report some various information. May or may not be shown to the user. + Mostly used for debugging. +
ECSACT_CODEGEN_REPORT_WARNINGWarning that may or may not be shown to the user.
ECSACT_CODEGEN_REPORT_ERROR + An error has occurred, but codegen may still continue. Must be shown + to user. +
ECSACT_CODEGEN_REPORT_ERROR + An error has occurred and codegen may not continue. + Must be shown to user. +
+ +

Codegen C++ Wrapper

+

+ The C API can be a little daunting to use. The Ecsact core development + team uses a C++ wrapper for creating plugins. If you're using C++ to + develop your Ecsact plugin we highly recommend using it. To start using it + include the ecsact/codegen/plugin.hh header and construct the + ecsact::codegen_plugin_context object with the plugin's entry + point arguments. +

+ + 

+			#include "ecsact/codegen/plugin.hh" // C++ plugin wrapper
+			#include "ecsact/runtime/meta.hh"   // C++ meta module wrapper
+
+			extern "C" auto ecsact_codegen_plugin(
+				ecsact_package_id           pkg_id,
+				ecsact_codegen_write_fn_t   write_fn,
+				ecsact_codegen_report_fn_t  report_fn
+			) -> void {{'{'}}
+				auto ctx = ecsact::codegen_plugin_context{{'{'}}pkg_id, write_fn, report_fn{{'}'}};
+				
+				ctx.writef("hello\n"); // write to file
+				ctx.info("its me!"); // report something
+				
+				// Use the meta module C++ wrapper
+				for(auto comp_id : ecsact::meta::get_component_ids(ctx.package_id)) {{'{'}}
+					auto comp_name = ecsact::meta::component_name(comp_id);
+					ctx.writef("found component {{'{}'}}\n", comp_name);
+				{{'}'}}
+			{{'}'}}
+
+ +

+ The various ctx.* methods wrap around + open_in_new std::format + so the same rules apply for writing/printing out various types. +

+ +

+ There are other C++ utilities that the core team uses that can be found in + the + open_in_new C++ language support repository. +

+
+
diff --git a/src/app/docs/extend/codegen.component.ts b/src/app/docs/extend/codegen.component.ts new file mode 100644 index 00000000..51613306 --- /dev/null +++ b/src/app/docs/extend/codegen.component.ts @@ -0,0 +1,47 @@ +import {Component} from '@angular/core'; +import {PrismComponent} from '../../../components/prism/prism.component'; +import {RouterLink} from '@angular/router'; + +@Component({ + templateUrl: './codegen.component.html', + standalone: true, + imports: [PrismComponent, RouterLink], +}) +export class ExtendCodegenComponent { + readonly known_sdk_plugins = [ + { + href: 'https://github.com/ecsact-dev/ecsact_lang_cpp/tree/main/cpp_header_codegen', + title: 'General C++ header', + description: 'Generates structs for components and systems.', + }, + { + href: 'https://github.com/ecsact-dev/ecsact_lang_cpp/tree/main/systems_header_codegen', + title: 'C Systems Header', + description: + 'Generates a header with Ecsact system function declarations.', + }, + { + href: 'https://github.com/ecsact-dev/ecsact_lang_cpp/tree/main/cpp_systems_header', + title: 'C++ systems header', + description: + 'Generates convenient C++ wrappers around the C system implementations.', + }, + { + href: 'https://github.com/ecsact-dev/ecsact_lang_cpp/tree/main/cpp_systems_header', + title: 'C++ systems source', + description: + 'The implementation the C system implementations for the C++ systems header plugin.', + }, + { + href: 'https://github.com/ecsact-dev/ecsact_lang_csharp/tree/main/csharp_codegen', + title: 'General C#', + description: 'Generates C# structs for components and systems.', + }, + { + href: 'https://github.com/ecsact-dev/ecsact_lang_json/tree/main/json_codegen', + title: 'Json', + description: + 'Generates a JSON file that lists the various components and systems. Useful for tooling.', + }, + ] as const; +} diff --git a/src/app/docs/extend/extend-routing.module.ts b/src/app/docs/extend/extend-routing.module.ts new file mode 100644 index 00000000..592dc7d4 --- /dev/null +++ b/src/app/docs/extend/extend-routing.module.ts @@ -0,0 +1,23 @@ +import {NgModule} from '@angular/core'; +import {RouterModule} from '@angular/router'; +import {ExtendCodegenComponent} from './codegen.component'; +import {ExtendBuildRecipeComponent} from './build-recipe.component'; + +@NgModule({ + imports: [ + RouterModule.forChild([ + { + path: 'codegen', + pathMatch: 'full', + component: ExtendCodegenComponent, + }, + { + path: 'build-recipe', + pathMatch: 'full', + component: ExtendBuildRecipeComponent, + }, + ]), + ], + exports: [], +}) +export class ExtendRoutingModule {} diff --git a/src/app/docs/overview/overview.component.html b/src/app/docs/overview/overview.component.html index 28f30dc4..580ad84a 100644 --- a/src/app/docs/overview/overview.component.html +++ b/src/app/docs/overview/overview.component.html @@ -18,7 +18,7 @@
- Codegen + Codegen
+ + +
+ + + cookie-bite + Build Recipes + + + + + + shapes + Codegen + + +
diff --git a/src/search/searchable-page-infos.ts b/src/search/searchable-page-infos.ts index 3e7de6e8..37a2691f 100644 --- a/src/search/searchable-page-infos.ts +++ b/src/search/searchable-page-infos.ts @@ -95,4 +95,26 @@ export const searchablePageInfos: {[key: string]: PageInfo | undefined} = { keywords: ['tutorial', 'unity sync', 'learn unity', 'moving block'], title: 'Unity Moving Block Example', }, + '/docs/extend/build-recipe': { + category: PageCategory.Documentation, + keywords: [ + 'build', + 'recipe', + 'yaml', + 'yml', + 'build-recipe-bundle', + 'bundle', + 'programming', + 'code', + 'plugin', + ], + title: 'Build Recipe', + description: 'Learn about Ecsact build recipes', + }, + '/docs/extend/codegen': { + category: PageCategory.Documentation, + keywords: ['codegen', 'programming', 'code', 'plugin', 'C'], + title: 'Codegen', + description: 'Learn about Ecsact codegen', + }, }; diff --git a/src/tailwind.config.js b/src/tailwind.config.js index 08086b7e..701cf22f 100644 --- a/src/tailwind.config.js +++ b/src/tailwind.config.js @@ -25,6 +25,9 @@ module.exports = { logoSvgOutline: 'url(assets/logo-outline.svg)', flowDownSvg: 'url(assets/flow-down.svg)', }, + backgroundSize: { + half: '50%', + }, keyframes: { 'slide-down': { '0%': {transform: 'translateY(-100%)'},