+ZPM - the ultimate package manager
+==================================
+
+Like "git" for packages.
+
+Would like a zpm-status and zpm-log, which should do things like
+list incompletely installed packages, perhaps unacknowledged notes,
+and so forth. zpm log should mainly show install/upgrade/deletes,
+and repository actions.
+
+Any machine readable outputs or inputs should be json, or something
+easily parsable by shell and awk
+
+Specifying the Package Database
+-------------------------------
+
+-f /path/to/db/or/file
+env ZPMFILE only for single package ops
+env ZPMDB
+sourced in /etc/zpm.conf by setting environment variable?
+default to /var/lib/zpm/local.zpm
+
+Should probably distinguish here between the "package" and the "localdb".
+They're not different technically, but
+thus zpm install -f /path will still record in the ZPMDB
+
+Specifying a Package Within a DB
+--------------------------------
+
+Need a name,version,release triple
+
+But any string can be used, the system will attempt to disambiguate.
+Can use zpm-findpkg to show how it would be interpreted.
+
+Otherwise drawn from (first wins):
+-p <package string>
+env ZPMPKG
+
+If you need specific versions:
+env ZPMPKGVER
+env ZPMPKGREL
+
+Or use zpm-findpkg -a to find all packages that match
+
+and any of those can be embedded in the them.
+but start with either full triple in either ZPMPKG or -p,
+or implied if neither is set
+zpm-findpkg will return a triple, so can always run
+zpm-findpkg and
+
Features
--------
package metadata
package integrity
- gpg signatures
+ gpg signatures :- use own signatures, or figure out PD way to get gpg
sha256 sums
- sha3 sums
+ sha3 sums - not implemented
package contents integrity
sha256 sums of installed files
- sha3 sums
- sha1 sums
+ sha3 sums - not implemented
+ sha1 sums - not implemented
lists of directory contents
package database editing
- e.g. marking a file as a configuration file
+ mark a file as a configuration file
repackaging
creating a package from the current state of an installed package
use shell scripts where possible
use shell functions as hooks and callbacks
-package is just a tarball
-can contain more than one package
-xz compressed
-
-version?
-package-name/version/files/{usr/bin/foo, etc}
-package-name/version/info/hooks - shell script of functions
-package-name/version/info/pkginfo - shell readable
-package-name/version/info/manifest? derivable from tarball
-package-name/version/info/dynamiclibs, or greppable from manifest?
+A package is an SQLite database file.
-/var/lib/zpac:
-packages/installed/<package>/files/sha1/ab/ab/hash -> file
-librefs/<library name>/<package> (or file?)
-sha1/ab/ab/<sha1hashs> -> file
-fileowner/sha1/ab/ab/hash/packagename - can be more than one
+Multiple packages in the same file.
need to mark a package as held for no automatic upgrade
-configure to run a command after an any package work
+configure to run a command after any package work
+
+System Administration
+---------------------
+
+Install a package
+
+ zpm install <pkgname>
+
+Add a repository
+
+ zpm repo add <repo_url>
+
+List the files owned by a package
+
+ zpm contents <pkgname>
+
+Capture current state of configuration files
+
+ zpm capture <pkgname>
+
+Create a package file from an installed package
+
+ zpm export <pkgname>
+
+Extract file content from a package
+
+ zpm extract <hash> <path>
+
+Remote Repositories
+-------------------
+
+ # add a new remote, -n don't do a pull immediately
+ zpm remote add [-n] <name> <url>
+
+ # show all the remotes
+ zpm remote list
+ # set the preference level, higher is better
+ # perhaps remote "order" with lower better
+ # alpha by name on ties
+ zpm remote preference <name> <number>
+
+ zpm remote pull [name ...] # all if no name
+ zpm remote drop <name ...>
+ zpm remote freeze <name ...> # prevent updates?
+ # fetch content of remotes, cached in filesystem?
+ zpm remote fetch [-a] [package ...]
+
+ # list
+
+Packaging Software
+------------------
+
+Build a package in the current directory
+
+ zpm build
+
+Create a package from a tarball
+
+ zpm build -t <tarfile> <packagefile>
+
+Import the contents of one package file into another
+
+ zpm merge <basefile> <otherfile>
+
+Create a package from a list of file names on stdin
+
+ find <find_options> | zpm build -s <packagefile>
+
+Create a new empty package
+
+ zpm newpackage <packagefile>
+
+Add a file to a package in a package db
+
+ zpm addtopackage <packagefile> <filepath>
+
+Mark a file as a configuration file
+
+ zpm mark -c <packagefile> <path>
+
+Mark a package as finished building
+
+ zpm complete <packagefile> <packagename>
+
+Utilities
+---------
+
+Show the elf libraries needed by a program or library
+
+ zpm soneed <file>
+
+Show the elf library provided by a library file
+
+ zpm soname <file>
+
+Get the sha256 hash of a file
+
+ zpm hash <file>
+
+Get the unix timestamp of a file
+
+ zpm stat -f '%m' <file>
+
+Get the uid of a file
+
+ zpm stat -f '%u' <file>
+
+Repositories
+------------
+
+A repository is just an archive of packages, which amounts to package metadata,
+plus possibly file path and hash information. That is, the packages and
+packagefiles tables, and possibly the elf information. Could be pretty much
+everything except the actual file content. Could put a repo column on all of
+those tables, with NULL being no repo information. Otherwise separate tables.
+For the file paths, or at least the repo, need a url, could require it to be
+automatically constructed from the repo url, possibly with escapes.
+
+Need a repo table with the remote repo name (locally decided), remote repo url,
+and perhaps preference and trust policy.
+
+Something like
+
+ zpm repo add <name> <url> # repo info download/fetch url
+ zpm repo sync [name] # all if no name
+ zpm repo preference <pref> [name ...]
+ zpm repo clone <name> # download all packages to some destination
+
+This might mean that the package identifier tuple would be the repo, name, version, release. Which is getting a bit complex, so we need some way to
+set sensible defaults.
+
+Build Scripts
+-------------
+
+A building a package with zpm build.
+
+Source a build script named ZBUILD, or package.build. Not sure which.
+Either way, build script itself shouldn't do anything other
+than setting variables and defining functions.
+
+zpm build variables:
+
+srcdir: where the source code is unpacked
+
+variables:
+
+source: a list of urls, suitable for curl to download
+checksum: a corresponding list of sha256 checksums
+PACKAGE: the name of the package
+VERSION: the package version
+
+functions:
+
+install: should install the package under $pkgtree
+can create more than one package under $pkgbase
+
+postpackage: optional a function to run after the package file is created,
+one arg, path to zpm file
+
+build: compile the package
+
+internal zpm functions:
+
+Package File tags
+-----------------
+
+There are no "subpackages", but you can tag paths
+at install time you can include or exclude paths
+you get ((tag match include) and (tag not match exclude))
+default include is all, and default exclude is none
+
+might use ^: for standard "what is this" tags,
+and ^@ for "sub-package" tagging, or what amount
+to optional parts of an install
+
+A tag must be no whitespace and no shell metacharacters
+
+ [a-zA-Z:=@.]+
+
+Hmm, it would make sense to tag regardless of package.
+perhaps require -A or somesuch.
+
+setting tags when building a package:
+
+ zpm tag [-r] -f $pkgfile <glob> tag [...]
+
+add tags
+
+ zpm tag -a -f $pkgfile <glob> tag [...]
+
+remove tags
+
+ zpm tag -d -f $pkgfile <glob> tag [...]
+
+list tags
+
+ zpm tag -l -f $pkgfile <glob>
+
+test tag: i.e. does a file have (all) given tag(s)
+
+ zpm tag -t -f $pkgfile <glob> tag [...]
+
+Standard tags
+-------------
+
+dev: headers and static libraries
+doc: man pages and other documentation
+man: man pages
+lib: libraries
+shlib: shared libraries
+
+maybe prefix standard tags with ':' and then anything else
+is free to be used. need a way to list all package tags
+zpm pkgtags ?