Skip to content

Commit 3049013

Browse files
wysaidLeeGoDamn
wysaid
and
LeeGoDamn
committed
feat: Complete CLI tool integration with comprehensive testing and documentation
Finalize the ccap CLI tool implementation with extensive refactoring, comprehensive test coverage, CI/CD integration, and complete documentation. This commit addresses all code review feedback and ensures production-ready quality. Major improvements: - Refactor CLI build system: rename CMakeLists.txt to ccap-cli.cmake, remove wuffs dependency, simplify configuration - Add dev.cmake.example for optional CLI tool development configuration - Enhance device listing with improved formatting and detail levels - Add internal-format option for raw frame data export - Implement release packaging for all platforms in workflows Testing enhancements: - Add 12 comprehensive CLI integration tests covering all functionality - Implement device selection and error handling tests - Add rigorous YUV to BMP format conversion validation tests - Enforce clean test environment with proper setup/teardown - Add stricter validation for captured image files - Achieve complete code coverage for CLI module - Fix Windows compilation errors in CLI tests CI/CD updates: - Enable CLI building in Linux, macOS, and Windows workflows - Add CLI artifacts to release workflow for distribution - Update test scripts to include CLI tests - Add VS Code launch configurations for CLI debugging - Add VS Code tasks for CLI operations Documentation: - Add comprehensive CLI tool documentation (cli/README.md, cli/README.zh-CN.md) - Add CLI tool reference in main README with direct links - Streamline main README by removing redundant CLI sections - Document all command-line options with usage examples - Add integration examples (Bash, Python, Makefile) - Include performance tips and troubleshooting guide - Update CMAKE_OPTIONS.md with CLI-related build flags - Add CLI tool setup instructions in BUILD_AND_INSTALL.md - Update version to 1.4.0 with CLI feature inclusion - Fix markdown table formatting in README files Code quality improvements: - Remove unnecessary references to external tools in code comments - Fix all CodeRabbit and Copilot code review issues - Resolve compilation warnings across all platforms - Improve code structure and readability - Add proper error handling and validation - Fix minor issues in example code comments - Update .github/copilot-instructions.md with development guidelines This commit brings the CLI tool to production-ready state with full test coverage, comprehensive documentation, and seamless CI/CD integration. Co-authored-by: LeeGoDamn <243561453+LeeGoDamn@users.noreply.github.com>
1 parent 793e399 commit 3049013

27 files changed

Lines changed: 2464 additions & 176 deletions

‎.github/copilot-instructions.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@
66
- Use English for git commit messages and PR descriptions
77
- All `.md` files in `docs/` must be in English
88
- Only commit necessary new `.md` files after review.
9+
- To update the version, run `./scripts/update_version.sh <new_version>` to update related files.

‎.github/workflows/linux-build.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ jobs:
5050
-DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
5151
-DCCAP_BUILD_EXAMPLES=ON \
5252
-DCCAP_BUILD_TESTS=ON \
53+
-DBUILD_CCAP_CLI=ON \
5354
$SHARED_FLAG
5455
5556
- name: Build
@@ -196,6 +197,7 @@ jobs:
196197
-DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
197198
-DCCAP_BUILD_EXAMPLES=ON \
198199
-DCCAP_BUILD_TESTS=ON \
200+
-DBUILD_CCAP_CLI=ON \
199201
$SHARED_FLAG
200202
201203
- name: Build
@@ -296,6 +298,7 @@ jobs:
296298
-DCMAKE_CROSSCOMPILING=ON \
297299
-DCCAP_BUILD_EXAMPLES=ON \
298300
-DCCAP_BUILD_TESTS=ON \
301+
-DBUILD_CCAP_CLI=ON \
299302
$SHARED_FLAG
300303
301304
- name: Build ARM64
@@ -412,6 +415,7 @@ jobs:
412415
-DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
413416
-DCCAP_BUILD_EXAMPLES=ON \
414417
-DCCAP_BUILD_TESTS=ON \
418+
-DBUILD_CCAP_CLI=ON \
415419
$SHARED_FLAG
416420
417421
- name: Build

‎.github/workflows/macos-build.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ jobs:
3030
fi
3131
mkdir -p build/${{ matrix.config }}-${{ matrix.library_type }}
3232
cd build/${{ matrix.config }}-${{ matrix.library_type }}
33-
cmake ../.. -DCMAKE_BUILD_TYPE=${{ matrix.config }} -DCCAP_BUILD_TESTS=ON $SHARED_FLAG
33+
cmake ../.. -DCMAKE_BUILD_TYPE=${{ matrix.config }} -DCCAP_BUILD_TESTS=ON -DBUILD_CCAP_CLI=ON $SHARED_FLAG
3434
3535
- name: Build
3636
run: |

