Skip to content

Commit 4834944

Browse files
piste2750piste2750
authored
Introduce CLAUDE.md for working with the claude code (#538)
1 parent 31ad2c6 commit 4834944

File tree

3 files changed

+682
-81
lines changed

3 files changed

+682
-81
lines changed

‎AGENTS.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is the reference implementation of the Linear Tape File System (LTFS) format specifications from SNIA, the LTFS format specification 2.5 (https://www.snia.org/sites/default/files/technical-work/ltfs/release/SNIA-LTFS-Format-v2.5-Technical-Position.pdf).
8+
9+
LTFS is a filesystem implementation that allows mounting LTFS-formatted tapes as regular filesystems. LTFS uses Filesystem in Userspace (FUSE) under the foot.
10+
11+
## Build Commands
12+
13+
### Linux Build Configuration
14+
```bash
15+
./autogen.sh
16+
./configure --prefix=</path_to_install>
17+
```
18+
19+
### Linux Build
20+
```bash
21+
make
22+
make install
23+
# May need: sudo ldconfig -v
24+
```
25+
26+
### macOS Build Configuration
27+
```bash
28+
# Setup environment first:
29+
export ICU_PATH="/usr/local/opt/icu4c/bin"
30+
export LIBXML2_PATH="/usr/local/opt/libxml2/bin"
31+
export PKG_CONFIG_PATH="/usr/local/opt/icu4c/lib/pkgconfig:/usr/local/opt/libxml2/lib/pkgconfig"
32+
export PATH="$PATH:$ICU_PATH:$LIBXML2_PATH"
33+
34+
./autogen.sh
35+
LDFLAGS="-framework CoreFoundation -framework IOKit" ./configure --disable-snmp --prefix=</path_to_install>
36+
```
37+
38+
### macOS Build
39+
```bash
40+
make
41+
make install
42+
```
43+
44+
### Clean Build
45+
```bash
46+
make clean
47+
```
48+
49+
### Clean up everything
50+
```bash
51+
make clean
52+
make distclean
53+
```
54+
55+
## Core Architecture
56+
57+
### Main Components
58+
59+
1. **libltfs** (`src/libltfs/`) - Core LTFS library
60+
- `ltfs.c/h` - Main LTFS data structures and operations
61+
- `ltfs_fsops.c` - Filesystem operations implementation
62+
- `tape.c/h` - Tape drive abstraction layer
63+
- `index_criteria.c` - Index management logic
64+
- `xml_reader.c/xml_writer.c` - XML index parsing/generation
65+
66+
2. **Tape Drivers** (`src/tape_drivers/`)
67+
- Platform-specific tape drive implementations
68+
- `linux/sg/` - Linux SCSI generic driver
69+
- `linux/lin_tape/` - IBM lin_tape driver
70+
- `osx/iokit/` - macOS IOKit driver
71+
- `freebsd/cam/` - FreeBSD CAM driver
72+
- `generic/file/` - Debug purpose tape emulation on a directory (for creating situations hard to recreate)
73+
74+
3. **I/O Schedulers** (`src/iosched/`)
75+
- `fcfs.c` - First-come-first-served scheduler (This is sample of I/O scheduler. Not used at all.)
76+
- `unified.c` - Unified I/O scheduler with optimization (This I/O scheduler can create 512KB block from chunked requests from FUSE layer)
77+
78+
4. **Key Management** (`src/kmi/`)
79+
- `simple.c` - Simple key management interface, receive keys from options
80+
- `flatfile.c` - Flat file-based key storage, receive keys specified unencrypted file
81+
82+
5. **Utilities** (`src/utils/`)
83+
- `mkltfs.c` - Format tapes for LTFS like `mkfs`
84+
- `ltfsck.c` - Check and repair LTFS volumes like `fsck`
85+
- `ltfsindextool.c` - Manipulate LTFS indexes outside of LTFS filesystem implementation
86+
- `ltfs_ordered_copy` - Python script for optimized file copying
87+
88+
6. **Entry point of `ltfs` process** (`src/main.c`)
89+
- This is the start point of LTFS filesystem process
90+
91+
7. **ltfs internal filesystem operations** (`src/libltfs/ltfs_fsops.c/h`)
92+
- This is the ltfs own filesystem operations implementation
93+
94+
8. **FUSE-LTFS bridge** (`ltfs_fuse.c`)
95+
- This layer converts request from FUSE to the ltfs own filesystem operations
96+
97+
### Key Design Patterns
98+
99+
- **Plugin Architecture**: Tape drivers, I/O schedulers, and key management are implemented as plugins loaded at runtime and called indirectly by pointer
100+
- **FUSE Integration**: Uses FUSE (Filesystem in Userspace) for filesystem operations
101+
- **XML Indexes**: Filesystem metadata stored as XML on tape (following LTFS format spec)
102+
- **Dual Partition**: Uses tape partition feature - index on Index Partition, data on Data Partition
103+
104+
### Important Files to Understand
105+
106+
- `src/libltfs/ltfs_internal.c` - This is low level function called from ltfs.c
107+
- `src/libltfs/ltfs_fsops_raw.c` - This is low level function to handle LTFS format called sequence is FUSE->FUSE-LTFS bridge->ltfs internal filesystem operations->I/O scheduler->low level function to handle LTFS format
108+
109+
# Tech Stack
110+
- Language: C99 with gcc
111+
112+
# Project Structure
113+
- `contrib`: Contribution code that is not a part of the project but is variable for this project
114+
- `docs`: Documents and configuration files for system. See also docs/README.md
115+
- `init.d`: Service script for init
116+
- `man`: man pages for the commands provided by the project
117+
- `man/sgml`: Original documents for man pages written by docbook 4.1 format
118+
- `messages`: Message files used in the code tree
119+
- `src/libltfs`: Source files for libltfs, the library that handles logical layer of the LTFS format
120+
- `src/iosched`: I/O scheduler plugins for libltfs. The libltfs makes indirect calls to an ioschead plugin loaded when a command is launched for creating 512KB block for tape R/W
121+
- `src/tape_drivers`: Tape drive handling plugins for libltfs. The libltfs makes indirect calls to an tape drive plugin loaded when a command is launched for issuing SCSI commands to different type of tape drives
122+
- `src/kmi`: Encryption key management plugins for libltfs
123+
- `utils/mkltfs.c`: Formatting tool for the LTFS like `mkfs`
124+
- `utils/ltfsck.c`: Recovery tool for the LTFS like `fsck`
125+
- `utils/ltfsindextool.c`: Tools for capturing indexes on the tape
126+
- `./main.c`: Main function for `ltfs` command, it is the file system command for FUSE
127+
- `./ltfs_fuse.*`: FUSE - LTFS file operation glue layer
128+
- `./ltfs_copyright.h`: Copyright definition for injecting to compiled binaries
129+
130+
## Common Development Tasks
131+
132+
### Running LTFS Commands
133+
134+
```bash
135+
# List available tape drives
136+
ltfs -o device_list
137+
138+
# Format a tape
139+
mkltfs -d <device_name>
140+
141+
# Mount a tape
142+
ltfs -o devname=<device_name> <mount_point>
143+
144+
# Unmount
145+
umount <mount_point>
146+
147+
# Check/repair LTFS volume
148+
ltfsck -d <device_name>
149+
```
150+
151+
### Debugging
152+
153+
- Use `--enable-debug` configure option for debug builds
154+
- Set log level with `-o loglevel=<level>` (0-4)
155+
- Check syslog for LTFS messages
156+
157+
## Platform-Specific Notes
158+
159+
- **Linux**: Supports both sg (SCSI generic) and lin_tape drivers
160+
- **macOS**: Requires disabling SNMP support (`--disable-snmp`)
161+
- **FreeBSD/NetBSD**: Uses platform-specific SCSI interfaces
162+
163+
## Message System
164+
165+
- Messages defined in `messages/` directory
166+
- Message is constructed a number and sevirity (Error, Warning, Info, Debug)
167+
- Number part of message must be unique
168+
- It means 11111W must not be used if 11111I is used
169+
- Number part of message must not be reused once used
170+
- It means 11111[EWID] must not be used if 11111[EWID] is already commented out
171+
- Message ID must be commented out when it is not required anymore
172+
- Each component has its own message file
173+
- Run `make_message_src.sh` to regenerate message headers
174+
175+
# Do Not Section
176+
- Do not commit directly to the any branches
177+
- Do not provide any changes which cannot be compiled
178+
- Do not use duplicated messege number under the `messages` directory
179+
- Do not reuse any message number which is commented out inder the `messages` directory

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

0 commit comments

Comments
 (0)