# PLIST Files

PLIST (Package List) files define which files are included in a package.

## Purpose

PLIST files serve several purposes:

1. **Include files** - Specify which files go into the SPK
2. **Set destinations** - Define where files are installed
3. **Track files** - Used during upgrades and uninstalls

## File Location

- `cross/<package>/PLIST` - For cross packages
- `spk/<package>/PLIST` - For SPK packages (if needed)

## Basic Format

```
<type>:<path>
```

### Entry Types

| Type | Description |
|------|-------------|
| `bin` | Executables |
| `lib` | Libraries |
| `rsc` | Resources (scripts, data files, configs) |
| `lnk` | Symbolic links |

### Example

```
bin:bin/myapp
lib:lib/libfoo.so.1
rsc:share/myapp/data.txt
rsc:etc/myapp.conf
```

## Installation Locations

Files are installed relative to the package installation directory. See [Synology FHS](https://help.synology.com/developer-guide/integrate_dsm/fhs.html) for DSM file system hierarchy details.

| Path | Description |
|------|-------------|
| `bin/` | Package executables |
| `lib/` | Package libraries |
| `share/` | Data files |
| `etc/` | Configuration templates |

## Wildcards

### Glob Patterns

```
# All .so files
lib:lib/libfoo.so*

# All files in directory
rsc:share/myapp/*
```

## Symbolic Links

Use `lnk:` for symbolic links:

```
lnk:lib/libfoo.so
lnk:lib/libfoo.so.1
lib:lib/libfoo.so.1.2.3
```

## Auto-Generated PLIST

For cross packages, PLIST can be auto-generated by creating an empty `PLIST.auto` file:

```bash
# Create auto-generation marker
touch cross/mypackage/PLIST.auto
```

When building, the framework will analyze the staging directory and create appropriate PLIST entries based on file types:

- ELF executables → `bin:`
- ELF libraries → `lib:`
- Scripts → `rsc:`
- Symbolic links → `lnk:`
- Other files → `rsc:`

### Manual PLIST Generation

```bash
make -C cross/mypackage ARCH=x64 TCVERSION=7.2 plist
```

This generates a PLIST from the staging directory contents which you can then refine.

## Best Practices

### Do Include

- Executables the user will run
- Libraries required at runtime
- Configuration templates
- Essential data files

### Don't Include

- Development headers (unless needed)
- Static libraries (usually)
- Man pages (saves space)
- Documentation (link to online docs instead)

### Common Patterns

```
# Binary with library
bin:bin/myapp
lib:lib/libmyapp.so*

# Application with data
bin:bin/myapp
rsc:share/myapp/*
```

## Debugging PLIST Issues

### View Staging Contents

```bash
find cross/mypackage/work-x64-7.2/staging -type f
```

### Test Package Contents

After building, examine the SPK:

```bash
tar -tvf packages/mypackage_x64-7.2_*.spk
```

## PLIST Transform

For complex cases, use `PLIST_TRANSFORM` in your Makefile to modify the PLIST dynamically:

```makefile
# Filter entries
PLIST_TRANSFORM = grep -v 'unwanted/path'
```
