Support "COMPONENTS" in ApraPipes like BOOST/OPENCV

[mraduldubey]

Is your feature request related to a problem? Please describe.
A valid requirement is to support COMPONENTS while using ApraPipes in any codebase (find_package)

Describe the solution you'd like
OPENCV and BOOST allows including COMPONENTS in CMakelists and the library links against only those components. For eg.
find_package(Boost COMPONENTS filesystem log chrono REQUIRED)
This will include only the filesystem, log & chrono components from BOOST.
For ApraPipes, following component, for eg, will make sense:
GTK -> currently this is correlated to CUDA on linux/arm and it is frequently not required in projects

Describe alternatives you've considered
Alternative is to create different flavored and custom builds, which seems unsustainable.

Additional context
ApraNVR has no requirement for GTK but building ApraPipes requires GTK ( this builds by default on ApraPipes ARM build which assumes CUDA by default) - but we do not need CUDA for ApraNVR, thus increasing the build size which is unnecessary. The alternative solution was to build arm-no-cuda build for ApraPipes

[mraduldubey]

ApraPipes Component-Based Build System Refactoring Log

Start Date: 2025-10-08
Status: Planning Complete - Ready for Implementation
Current Phase: Phase 0 - Planning

---

Executive Summary

Restructuring ApraPipes build system to support optional COMPONENTS (similar to Boost), allowing users to build only needed functionality. This addresses the issue where all dependencies must be built even for specialized use cases, causing excessive build times (60-90 min) and large dependency footprints.

---

Complete Module Inventory (90+ modules)

Current CMake Organization:

• CORE_FILES: 30 modules (pipeline infrastructure + some specialized)
• GENERIC_FILES: 5 modules (H264/RTSP utilities)
• IP_FILES: 25 modules (OpenCV-based image processing)
• CUDA_CORE_FILES: 7 modules (CUDA memory management)
• CUDA_IP_FILES: 13 modules (CUDA image processing)
• ARM64-specific: 21 modules (Jetson hardware)
• GTKGL_FILES: 6 modules (Linux rendering)

Total: 90+ modules to be organized into 12 components

---

Approved Component Structure

1. CORE (Always built, truly minimal dependencies)

Modules (17 - cleaned up):

• Pipeline infrastructure: Module, Frame, FrameFactory, FrameContainerQueue, PipeLine
• Utilities: Logger, Utils, ApraPool, QuePushStrategy
• Basic I/O: FileReaderModule, FileWriterModule, FileSequenceDriver, FilenameStrategy, FIndexStrategy
• Control flow: Split, Merge, SimpleControlModule, AbsControlModule
• Error handling: APErrorObject, APHealthObject
• Metadata: FramesMuxer, ValveModule
• Test utilities: TestSignalGeneratorSrc
• LINUX: KeyboardListener

Dependencies:

• Boost (system, thread, filesystem, serialization, log, chrono)
• libjpeg-turbo, BZip2, ZLIB, LibLZMA

Build Time: ~5 min

---

2. VIDEO (Video codecs and streaming)

Modules (11):

• Mp4 I/O: Mp4ReaderSource, Mp4WriterSink, Mp4WriterSinkUtils, OrderedCacheOfFiles
• H264: H264FrameDemuxer, H264ParserUtils, H264Utils
• Streaming: RTSPPusher, RTSPClientSrc
• Processing: MultimediaQueueXform, MotionVectorExtractor
• LINUX: VirtualCameraSink

Dependencies:

• FFmpeg (libavcodec, libavformat, libavutil)
• openh264-apra
• libmp4

Depends On: CORE

---

3. IMAGE_PROCESSING (OpenCV CPU-based processing)

Modules (17):

• Core processing: ImageDecoderCV, ImageEncoderCV, ImageResizeCV, RotateCV, BMPConverter
• Transformations: AffineTransform, BrightnessContrastControlXform, VirtualPTZ, ColorConversionXForm, AbsColorConversionFactory
• Overlays: Overlay, OverlayFactory, OverlayModule, TextOverlayXForm
• Analysis: CalcHistogramCV, HistogramOverlay, ApraLines
• Storage: ArchiveSpaceManager

