2025-09-29 02:27:58 -04:00

9.3 KiB

Raw Blame History

AzerothCore Module Manager

This directory contains the module management system for AzerothCore, providing advanced functionality for installing, updating, and managing server modules.

🚀 Features

Advanced Syntax: Support for repo[:dirname][@branch[:commit]] format
Cross-Format Recognition: Intelligent matching across URLs, SSH, and simple names
Custom Directory Naming: Prevent conflicts with custom directory names
Duplicate Prevention: Smart detection and prevention of duplicate installations
Multi-Host Support: GitHub, GitLab, and other Git hosts
Module Exclusion: Support for excluding modules via environment variable
Interactive Menu System: Easy-to-use menu interface for module management
Colored Output: Enhanced terminal output with color support (respects NO_COLOR)
Flat Directory Structure: Uses flat module installation (no owner subfolders)

📁 File Structure

modules-manager/
├── modules.sh              # Core module management functions
└── README.md               # This documentation file

🔧 Module Specification Syntax

The module manager supports flexible syntax for specifying modules:

New Syntax Format

repo[:dirname][@branch[:commit]]

Examples

Specification	Description
`mod-transmog`	Simple module name, uses default branch and directory
`mod-transmog:my-custom-dir`	Custom directory name
`mod-transmog@develop`	Specific branch
`mod-transmog:custom@develop:abc123`	Custom directory, branch, and commit
`https://github.com/owner/repo.git@main`	Full URL with branch
`git@github.com:owner/repo.git:custom-dir`	SSH URL with custom directory

🎯 Usage Examples

Installing Modules

# Simple module installation
./acore.sh module install mod-transmog

# Install with custom directory name
./acore.sh module install mod-transmog:my-transmog-dir

# Install specific branch
./acore.sh module install mod-transmog@develop

# Install with full specification
./acore.sh module install mod-transmog:custom-dir@develop:abc123

# Install from URL
./acore.sh module install https://github.com/azerothcore/mod-transmog.git@main

# Install multiple modules
./acore.sh module install mod-transmog mod-eluna:custom-eluna

# Install all modules from list
./acore.sh module install --all

Updating Modules

# Update specific module
./acore.sh module update mod-transmog

# Update all modules
./acore.sh module update --all

# Update with branch specification
./acore.sh module update mod-transmog@develop

Removing Modules

# Remove by simple name (cross-format recognition)
./acore.sh module remove mod-transmog

# Remove by URL (recognizes same module)
./acore.sh module remove https://github.com/azerothcore/mod-transmog.git

# Remove multiple modules
./acore.sh module remove mod-transmog mod-eluna

Searching Modules

# Search for modules
./acore.sh module search transmog

# Search with multiple terms
./acore.sh module search auction house

# Search with input prompt
./acore.sh module search

Listing Installed Modules

# List all installed modules
./acore.sh module list

# Start interactive menu system
./acore.sh module

# Menu options:
# s - Search for available modules
# i - Install one or more modules  
# u - Update installed modules
# r - Remove installed modules
# l - List installed modules
# h - Show detailed help
# q - Close this menu

🔍 Cross-Format Recognition

The system intelligently recognizes the same module across different specification formats:

# These all refer to the same module:
mod-transmog
azerothcore/mod-transmog
https://github.com/azerothcore/mod-transmog.git
git@github.com:azerothcore/mod-transmog.git

This allows:

Installing with one format and removing with another
Preventing duplicates regardless of specification format
Consistent module tracking across different input methods

🛡️ Conflict Prevention

The system prevents common conflicts:

Directory Conflicts

# If 'mod-transmog' directory already exists:
$ ./acore.sh module install mod-transmog:mod-transmog
Possible solutions:
  1. Use a different directory name: mod-transmog:my-custom-name
  2. Remove the existing directory first
  3. Use the update command if this is the same module

Duplicate Module Prevention

The system uses intelligent owner/name matching to prevent installing the same module multiple times, even when specified in different formats.

🚫 Module Exclusion

You can exclude modules from installation using the MODULES_EXCLUDE_LIST environment variable:

