add range search to findpkg

[zpackage] / README

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
--------

binary installs

package metadata

package integrity
        gpg signatures :- use own signatures, or figure out PD way to get gpg
        sha256 sums
        sha3 sums - not implemented

package contents integrity
        sha256 sums of installed files
        sha3 sums - not implemented
        sha1 sums - not implemented
        lists of directory contents

package database editing
        mark a file as a configuration file

repackaging
        creating a package from the current state of an installed package

package a tarball
        create a package from a tarball

package from stdin
        like cpio

package a directory
        like tar

build from shell scripts

rebuild a package

write ahead log for package filesystem operations
        it should always be possible for the package system
        to figure out if it was interrupted

install, uninstall, upgrade, and downgrade hooks

dependency tracking

network fetching of packages and package databases
reference counting of dynamic libs

simple packaging constructs
        use shell scripts where possible
        use shell functions as hooks and callbacks

A package is an SQLite database file.

Multiple packages in the same file.

need to mark a package as held for no automatic upgrade

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 ?