Dependencies:

• OpenCV (core, imgproc, imgcodecs, highgui - without CUDA/DNN/contrib)

Depends On: CORE

---

4. CUDA (GPU acceleration)

Modules (20):

• Memory management: apra_cudamalloc_allocator, apra_cudamallochost_allocator, CudaMemCopy, MemTypeConversion, CudaStreamSynchronize, CuCtxSynchronize, CudaCommon
• NPP processing: ResizeNPPI, RotateNPPI, OverlayNPPI, CCNPPI, EffectsNPPI, CCKernel, EffectsKernel, OverlayKernel, build_point_list
• Image codecs: JPEGEncoderNVJPEG, JPEGDecoderNVJPEG
• Video codecs: H264EncoderNVCodec, H264EncoderNVCodecHelper, H264Decoder, H264DecoderNvCodecHelper (non-ARM64)
• Other: GaussianBlur

Dependencies:

• CUDA Toolkit, NPP, NVJPEG, NVCODEC
• OpenCV (with CUDA features)

Depends On: CORE, IMAGE_PROCESSING

---

5. ARM64 (Jetson/ARM64-specific)

Modules (21):

• JPEG L4TM: JPEGEncoderL4TM, JPEGEncoderL4TMHelper, JPEGDecoderL4TM, JPEGDecoderL4TMHelper
• H264 V4L2: H264EncoderV4L2, H264EncoderV4L2Helper, H264DecoderV4L2Helper, V4L2CUYUV420Converter
• V4L2: AV4L2Buffer, AV4L2ElementPlane
• Cameras: NvArgusCamera, NvArgusCameraHelper, NvV4L2Camera, NvV4L2CameraHelper
• Rendering: EglRenderer, NvEglRenderer, ApraEGLDisplay
• DMA: DMAFDWrapper, DMAUtils, DMAFDToHostCopy
• Transform: NvTransform

Dependencies:

• V4L2 (nvv4l2), Jetson multimedia API
• EGL, GLESv2, nvbuf_utils, nveglstream_camconsumer, nvargus_socketclient
• libcuda, libcudart_static

Depends On: CORE, CUDA
Platform: ARM64 Linux only

---

6. WEBCAM (Webcam capture)

Modules (1):

• WebCamSource

Dependencies: OpenCV (videoio)
Depends On: CORE, IMAGE_PROCESSING

---

7. QR (QR code reading)

Modules (1):

• QRReader

Dependencies: ZXing (nu-book-zxing-cpp)
Depends On: CORE, IMAGE_PROCESSING

---

8. AUDIO (Audio capture & transcription - MERGED)

Modules (2):

• AudioCaptureSrc (audio capture)
• AudioToTextXForm (transcription with whisper)

Dependencies:

• SFML (audio, system, window, graphics)
• whisper (with CUDA support)

Depends On: CORE, optionally CUDA for whisper acceleration

Note: Whisper build is time-intensive (30+ min). Users can build AUDIO without transcription if needed via sub-component flag.

---

9. FACE_DETECTION (Face detection & landmarks)

Modules (2):

• FaceDetectorXform
• FacialLandmarksCV

Dependencies: OpenCV (with DNN, contrib, objdetect modules)
Depends On: CORE, IMAGE_PROCESSING

---

10. GTK_RENDERING (Linux GUI rendering)

Modules (6):

• GtkGlRenderer, GTKMatrix, GTKModel, GTKSetup, GTKView, Background

Dependencies:

• GTK3, GDK3, glib, gio, gobject
• GLEW, glfw3, FreeGLUT, OpenGL

Depends On: CORE, IMAGE_PROCESSING
Platform: Linux only

---

11. THUMBNAIL (Thumbnail generation)

Modules (1):

• ThumbnailListGenerator

Dependencies: OpenCV (imgproc)
Depends On: CORE, IMAGE_PROCESSING

---

12. IMAGE_VIEWER (Image viewing - GUI)

Modules (1):

