endcap-sl-software-ri-generator/README.md

# Endcap SL Software RI Generator

[![pipeline status](https://gitlab.cern.ch/wotsubo/endcap-sl-software-ri-generator/badges/main/pipeline.svg)](https://gitlab.cern.ch/wotsubo/endcap-sl-software-ri-generator/-/commits/main)
[![Latest Release](https://gitlab.cern.ch/wotsubo/endcap-sl-software-ri-generator/-/badges/release.svg)](https://gitlab.cern.ch/wotsubo/endcap-sl-software-ri-generator/-/releases)

[日本語版](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 --features=bin --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").