.copilot-instructions.md

Dmod Repository - Copilot Instructions

Overview

The Dmod (Dynamic Modules) library enables dynamic loading of programs and libraries into embedded architectures at runtime. This allows you to dynamically extend embedded system capabilities without recompiling or restarting the entire application.

Branching Strategy and Workflow

Branch Structure

• master: Contains only released and tested versions

  • Only repository owners can merge to master
  • Every merge to master should include a tag with the new release version
  • Used for production releases only

• develop: Main development branch

  • Developers and copilot can create pull requests from and into this branch
  • All new features and bug fixes should be developed here
  • Should always be in a stable, buildable state

Branch Naming Conventions

All development branches should use the following prefixes:

• feature/: For new features and enhancements

  • Example: feature/add-new-api-endpoint
  • Example: feature/improve-memory-management

• bug/: For bug fixes

  • Example: bug/fix-memory-leak
  • Example: bug/resolve-segfault-on-module-load

• documentation/: For documentation updates

  • Example: documentation/update-api-docs
  • Example: documentation/add-contributing-guide

Pull Request Guidelines

1. Base Branch: Always create pull requests targeting the develop branch
2. Title: Use clear, descriptive titles that explain the change
3. Description: Include:
   • What changes were made
   • Why the changes were necessary
   • Any testing performed
   • Links to related issues

Build System

Prerequisites

• Compiler: GCC-compatible compiler
• Build System: CMake 3.18+ (recommended) or Make 4.2+
• Architecture: Currently supports x86_64 and ARMv7

Build Configuration

IMPORTANT: Always use the build/ directory for builds (not build_cmake/ or other names). This directory is gitignored and should never be committed to the repository.

The project uses two build modes:

1. SYSTEM Mode: For building the library to include in host projects

   cmake -DDMOD_MODE=DMOD_SYSTEM -DDMOD_TOOLS_NAME=arch/x86_64 -B build -S .
   cmake --build build/

2. MODULE Mode: For building dynamic modules (DMF files)

   cmake -DDMOD_MODE=DMOD_MODULE -DDMOD_TOOLS_NAME=arch/x86_64 -B build -S .
   cmake --build build/

Alternative with Make:

# System mode
make DMOD_MODE=DMOD_SYSTEM

# Module mode  
make DMOD_MODE=DMOD_MODULE

Required Configuration Files

Before building, copy the appropriate architecture configuration:

# For x86_64 development (most common)
cp configs/arch/x86_64/tools-cfg.cmake ./

# For ARM development
cp configs/arch/armv7/cortex-m7/tools-cfg.cmake ./

• Adapt dmod-cfg.cmake for your specific project needs
• Include dmod-common.ld in your linker script
• The tools-cfg.cmake file is gitignored as it's architecture-specific

Running Tests

# Complete test workflow (as per CI pipeline)
# 1. Build in MODULE mode first to generate DMF files
cmake -DDMOD_MODE=DMOD_MODULE -DDMOD_TOOLS_NAME=arch/x86_64 -B build -S . -Wno-dev
cmake --build build/

# 2. Build in SYSTEM mode
cmake -DDMOD_MODE=DMOD_SYSTEM -DDMOD_TOOLS_NAME=arch/x86_64 -B build -S . -Wno-dev
cmake --build build/

# 3. Test the system with example DMF
./build/examples/system/dmod_loader ./build/dmf/example_app.dmf

# 4. Run individual unit tests
./build/tests/tests_dmod_ctx
./build/tests/tests_dmod_hlp
./build/tests/tests_dmod_ldr
./build/tests/tests_dmod_mgr

# 5. Optional: Run coverage check (requires gcovr)
cmake --build build/ --target coverage_check

Note: Some tests require DMF files to be built in MODULE mode first.

Development Guidelines

Continuous Integration

The project uses Bitbucket Pipelines for CI/CD with the following workflow:

1. CMake Build Pipeline:

   • Build MODULE mode for x86_64
   • Build SYSTEM mode for x86_64
   • Test loader with example DMF file
   • Run coverage check