• ImageViewerModule

Dependencies: OpenCV (highgui)
Depends On: CORE, IMAGE_PROCESSING
Note: Requires GUI support (X11/Windows)

---

Implementation Phases

Phase 0: Planning ✓ COMPLETE

Duration: 1 day
Status: Complete
Date: 2025-10-08

• Analyze codebase structure
• Inventory all 90+ modules
• Design component architecture
• Define component dependencies
• Create implementation plan
• Create log file

---

Phase 1: CMake Infrastructure

Duration: 1 week
Status: Not Started
Target Start: TBD

Tasks:

1. Create component option system in base/CMakeLists.txt
2. Add ENABLE_COMPONENTS cache variable with default "ALL"
3. Create component dependency validation logic
4. Add component-specific compile definitions (APRA_ENABLE_VIDEO, etc.)
5. Split source file lists by component
6. Update target_link_libraries to be conditional
7. Test basic CORE-only build

Success Criteria:

• CMake accepts ENABLE_COMPONENTS variable
• CORE component builds successfully
• Component dependency validation works

---

Phase 2: vcpkg Dependency Management

Duration: 1-2 weeks
Status: Not Started
Target Start: TBD

Tasks:

1. Make vcpkg dependencies conditional
2. Split OpenCV into minimal vs full configurations
3. Make optional: whisper, ZXing, SFML, GTK3, GLEW, glfw3
4. Update base/vcpkg.json with conditional logic
5. Test dependency resolution for each component
6. Verify vcpkg caching works correctly

Success Criteria:

• CORE build doesn't pull in heavy dependencies
• Each component pulls only required dependencies
• vcpkg manifest mode works correctly

---

Phase 3: Source Code Separation

Duration: 1-2 weeks
Status: Not Started
Target Start: TBD

Tasks:

1. Add #ifdef APRA_ENABLE_<COMPONENT> guards to ModuleFactory
2. Update module registration to be conditional
3. Ensure clean separation - no cross-component dependencies
4. Handle optional module headers in client code
5. Update include guards and forward declarations
6. Fix any circular dependencies

Success Criteria:

• All modules compile only when their component is enabled
• No undefined references when components are disabled
• Clean compilation for all component combinations

---

Phase 4: Testing Infrastructure

Duration: 1-2 weeks
Status: Not Started
Target Start: TBD

Tasks:

1. Split test files by component
2. Create conditional test compilation
3. Add component availability tests
4. Create test matrix for component combinations
5. Update CI/CD to test multiple configs
6. Verify all existing tests still pass with ALL components

Success Criteria:

• Tests compile only for enabled components
• All component combinations build and test successfully
• No test regressions in full build

---

Phase 5: Build Scripts Update

Duration: 1 week
Status: Not Started
Target Start: TBD

Tasks:

1. Update build_windows_cuda.bat with component flags
2. Update build_windows_no_cuda.bat
3. Update build_linux_cuda.sh
4. Update build_linux_no_cuda.sh
5. Update build_jetson.sh
6. Create preset configurations
7. Add component selection help text

Success Criteria:

• All build scripts support component selection
• Preset configurations work correctly
• Clear error messages for invalid combinations

---

Phase 6: Documentation

Duration: 1 week
Status: Not Started
Target Start: TBD

Tasks:

1. Update CLAUDE.md with component information
2. Create component dependency diagram
3. Document recommended component combinations
4. Add troubleshooting guide
5. Update README.md
6. Create migration guide for existing users

Success Criteria:

• Complete component documentation
• Clear usage examples
• Migration path documented

---

Phase 7: CI/CD Updates

Duration: 1 week
Status: Not Started
Target Start: TBD

Tasks:

1. Update GitHub Actions workflows
2. Add matrix builds for component combinations
3. Validate full builds still work
4. Test incremental builds
5. Add build time tracking
6. Update test result badges

Success Criteria:

• CI tests multiple component combinations
• Build times tracked and reported
• All existing workflows pass

---

CMake Usage Examples

# Minimal build - pipeline only
cmake -DENABLE_COMPONENTS="CORE" ../base

