integrate previous work

[zpackage] / Commands

zpm: always a shell script, that way it can source config files and export environment
variables for sub-programs

Good to have a program to check if a package exists.  That is, would
zpm install do anything, at least notionally.

Three basic modes

1: working on the local database and manipulating packages
This is where 'install' 'update' 'remove' etc are done.
Additionally, this is where notes, bug reports, repo
control, and so forth are done.  Since this is the most
common mode, these commands shouldn't need a prefix or
something saying we're dealing with the local package DB.

2: working on a package file.
This is where building a new package, adding files, and otherwise
dealing with package metadata happens

3: working on a repository of package files

Since 2 and 3 are the less common operations, they can have
more verbose syntax, also, 2 "expects" a package file, so
require an option to force using the local DB, and 3 expects
needs repos, perhaps force not using local DB
Difference between working on a repository, and manipulating
repository info for the local or other DB
And 1 expects the local db, so option to specify package file.

-f for package file?  or -p? and for cat 2, take as argument if
not specified?  perhaps an option to construct?  probably
not, have a program to construct if needed.

Need a way to specify a non-default local database location,
/var/lib/zpm/local.zpm by default

For 2: zpm pkg
For 3: zpm repo

Conceivably for 2: 'zpm -f <pkgfile>', since if it's not the
local package database, you'll have to specify the package file

install: will search the repos for the most recent package.
of install a from a package file given with -f.

so zpm install -f 'pkgfile' will install all packages in that file
zpm install -f pkgfile package will install just the named package
zpm install -f pkfile package package2 will installed both packages
zpm install -f pkgfile -V 1.2 will install version 1.2 of all packages
that have a version 1.2
zpm install -f pkgfile foo-1.2 will install version 1.2 of package foo

zpm install foo will install the most up to date foo from the
repos

zpm install foo-1.2 install version 1.2.  how to distinguish
between versions and package names with hyphens?  Use @?

Package filters: Version, release, name, min/max version, min/max release
Package tags?

File filters: Get everything, except exclude by tag, which will
exclude every file with the tag.  Can reverse sense, and get
nothing, except what's in tag. +tag will add a tag to the set,
-tag will remove it.  'tag' sets the tag list


Environment Variables
---------------------

Always set by the zpm wrapper.

ZPMDB: path to local database
ZPMPACKAGE: package name
ZPMPKGVER: package version
ZPMPKGREL: package release
ZPMPKGFILE: package file

Command Line Options
--------------------

Used by all programs, so can be passed to zpm

-f package file

Package Selector
----------------

-p <package name> -V <package version> -R <package release>

version and release are always the latest available if not specified for new
packages, version defaults to 1.0, release to 1, but may also be taken from the
environment

If there is more than one package name in a database the shortest name is the
default, and the earliest alphabetically after that.  This makes it so that if
you have 'db' and 'db-dev' in the same package, db will be the default.  Though
that's not the way to do it, instead you should tag files within a package, and
then filter the install.

command line over-rides environment, which over-rides defaults

ZPM Wrapper Script
------------------

The primary executable is zpm, which is a shell script.  This script
sources (if they exist) in order, /etc/zpm.conf ~/.zpmrc

The script then parses its command line options up until the first non-option,
export environment variables, and looks for a command of the form zpm-$1 which
it then executes.  If the ZPMPATH is not set, it looks in PATH and if that is
not set, in /sbin:/usr/libexec/zpm

        -d <database file>
        -f <database file> -- they're the same option, just different way of thinking about it

Low Level Commands
------------------

Very low level commands to manipulate a database.  These can be used directly,
but are primarily intended to be wrapped up in shell scripts.  Each of these
should also have an equivalent in the C library API.  The zpm- prefix is omitted below.

newpackage: add package metadata to a zpm database, creating the target file if
needed.

        -N require the target file to not exist (new)
        -A require the target file to exist (add)
        -P packager string, should be an email, use ZPMPACKAGER environment

addtopackage: add a file to a package
        
        -C <n> number of leading components to strip
        -P <path prefix> prefix to strip
        -H hard coded path, regardless of the source 
        -T track only, don't import the contents
        -c flag as configuration file
        -t <tag list> comma or space separated tags on file

        zpm -f foobar-1.0-1.zpm addtopackage /usr/bin/foo /usr/bin/bar
        zpm addtopackage foobar-1.1-3.zpm /usr/bin/foo /usr/bin/bar
        zpm add -f foobar-1.1-3.zpm -p bar /usr/bin/bar

        need to think about the syntax here, but best to just write something,
        then change it later
        
extract: pull file content to disk
        $1 is hash or hash prefix if unique, $2 is target path

        As per install(8)
        -m mode
        -o owner
        -g group

        -D don't create leading directories

list: list package contents

        -F <format> %p path %m mode %o owner %g group %h hash
        -N don't append a newline to format
        -0 append a null byte to the format

        default format is '%h %m %o %g %p'

show: list packages
        maybe reverse list and show

drop: delete a package

delete: remove a file from a package

adjust: adjust file metadata
        
Higher Level Commands
---------------------

install: install a package to the local system
        search repositories known in the local db for a matching package
remove: remove a package
update: update a package

        -D dry-run, just show what might be done

export: create a standalone package file from a repo/localdb

json: dump the metadata of a repo as json

Repositories
------------

A repository is just a collection of packages.  All in one DB, or perhaps
mark an external file location for package contents.

Repository Definition is just a url.
Has a priority.  Can require trusted signer.  Can require confirmation.
Install/Search will ask on tied priorities.  Warn on lower priorities.

Fetch a repo by getting the json file, or by getting a stripped down DB file.

repo import: adds repository information from the json file
repo drop <url or name>
repo add <url> [name]
repo refresh: update repository info

repo command needs to know how to get metadata from local files
for http[s] urls, path given should return either json or sqlite db, responsibility
of repo to make this work

Building Packages
-----------------

build: builds a package file
        -S read paths from stdin

        Reads PKGBUILD in the current directory
        -b build script path instead of PKGBUILD

Other Commands
--------------

absorb: pull in the content of a file.  note the mtime if it's a config file, possibly
keeping multiple versions

truncate: drop the content of a file

status:
        investigate the status of a repo, reporting things like failed installs or removes,
        file conflicts, anything else

integritycheck: compare the stored hashes with the hashes on disk

note:
        add a note file, - from stdin, list if none

edit:
        edit a note file

ack:
        acknowledge a note file

diff:
        compare two versions of a package, show what would be done
        or different

info:
        get information on a package

track:
        add a package to config tracked packages

add: add to a repository/database

clean: clean a repository/database