Prepare for release (Refine cli, writing docs)

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Implemented basic code generation covering current CSR XML.
+
+[unreleased]: https://gitlab.cern.ch/wotsubo/endcap-sl-software-ri-generator/-/commits/main

Cargo.lock

@@ -164,6 +164,46 @@ dependencies = [
  "windows-targets",
 ]
 
+[[package]]
+name = "clap"
+version = "4.5.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3e77c3243bd94243c03672cb5154667347c457ca271254724f9f393aee1c05ff"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.5.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b26884eb4b57140e4d2d93652abfa49498b938b3c9179f9fc487b0acc3edad7"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.5.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf4ced95c6f4a675af3da73304b9ac4ed991640c36374e4b46795c49e17cf1ed"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "clap_lex"
+version = "0.7.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f46ad14479a25103f283c0f10005961cf086d8dc42205bb44c46ac563475dca6"
+
 [[package]]
 name = "colorchoice"
 version = "1.0.3"
@@ -317,6 +357,7 @@ version = "0.1.0"
 dependencies = [
  "anyhow",
  "chrono",
+ "clap",
  "env_logger",
  "heck",
  "hex",

Cargo.toml

@@ -15,6 +15,7 @@ path = "src/lib.rs"
 [dependencies]
 anyhow = "1.0.95"
 chrono = "0.4.39"
+clap = { version = "4.5.28", features = ["derive"] }
 env_logger = "0.11.6"
 heck = "0.5"
 hex = "0.4.3"

README-ja.md

@@ -0,0 +1,79 @@
+# Endcap SL Software RI Generator
+
+これはXMLのレジスタマップからMPSoCソフトで使う用のコードを生成するソフトです。
+
+XMLおよびそのスキーマは[L0 Muon Endcap/Endcap Sl CSR XML](https://gitlab.cern.ch/l0muon-endcap/endcap-sl-csr-xml)にあります。
+生成されたコードは[MPSoC Software](https://gitlab.cern.ch/wotsubo/mpsoc-software)で使うことが想定されています。
+そこに`RegisterSpec`などのレジスタ向けのトレイトが定義されてます。
+
+## 使い方
+
+このプロジェクトでは、バイナリとライブラリの両方のクレートを提供しています。
+バイナリクレートはシェルから使うことができ、ライブラリクレートは他のプログラムから使うためのものです。
+
+### ビルド環境の構築
+
+このコードは[Rust](https://www.rust-lang.org/ja/)で書かれているので、[rustup](https://www.rust-lang.org/ja/tools/install)をインストールする必要があります。
+rustupのインストールには公式サイトにある`curl`スクリプトを使うか、あるいはシステムのパッケージマネージャを使うことができます。
+`cargo`を実行してみることでインストールのチェックができます。
+
+`cargo`はlxplusにインストールされているみたいなので、それも使えるかもしれません(ただし、バージョンは最新ではありません)。
+
+### バイナリクレートの使い方
+
+```bash
+cargo build --bins --release
+```
+を実行します。
+`--release`はオプションです。
+
+`target/release`に入ってるバイナリファイルを実行するか、`cargo run -- <XML> <OUT>`で実行できます。
+
+詳しくは`--help`を見てください。
+
+### ライブラリクレートの使い方
+
+```bash
+cargo doc --open
+```
+
+で閲覧できるドキュメントを見てください。
+
+## 開発
+
+```bash
+cargo doc --document-private-items --open
+```
+
+でみれるプライベートアイテムを含んだドキュメントを見てください。
+
+テストなどは以下のコマンドで実行できます
+```bash
+$ cargo test # テスト
+$ cargo fmt # フォーマット
+$ cargo clippy # リント (`rustup component add clippy`でインストールできます)
+```
+
+### rust-analyzer
+
+開発には[rust-analyzer](https://rust-analyzer.github.io)を使用することを __強く推奨__ します。
+推論された型の表示や補完に関して必要不可欠な上、フォーマットやclippyを実行することができます。
+
+### CIについて
+
+ビルドとフォーマットとclippyのテストが走ります。
+フォーマットやclippyのチェックをしてpushしてください。
+
+### Rustについて
+
+以下のウェブサイトでRustを良く学べます。
+
+- [The Book](https://doc.rust-jp.rs/book-ja/)
+
+もしくはターミナルで
+```bash
+rustup doc
+```
+を実行してみてください。
+様々な有益なドキュメントへのリンクが載っています(自分はThe Bookとstandard libraryのドキュメントとRust By Exampleが役に立ちました)。
+

README.md

@@ -0,0 +1,82 @@
+# Endcap SL Software RI Generator
+
+[日本語版](README-ja.md)
+
+Generates register interface for mpsoc software from register map in xml format.
+
+The XML and its schema definition are in [L0 Muon Endcap/Endcap Sl CSR XML](https://gitlab.cern.ch/l0muon-endcap/endcap-sl-csr-xml).
+The generated code is intended to be used in [MPSoC Software](https://gitlab.cern.ch/wotsubo/mpsoc-software), which provides definition of register traits (`RegisterSpec`) used in the generated code.
+
+## Usage
+
+This project provides both binary and library crates.
+Binary crates can be used from shell, while library crates can be used in other programs.
+
+### Setting up building environment
+
+This code is written in [Rust](https://www.rust-lang.org), so you need to install [rustup](https://www.rust-lang.org/tools/install).
+You can use either officially provided `curl` script, or system package manager to install.
+You can check the installation by executing `cargo` in the terminal.
+
+Note that `cargo` is available on lxplus, so you might be able to use that (it is not the latest version though).
+
+### Binary crate usage
+
+Execute
+
+```bash
+cargo build --bins --release
+```
+
+to build.
+`--release` is optional(this is a compiler optimization config).
+
+Execute the binary generated in `target/release/`, or run with `cargo run -- <XML> <OUT>`.
+
+See the `--help` for more information.
+
+### Library crate usage
+
+See the doc, which is available with
+
+```bash
+cargo doc --open
+```
+
+## Development
+
+See the doc with private items with
+
+```bash
+cargo doc --document-private-items --open
+```
+
+You can execute test, format and lint with:
+
+```bash
+$ cargo test # test
+$ cargo fmt # format
+$ cargo clippy # lint (run `rustup component add clippy` to install)
+```
+
+### rust-analyzer
+
+It is __heavily recommended__ to use [rust-analyzer](https://rust-analyzer.github.io) in development.
+It is not only essential for displaying inferred types and completion, but also it can execute formatter and clippy.
+
+### About CI
+
+In the CI, test for build, format and clippy run.
+Please format your code and check clippy before pushing.
+
+### About Rust
+
+You can learn Rust with the following webpage.
+
+- [The Book](https://doc.rust-lang.org/book/)
+
+Or in terminal, execute
+```bash
+rustup doc
+```
+It has a lot of links to helpful documents (personally, I appreciate "The Book", std library doc and "Rust By Example").

src/io.rs

@@ -13,7 +13,7 @@ pub fn write_to_files(
     if fs::read_dir(out_path)?.next().is_some() {
         return Err(io::Error::new(
             io::ErrorKind::AlreadyExists,
-            "out path is not empty",
+            format!("out path `{}` is not empty", out_path.display()),
         ));
     }
     for (file_path, code) in files {

src/lib.rs

@@ -1,3 +1,9 @@
+#![doc = include_str!("../README.md")]
+//!
+//! ----
+//!
+//! _documents in the library_
+//!
 //! Generate register interface software from register map in XML.
 //!
 //! # Example
@@ -25,7 +31,7 @@
 //!
 //! # Overview
 //!
-//! 1. Convert [`roxmltree::Document`] to register map respresented with types defined in
+//! 1. Convert [`roxmltree::Document`] to register map represented with types defined in
 //!    [`types`], filling missing parameters. See [`converter`].
 //! 2. Generate [`proc_macro2::TokenStream`] from register map produced in the previous step. See
 //!    [`generator`].

src/main.rs

@@ -1,14 +1,27 @@
-use std::fs;
+use std::{fs, path};
 
 use anyhow::Result;
+use clap::Parser;
 use endcap_sl_software_ri_generator::types;
 use itertools::Itertools;
 
+/// Generate register interface from register map xml.
+#[derive(Parser, Debug)]
+#[command(version, about)]
+struct Args {
+    /// Input XML register map.
+    xml: path::PathBuf,
+    /// Output directory.
+    out: path::PathBuf,
+}
+
 fn main() -> Result<()> {
     env_logger::init();
     log::debug!("logger enabled");
+    let args = Args::parse();
+    log::debug!("args: {:?}", args);
 
-    let xmlfile = fs::read_to_string("./csr.xml")?;
+    let xmlfile = fs::read_to_string(args.xml)?;
     let doc = roxmltree::Document::parse_with_options(
         &xmlfile,
         roxmltree::ParsingOptions {
@@ -36,7 +49,7 @@ fn main() -> Result<()> {
         }
     }
 
-    endcap_sl_software_ri_generator::write_to_files(files, &std::path::PathBuf::from("out"))?;
+    endcap_sl_software_ri_generator::write_to_files(files, &args.out)?;
 
     Ok(())
 }

src/meta.rs

@@ -1,3 +1,7 @@
+//! Get build metadata at compile time.
+//!
+//! See build.rs for more detail.
+
 pub(crate) const GENERATOR_BUILD_TIMESTAMP: &str =
     env!("VERGEN_BUILD_TIMESTAMP", "Failed to get build timestamp");
 pub(crate) const GENERATOR_GIT_DESCRIBE: &str =