# Project goal

This is a TUI program to allow quick monitoring a signals.  We will start
with an EPICS backend, and maybe add others in the future.

The user will provide a list of signal names (channels) and request that
we show those channels live.

## Technical choices

Implementation language: Rust
TUI Libraries: ratatui + crossterm
CLI Parsing: Clap crate with the Derive pattern
Target platforms: Linux
Version control: git
Data backend: EPICS 3 (channel access)
License: GPL3+
Copyright: California Institute of Technology

## General layout

This project is a rust workspace.

Crates:
 * epics_rs_sys - a bindgen wrapping of the EPICS CA libraries.
 * term_scope - the main application

Documentation and Direction:
 Each crate/folder may have their own verion of these which
 is specific to that subtree in the filesystem.
 * CLAUDE.md - this file
 * plan.md - top level plan documents

## General work flow

 * Work with me to generate a plan.
 * After we agree on the plan it will be saved in the plan.md for the section we are working on
 * Do feature work in a branch
 * Tests must pass
 * Lint with clippy
 * Format with cargo fmt
 * Commit back onto main (or the sub branch we branched from) and delete the branch

## Copyright / license headers

Every source file (Rust, C headers, Python, shell, ...) must start with this
blurb in the file's comment style, placed after the shebang if there is one:

```
Copyright 2026 California Institute of Technology

You should have received a copy of the licensing terms for this
software included in the file “LICENSE” located in the top-level
directory of this package. If you did not, you can view a copy at
http://dcc.ligo.org/M1500244/LICENSE.txt
```

Add it to every new source file; data/config files and Markdown don't need it.

## Handling unsafe code
We will use unsafe code due to linking with C libraries.
We should follow best practices, including:
 * Minimizing unsafe code
 * Including proper safety comments

## Packaging

### Debian Packaging

 We will maintain a debian packaging branch "debian".
  * Target being able to build under debian 11-13
  * We will use LIGO CDS EPICS packages
    * require for building:
      * epics-dev
      * python3-pcaspy
  * We will use the following dependencies for rust
    * rustc >= 1.95.0 or rust-compiler >= 1.95.0-1
    * cargo >= 1.95.0 or rust-compiler >= 1.95.0-1
  * For our C code integration in the epics code we will need
    * libclang-19-dev
  * We want to build the package with git build package (gbp)
  * When a release is made we will tag the code in the main branch
    * then the main branch can be merged into the packaging branch
    * after that is done the packaging metadata can be updated to reflect
      any needed changes, including the version number update
