# Creating System Installers

This guide shows how to create a custom system installer package. System installers allow aux4 to install system-level dependencies using package managers that aren't included by default.

## What is a System Installer?

A system installer is an aux4 package that provides `install` and `uninstall` commands for a specific package manager. When another package declares a system dependency using that package manager, aux4 uses your system installer to install it.

For example, the `aux4/system-installer-brew` package enables the `brew:` prefix in system dependencies.

## Package Structure

```text
system-installer-mypm/
├── .aux4
├── LICENSE
└── README.md
```

## Step 1: Create the .aux4 File

System installers must:
1. Include `system-installer` in the tags array
2. Depend on `aux4/pkger`
3. Implement the `aux4:pkger:system` profile with your package manager name
4. Provide `install` and `uninstall` commands

```json
{
  "scope": "myorg",
  "name": "system-installer-mypm",
  "description": "aux4 system installer for MyPM package manager",
  "version": "1.0.0",
  "license": "MIT",
  "dependencies": [
    "aux4/pkger"
  ],
  "tags": [
    "aux4",
    "system-installer"
  ],
  "profiles": [
    {
      "name": "aux4:pkger:system",
      "commands": [
        {
          "name": "mypm",
          "execute": [
            "profile:aux4:pkger:system:mypm"
          ],
          "help": {
            "text": "Manage MyPM packages"
          }
        }
      ]
    },
    {
      "name": "aux4:pkger:system:mypm",
      "commands": [
        {
          "name": "install",
          "execute": [
            "mypm install ${package}"
          ],
          "help": {
            "text": "Install a MyPM package",
            "variables": [
              {
                "name": "package",
                "text": "Package name",
                "arg": true
              }
            ]
          }
        },
        {
          "name": "uninstall",
          "execute": [
            "mypm uninstall ${package}"
          ],
          "help": {
            "text": "Uninstall a MyPM package",
            "variables": [
              {
                "name": "package",
                "text": "Package name",
                "arg": true
              }
            ]
          }
        }
      ]
    }
  ]
}
```

## Profile Naming Convention

The profile names must follow this convention:

- Entry profile: `aux4:pkger:system`
- Command name: Your package manager identifier (e.g., `mypm`)
- Implementation profile: `aux4:pkger:system:<identifier>` (e.g., `aux4:pkger:system:mypm`)

## Step 2: Create Supporting Files

### LICENSE

```bash
cat > LICENSE << 'EOF'
MIT License
...
EOF
```

### README.md

````bash
cat > README.md << 'EOF'
# System Installer for MyPM

Enables aux4 packages to declare MyPM dependencies.

## Usage

After installing this package, other packages can use:

```json
{
  "system": [
    [
      "test:mytool --version",
      "mypm:mytool"
    ]
  ]
}
```
EOF
````

## Step 3: Build and Publish

```bash
aux4 aux4 pkger build ./out .
aux4 aux4 login
aux4 aux4 pkger publish ./out/myorg_system-installer-mypm_1.0.0.zip
```

## Step 4: Use in Other Packages

Once your system installer is published, other packages can use it:

```json
{
  "scope": "myorg",
  "name": "my-tool",
  "version": "1.0.0",
  "license": "MIT",
  "system": [
    [
      "test:sometool --version",
      "mypm:sometool"
    ]
  ],
  "profiles": [...]
}
```

When `myorg/my-tool` is installed:
1. aux4 sees the `mypm:sometool` dependency
2. aux4 installs `myorg/system-installer-mypm` if not already installed
3. aux4 runs the test command `sometool --version`
4. If the test fails, aux4 runs `aux4 aux4:pkger:system mypm install sometool`

## Real-World Examples

### Homebrew (brew)

```json
{
  "name": "aux4:pkger:system:brew",
  "commands": [
    {
      "name": "install",
      "execute": [
        "brew install ${package}"
      ],
      "help": {
        "text": "Install brew package",
        "variables": [
          {
            "name": "package",
            "text": "Package name",
            "arg": true
          }
        ]
      }
    },
    {
      "name": "uninstall",
      "execute": [
        "brew uninstall ${package}"
      ],
      "help": {
        "text": "Uninstall brew package",
        "variables": [
          {
            "name": "package",
            "text": "Package name",
            "arg": true
          }
        ]
      }
    }
  ]
}
```

### APT (Debian/Ubuntu)

```json
{
  "name": "aux4:pkger:system:apt",
  "commands": [
    {
      "name": "install",
      "execute": [
        "apt-get install -y ${package}"
      ],
      "help": {
        "text": "Install apt package",
        "variables": [
          {
            "name": "package",
            "text": "Package name",
            "arg": true
          }
        ]
      }
    },
    {
      "name": "uninstall",
      "execute": [
        "apt-get remove -y ${package}"
      ],
      "help": {
        "text": "Uninstall apt package",
        "variables": [
          {
            "name": "package",
            "text": "Package name",
            "arg": true
          }
        ]
      }
    }
  ]
}
```

### npm (Global packages)

```json
{
  "name": "aux4:pkger:system:npm",
  "commands": [
    {
      "name": "install",
      "execute": [
        "npm install -g ${package}"
      ],
      "help": {
        "text": "Install npm package globally",
        "variables": [
          {
            "name": "package",
            "text": "Package name",
            "arg": true
          }
        ]
      }
    },
    {
      "name": "uninstall",
      "execute": [
        "npm uninstall -g ${package}"
      ],
      "help": {
        "text": "Uninstall npm package globally",
        "variables": [
          {
            "name": "package",
            "text": "Package name",
            "arg": true
          }
        ]
      }
    }
  ]
}
```

## Available System Installers

| Package | Prefix | Package Manager |
|---------|--------|-----------------|
| [aux4/system-installer-brew](https://hub.aux4.io/r/public/packages/aux4/system-installer-brew) | `brew:` | Homebrew (macOS) |
| [aux4/system-installer-apt](https://hub.aux4.io/r/public/packages/aux4/system-installer-apt) | `apt:` | APT (Debian/Ubuntu) |
| [aux4/system-installer-dnf](https://hub.aux4.io/r/public/packages/aux4/system-installer-dnf) | `dnf:` | DNF (Fedora/RHEL) |
| [aux4/system-installer-yum](https://hub.aux4.io/r/public/packages/aux4/system-installer-yum) | `yum:` | YUM (CentOS/RHEL) |
| [aux4/system-installer-apk](https://hub.aux4.io/r/public/packages/aux4/system-installer-apk) | `apk:` | APK (Alpine Linux) |
| [aux4/system-installer-npm](https://hub.aux4.io/r/public/packages/aux4/system-installer-npm) | `npm:` | npm (Node.js) |
| [aux4/system-installer-pkgx](https://hub.aux4.io/r/public/packages/aux4/system-installer-pkgx) | `pkgx:` | pkgx |

---

## See Also

- [Package with System Dependencies](/packaging/system-dependencies)
- [Simple Package](/packaging/simple)
- [Package with Dependencies](/packaging/dependencies)