501fa65d76
Some checks failed
Build-Test-Publish / build (linux/amd64) (push) Successful in 1m4s
Build-Test-Publish / build (linux/arm64) (push) Failing after 1m51s
Build-Test-Publish / test-install-from-scratch (linux/amd64) (push) Has been skipped
Build-Test-Publish / test-install-from-scratch (linux/arm64) (push) Has been skipped
107 lines
3.7 KiB
Markdown
107 lines
3.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
This repository contains Dropshell Tools - a collection of utilities that support dropshell development. The main tool is `getpkg`, a C++ command-line application that manages tool installation, updates, and publishing for the dropshell ecosystem.
|
|
|
|
## Repository Structure
|
|
|
|
- **getpkg**: Package manager for dropshell tools (C++23)
|
|
- **sos**: Simple object storage upload utility (Bash)
|
|
- **whatsdirty**: Git repository status checker (Bash)
|
|
- **dehydrate**: File to C++ code generator (C++)
|
|
- **bb64**: Base64 encoder/decoder (C++)
|
|
- **gp**: Git push utility (Bash)
|
|
|
|
## Architecture
|
|
|
|
### Core Components (getpkg)
|
|
|
|
- **getpkg**: Main C++ application (`getpkg/src/`)
|
|
- `main.cpp`: CLI interface and command routing
|
|
- `GetbinClient`: Multi-server HTTP client for downloading/uploading tools
|
|
- `PackageMetadata`: Enhanced metadata with server tracking and migration support
|
|
- `ServerManager`: Manages multiple package servers with write tokens
|
|
- `BashrcEditor`: Manages ~/.bashrc_getpkg script modifications
|
|
- `DropshellScriptManager`: Manages tool installation and configuration
|
|
- `MigrationManager`: Handles legacy format migrations
|
|
- `common/`: Shared utilities (archive_tgz, hash, output, temp_directory)
|
|
|
|
### Key Features
|
|
|
|
- **Multi-server support**: Fallback logic for package downloads
|
|
- **Architecture awareness**: Supports x86_64, aarch64, and universal packages
|
|
- **Migration support**: Handles upgrades from legacy single-server format
|
|
- **Static linking**: All tools built as static binaries for portability
|
|
|
|
### Build System
|
|
|
|
- Uses CMake with C++23 standard
|
|
- Docker-based builds with static linking
|
|
- Uses external build base image `gitea.jde.nz/public/dropshell-build-base:latest`
|
|
- Versioning based on timestamp format YYYY.MMDD.HHMM
|
|
|
|
## Common Commands
|
|
|
|
### Build Tools
|
|
```bash
|
|
# Build all tools (includes install from getbin.xyz)
|
|
./buildtestpublish_all.sh
|
|
|
|
# Build specific tool (getpkg)
|
|
cd getpkg && ./build.sh
|
|
|
|
# Test specific tool
|
|
cd getpkg && ./test.sh
|
|
|
|
# Publish specific tool (requires SOS_WRITE_TOKEN)
|
|
cd getpkg && ./publish.sh
|
|
```
|
|
|
|
### Development Workflow
|
|
```bash
|
|
# Check status of all git repositories
|
|
./whatsdirty/whatsdirty.sh
|
|
|
|
# Build debug version (default in build.sh)
|
|
export CMAKE_BUILD_TYPE="Debug"
|
|
|
|
# Build release version (used in publish.sh)
|
|
export CMAKE_BUILD_TYPE="Release"
|
|
```
|
|
|
|
## Tool Functionality
|
|
|
|
getpkg manages a tool ecosystem by:
|
|
- Installing tools to `~/.getpkg/<tool_name>/` with symlinks in `~/.local/bin/getpkg/`
|
|
- Managing bash completions and PATH updates via `~/.bashrc_getpkg`
|
|
- Storing tool metadata in `~/.config/getpkg/packages/` (JSON format)
|
|
- Supporting multi-server package distribution with fallback
|
|
- Publishing/downloading tools via object storage servers (default: getpkg.xyz)
|
|
|
|
## File Locations
|
|
|
|
- **Tool installations**: `~/.getpkg/<tool_name>/`
|
|
- **Executable symlinks**: `~/.local/bin/getpkg/` (added to PATH)
|
|
- **Package metadata**: `~/.config/getpkg/packages/<tool_name>.json`
|
|
- **Server configuration**: `~/.config/getpkg/servers.json`
|
|
- **Bash integration**: `~/.bashrc_getpkg` (sourced by ~/.bashrc)
|
|
|
|
## Publishing Requirements
|
|
|
|
Publishing requires the `SOS_WRITE_TOKEN` environment variable for authentication to the object storage system.
|
|
|
|
## Testing
|
|
|
|
- Tests create temporary files in `test_temp/` directory
|
|
- Docker-based test environment using same build image
|
|
- Run `cleanup_test_packages.sh` to remove orphaned test packages from servers
|
|
|
|
## Important Notes
|
|
|
|
- All builds use static linking for maximum portability
|
|
- Version format is YYYY.MMDD.HHMM (timestamp-based)
|
|
- Tools should support `version` and `autocomplete` subcommands
|
|
- Architecture-specific builds use suffixes like `:x86_64` or `:aarch64` |