mirror of
https://github.com/awalsh128/cache-apt-pkgs-action.git
synced 2025-09-08 11:06:48 +00:00
07366a6d1e
- Refactored README.md - Added workflows for version export and management. - Removed src directory, following Go best practices - Added COMMANDS.md documentation Saving the AI semi-slop for now with broken states to get a snapshot. Too lazy to setup another chained repo.
216 lines
4.2 KiB
Markdown
216 lines
4.2 KiB
Markdown
# Command Line Usage Guide
|
|
|
|
This document provides information about using the `cache-apt-pkgs` command line tool.
|
|
|
|
## Basic Usage
|
|
|
|
The basic syntax for the command is:
|
|
|
|
```bash
|
|
cache-apt-pkgs <command> [flags] [packages]
|
|
```
|
|
|
|
## Available Commands
|
|
|
|
### 1. Install Command
|
|
|
|
Install and cache APT packages:
|
|
|
|
```bash
|
|
cache-apt-pkgs install [flags] [packages]
|
|
```
|
|
|
|
#### Flags for Install
|
|
|
|
- `--version`: Cache version identifier (optional)
|
|
- `--execute-scripts`: Execute package install scripts (optional, default: false)
|
|
|
|
#### Install Examples
|
|
|
|
```bash
|
|
# Install specific versions
|
|
cache-apt-pkgs install python3-dev=3.9.5-3 cmake=3.18.4-2
|
|
|
|
# Install latest versions
|
|
cache-apt-pkgs install python3-dev cmake
|
|
|
|
# Install with custom cache version
|
|
cache-apt-pkgs install --version=1.0 python3-dev cmake
|
|
|
|
# Install with script execution
|
|
cache-apt-pkgs install --execute-scripts=true python3-dev cmake
|
|
```
|
|
|
|
### 2. Create Key Command
|
|
|
|
Create a cache key for packages:
|
|
|
|
```bash
|
|
cache-apt-pkgs create-key [flags] [packages]
|
|
```
|
|
|
|
#### Flags for Create Key
|
|
|
|
- `--version`: Cache version identifier (optional)
|
|
|
|
#### Create Key Examples
|
|
|
|
```bash
|
|
# Create key with default version
|
|
cache-apt-pkgs create-key python3-dev cmake
|
|
|
|
# Create key with custom version
|
|
cache-apt-pkgs create-key --version=1.0 python3-dev cmake
|
|
```
|
|
|
|
### 3. Restore Command
|
|
|
|
Restore packages from cache:
|
|
|
|
```bash
|
|
cache-apt-pkgs restore [flags] [packages]
|
|
```
|
|
|
|
#### Flags for Restore
|
|
|
|
- `--version`: Cache version to restore from (optional)
|
|
- `--execute-scripts`: Execute package install scripts (optional, default: false)
|
|
|
|
#### Restore Examples
|
|
|
|
```bash
|
|
# Restore with specific version
|
|
cache-apt-pkgs restore --version=1.0 python3-dev cmake
|
|
|
|
# Restore with script execution
|
|
cache-apt-pkgs restore --execute-scripts=true python3-dev cmake
|
|
```
|
|
|
|
### 4. Validate Command
|
|
|
|
Validate package names and versions:
|
|
|
|
```bash
|
|
cache-apt-pkgs validate [packages]
|
|
```
|
|
|
|
#### Examples
|
|
```bash
|
|
# Validate package names and versions
|
|
cache-apt-pkgs validate python3-dev=3.9.5-3 cmake=3.18.4-2
|
|
|
|
# Validate package names only
|
|
cache-apt-pkgs validate python3-dev cmake
|
|
```
|
|
|
|
## Package Specification
|
|
|
|
Packages can be specified in two formats:
|
|
|
|
1. Name only: `package-name`
|
|
2. Name with version: `package-name=version`
|
|
|
|
Examples:
|
|
|
|
- `python3-dev`
|
|
- `python3-dev=3.9.5-3`
|
|
- `cmake=3.18.4-2`
|
|
|
|
## Environment Variables
|
|
|
|
The following environment variables can be used to configure the tool:
|
|
|
|
- `RUNNER_DEBUG`: Set to `1` to enable debug logging
|
|
- `RUNNER_TEMP`: Directory for temporary files (default: system temp dir)
|
|
|
|
## Common Tasks
|
|
|
|
### Installing Multiple Packages
|
|
|
|
```bash
|
|
cache-apt-pkgs install \
|
|
python3-dev \
|
|
cmake \
|
|
build-essential \
|
|
libssl-dev
|
|
```
|
|
|
|
### Creating Custom Cache Keys
|
|
|
|
```bash
|
|
cache-apt-pkgs create-key \
|
|
--version="$(date +%Y%m%d)" \
|
|
python3-dev \
|
|
cmake
|
|
```
|
|
|
|
### Restoring Specific Versions
|
|
|
|
```bash
|
|
cache-apt-pkgs restore \
|
|
--version=1.0 \
|
|
python3-dev=3.9.5-3 \
|
|
cmake=3.18.4-2
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. Version Management
|
|
- Use specific versions for reproducible builds
|
|
- Use version-less package names for latest versions
|
|
- Use timestamp-based cache versions for forced updates
|
|
|
|
2. Cache Optimization
|
|
- Group related packages in the same cache
|
|
- Use consistent version strings across workflows
|
|
- Clean up old caches periodically
|
|
|
|
3. Error Handling
|
|
- Validate packages before installation
|
|
- Check for missing dependencies
|
|
- Use debug logging for troubleshooting
|
|
|
|
## Troubleshooting
|
|
|
|
Common issues and solutions:
|
|
|
|
1. Package Not Found
|
|
|
|
```bash
|
|
# Validate package name and availability
|
|
cache-apt-pkgs validate package-name
|
|
```
|
|
|
|
2. Cache Miss
|
|
|
|
```bash
|
|
# Check if package versions match exactly
|
|
cache-apt-pkgs restore --version=1.0 package-name=exact-version
|
|
```
|
|
|
|
3. Installation Errors
|
|
|
|
```bash
|
|
# Try with script execution
|
|
cache-apt-pkgs install --execute-scripts=true package-name
|
|
```
|
|
|
|
## Advanced Usage
|
|
|
|
### Using with GitHub Actions
|
|
|
|
```yaml
|
|
steps:
|
|
- name: Cache APT Packages
|
|
uses: awalsh128/cache-apt-pkgs-action@v2
|
|
with:
|
|
packages: python3-dev cmake
|
|
version: ${{ github.sha }}
|
|
execute_install_scripts: true
|
|
```
|
|
|
|
For more information, refer to:
|
|
|
|
- [GitHub Action Documentation](README.md)
|
|
- [Source Code](cmd/cache_apt_pkgs/)
|