Skip to content

Commit

Permalink
chore(docs): added info on protobuf and packr into README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
decibelcooper committed Feb 21, 2020
1 parent 95dbd6f commit 4788655
Showing 1 changed file with 39 additions and 0 deletions.
39 changes: 39 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,11 @@ radiation detectors.
This material is based upon work supported by the U.S. Department of Energy,
Office of Science, Nuclear Physics program office under Award Number
DE-SC0015136.

## Screenshots
![Demo animation](images/software_demo.gif)
![RDI logo beam scan](images/screenshot1.png)

## Tools installation
The tools include the main `rdi-live` binary.
1. Install the Go compiler toolchain (version 1.11 or newer) from
Expand All @@ -19,3 +21,40 @@ The tools include the main `rdi-live` binary.
```shell
go get github.com/rditech/rdi-live/tools/...
```

## Protobuf
RDI Live uses Protobuf for (de)serialization of event data. Additionally,
Protobuf is used to store detector mappings, or metadata that is used to
related data streams to things like physical layout and calibration. Finally,
Protobuf is used for "slow data", or data that are slowly changing compared to
events, and passed along in the proio streams as stream metadata. See, e.g.,
[https://godoc.org/github.com/proio-org/go-proio#Reader](https://godoc.org/github.com/proio-org/go-proio#Reader)
and [arXiv:1812.03967](https://arxiv.org/abs/1812.03967)).

The Protobuf files that describe the data models for these data are stored
under the `proto` directory. Also, Protobuf binaries used for storing detector
mappings are located in the `detmap` directory. These files are generated
elsewhere. If changes are made to the Protobuf data model files in `proto`,
the generated source in `model` must be regenerated using `go generate`. This
requires the `protoc` command to be installed on your system, as well as a go
Protobuf compiler plugin.

## Packr
Executable binaries like `rdi-live` are intended to be completely
self-contained. To that end, binaries like detector mappings and web data are
packaged into the executables using
[Packr](https://github.com/gobuffalo/packr). This tool encodes data in certain
directories in this repository into source code that gets compiled into
executables when necessary. For example, Packr is instructed to pack the web
data into source code
[here](https://github.com/rditech/rdi-live/blob/master/live/webdata.go),
resulting in the autogenerated file
[here](https://github.com/rditech/rdi-live/blob/master/live/a_live-packr.go).
This makes a highly portable executable, but it also means that any time web
data or detector mappings are changed, Packr must be called to regenerate
source code with the new data packed in. This can be by first installing the
`packr` tool, and then running
```shell
packr -z
```
in the root directory of the repository.

0 comments on commit 4788655

Please sign in to comment.