docs: prepare Pakker documentation
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: I03df3787081bde6ebf0366a24320307a6a6a6964
This commit is contained in:
parent
563ff2b187
commit
5a0a5cedeb
GPG key ID:
29D95B64378DB4BF
4 changed files with 2285 additions and 0 deletions
348
docs/EXPORT_PROFILES.md
Normal file
348
docs/EXPORT_PROFILES.md
Normal file
|
|
@ -0,0 +1,348 @@
|
|||
# Export Profiles Configuration
|
||||
|
||||
Pakker supports profile-specific export configurations, allowing you to customize export behavior for different platforms and use cases.
|
||||
|
||||
## Overview
|
||||
|
||||
Export profiles enable you to:
|
||||
- Use different override directories per profile
|
||||
- Filter projects by platform availability
|
||||
- Control non-redistributable mod inclusion
|
||||
- Customize client-only mod filtering
|
||||
- Override settings per project
|
||||
|
||||
## Configuration
|
||||
|
||||
Add an `exportProfiles` section to your `pakku.json` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "My Modpack",
|
||||
"version": "1.0.0",
|
||||
"overrides": ["overrides"],
|
||||
"exportProfiles": {
|
||||
"curseforge": {
|
||||
"filterPlatform": "curseforge",
|
||||
"includeNonRedistributable": false,
|
||||
"overrides": ["overrides", "curseforge-overrides"]
|
||||
},
|
||||
"modrinth": {
|
||||
"filterPlatform": "modrinth",
|
||||
"includeNonRedistributable": true
|
||||
},
|
||||
"serverpack": {
|
||||
"includeClientOnly": false,
|
||||
"serverOverrides": ["server-config"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Profile Configuration Options
|
||||
|
||||
### `filterPlatform` (string, optional)
|
||||
|
||||
Filter projects to only include those available on the specified platform.
|
||||
|
||||
**Supported values**: `"curseforge"`, `"modrinth"`, `"github"`
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"filterPlatform": "modrinth"
|
||||
}
|
||||
```
|
||||
|
||||
Projects without a Modrinth version will be excluded from the export.
|
||||
|
||||
---
|
||||
|
||||
### `includeNonRedistributable` (boolean, optional)
|
||||
|
||||
Control whether non-redistributable mods are included in the export.
|
||||
|
||||
**Default**: `false` for CurseForge, `true` for others
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"includeNonRedistributable": false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `includeClientOnly` (boolean, optional)
|
||||
|
||||
Control whether client-only mods are included in server pack exports.
|
||||
|
||||
**Default**: `false` for serverpack profile, `true` for others
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"includeClientOnly": false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `overrides` (array of strings, optional)
|
||||
|
||||
Override directories to include in the export. Replaces global `overrides` setting.
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"overrides": ["overrides", "platform-specific-overrides"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `serverOverrides` (array of strings, optional)
|
||||
|
||||
Server-specific override directories. Replaces global `serverOverrides` setting.
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"serverOverrides": ["server-config", "server-scripts"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `clientOverrides` (array of strings, optional)
|
||||
|
||||
Client-specific override directories. Replaces global `clientOverrides` setting.
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"clientOverrides": ["client-config", "shaderpacks"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `projectOverrides` (object, optional)
|
||||
|
||||
Per-project configuration within this profile. Not yet implemented.
|
||||
|
||||
**Future feature**:
|
||||
```json
|
||||
{
|
||||
"projectOverrides": {
|
||||
"sodium": {
|
||||
"export": false
|
||||
},
|
||||
"optifine": {
|
||||
"export": true,
|
||||
"subpath": "mods/performance/"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Default Profiles
|
||||
|
||||
Pakker provides sensible defaults for common profiles:
|
||||
|
||||
### CurseForge Default
|
||||
|
||||
```json
|
||||
{
|
||||
"filterPlatform": "curseforge",
|
||||
"includeNonRedistributable": false
|
||||
}
|
||||
```
|
||||
|
||||
### Modrinth Default
|
||||
|
||||
```json
|
||||
{
|
||||
"filterPlatform": "modrinth",
|
||||
"includeNonRedistributable": true
|
||||
}
|
||||
```
|
||||
|
||||
### ServerPack Default
|
||||
|
||||
```json
|
||||
{
|
||||
"includeClientOnly": false
|
||||
}
|
||||
```
|
||||
|
||||
These defaults are used automatically when exporting with `pakker export --profile <name>` if no custom configuration is specified.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: Multi-Platform Modpack
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Multi-Platform Pack",
|
||||
"version": "1.0.0",
|
||||
"overrides": ["overrides"],
|
||||
"exportProfiles": {
|
||||
"curseforge": {
|
||||
"filterPlatform": "curseforge",
|
||||
"includeNonRedistributable": false,
|
||||
"overrides": ["overrides", "curseforge-overrides"]
|
||||
},
|
||||
"modrinth": {
|
||||
"filterPlatform": "modrinth",
|
||||
"includeNonRedistributable": true,
|
||||
"overrides": ["overrides", "modrinth-overrides"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
pakker export --profile curseforge
|
||||
pakker export --profile modrinth
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Server Pack with Custom Config
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Survival Server",
|
||||
"version": "2.0.0",
|
||||
"overrides": ["overrides"],
|
||||
"serverOverrides": ["server-base"],
|
||||
"exportProfiles": {
|
||||
"serverpack": {
|
||||
"includeClientOnly": false,
|
||||
"serverOverrides": ["server-base", "server-production"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
pakker export --profile serverpack
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Development vs Production
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Dev Pack",
|
||||
"version": "1.0.0-dev",
|
||||
"overrides": ["overrides"],
|
||||
"exportProfiles": {
|
||||
"dev": {
|
||||
"includeNonRedistributable": true,
|
||||
"overrides": ["overrides", "dev-config"]
|
||||
},
|
||||
"production": {
|
||||
"filterPlatform": "curseforge",
|
||||
"includeNonRedistributable": false,
|
||||
"overrides": ["overrides", "prod-config"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
pakker export --profile dev # For testing
|
||||
pakker export --profile production # For release
|
||||
```
|
||||
|
||||
## How Profile Configuration Works
|
||||
|
||||
### Priority Order
|
||||
|
||||
1. **Profile-specific settings** from `exportProfiles.<profile>`
|
||||
2. **Profile defaults** (curseforge/modrinth/serverpack)
|
||||
3. **Global settings** from root `pakku.json`
|
||||
|
||||
### Example Resolution
|
||||
|
||||
Given this configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"overrides": ["overrides"],
|
||||
"serverOverrides": ["server-global"],
|
||||
"exportProfiles": {
|
||||
"myprofile": {
|
||||
"overrides": ["custom-overrides"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When exporting with `--profile myprofile`:
|
||||
- `overrides`: Uses `["custom-overrides"]` (from profile)
|
||||
- `serverOverrides`: Uses `["server-global"]` (from global, no profile override)
|
||||
|
||||
### Filter Execution Order
|
||||
|
||||
Export rules are executed in this order:
|
||||
|
||||
1. **Copy project files** - Download and copy mod files
|
||||
2. **Filter by platform** - Remove mods not available on target platform
|
||||
3. **Copy overrides** - Copy override directories
|
||||
4. **Generate manifest** - Create platform-specific manifest
|
||||
5. **Filter non-redistributable** - Remove non-redistributable mods (if configured)
|
||||
6. **Filter client-only** - Remove client-only mods (for server packs)
|
||||
|
||||
## Migration from Pakku
|
||||
|
||||
If you're migrating from Pakku, export profiles work the same way. The configuration format is compatible.
|
||||
|
||||
### Pakku Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"exportProfiles": {
|
||||
"curseforge": {
|
||||
"filterPlatform": "curseforge"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This works identically in Pakker.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Mods Missing from Export
|
||||
|
||||
**Problem**: Some mods are missing after export.
|
||||
|
||||
**Solution**: Check if `filterPlatform` is excluding them. Use `pakker inspect <project>` to see platform availability.
|
||||
|
||||
---
|
||||
|
||||
### Override Files Not Copied
|
||||
|
||||
**Problem**: Override files aren't appearing in the export.
|
||||
|
||||
**Solution**: Verify the override path in your profile config matches the actual directory structure.
|
||||
|
||||
---
|
||||
|
||||
### Non-Redistributable Mods Included
|
||||
|
||||
**Problem**: Non-redistributable mods are in the export when they shouldn't be.
|
||||
|
||||
**Solution**: Set `includeNonRedistributable: false` in your profile configuration.
|
||||
|
||||
## See Also
|
||||
|
||||
- [Export Command Documentation](./COMMANDS.md#export)
|
||||
- [Configuration Reference](./CONFIGURATION.md)
|
||||
- [Project Configuration](./PROJECTS.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue