commit: e1da9e5bde6c18bd9bd411ce20cdacdcb97e135c
Author: Mike Frysinger <vapier <AT> gentoo <DOT> org>
AuthorDate: Sat Nov 26 23:34:33 2016 +0000
Commit: Mike Frysinger <vapier <AT> gentoo <DOT> org>
CommitDate: Sat Nov 26 23:34:33 2016 +0000
URL: https://gitweb.gentoo.org/proj/portage-utils.git/commit/?id=e1da9e5b
rewrite docs in markdown for github integration
HACKING | 32 --------------------------
HACKING.md | 20 ++++++++++++++++
README | 31 -------------------------
README.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
TODO | 59 -----------------------------------------------
TODO.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
6 files changed, 169 insertions(+), 122 deletions(-)
diff --git a/HACKING b/HACKING
deleted file mode 100644
index 67dbbaf..0000000
--- a/HACKING
+++ /dev/null
@@ -1,32 +0,0 @@
-- Adding applets is easy using the q framework.
- Note: Please try to keep applet names under 8 chars.
- * cp template.c qmyapplet.c (all applets use the prefix of the letter
'q')
- * applets.h: add your prototype (see DECLARE_APPLET macro)
- * applets.h: add a new line to applets[] following the existing syntax
- * run `make depend` to auto regenerate dependent files
-
-When and where you can please try to use an existing applet and extend
-on its functionality by adding more options vs adding a bunch of new
-little applets.
-
-- Keep behavior consistent
- * matching:
- default is sloppy match
- -e exact match
- -r regex match
-
-## Examples:
- * find elf files linking to old openssl
- qlist -ao | scanelf -BqgN libssl.so.0.9.6 -f -
-
- * print a package.use
- qlist -UCq | grep ' ' > package.use
-
- * find orphan files not owned by any package in /lib and /usr/lib
- qfile -o {,/usr}/lib/*
-
- # get PORTDIR
- DEBUG=: ./q -Ch 2>&1 | grep ^PORTDIR | awk '{print $3}
-
- # Verify all packages
- qcheck -a
diff --git a/HACKING.md b/HACKING.md
new file mode 100644
index 0000000..e0536fa
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,20 @@
+# New applets
+
+Adding applets is easy using the q framework.
+
+Note: Please try to keep applet names under 8 chars.
+
+- cp template.c qmyapplet.c (all applets use the prefix of the letter 'q')
+- applets.h: add your prototype (see DECLARE_APPLET macro)
+- applets.h: add a new line to applets[] following the existing syntax
+- run `make depend` to auto regenerate dependent files
+
+When and where you can please try to use an existing applet and extend
+on its functionality by adding more options vs adding a bunch of new
+little applets.
+
+- Keep behavior consistent
+ - matching:
+ - default is sloppy match
+ - -e exact match
+ - -r regex match
diff --git a/README b/README
deleted file mode 100644
index 1a8dc3d..0000000
--- a/README
+++ /dev/null
@@ -1,31 +0,0 @@
-# Copyright 2005-2014 Gentoo Foundation
-# Distributed under the terms of the GNU General Public License v2
-
-Contact:
- Please file bugs at:
-
https://bugs.gentoo.org/enter_bug.cgi?product=Portage%20Development&format=guided
- Use Component of "Third-Party Tools".
-
-Current developer list:
- so...@gentoo.org
- vap...@gentoo.org
-
-
-- Speed is everything.
- Having your PORTDIR and VDB on the right file system helps dramatically
-
- IDE raid with PORTDIR on reiserfs:
- q -r
- q: Finished 20655 entries in 1.990951 seconds
-
- IDE raid with PORTDIR on ext3:
- q -r
- q: Finished 20655 entries in 203.664252 seconds
-
-
-- Fetching via anon git:
-
- git clone git://anongit.gentoo.org/proj/portage-utils.git
-
-You can view it online via gitweb:
- https://gitweb.gentoo.org/proj/portage-utils.git/
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3889ee2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,72 @@
+# Gentoo Portage Utilities
+
+| What | How |
+| -------- | --------------------------------------------------------- |
+| HOMEPAGE | https://wiki.gentoo.org/wiki/Portage-utils |
+| GIT | git clone git://anongit.gentoo.org/proj/portage-utils.git |
+| VIEWVCS | https://gitweb.gentoo.org/proj/portage-utils.git/ |
+| STATUS | [](https://travis-ci.org/gentoo/portage-utils)
[](https://scan.coverity.com/projects/gentoo-portage-utils)
|
+
+portage-utils is a small set of utilities for working with Portage, Gentoo
+ebuilds, Gentoo ebuild overlays, installed packages (vdb), and similar sources
+of information. The focus is on size and speed, so everything is in C.
+
+## Building
+
+Just run `make`. This should work on any recent POSIX compliant system.
+
+## Helping out
+
+There's a large [TODO](./TODO.md) list with various ideas for improvements.
+
+There's also a [HACKING](./HACKING.md) doc to help you get started.
+
+## Examples
+
+* find elf files linking to old openssl<br>
+ `qlist -ao | scanelf -BqgN libssl.so.0.9.6 -f -`
+
+* print a package.use<br>
+ `qlist -UCq | grep ' ' > package.use`
+
+* find orphan files not owned by any package in /lib and /usr/lib<br>
+ `qfile -o {,/usr}/lib/*`
+
+* get PORTDIR<br>
+ `DEBUG=: ./q -Ch 2>&1 | grep ^PORTDIR | awk '{print $3}`
+
+* Verify all packages<br>
+ `qcheck -a`
+
+## Contact
+
+### Bugs
+
+Please file bugs at:
+
https://bugs.gentoo.org/enter_bug.cgi?product=Portage%20Development&format=guided
+
+Use Component of "Third-Party Tools".
+
+### Developers
+
+* so...@gentoo.org
+* vap...@gentoo.org
+
+## Notes
+
+### Speed is everything.
+
+Having your PORTDIR and VDB on the right file system helps dramatically
+
+IDE raid with PORTDIR on reiserfs:
+
+```
+$ q -r
+q: Finished 20655 entries in 1.990951 seconds
+
+IDE raid with PORTDIR on ext3:
+
+```
+$ q -r
+q: Finished 20655 entries in 203.664252 seconds
+```
diff --git a/TODO b/TODO
deleted file mode 100644
index 08e8bc3..0000000
--- a/TODO
+++ /dev/null
@@ -1,59 +0,0 @@
-- unify match behavior:
- default *foo*
- -e foo
- -r (-R ?) regexp foo.*
-
-- disable color when tty = NULL; may break less?
-
-- multiline reads don't yet work for quse/qsearch
-
-- standardize/unify/clean up misc handling of colors
-
-- speed up queue structure ... append walks the whole list
-
-- qmerge
- - dep resolver needs spanktastic love.
- - needs safe deleting (merge in place rather than unmerge;merge)
- - multiple binary repos (talk to zmedico)
- - handle compressed Packages file (talk to zmedico)
- - handle binary Packages file (talk to zmedico)
- - gpg sign the packages file (before compression)
- - binary vdb (sqlite) ... talk to zmedico
- - remote vdb
- - don't bother emitting any "DIR" entries to CONTENTS ?
- - auto rmdir any empty dirs
- - avoid Packages fetching all the damned time
- - parallel fetch tbz2s
- - check order of pkg_{pre,post}{inst,rm} during install, unmerge, and
upgrade
- - env is not saved/restored between pkg_{pre,post}inst (see portage and
REPO_LAYOUT_CONF_WARN)
- - support installing via path to tbz2 package
- - support TTL field in binpkgs file
-
-- atoms:
- - only 32bit values are supported for revision (-r#)
- - only 64bit values are supported in any individual version component
- foo-(1234)_alpha(56789)
- - these limits should not be an issue for all practical purposes
- - need to handle USE deps like: cat/pkg-123[foo(+)]
- - show support slots like: qmerge -U automake:1.12
-
-- qcache:
- - need to convert it to new metadata/md5 style
-
-- qdepends:
- - support querying uninstalled packages (via metadata/md5 cache)
-
-- env vars only get expanded once, so this fails:
- ACCEPT_LICENSE="foo"
- ACCEPT_LICENSE="${ACCEPT_LICENSE} bar"
- we end up getting just:
- ACCEPT_LICENSE=" bar"
-
-- qpkg:
- - fix "would be freed" message when --pretend is *not* active
- - add a verbose output that describes why a package is cleaned
- - newer binpkgs available
- - newer installed version available
-
-- qsync:
- - rewrite to use new repos.conf standard
diff --git a/TODO.md b/TODO.md
new file mode 100644
index 0000000..86ebbd7
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,77 @@
+# Common
+
+- unify match behavior:
+ - default *foo*
+ - -e foo
+ - -r (-R ?) regexp foo.*
+
+- disable color when tty = NULL; may break less?
+
+- multiline reads don't yet work for quse/qsearch
+
+- standardize/unify/clean up misc handling of colors
+
+- speed up queue structure ... append walks the whole list
+
+- equiv of `equery m` (metadata)
+
+- env vars only get expanded once, so this fails:<br>
+ `ACCEPT_LICENSE="foo"`<br>
+ `ACCEPT_LICENSE="${ACCEPT_LICENSE} bar"`<br>
+ we end up getting just:<br>
+ `ACCEPT_LICENSE=" bar"`
+
+# Atoms
+
+- only 32bit values are supported for revision (-r#)
+- only 64bit values are supported in any individual version component
+ foo-(1234)_alpha(56789)
+- these limits should not be an issue for all practical purposes
+- need to handle USE deps like: cat/pkg-123[foo(+)]
+- show support slots like: qmerge -U automake:1.12
+
+# qmerge
+
+- dep resolver needs spanktastic love.
+- needs safe deleting (merge in place rather than unmerge;merge)
+- multiple binary repos (talk to zmedico)
+- handle compressed Packages file (talk to zmedico)
+- handle binary Packages file (talk to zmedico)
+- gpg sign the packages file (before compression)
+- binary vdb (sqlite) ... talk to zmedico
+- remote vdb
+- don't bother emitting any "DIR" entries to CONTENTS ?
+ - auto rmdir any empty dirs
+- avoid Packages fetching all the damned time
+- parallel fetch tbz2s
+- check order of pkg_{pre,post}{inst,rm} during install, unmerge, and upgrade
+- env is not saved/restored between pkg_{pre,post}inst (see portage and
REPO_LAYOUT_CONF_WARN)
+- support installing via path to tbz2 package
+- support TTL field in binpkgs file
+- merge duplicate atoms on the CLI (`qmerge -Uq nano nano nano`)
+- unmerging should clean out @world set
+
+# qcache
+
+- need to convert it to new metadata/md5 style
+
+# qdepends
+
+- support querying uninstalled packages (via metadata/md5 cache)
+- support atoms like `qdepends -rQ qtsql:4` (should match unslotted deps)
+- add -S/-v/-R behavior like qlist #574934
+
+# qpkg
+
+- fix "would be freed" message when --pretend is *not* active
+- add a verbose output that describes why a package is cleaned
+ - newer binpkgs available
+ - newer installed version available
+
+# qsync
+
+- rewrite to use new repos.conf standard
+
+# qlist
+
+- support atoms instead of exact matches
