PAX Package Manager Manual

PAX is the official package manager for XCX, integrated directly into the xcx binary. It manages dependencies, project scaffolding, registry publishing, and build automation.

Project Configuration: project.pax

Every PAX project must have a project.pax file in its root directory. It uses a custom declarative format.

PAX Project Configuration
*---
/
    name        :: "my_project",
    version     :: "1.0.0",
    author      :: "yourname",
    description :: "A short description of the project",
    main        :: "src/main.xcx",
    tags  :: ["tag1", "tag2"],
    files :: ["src/main.xcx", "src/lib.xcx"],
    deps  :: [
        "somelib@1.0.0",
        "author/repo@latest",
        "https://example.com/lib.xcx"
    ]
/

Fields

Dependency Formats

deps :: [
    "mylib@1.0.0",           --- versioned registry package
    "mylib@latest",          --- latest registry package
    "author/mylib@2.1.0",    --- with author prefix
    "https://example.com/lib.xcx"  --- direct URL
]

Lock File: pax.lock

PAX automatically maintains a pax.lock file after each install. It records the exact resolved version and local path of every installed dependency.

{
  "mylib": { "version": "mylib@1.0.0", "file": "lib/mylib/" },
  "otherlib": { "version": "otherlib@latest", "file": "lib/otherlib/" }
}

Directory Structure

A standard PAX project follows this layout:

my_project/
├── project.pax       # Project configuration
├── pax.lock          # Auto-generated lockfile
├── src/
│   └── main.xcx      # Main entry point
├── lib/              # Installed dependencies (managed by PAX)
└── tests/            # Project-specific tests

Command Reference

PAX is invoked via xcx pax <command>.

Command Details

xcx pax new <name>

Scaffolds a new project with the standard directory layout.

xcx pax new my_project

Creates:

my_project/
├── project.pax
├── src/
│   └── main.xcx
└── README.md

xcx pax install

Reads project.pax, resolves all deps, and downloads them into lib/. Skips packages already present (by name).

xcx pax install

xcx pax add <dep>

Adds a dependency to project.pax and immediately runs install.

xcx pax add mylib@1.0.0
xcx pax add author/mylib@latest

xcx pax remove <name>

Removes a dependency entry from project.pax.

xcx pax remove mylib

> Note: lib/ folders and pax.lock entries are not automatically cleaned up. Re-run xcx pax install or remove them manually.

xcx pax clone <package>

Downloads a published package from the PAX registry as a full local project, ready to run or modify.

xcx pax clone snake_game
xcx pax clone author/snake_game

Typical workflow:

xcx pax clone snake_game
cd snake_game
xcx pax install
xcx pax run

xcx pax run [path]

Executes the project. Entry point resolution order:

1. Path provided as argument (e.g. xcx pax run other/main.xcx)

2. main field in project.pax

3. Default: src/main.xcx

xcx pax run
xcx pax run src/alt.xcx

xcx pax search <query>

Searches the PAX registry for packages matching the query.

xcx pax search json

Output format:

- json_utils (v1.2.0) by alice
fast_json (v0.9.1) by bob

xcx pax login <token>

Stores a registry authentication token locally in .pax_token.

xcx pax login yourtokenhere

xcx pax logout

Removes the stored authentication token.

xcx pax logout

xcx pax whoami

Verifies your current registry session and prints your account info.

xcx pax whoami
Account: alice [developer]

xcx pax publish

Publishes the current project to the PAX registry. Requires login.

xcx pax publish

> Note: Bump version in project.pax before each publish. The registry may reject duplicate versions.

Registry Configuration

By default PAX connects to pax.xcxlang.com. You can override this via a .pax_config file in the project root:

{
  "registry": "https://my-custom-registry.example.com"
}