format

warned by rustdoc

.gitignore

@@ -1 +1,2 @@
 /target
+result*

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [unreleased]
 
+### Added
+
+- Packagin with Nix flakes (with nixpkgs buildRustPackage) [!16](https://gitlab.cern.ch/wotsubo/endcap-sl-software-ri-generator/-/merge_requests/16)
+- Now xml metadata can be overwritten with corresponding environmental variables. [!17](https://gitlab.cern.ch/wotsubo/endcap-sl-software-ri-generator/-/merge_requests/17)
+
+### Changed
+
+- Improve error message from syn in generator. !15
+- Removed top level module (register_interface), and now it can have arbitrary name.
+
 ## [0.3.1] - 2025-04-11
 
 ### Changed

README-ja.md

@@ -33,7 +33,7 @@ cargo build --features=bin --bins --release
 
 `target/release`に入ってるバイナリファイルを実行するか、`cargo run -- <XML> <OUT>`で実行できます。
 
-詳しくは`--help`を見てください。
+詳しくは(`-h`ではなく)`--help`を見てください。
 
 ### ライブラリクレートの使い方
 

README.md

@@ -36,7 +36,7 @@ to build.
 
 Execute the binary generated in `target/release/`, or run with `cargo run -- <XML> <OUT>`.
 
-See the `--help` for more information.
+See the `--help`(not `-h`) for more information.
 
 ### Library crate usage
 

flake.lock

@@ -0,0 +1,82 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1744098102,
+        "narHash": "sha256-tzCdyIJj9AjysC3OuKA+tMD/kDEDAF9mICPDU7ix0JA=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "c8cd81426f45942bb2906d5ed2fe21d2f19d95b7",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs",
+        "rust-overlay": "rust-overlay"
+      }
+    },
+    "rust-overlay": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1744166053,
+        "narHash": "sha256-mpI7OzFwp+fUeDtZYQbVZ2YmtxTN2UNrrOwbYD27xKU=",
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "rev": "896158be1835589db6f42f45ef0a49b8b492cc66",
+        "type": "github"
+      },
+      "original": {
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "type": "github"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,37 @@
+{
+  description = "A very basic flake";
+
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+    rust-overlay = {
+      url = "github:oxalica/rust-overlay";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs = 
+    {
+      nixpkgs,
+      flake-utils,
+      rust-overlay,
+      ...
+    }:
+    flake-utils.lib.eachDefaultSystem (
+      system:
+      let
+        pkgs = import nixpkgs {
+          inherit system;
+          overlays = [ rust-overlay.overlays.default ];
+        };
+      in
+      {
+        devShells.default = pkgs.mkShell {
+          packages = [
+            pkgs.rust-bin.stable.latest.default
+          ];
+        };
+        packages.default = pkgs.callPackage ./nix/endcap-sl-software-ri-generator.nix { };
+      }
+    );
+}

nix/endcap-sl-software-ri-generator.nix

@@ -0,0 +1,11 @@
+{ rustPlatform }:
+# https://nixos.org/manual/nixpkgs/stable/#rust
+rustPlatform.buildRustPackage {
+  pname = "endcap-sl-software-ri-generator";
+  version = "0.3.0";
+
+  src = ../.;
+  cargoLock.lockFile = ../Cargo.lock;
+
+  buildFeatures = [ "bin" ];
+}

src/generator.rs

@@ -26,8 +26,12 @@ use thiserror::Error;
 
 #[derive(Debug, Error)]
 pub enum CodeGenError {
-    #[error("tokenization(syn) error")]
-    SynError(#[from] syn::Error),
+    #[error("tokenization(syn) error: {source}: {code}")]
+    SynError {
+        #[source]
+        source: syn::Error,
+        code: String,
+    },
     #[error("failed to create file (name duplicated): {0}")]
     FilePathDuplicatedError(String),
     #[error("parent is required for {module}")]
@@ -42,11 +46,17 @@ mod util {
     use super::CodeGenError;
 
     pub(super) fn parse_to_ident(s: &str) -> Result<proc_macro2::Ident, CodeGenError> {
-        Ok(syn::parse_str(s)?)
+        syn::parse_str(s).map_err(|e| CodeGenError::SynError {
+            source: e,
+            code: s.to_string(),
+        })
     }
 
     pub(super) fn parse_to_literal(s: &str) -> Result<proc_macro2::Literal, CodeGenError> {
-        Ok(syn::parse_str(s)?)
+        syn::parse_str(s).map_err(|e| CodeGenError::SynError {
+            source: e,
+            code: s.to_string(),
+        })
     }
 
     // currently only U32 is used, so `dead_code` for Debug, PartialEq
@@ -161,27 +171,26 @@ This code is auto generated using endcap_sl_software_ri_generator.
             GENERATOR_GIT_SHA,
         );
         let files = self.generate_register_interface(None, None, HashMap::new())?;
-        Ok(files
+        files
             .into_iter()
-            .map(
-                |(path, tokens)| -> Result<(PathBuf, syn::File), syn::Error> {
-                    let tokens = if path
-                        .file_name()
-                        .is_some_and(|file| file == "register_interface.rs")
-                    {
-                        quote! {
-                            #![doc = #build_metadata]
+            .map(|(path, tokens)| -> Result<(PathBuf, syn::File), _> {
+                let tokens = if path.file_name().is_some_and(|file| file == "mod.rs") {
+                    quote! {
+                        #![doc = #build_metadata]
 
-                            #tokens
-                        }
-                    } else {
-                        tokens
-                    };
-                    let file: syn::File = syn::parse2(tokens)?;
-                    Ok((path, file))
-                },
-            )
-            .process_results(|kv| HashMap::from_iter(kv))?)
+                        #tokens
+                    }
+                } else {
+                    tokens
+                };
+                let file: syn::File =
+                    syn::parse2(tokens.clone()).map_err(|e| CodeGenError::SynError {
+                        source: e,
+                        code: tokens.to_string(),
+                    })?;
+                Ok((path, file))
+            })
+            .process_results(|kv| HashMap::from_iter(kv))
     }
 }
 
@@ -222,10 +231,10 @@ impl CodeGen for Module {
 
             pub use super::RegisterInterface;
         };
-        files.insert(PathBuf::from("./register_interface.rs"), out);
+        files.insert(PathBuf::from("./mod.rs"), out);
 
         let ident_register_interface = util::parse_to_ident("RegisterInterface").unwrap();
-        let register_interface_mod = PathBuf::from("register_interface");
+        let register_interface_mod = PathBuf::from("./");
         let files = self
             .elements_other
             .into_iter()

src/integrated.rs

@@ -99,7 +99,11 @@ pub fn generate_flatmap(xml: &path::Path, out: Option<&path::Path>) -> Result<()
     }
     let f: Box<dyn Write> = match out {
         Some(f) => {
-            let file = File::options().write(true).truncate(true).open(f)?;
+            let file = File::options()
+                .create(true)
+                .write(true)
+                .truncate(true)
+                .open(f)?;
             Box::new(BufWriter::new(file))
         }
         None => Box::new(io::stdout()),

src/io.rs

@@ -1,68 +1,114 @@
 //! File IO for generated codes.
 
-use std::{collections::HashMap, fs, io, path, process};
+use std::{collections::HashMap, env, ffi::OsString, fs, io, path, process};
 
 use thiserror::Error;
 
 use crate::types::XmlGitInfo;
 
+const ENVVAR_XML_GIT_DESCRIBE: &str = "XML_GIT_DESCRIBE";
+const ENVVAR_XML_GIT_TIMESTAMP: &str = "XML_GIT_TIMESTAMP";
+const ENVVAR_XML_GIT_SHA: &str = "XML_GIT_SHA";
+
 #[derive(Debug, Error)]
 pub enum XmlGitInfoError {
     #[error("io error while getting xml git info: {msg} {source}")]
-    IOError {
+    GitCommandSpawnError {
         msg: &'static str,
         #[source]
         source: io::Error,
     },
     #[error("git failed: {msg}: {stderr}")]
     CommandFailed { msg: &'static str, stderr: String },
+    #[error("env var {var} is not unicode: {}", s.to_string_lossy())]
+    NotUnicodeEnvVar { var: &'static str, s: OsString },
 }
 
 impl XmlGitInfoError {
-    fn io_error(e: io::Error, msg: &'static str) -> Self {
-        XmlGitInfoError::IOError { msg, source: e }
+    fn git_command_spawn_error(e: io::Error, msg: &'static str) -> Self {
+        XmlGitInfoError::GitCommandSpawnError { msg, source: e }
     }
 }
 
 pub(crate) fn get_xml_gitinfo(xml_path: &path::Path) -> Result<XmlGitInfo, XmlGitInfoError> {
-    let describe = process::Command::new("git")
-        .args(["describe", "--always", "--dirty"])
-        .current_dir(xml_path.parent().unwrap())
-        .output()
-        .map_err(|e| XmlGitInfoError::io_error(e, "git describe"))?;
-    let describe = if describe.status.success() {
-        String::from_utf8_lossy(&describe.stdout).trim().to_owned()
-    } else {
-        return Err(XmlGitInfoError::CommandFailed {
-            msg: "git describe",
-            stderr: String::from_utf8_lossy(&describe.stderr).into_owned(),
-        });
+    let describe = match env::var(ENVVAR_XML_GIT_DESCRIBE) {
+        Ok(describe) => describe,
+        Err(env::VarError::NotUnicode(s)) => {
+            return Err(XmlGitInfoError::NotUnicodeEnvVar {
+                var: ENVVAR_XML_GIT_DESCRIBE,
+                s,
+            });
+        }
+        Err(env::VarError::NotPresent) => {
+            let out_describe = process::Command::new("git")
+                .args(["describe", "--always", "--dirty"])
+                .current_dir(xml_path.parent().unwrap())
+                .output()
+                .map_err(|e| XmlGitInfoError::git_command_spawn_error(e, "git describe"))?;
+            let describe = if out_describe.status.success() {
+                String::from_utf8_lossy(&out_describe.stdout)
+                    .trim()
+                    .to_owned()
+            } else {
+                return Err(XmlGitInfoError::CommandFailed {
+                    msg: "git describe",
+                    stderr: String::from_utf8_lossy(&out_describe.stderr).into_owned(),
+                });
+            };
+            describe
+        }
     };
-    let timestamp = process::Command::new("git")
-        .args(["log", "-1", "--pretty=format:'%cI'"])
-        .current_dir(xml_path.parent().unwrap())
-        .output()
-        .map_err(|e| XmlGitInfoError::io_error(e, "git log (timestamp)"))?;
-    let timestamp = if timestamp.status.success() {
-        String::from_utf8_lossy(&timestamp.stdout).trim().to_owned()
-    } else {
-        return Err(XmlGitInfoError::CommandFailed {
-            msg: "git log (timestamp)",
-            stderr: String::from_utf8_lossy(&timestamp.stderr).into_owned(),
-        });
+    let timestamp = match env::var(ENVVAR_XML_GIT_TIMESTAMP) {
+        Ok(timestamp) => timestamp,
+        Err(env::VarError::NotUnicode(s)) => {
+            return Err(XmlGitInfoError::NotUnicodeEnvVar {
+                var: ENVVAR_XML_GIT_TIMESTAMP,
+                s,
+            });
+        }
+        Err(env::VarError::NotPresent) => {
+            let timestamp_out = process::Command::new("git")
+                .args(["log", "-1", "--pretty=format:'%cI'"])
+                .current_dir(xml_path.parent().unwrap())
+                .output()
+                .map_err(|e| XmlGitInfoError::git_command_spawn_error(e, "git log (timestamp)"))?;
+            let timestamp = if timestamp_out.status.success() {
+                String::from_utf8_lossy(&timestamp_out.stdout)
+                    .trim()
+                    .to_owned()
+            } else {
+                return Err(XmlGitInfoError::CommandFailed {
+                    msg: "git log (timestamp)",
+                    stderr: String::from_utf8_lossy(&timestamp_out.stderr).into_owned(),
+                });
+            };
+            timestamp
+        }
     };
-    let sha = process::Command::new("git")
-        .args(["rev-parse", "HEAD"])
-        .current_dir(xml_path.parent().unwrap())
-        .output()
-        .map_err(|e| XmlGitInfoError::io_error(e, "git rev-parse (sha)"))?;
-    let git_sha = if sha.status.success() {
-        String::from_utf8_lossy(&sha.stdout).trim().to_owned()
-    } else {
-        return Err(XmlGitInfoError::CommandFailed {
-            msg: "git rev-parse (sha)",
-            stderr: String::from_utf8_lossy(&sha.stderr).into_owned(),
-        });
+    let git_sha = match env::var(ENVVAR_XML_GIT_SHA) {
+        Ok(sha) => sha,
+        Err(env::VarError::NotUnicode(s)) => {
+            return Err(XmlGitInfoError::NotUnicodeEnvVar {
+                var: ENVVAR_XML_GIT_SHA,
+                s,
+            });
+        }
+        Err(env::VarError::NotPresent) => {
+            let sha = process::Command::new("git")
+                .args(["rev-parse", "HEAD"])
+                .current_dir(xml_path.parent().unwrap())
+                .output()
+                .map_err(|e| XmlGitInfoError::git_command_spawn_error(e, "git rev-parse (sha)"))?;
+            let git_sha = if sha.status.success() {
+                String::from_utf8_lossy(&sha.stdout).trim().to_owned()
+            } else {
+                return Err(XmlGitInfoError::CommandFailed {
+                    msg: "git rev-parse (sha)",
+                    stderr: String::from_utf8_lossy(&sha.stderr).into_owned(),
+                });
+            };
+            git_sha
+        }
     };
     Ok(XmlGitInfo {
         describe,

src/main.rs

@@ -3,11 +3,16 @@ use std::path;
 use anyhow::Result;
 use clap::{Parser, Subcommand};
 
-/// Generate register interface from register map xml.
+/// Validate the register map xml and generate register interface from register map xml.
+/// See `help` with each commands to see detailed explanations.
 #[derive(Parser, Debug)]
-#[command(version, about)]
+#[command(version, about, long_about)]
 struct Args {
     /// Input XML register map.
+    ///
+    /// The path must be a valid git repository to get git metadata.
+    /// You can also force these metadata with environmental variables `XML_GIT_DESCRIBE`,
+    /// `XML_GIT_TIMESTAMP` and `XML_GIT_SHA`.
     xml: path::PathBuf,
     #[command(subcommand)]
     command: Commands,
@@ -23,6 +28,8 @@ enum Commands {
         out: path::PathBuf,
     },
     /// Generate flattened register map in CSV.
+    ///
+    /// Also run validation before generation.
     #[cfg(feature = "flatmap")]
     Flatmap {
         /// Flattened csv out path.

src/validator.rs

@@ -16,7 +16,7 @@ pub struct FlattenedRegisterEntry<'a> {
 }
 
 /// Flattened register map.
-type FlattenedRegisterMap<'a> = Vec<Option<FlattenedRegisterEntry<'a>>>;
+pub type FlattenedRegisterMap<'a> = Vec<Option<FlattenedRegisterEntry<'a>>>;
 
 impl Module {
     /// Validate the address assignment, generating a flatten register map.