ZX User Manual

ZX provides a somewhat large number of commands. The syntax for each command is simple, but a few core concepts must be understood to fully leverage the system and develop a smooth workflow as a developer, packager, maintainer, sysop or power user.

This page is broken into two parts:

  1. The Help Screen
  2. Explanation of Identifier Types

The help screen reproduced below lists every command in ZX. You generally only need to know the things relevant to your level of interaction with the system.

Identifiers are useful to be understood by everyone and intuitive enough that usually only developers really need to concern themselves with the details.

The Help Screen

A complete list of commands and command argument types can be viewed by entering zx help [user type].

Each element in the list below is a link to its usage page.

Usage: zx [command] [object] [args]

User Actions:
  zx help [user | dev | sysop]
  zx run PackageID [Args]
  zx integrate desktop PackageID
  zx list realms
  zx list packages Realm
  zx list versions PackageID
  zx list [gui | cli | app | lib]
  zx latest PackageID
  zx search Args
  zx describe PackageID
  zx upgrade
  zx import realm RealmFile
  zx drop realm Realm
  zx add mirror [Address [Port]]
  zx drop mirror [Address [Port]]
  zx --version

Developer/Packager/Maintainer Actions:
  zx create project
  zx template Type
  zx runlocal [Args]
  zx rundir Path [Args]
  zx init
  zx list deps [PackageID]
  zx set dep PackageID
  zx drop dep PackageID
  zx verup Level
  zx set version Version
  zx provides Module
  zx update meta
  zx update .app
  zx package Path
  zx submit ZSP
  zx list pending PackageName
  zx review PackageID
  zx approve PackageID
  zx reject PackageID
  zx create user
  zx create keypair
  zx export user [dangerous]
  zx import user ZDUF
  zx list users Realm
  zx list packagers PackageName
  zx list maintainers PackageName
  zx list sysops Realm
  zx export realm [Realm]
  zx install ZSP

Sysop Actions:
  zx list approved Realm
  zx accept ZSP
  zx add package PackageName
  zx add user ZPUF
  zx rem user Realm UserName
  zx add packager PackageName UserName
  zx rem packager PackageName UserName
  zx add maintainer PackageName UserName
  zx rem maintainer PackageName UserName
  zx create realm
  zx takeover Realm
  zx abdicate Realm

Where
  PackageID   :: A string of the form [Realm-]Name[-Version]
  PackageName :: A string that matches [^[a-z]a-z0-9_]
  UserName    :: A string that matches [^[a-z]a-z0-9_]
  Args        :: Arguments to pass to the application
  Type        :: The project type: a standalone "app" or a "lib"
  Version     :: Version string X, X.Y, or X.Y.Z: "1", "1.2", "1.2.3"
  RealmFile   :: Path to a valid .zrf realm file
  Realm       :: The name of a realm as a string [:a-z:]
  Module      :: Name of a code module.
  KeyName     :: The prefix of a keypair
  Level       :: The version level, one of "major", "minor", or "patch"
  Path        :: Path or filename.
  ZSP         :: Path to a .zsp file (Zomp Source Package).
  ZPUF        :: Path to a .zpuf file (Zomp Public User File).
  ZDUF        :: Path to a .zduf file (Zomp DANGEROUS User File).

Explanation of Identifier Types

Two strictly defined string types are used throughout the system: identifiers and version strings.

Resource IDs are composed of identifiers and version strings.

Names of export/import files are similar to resource IDs with the addition of a file extension that tells you what they do.

Identifiers

Identifiers are strings that can contain lower-case ASCII letters, numeric ASCII characters "0" through "9", and the ASCII underscore (U+005F). Identifiers must start with a lower-case letter "a" through "z". Consecutive underscores are not permitted. Identifiers are used in the following cases:

Version Strings

Zomp adheres strictly to the semantic version number recommendation. All packages have a complete version number represented as a string. A version string is of the form X.Y.Z where each section is a string representation of a number using the characters "0" through "9" connected by a single "." between sections.

A "fully qualified" version number is one where all three segments are written. A "partial" version number is one where trailing segments are omitted and always default to "highest available sub-version". Partial version strings are used most often by users and system administrators who want to have ZX automatically run the latest available version of a package either in absolute terms (by completely omitting the version number) or by specifying part of the version number. The cases where partial version numbers are not permitted are when specifying dependencies with the set dep command and realm index commands where a partial version number would cause a command to be ambigous.

Note that throughout the documentation and the source code for Zomp and ZX the semver represenation Major.Minor.Patch is usually written as X.Y.Z.

Resource IDs

A resource ID is a combined identifier where segments are connected by a single ASCII dash character (U+002D). A "fully qualified" resource ID is a globally unique identifier and includes all segments of the ID. In many cases some sections of an ID can be omitted either because they are implied by system defaults (such as when specifying the default "otpr" realm) or when automatic selection of the latest version of a package is desired.

Several types of resource IDs exist:

Type Fully Qualified Partial
PackageID otpr-example_package-1.2.3 example_package
otpr-example_package
example_package-1
otpr-example_package-1.2
UserID some_realm-user_name user_name
(only in cases where the realm is unambiguous)
KeyID some_realm-key_name key_name
(only in cases where the realm is unambiguous)

File Names

The file names of bundle files for import/export of system data (importing a realm, exporting a user, etc.) are composed of resource ID strings and a file extension that indicates the file type.

Extension File Type Example Command Example
.zrf Zomp realm file example_realm.zrf zx add realm example_realm.zrf
.zsp Zomp source package otpr-some_app-3.2.1.zsp zx submit otpr-some_app-3.2.1.zsp
.zpuf Zomp public user file mushroom-mario.zpuf zx add user mushroom-mario.zpuf
.zduf Zomp dangerous user file mushroom-mario.zduf zx import user mushroom-mario.zduf

More information about each file type can be found on the files page.