# Exclude specific modules (space-separated)
export MODULES_EXCLUDE_LIST="mod-test-module azerothcore/mod-dev-only"
./acore.sh module install --all  # Will skip excluded modules

# Supports cross-format matching
export MODULES_EXCLUDE_LIST="https://github.com/azerothcore/mod-transmog.git"
./acore.sh module install mod-transmog  # Will be skipped as excluded

The exclusion system:

Uses the same cross-format recognition as other module operations
Works with all installation methods (install, install --all)
Provides clear feedback when modules are skipped
Supports URLs, owner/name format, and simple names

🎨 Color Support

The module manager provides enhanced terminal output with colors:

Info: Cyan text for informational messages
Success: Green text for successful operations
Warning: Yellow text for warnings
Error: Red text for errors
Headers: Bold cyan text for section headers

Color support is automatically disabled when:

Output is not to a terminal (piped/redirected)
NO_COLOR environment variable is set
Terminal doesn't support colors

You can force color output with:

export FORCE_COLOR=1

🔄 Integration

Including in Scripts

# Source the module functions
source "$AC_PATH_INSTALLER/includes/modules-manager/modules.sh"

# Use module functions
inst_module_install "mod-transmog:custom-dir@develop"

Testing

The module system is tested through the main installer test suite:

./apps/installer/test/test_module_commands.bats

📋 Module List Format

Modules are tracked in conf/modules.list with the format:

# Comments start with #
repo_reference branch commit

# Examples:
azerothcore/mod-transmog master abc123def456
https://github.com/custom/mod-custom.git develop def456abc789
mod-eluna:custom-eluna-dir main 789abc123def

The list maintains:

Alphabetical ordering by normalized owner/name for consistency
Original format preservation of how modules were specified
Automatic deduplication across different specification formats
Custom directory tracking when specified

🔧 Configuration

Environment Variables

Variable	Description	Default
`MODULES_LIST_FILE`	Override default modules list path	`$AC_PATH_ROOT/conf/modules.list`
`MODULES_EXCLUDE_LIST`	Space-separated list of modules to exclude	-
`J_PATH_MODULES`	Modules installation directory	`$AC_PATH_ROOT/modules`
`AC_PATH_ROOT`	AzerothCore root path	-
`NO_COLOR`	Disable colored output	-
`FORCE_COLOR`	Force colored output even when not TTY	-

Default Paths

Modules list: $AC_PATH_ROOT/conf/modules.list
Installation directory: $J_PATH_MODULES (flat structure, no owner subfolders)

🏗️ Architecture

Core Functions

Function	Purpose
`inst_module()`	Main dispatcher and interactive menu
`inst_parse_module_spec()`	Parse advanced module syntax
`inst_extract_owner_name()`	Normalize modules for cross-format recognition
`inst_mod_list_*()`	Module list management (read/write/update)
`inst_module_*()`	Module operations (install/update/remove/search)

Key Features

Flat Directory Structure: All modules install directly under modules/ without owner subdirectories
Smart Conflict Detection: Prevents directory name conflicts with helpful suggestions
Cross-Platform Compatibility: Works on Linux, macOS, and Windows (Git Bash)
Version Compatibility: Checks acore-module.json for AzerothCore version compatibility
Git Integration: Uses Joiner system for Git repository management

Debug Mode

For debugging module operations, you can examine the generated commands:

# Check what Joiner commands would be executed
tail -f /tmp/joiner_called.txt  # In test environments

🤝 Contributing

When modifying the module manager:

Maintain backwards compatibility with existing module list format
Update tests in test_module_commands.bats for new functionality
Update this documentation for any new features or changes
Test cross-format recognition thoroughly across all supported formats
Ensure helpful error messages for common user mistakes
Test exclusion functionality with various module specification formats
Verify color output works correctly in different terminal environments

Testing Guidelines

# Run all module-related tests
cd apps/installer
bats test/test_module_commands.bats

# Test with different environments
NO_COLOR=1 ./acore.sh module list
FORCE_COLOR=1 ./acore.sh module help

9.3 KiB Raw Blame History