2. Make Build Pipeline:

   • Build SYSTEM mode
   • Build MODULE mode
   • Test execution

All changes should pass both build systems before merging.

Code Style

• C Standard: C11
• C++ Standard: C++17
• Compiler Flags: -Wall for warnings
• Follow existing code formatting and naming conventions

API Development

The project supports three types of APIs:

1. Built-in API: System-wide functions using DMOD_BUILTIN_API macro
2. Module API: Module-specific functions using dmod_<module_name>_api macro
3. Global API: Global scope functions using dmod_<module_name>_global_api macro

Memory Management

• Implement Dmod_Malloc and Dmod_Free functions
• Consider implementing Dmod_AlignedAlloc for aligned memory allocation
• Optional: Implement Dmod_Printf for logging

Testing

• Write unit tests for new functionality using Google Test framework
• Ensure tests pass in both MODULE and SYSTEM modes where applicable
• Test on target architectures when possible

Module Development

Creating New Modules

1. Create module directory structure
2. Use either CMake or Make build system
3. Define module metadata:
   • Module name and version
   • Author information
   • Stack size and priority

CMake Module Template

cmake_minimum_required(VERSION 3.18)

set(DMOD_MODULE_NAME        my_module)
set(DMOD_MODULE_VERSION     "0.1")
set(DMOD_AUTHOR_NAME        "Your Name")
set(DMOD_STACK_SIZE         1024)
set(DMOD_PRIORITY           0)

dmod_add_executable(${DMOD_MODULE_NAME} ${DMOD_MODULE_VERSION} 
    main.c
)

Integration Guidelines

Linker Script Integration

Include dmod-common.ld in your linker script within the .SECTIONS block:

SECTIONS
{
    /* Your sections */
    
    /* Include dmod definitions */
    INCLUDE dmod-common.ld
    
    /* More sections */
}

System Abstract Layer (SAL)

Implement these required functions:

• Dmod_Malloc - Memory allocation
• Dmod_Free - Memory deallocation
• Dmod_AlignedAlloc - Aligned memory allocation

Optional but recommended:

• Dmod_Printf - Logging
• Mutex functions for thread safety

Common Development Tasks

Adding New Features

1. Create feature branch: git checkout -b feature/your-feature-name
2. Implement changes with appropriate tests
3. Update documentation if needed
4. Build and test thoroughly
5. Create pull request to develop branch

Bug Fixes

1. Create bug fix branch: git checkout -b bug/fix-description
2. Identify and fix the issue
3. Add regression tests if appropriate
4. Verify fix doesn't break existing functionality
5. Create pull request to develop branch

Documentation Updates

1. Create documentation branch: git checkout -b documentation/update-description
2. Update relevant documentation files
3. Verify formatting and accuracy
4. Create pull request to develop branch

File Structure

dmod/
├── src/           # Source code
│   ├── common/    # Common utilities
│   ├── system/    # System mode code
│   └── module/    # Module mode code
├── inc/           # Public headers
├── tests/         # Unit tests
├── examples/      # Example applications
├── configs/       # Architecture-specific configs
├── scripts/       # Build scripts and linker files
└── README.md      # Main documentation

Important Notes

• Always test changes on both x86_64 and target embedded architectures when possible
• DMF files contain compiled module code and metadata for dynamic loading
• The library manages module dependencies automatically
• Modules can communicate through well-defined APIs
• Thread safety is optional but recommended for multi-threaded environments
• NEVER commit build artifacts: The build/ directory and all build artifacts (*.o, *.a, *.dmf, *.dmfc, CMakeCache.txt, CMakeFiles/, etc.) are gitignored and should NEVER be committed to the repository. Always verify with git status before committing.
• Build directory naming: Always use build/ for the build directory, not build_cmake/ or other names

Getting Help

• Check the main README.md for comprehensive documentation
• Review existing examples in the examples/ directory
• Look at test files for usage patterns
• Follow existing code patterns and conventions