‎.github/workflows/release.yml‎

Lines changed: 256 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -375,8 +375,232 @@ jobs:
375375
path: ${{ matrix.artifact_name }}.*
376376
retention-days: 5
377377

378+
build-cli:
379+
name: Build CLI Tool
380+
needs: test
381+
strategy:
382+
fail-fast: false
383+
matrix:
384+
include:
385+
# Static-only Release builds for CLI tool
386+
- os: macos-latest
387+
name: macOS CLI
388+
artifact_name: ccap-cli-macos-universal
389+
build_type: Release
390+
391+
- os: windows-latest
392+
name: Windows CLI
393+
artifact_name: ccap-cli-msvc-x86_64
394+
build_type: Release
395+
396+
- os: ubuntu-latest
397+
name: Linux CLI
398+
artifact_name: ccap-cli-linux-x86_64
399+
build_type: Release
400+
401+
- os: ubuntu-latest
402+
name: Linux ARM64 CLI
403+
artifact_name: ccap-cli-linux-arm64
404+
build_type: Release
405+
arch: arm64
406+
407+
runs-on: ${{ matrix.os }}
408+
409+
steps:
410+
- name: Checkout code
411+
uses: actions/checkout@v4
412+
413+
- name: Setup cross-compilation for ARM64
414+
if: matrix.arch == 'arm64'
415+
shell: bash
416+
run: |
417+
sudo apt-get update
418+
sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
419+
420+
- name: Setup Visual Studio (Windows)
421+
if: matrix.os == 'windows-latest'
422+
uses: microsoft/setup-msbuild@v1.1
423+
424+
- name: Install Linux dependencies
425+
if: matrix.os == 'ubuntu-latest'
426+
run: |
427+
sudo apt-get update
428+
sudo apt-get install -y cmake build-essential gcc
429+
430+
- name: Configure CMake
431+
shell: bash
432+
run: |
433+
if [ "${{ matrix.os }}" = "windows-latest" ]; then
434+
# Windows: Use multi-config generator (Visual Studio)
435+
cmake -B build -G "Visual Studio 17 2022" -A x64 \
436+
-DCCAP_BUILD_EXAMPLES=OFF \
437+
-DCCAP_BUILD_TESTS=OFF \
438+
-DCCAP_BUILD_SHARED=OFF \
439+
-DBUILD_CCAP_CLI=ON
440+
elif [ "${{ matrix.os }}" = "ubuntu-latest" ]; then
441+
# Linux: Use single-config generator
442+
if [ "${{ matrix.arch }}" = "arm64" ]; then
443+
# ARM64 cross-compilation
444+
cmake -B build -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
445+
-DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \
446+
-DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \
447+
-DCMAKE_SYSTEM_NAME=Linux \
448+
-DCMAKE_SYSTEM_PROCESSOR=aarch64 \
449+
-DCCAP_BUILD_EXAMPLES=OFF \
450+
-DCCAP_BUILD_TESTS=OFF \
451+
-DCCAP_BUILD_SHARED=OFF \
452+
-DBUILD_CCAP_CLI=ON
453+
else
454+
# Regular Linux x86_64
455+
cmake -B build -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
456+
-DCCAP_BUILD_EXAMPLES=OFF \
457+
-DCCAP_BUILD_TESTS=OFF \
458+
-DCCAP_BUILD_SHARED=OFF \
459+
-DBUILD_CCAP_CLI=ON
460+
fi
461+
else
462+
# macOS: Use single-config generator with universal binary
463+
cmake -B build -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' \
464+
-DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
465+
-DCCAP_BUILD_EXAMPLES=OFF \
466+
-DCCAP_BUILD_TESTS=OFF \
467+
-DCCAP_BUILD_SHARED=OFF \
468+
-DBUILD_CCAP_CLI=ON
469+
fi
470+
471+
- name: Build CLI
472+
shell: bash
473+
run: |
474+
if [ "${{ matrix.os }}" = "windows-latest" ]; then
475+
# Windows: Build Release version only
476+
cmake --build build --config Release --target ccap-cli --parallel
477+
else
478+
# Other platforms: Build specified version
479+
cmake --build build --config ${{ matrix.build_type }} --target ccap-cli --parallel
480+
fi
481+
482+
- name: Prepare CLI package directory
483+
shell: bash
484+
run: |
485+
mkdir -p cli-package
486+
487+
- name: Copy CLI executable (Windows)
488+
if: matrix.os == 'windows-latest'
489+
shell: bash
490+
run: |
491+
# Copy CLI executable (renamed from ccap.exe to ccap-cli.exe for clarity)
492+
cp build/Release/ccap.exe cli-package/ccap-cli.exe || echo "CLI executable not found"
493+
494+
# Copy required DLLs if any
495+
# Note: Static build should not need additional DLLs
496+
497+
- name: Copy CLI executable (macOS)
498+
if: matrix.os == 'macos-latest'
499+
shell: bash
500+
run: |
501+
# Copy CLI executable (renamed from ccap to ccap-cli for clarity)
502+
cp build/ccap cli-package/ccap-cli || echo "CLI executable not found"
503+
504+
# Verify universal binary
505+
if [ -f "cli-package/ccap-cli" ]; then
506+
file cli-package/ccap-cli
507+
lipo -info cli-package/ccap-cli
508+
fi
509+
510+
- name: Copy CLI executable (Linux)
511+
if: matrix.os == 'ubuntu-latest'
512+
shell: bash
513+
run: |
514+
# Copy CLI executable (renamed from ccap to ccap-cli for clarity)
515+
cp build/ccap cli-package/ccap-cli || echo "CLI executable not found"
516+
517+
# Verify architecture
518+
if [ -f "cli-package/ccap-cli" ]; then
519+
file cli-package/ccap-cli
520+
fi
521+
522+
- name: Copy documentation
523+
shell: bash
524+
run: |
525+
# Copy README files
526+
cp README.md cli-package/ || echo "README not found"
527+
cp README.zh-CN.md cli-package/ || echo "Chinese README not found"
528+
cp LICENSE cli-package/ || echo "LICENSE not found"
529+
530+
# Create a simple usage guide for CLI
531+
cat > cli-package/USAGE.md << 'EOF'
532+
# ccap CLI Tool Usage
533+
534+
## Quick Start
535+
536+
```bash
537+
# List all available cameras
538+
./ccap-cli --list-devices
539+
540+
# Capture a single frame (saves as output.bmp by default)
541+
./ccap-cli
542+
543+
# Capture with specific device
544+
./ccap-cli --device 0
545+
546+
# Capture with specific resolution
547+
./ccap-cli --width 1920 --height 1080
548+
549+
# Capture with specific pixel format
550+
./ccap-cli --format YUYV
551+
552+
# Capture with internal format (camera native format)
553+
./ccap-cli --internal-format MJPEG
554+
555+
# Capture multiple frames
556+
./ccap-cli --count 10
557+
558+
# Save to specific file
559+
./ccap-cli --output my-capture.bmp
560+
561+
# Preview window (if compiled with GLFW support)
562+
./ccap-cli --preview
563+
```
564+
565+
## Available Options
566+
567+
Run `./ccap-cli --help` for complete list of options.
568+
569+
## System Requirements
570+
571+
- **macOS**: 10.13 or higher
572+
- **Windows**: Windows 10 or higher
573+
- **Linux**: Modern Linux distribution with V4L2 support (kernel 2.6+)
574+
575+
## Notes
576+
577+
- This CLI tool is statically linked and has no external dependencies
578+
- BMP format is the only supported output format
579+
- For more advanced usage, please refer to the ccap library documentation
580+
EOF
581+
582+
- name: Create CLI archive
583+
shell: bash
584+
run: |
585+
cd cli-package
586+
if [ "${{ matrix.os }}" = "windows-latest" ]; then
587+
# Windows: Create ZIP file
588+
7z a ../${{ matrix.artifact_name }}.zip ./*
589+
else
590+
# macOS and Linux: Create tar.gz file
591+
tar -czf ../${{ matrix.artifact_name }}.tar.gz .
592+
fi
593+
cd ..
594+
595+
- name: Upload CLI artifact
596+
uses: actions/upload-artifact@v4
597+
with:
598+
name: ${{ matrix.artifact_name }}
599+
path: ${{ matrix.artifact_name }}.*
600+
retention-days: 5
601+
378602
release:
379-
needs: [test, build]
603+
needs: [test, build, build-cli]
380604
runs-on: ubuntu-latest
381605
permissions:
382606
contents: write
@@ -446,6 +670,8 @@ jobs:
446670
447671
### 📦 Downloads
448672
673+
**Library Packages:**
674+
449675
**Static Library Packages (for static linking):**
450676
- **macOS** (Universal Binary - supports Intel & Apple Silicon): `ccap-macos-universal-static.tar.gz`
451677
- **Windows** (MSVC x64 - includes Debug and Release versions): `ccap-msvc-x86_64-static.zip`
@@ -458,6 +684,14 @@ jobs:
458684
- **Linux x86_64** (compatible with most distributions): `ccap-linux-x86_64-shared.tar.gz`
459685
- **Linux ARM64** (compatible with Raspberry Pi, ARM servers, and other ARM64 boards): `ccap-linux-arm64-shared.tar.gz`
460686
687+
**CLI Tool Packages (standalone command-line tool):**
688+
- **macOS** (Universal Binary): `ccap-cli-macos-universal.tar.gz`
689+
- **Windows** (x64): `ccap-cli-msvc-x86_64.zip`
690+
- **Linux x86_64**: `ccap-cli-linux-x86_64.tar.gz`
691+
- **Linux ARM64**: `ccap-cli-linux-arm64.tar.gz`
692+
693+
> **CLI Tool**: The CLI packages contain only the standalone `ccap-cli` executable (statically linked). Perfect for quick testing and simple capture tasks without requiring library integration.
694+
461695
### 📁 Package Contents
462696
463697
**Static Library Packages:**
@@ -511,6 +745,19 @@ jobs:
511745
- **Linux ARM64**: Link `lib/libccap.so`, ensure so is in LD_LIBRARY_PATH or install location
512746
5. Refer to example code in the `examples` directory
513747
748+
**For CLI Tool:**
749+
1. Download the appropriate CLI package for your platform
750+
2. Extract the archive
751+
3. Run the `ccap-cli` executable directly (no installation required):
752+
```bash
753+
# List available cameras
754+
./ccap-cli --list-devices
755+
756+
# Capture a frame
757+
./ccap-cli --output my-capture.bmp
758+
```
759+
4. See `USAGE.md` in the package for complete usage guide
760+
514761
### 📋 System Requirements
515762
516763
- **macOS**: 10.13 or higher
@@ -533,6 +780,8 @@ jobs:
533780
files: |
534781
*/ccap-*.zip
535782
*/ccap-*.tar.gz
783+
*/ccap-cli-*.zip
784+
*/ccap-cli-*.tar.gz
536785
draft: false
537786
prerelease: ${{ steps.release_type.outputs.prerelease }}
538787
generate_release_notes: true
@@ -570,4 +819,10 @@ jobs:
570819
echo "- ccap-linux-x86_64-shared.tar.gz" >> $GITHUB_STEP_SUMMARY
571820
echo "- ccap-linux-arm64-shared.tar.gz" >> $GITHUB_STEP_SUMMARY
572821
echo "" >> $GITHUB_STEP_SUMMARY
822+
echo "**CLI Tool Packages:**" >> $GITHUB_STEP_SUMMARY
823+
echo "- ccap-cli-macos-universal.tar.gz" >> $GITHUB_STEP_SUMMARY
824+
echo "- ccap-cli-msvc-x86_64.zip" >> $GITHUB_STEP_SUMMARY
825+
echo "- ccap-cli-linux-x86_64.tar.gz" >> $GITHUB_STEP_SUMMARY
826+
echo "- ccap-cli-linux-arm64.tar.gz" >> $GITHUB_STEP_SUMMARY
827+
echo "" >> $GITHUB_STEP_SUMMARY
573828
echo "Release page: ${{ github.server_url }}/${{ github.repository }}/releases/tag/${{ steps.release_type.outputs.tag_name }}" >> $GITHUB_STEP_SUMMARY

‎.github/workflows/windows-build.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ jobs:
3535
}
3636
mkdir -p "build/${{ matrix.config }}-${{ matrix.library_type }}"
3737
cd "build/${{ matrix.config }}-${{ matrix.library_type }}"
38-
cmake ../.. -G "Visual Studio 17 2022" -A x64 -DCCAP_BUILD_TESTS=ON $SHARED_FLAG
38+
cmake ../.. -G "Visual Studio 17 2022" -A x64 -DCCAP_BUILD_TESTS=ON -DBUILD_CCAP_CLI=ON $SHARED_FLAG
3939
4040
- name: Build
4141
run: |

0 commit comments

Comments
 (0)