brgen - BinaRy encoder/decoder GENerator

ネットワーク・プロトコルのパケットやファイルフォーマットなどの解析/生成のためのコードを吐くジェネレーター及びバイナリフォーマット定義言語

読み方: ビーアールジェン(英語圏向け)あるいはビーアールゲン(作者の読み方/ローマ字風/~~作者が勝手に言っているだけ~~)

the generators that generate encoder/decoder code for parse/create network packet, binary file, etc... and binary format definition language

Here are the pronunciations for brgen:

B-R-Gen (for English speakers)

Alternatively, B-R-Gehn (the author's (not means preferred for other people) pronunciation, with a Romanized(romaji) "gen" sound)

目標(Goal)

• enough to represent formats - 世の中にあるネットワークプロトコルフォーマットを表現するのに十分な表現力
• easy to write and read - 簡単に書ける/読める
• write once generate any language code - 一回書けば様々な言語で生成

Note

本プロダクトは開発途上のものです。使用したことによる効果は保証しかねます。また破壊的変更が予告なしに行われることがあります。 This product is still under development. We cannot guarantee the effectiveness of using this product. In addition, breaking changes may be made without notice.

~~現在こちらのリポジトリでサブプロジェクトの開発が進んでいます。~~ ~~Currently, a subproject is being developed in this(rebrgen) repository.~~ ~~ https://github.com/on-keyday/rebrgen ~~ こちらのリポジトリのrebrgen/ディレクトリに統合されました

Document

https://on-keyday.github.io/brgen/doc

Playground

https://on-keyday.github.io/brgen

F1 キー(もしくは右クリック->Command Palette)で表示されるコマンドパレットに load example file と入力いただきますと、サンプルファイルがロードできます

You can load the sample file by typing load example file in the command palette displayed by pressing the F1 key (or right-click -> Command Palette).

Design Doc

このプロダクトの目標

本プロダクトの最終的な目標(大それた野望とも言う)はバイナリフォーマットの仕様書に brgen の定義言語をつけることが常識となることである。 それによってバイナリフォーマットの仕様書を手に入れたら即コードジェネレーターに生成させることができ、 そして実際に使用をすることも簡単になるであろう。また、一意に定まる構文によって文章や図表による曖昧さがなくなり、 より初学者やプログラマーにとって理解しやすいものになるであろう。

もちろん現実的にはバイナリフォーマットを開発した人がそれを扱うためのライブラリを提供しているだったり、速度的な制約等がありこれらのコードジェネレーターでは無理という場合、 他にも何かしら都合が悪かったりして使えない場合もあるだろう。 しかし、意味的に曖昧さのない定義書が存在することはそういった手書きで実装する際にも大いに役に立つであろう。

設計概要

本プロダクトはコアの部分としてバイナリフォーマット定義言語(brgen(lang)と表記する)のパーサーと コードジェネレーターの２つの部分に分けられる。 brgen(lang)のパーサーは本プロダクトでは C++で書かれており、これが同時に定義言語の文法を決定しているという面がある。 そしてコードジェネレーターは C++向けを C++で、 Go 向けは Go で、Rust 向けは Rust で書かれつつある。これは、brgen(lang)のパース結果が様々な言語で扱えることを示す PoC 的な意味合いが強く、実際開発する際は、 かならずしもその言語自身での開発が要求されるわけではない。

開発方針

本プロダクトは、まず最小限でいいから動くものを作り、そこから徐々に成長させていくという 方針で作っている。実際本リポジトリには多くの書きかけの、しかし一応は動くというコードがかなりの数ある。 また、brgen のコードジェネレーター自体の実装方針も全部が全部すべての言語仕様を出力できなくても良いという方針を敷いている。 将来的にはこれらの完成度合いを表す指標を導入したいと考えている。 ~~ 現段階で CI/CD をしてはいるが、現状ビルド可能かと tool\brgen と入力した際に、brgen.jsonに書いたジェネレーターが動く(動くというのは実行可能であるかであり、仕様通りに動くかではない)ことしか検証していないため、今後より強化していきたい。 ~~

tool/brgenによる検証は一旦停止されている。現在はrebrgenベースのebm2xxx系ジェネレーターについて unictest(e2e test) ベースの検証と結果の公開を行っている。

https://on-keyday.github.io/brgen/unictest-results/

開発途上であるため失敗ケースが多いと思われるがそんなもんである。テストケースの拡充やテストフレームワークの拡充、バックエンド開発についてぜひ貢献を求む。

Design Document

Goals of the Product

The ultimate goal of this product (some might call it a lofty ambition) is to make it common practice to include the definition language of brgen in binary format specifications. This would enable individuals to obtain a binary format specification and immediately generate code using a code generator. Consequently, using the format would become much simpler. Additionally, having a syntax that is unambiguous would eliminate ambiguities found in textual descriptions and diagrams, making it more accessible to beginners and programmers alike.

Of course, in reality, there may be constraints such as the developers of the binary format providing libraries for handling it, or limitations in terms of speed that make it impossible to use such code generators. However, having a definition document that is unambiguous in meaning would still be immensely helpful even in scenarios where manual implementation is necessary.

Design Overview

This product can be divided into two core components: the parser for the binary format definition language (brgen(lang)) and the code generator.

• The parser for brgen(lang) is implemented in C++. It simultaneously determines the grammar of the definition language.
• The code generator is being developed separately for C++, Go, and Rust. This serves as a proof of concept showing that the parsing results of brgen(lang) can be handled in various languages. However, it is not mandatory to develop in the same language as the target language when actually developing.

Development Approach

The development approach for this product is to create a minimum viable product first and then gradually expand its capabilities. The repository contains many incomplete but somewhat functional pieces of code. Additionally, the implementation strategy for the brgen code generator itself does not require it to be able to output all language specifications perfectly. In the future, we aim to introduce metrics to indicate the completeness of these implementations. ~~ At the current stage, while we are implementing CI/CD, we are only verifying whether the project is buildable and whether the generators listed in brgen.json actually run (by "run", I mean they are executable, not necessarily that they function as specified) when the command tool\brgen is input. We haven't yet validated whether they function according to specifications. ~~ Therefore, we aim to enhance our CI/CD process in the future.

Verification using tool/brgen has been temporarily stopped. Currently, we are verifying the unictest(e2e test)-based verification and publishing the results for the rebrgen-based ebm2xxx series generator.

https://on-keyday.github.io/brgen/unictest-results/

Since it is still in the development stage, it seems like there will be many failures, but that's just the way it is. We are looking for contributions regarding the expansion of test cases, the expansion of test frameworks, and back-end development.

謝辞

本作品は SecHack365'23 の作品として作り始められました。 成果発表会時点のコードは SecHack365-final タグのコミットになります。

examples

https://github.com/on-keyday/brgen/tree/main/example を御覧ください

TODO(on-keyday): 現在、example 内のコードのいくつかは実装されていない機能が使われており、ジェネレーターで生成できる保証がありません

see https://github.com/on-keyday/brgen/tree/main/example

TODO(on-keyday): some of these examples use non-implemented functionality and not working with current generator implementation

How to Use (simple)

1. brgen.jsonのinput_dirを入力ファイルのあるディレクトリoutput_dirの項目を出力先ディレクトリに設定(デフォルトでは入力はexampleディレクトリ、出力はignore/example/<language name>となっています)
2. tool/brgenを実行
3. 出力先ディレクトリにコードが生成されます

現在、生成されたコードが言語の構文通りかはチェックされません。別途コンパイラ等で確認してください。

How to build

必要なもの

• cmake (必須)
• clang++ (必須)
• ninja (必須)
• go (必須)
• emscripten/emsdk (wasm/build_all のときのみ)
• npm (wasm/build_all のときのみ)
• webpack (wasm/build_all のときのみ)
• typescript (wasm/build_all のときのみ)
• python (build_all のときのみ)
• vsce (build_all のときのみ)

ネイティブ

• 全環境共通:
  1. python build.py native を実行

wasm(web)

• 全環境共通:
  1. python build.py web を実行（emsdk の設定は build_config.json の EMSDK_DIR で指定）

all (ネイティブ + wasm + npm + generate + lsp)

• 全環境共通:
  1. python build.py all を実行

License

MIT License

All source code is released under the MIT license. The copyright remains with on-keyday and contributors. if you want to contribute this product, you must agree with publishing your code under the MIT license.

You can decide license of code that is generated from code generator (and not contained in this repository) freely.

For built binary released on GitHub, license of dependency are collected by licensed and gocredits and bundled with released binaries.

If you find license problem, please tell us via GitHub Issue. see also license_note.txt

Issue Policy

機能の改善、提案、バグ報告などは このリポジトリの GitHub Issue で受け付けています。 セキュリティ脆弱性等の報告方針は SECURITY.md を参照してください

We welcome Feature improvements, requests, and bug reports etc... on this repository's GitHub Issue. see SECURITY.md about security vulnerability report policy.

Pull Request Policy

Issue と同様に受け付けています。 ただし、マージする場合は作者(リポジトリオーナー)に意図がわかる説明(目的、変更点など)をつけることと CI にパスすることを求めます。 以下のブランチ命名規則に従っていただけると作者に意図が伝わりやすくなると思います。

• doc/ - ドキュメントへの提案/変更
• lang/ - 言語仕様/言語パーサーへの提案/変更
• gen/ - brgen(lang)を入力とするコードジェネレーターへの提案/変更
• ast/ - AST コードジェネレーターや AST ハンドリングツールへの提案/変更
• web/ - WebPlayground への提案/変更
• lsp/ - LSP サーバーへの提案/変更
• env/ - 開発環境(shell script, GitHub Actions Workflow ファイル,Dockerfile など)への提案/変更
• tool/ - その他のツール(他言語から brgen 形式にするツールなど)の提案/変更
• sample/ - フォーマットのサンプルへの提案変更
• other/ - 以上以外で何かしらの

分類を増やすべきという場合やその他の事項は GitHub Issue で提案してください。

We welcome PR as well as issues. However, if you ask for a PR to be merged, you will need to provide the author (repository owner) with a description of your PR (purpose, changes, etc.) and pass a CI test. Following the branch naming conventions below would make it easier for the author to understand the intention:

• doc/ - Proposals/changes to documentation
• lang/ - Proposals/changes to language specifications/language parsers
• gen/ - Proposals/changes to code generators taking brgen(lang) as input
• ast/ - Proposals/changes to AST code generators or AST handling tools
• web/ - Proposals/changes to WebPlayground
• lsp/ - Proposals/changes to LSP servers
• env/ - Proposals/changes to development environment (shell scripts, GitHub Actions Workflow files,Dockerfile, etc.)
• tool/ - Proposals/changes to other tools (tools to convert from other languages to brgen format, etc.)
• sample/ - Proposals/changes to format samples
• other/ - Anything else not covered above

If there is a need to add more categories or any other issues, please propose them through GitHub Issue.

Version Policy

0.0.x の間は作者(リ