188 lines
4.9 KiB
Markdown
188 lines
4.9 KiB
Markdown
# 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
|
|
|
|
## 📁 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
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Search for modules
|
|
./acore.sh module search transmog
|
|
|
|
# Search with multiple terms
|
|
./acore.sh module search auction house
|
|
|
|
# Show all available modules
|
|
./acore.sh module search
|
|
```
|
|
|
|
## 🔍 Cross-Format Recognition
|
|
|
|
The system intelligently recognizes the same module across different specification formats:
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# If 'mod-transmog' directory already exists:
|
|
$ ./acore.sh module install mod-transmog:mod-transmog
|
|
Error: Directory 'mod-transmog' already exists.
|
|
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
|
|
```
|
|
|
|
## 🔄 Integration
|
|
|
|
### Including in Scripts
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
./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
|
|
```
|
|
## 🔧 Configuration
|
|
|
|
### Environment Variables
|
|
- `MODULES_LIST_FILE`: Override default modules list path
|
|
- `J_PATH_MODULES`: Modules installation directory
|
|
- `AC_PATH_ROOT`: AzerothCore root path
|
|
|
|
### Default Paths
|
|
- Modules list: `$AC_PATH_ROOT/conf/modules.list`
|
|
|
|
## 🤝 Contributing
|
|
|
|
When modifying the module manager:
|
|
|
|
1. Maintain backwards compatibility
|
|
2. Update tests in `test_module_commands.bats`
|
|
3. Update this documentation
|
|
4. Test cross-format recognition thoroughly
|
|
5. Ensure helpful error messages
|
|
|
|
|