]> pd.if.org Git - zpackage/blob - Commands
create combined single header for jsw library
[zpackage] / Commands
1 Cut it down: You're:
2 manipulating a package file
3         add a file
4         remove a file
5         tag a file
6         tag the package
7         setting package metadata
8         setting file metadata
9 installing a package
10         options: include/exclude tagsets/files, package root, package database
11 uninstalling a package
12         options: preserve files/tags
13 updating a package
14 manipulating the local database
15         same a package file, but more obvious that you have to specify
16         a specific package
17 showing local database information
18 showing package file information
19 manipulating remote repositories
20
21 zpm: always a shell script, that way it can source config files and export environment
22 variables for sub-programs
23
24 Good to have a program to check if a package exists.  That is, would
25 zpm install do anything, at least notionally.
26
27 Three basic modes
28
29 1: working on the local database and manipulating packages
30 This is where 'install' 'update' 'remove' etc are done.
31 Additionally, this is where notes, bug reports, repo
32 control, and so forth are done.  Since this is the most
33 common mode, these commands shouldn't need a prefix or
34 something saying we're dealing with the local package DB.
35
36 2: working on a package file.
37 This is where building a new package, adding files, and otherwise
38 dealing with package metadata happens
39
40 3: working on a repository of package files
41
42 Since 2 and 3 are the less common operations, they can have
43 more verbose syntax, also, 2 "expects" a package file, so
44 require an option to force using the local DB, and 3 expects
45 needs repos, perhaps force not using local DB
46 Difference between working on a repository, and manipulating
47 repository info for the local or other DB
48 And 1 expects the local db, so option to specify package file.
49
50 -f for package file?  or -p? and for cat 2, take as argument if
51 not specified?  perhaps an option to construct?  probably
52 not, have a program to construct if needed.
53
54 Need a way to specify a non-default local database location,
55 /var/lib/zpm/local.zpm by default
56
57 For 2: zpm pkg
58 For 3: zpm repo
59
60 Conceivably for 2: 'zpm -f <pkgfile>', since if it's not the
61 local package database, you'll have to specify the package file
62
63 install: will search the repos for the most recent package.
64 of install a from a package file given with -f.
65
66 so zpm install -f 'pkgfile' will install all packages in that file
67 zpm install -f pkgfile package will install just the named package
68 zpm install -f pkfile package package2 will installed both packages
69 zpm install -f pkgfile -V 1.2 will install version 1.2 of all packages
70 that have a version 1.2
71 zpm install -f pkgfile foo-1.2 will install version 1.2 of package foo
72
73 zpm install foo will install the most up to date foo from the
74 repos
75
76 zpm install foo-1.2 install version 1.2.  how to distinguish
77 between versions and package names with hyphens?  Use @?
78
79 Package filters: Version, release, name, min/max version, min/max release
80 Package tags?
81
82 File filters: Get everything, except exclude by tag, which will
83 exclude every file with the tag.  Can reverse sense, and get
84 nothing, except what's in tag. +tag will add a tag to the set,
85 -tag will remove it.  'tag' sets the tag list
86
87
88 Environment Variables
89 ---------------------
90
91 Always set by the zpm wrapper.
92
93 ZPMDB: path to local database
94 ZPMPACKAGE: package name
95 ZPMPKGVER: package version
96 ZPMPKGREL: package release
97 ZPMPKGFILE: package file
98
99 Command Line Options
100 --------------------
101
102 Used by all programs, so can be passed to zpm
103
104 -f package file
105
106 Package Selector
107 ----------------
108
109 -p <package name> -V <package version> -R <package release>
110
111 version and release are always the latest available if not specified for new
112 packages, version defaults to 1.0, release to 1, but may also be taken from the
113 environment
114
115 If there is more than one package name in a database the shortest name is the
116 default, and the earliest alphabetically after that.  This makes it so that if
117 you have 'db' and 'db-dev' in the same package, db will be the default.  Though
118 that's not the way to do it, instead you should tag files within a package, and
119 then filter the install.
120
121 command line over-rides environment, which over-rides defaults
122
123 ZPM Wrapper Script
124 ------------------
125
126 The primary executable is zpm, which is a shell script.  This script
127 sources (if they exist) in order, /etc/zpm.conf ~/.zpmrc
128
129 The script then parses its command line options up until the first non-option,
130 export environment variables, and looks for a command of the form zpm-$1 which
131 it then executes.  If the ZPMPATH is not set, it looks in PATH and if that is
132 not set, in /sbin:/usr/libexec/zpm
133
134         -d <database file>
135         -f <database file> -- they're the same option, just different way of thinking about it
136
137 Low Level Commands
138 ------------------
139
140 Very low level commands to manipulate a database.  These can be used directly,
141 but are primarily intended to be wrapped up in shell scripts.  Each of these
142 should also have an equivalent in the C library API.  The zpm- prefix is omitted below.
143
144 newpackage: add package metadata to a zpm database, creating the target file if
145 needed.
146
147         -N require the target file to not exist (new)
148         -A require the target file to exist (add)
149         -P packager string, should be an email, use ZPMPACKAGER environment
150
151 addtopackage: add a file to a package
152         
153         -C <n> number of leading components to strip
154         -P <path prefix> prefix to strip
155         -H hard coded path, regardless of the source 
156         -T track only, don't import the contents
157         -c flag as configuration file
158         -t <tag list> comma or space separated tags on file
159
160         zpm -f foobar-1.0-1.zpm addtopackage /usr/bin/foo /usr/bin/bar
161         zpm addtopackage foobar-1.1-3.zpm /usr/bin/foo /usr/bin/bar
162         zpm add -f foobar-1.1-3.zpm -p bar /usr/bin/bar
163
164         need to think about the syntax here, but best to just write something,
165         then change it later
166         
167 extract: pull file content to disk
168         $1 is hash or hash prefix if unique, $2 is target path
169
170         As per install(8)
171         -m mode
172         -o owner
173         -g group
174
175         -D don't create leading directories
176
177 list: list package contents
178
179         -F <format> %p path %m mode %o owner %g group %h hash
180         -N don't append a newline to format
181         -0 append a null byte to the format
182
183         default format is '%h %m %o %g %p'
184
185 show: list packages
186         maybe reverse list and show
187
188 drop: delete a package
189
190 delete: remove a file from a package
191
192 adjust: adjust file metadata
193         
194 Higher Level Commands
195 ---------------------
196
197 install: install a package to the local system
198         search repositories known in the local db for a matching package
199 remove: remove a package
200 update: update a package
201
202         -D dry-run, just show what might be done
203
204 export: create a standalone package file from a repo/localdb
205
206 json: dump the metadata of a repo as json
207
208 Repositories
209 ------------
210
211 A repository is just a collection of packages.  All in one DB, or perhaps
212 mark an external file location for package contents.
213
214 Repository Definition is just a url.
215 Has a priority.  Can require trusted signer.  Can require confirmation.
216 Install/Search will ask on tied priorities.  Warn on lower priorities.
217
218 Fetch a repo by getting the json file, or by getting a stripped down DB file.
219
220 repo import: adds repository information from the json file
221 repo drop <url or name>
222 repo add <url> [name]
223 repo refresh: update repository info
224
225 repo command needs to know how to get metadata from local files
226 for http[s] urls, path given should return either json or sqlite db, responsibility
227 of repo to make this work
228
229 Building Packages
230 -----------------
231
232 build: builds a package file
233         -S read paths from stdin
234
235         Reads PKGBUILD in the current directory
236         -b build script path instead of PKGBUILD
237
238 Other Commands
239 --------------
240
241 absorb: pull in the content of a file.  note the mtime if it's a config file, possibly
242 keeping multiple versions
243
244 truncate: drop the content of a file
245
246 status:
247         investigate the status of a repo, reporting things like failed installs or removes,
248         file conflicts, anything else
249
250 integritycheck: compare the stored hashes with the hashes on disk
251
252 note:
253         add a note file, - from stdin, list if none
254
255 edit:
256         edit a note file
257
258 ack:
259         acknowledge a note file
260
261 diff:
262         compare two versions of a package, show what would be done
263         or different
264
265 info:
266         get information on a package
267
268 track:
269         add a package to config tracked packages
270
271 add: add to a repository/database
272
273 clean: clean a repository/database
274