# Video processing (no GPU)
cmake -DENABLE_COMPONENTS="CORE;VIDEO;IMAGE_PROCESSING" ../base

# Full CUDA build
cmake -DENABLE_COMPONENTS="CORE;VIDEO;IMAGE_PROCESSING;CUDA" ../base

# Specialized: Audio transcription with GPU
cmake -DENABLE_COMPONENTS="CORE;AUDIO;CUDA" ../base

# Face detection system
cmake -DENABLE_COMPONENTS="CORE;IMAGE_PROCESSING;WEBCAM;FACE_DETECTION" ../base

# Current full build (default, maintains backward compatibility)
cmake ../base  # or -DENABLE_COMPONENTS="ALL"

---

Expected Benefits

Build Time Reduction

• Minimal (CORE only): 5-10 min (vs 60-90 min full)
• Standard (no CUDA): 15-25 min
• No Whisper: Save 30+ min
• No GTK: Save 10-15 min on Linux

Dependency Size Reduction

• Without CUDA: ~50% smaller vcpkg cache
• Without Whisper: ~30% smaller
• Without GTK: ~20% smaller on Linux

---

Module Verification Checklist

• All 30 CORE_FILES modules accounted for (redistributed appropriately)
• All 5 GENERIC_FILES modules accounted for
• All 25 IP_FILES modules accounted for (redistributed)
• All 7 CUDA_CORE_FILES modules in CUDA component
• All 13 CUDA_IP_FILES modules in CUDA component
• All 21 ARM64 modules in ARM64 component
• All 6 GTKGL modules in GTK_RENDERING component
• Linux-specific modules accounted for
• Duplicates resolved (QRReader)

Total: 90+ modules across 12 components ✓

---

Risk Mitigation

1. Backward Compatibility: Default to ALL components (current behavior)
2. Dependency Validation: CMake enforces component dependencies
3. Testing: Extensive matrix testing of component combinations
4. Incremental Rollout: Phase by phase with validation
5. Rollback Plan: Git branch allows easy revert if needed

---

Change Log

2025-10-08 - Planning Phase Complete

• Phase: 0 - Planning
• Status: Complete
• Changes:
  • Analyzed complete codebase structure
  • Inventoried all 90+ modules across current file groups
  • Designed 12-component architecture
  • Created implementation plan with 7 phases
  • Defined success criteria for each phase
  • Created this log file

---

Build Performance Tracking

Configuration	Expected Time	Actual Time	vcpkg Size	Notes
Full Build (ALL)	60-90 min	TBD	TBD	Baseline
CORE only	5-10 min	TBD	TBD
CORE+VIDEO+IMAGE	15-25 min	TBD	TBD
CORE+CUDA	20-30 min	TBD	TBD

---

Issues & Resolutions

Issue Log

No issues yet - will be populated during implementation

---

Next Steps

1. Review and approve this plan
2. Create git branch for component refactoring work
3. Start Phase 1 - CMake Infrastructure
4. Set up test environment for validation

---

Notes

• All changes will be made on a separate branch
• Each phase will be committed separately
• Testing at each phase before proceeding
• Log will be updated with progress and issues

[kumaakh]

🔍 Deep Analysis - PR Exists, Awaiting Decision

Associated PR: #427 Feature/component based build
PR Status: Open since Oct 2025 (4 months)
PR Branch: feature/component-based-build

What the issue requests:
Support find_package(ApraPipes COMPONENTS gtk cuda ...) like Boost/OpenCV

Critical Assessment:

• This is a significant architectural change
• Requires refactoring CMake build system
• Would benefit downstream users who don't need all features
• 4 months without merge suggests complexity or lack of priority

Questions:

1. Is PR Feature/component based build #427 complete and working?
2. What's blocking the merge?
3. Is there active demand from downstream users?

Recommendation:

• If there are real users requesting this, prioritize review
• If speculative, consider closing to reduce backlog
• Complexity vs benefit ratio seems high

Impact: Medium - would benefit ApraNVR and other downstream projects