On 15/09/15 08:42, Andrew Gregory wrote:
--- doc/.gitignore | 1 + doc/Makefile.am | 4 ++ doc/alpm-hooks.5.txt | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 112 insertions(+) create mode 100644 doc/alpm-hooks.5.txt
libalpm-hooks vs alpm-hooks... I lean towards using libalpm-hooks. Especially as we already have libalpm(3).
diff --git a/doc/.gitignore b/doc/.gitignore index ad496ce..2eae9e4 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,3 +1,4 @@ +alpm-hooks.5 PKGBUILD.5 libalpm.3 makepkg.8 diff --git a/doc/Makefile.am b/doc/Makefile.am index 60a70b3..7e83dd2 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -4,6 +4,7 @@ # man_MANS if --enable-asciidoc and/or --enable-doxygen are used.
ASCIIDOC_MANS = \ + alpm-hooks.5 \ pacman.8 \ makepkg.8 \ makepkg-template.1 \ @@ -20,6 +21,7 @@ ASCIIDOC_MANS = \ DOXYGEN_MANS = $(wildcard man3/*.3)
HTML_MANPAGES = \ + alpm-hooks.5 \ pacman.8.html \ makepkg.8.html \ makepkg-template.1.html \ @@ -46,6 +48,7 @@ HTML_DOCS = \ EXTRA_DIST = \ asciidoc.conf \ asciidoc-override.css \ + alpm-hooks.5.txt \ pacman.8.txt \ makepkg.8.txt \ makepkg-template.1.txt \ @@ -147,6 +150,7 @@ $(HTML_OTHER): asciidoc.conf Makefile.am %.3.html: ASCIIDOC_OPTS += -d manpage
# Dependency rules +alpm-hooks.5 alpm-hooks.5.html: alpm-hooks.5.txt pacman.8 pacman.8.html: pacman.8.txt makepkg.8 makepkg.8.html: makepkg.8.txt makepkg-template.1 makepkg-template.1.html: makepkg-template.1.txt diff --git a/doc/alpm-hooks.5.txt b/doc/alpm-hooks.5.txt new file mode 100644 index 0000000..36e69c4 --- /dev/null +++ b/doc/alpm-hooks.5.txt @@ -0,0 +1,107 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// +alpm-hooks(5) +============= + +NAME +---- + +alpm-hooks - alpm hook file format + +SYNOPSIS +-------- + + [Trigger] (Required, Repeatable) + Operation = Sync|Remove (Required) + Type = File|Package (Required) + Target = <Path|PkgName> (Required, Repeatable) + + [Action] (Required) + When = PreTransaction|PostTransaction (Required) + Exec = <Command> (Required) + Depends = <PkgName> (Optional) + AbortOnFail (Optional, PreTransaction only) + +DESCRIPTION +----------- + +libalpm provides the ability to specify hooks to run before or after +transactions based on the packages and/or files being modified. Hooks consist +of a single "[Action]" section describing the action to be run and one or more +"[Trigger]" section describing which transactions it should be run for. + +TRIGGERS +-------- + +Hooks must contain at least one "[Trigger]" section that determines which +transactions will cause the hook to run. If multiple trigger sections are +defined the hook will run if the transaction matches *any* of the triggers. + +*Operation =* Sync|Remove:: + Select the type of operation to match targets against. +
There should be a description of what an upgrade is.
+*Type =* File|Package:: + Select whether targets are matched against transaction packages or files. + See CAVEATS for special notes regarding File triggers. + +*Target =* path|package:: + The file path or package name to match against the active transaction. + File paths refer to the files in the package archive; the installation root + should *not* be included in the path. Shell-style glob patterns are + allowed. It is possible to invert matches by prepending a file with an + exclamation mark. May be specified multiple times. Required. + +ACTIONS +------- + +*Exec =* /path/to/executable:: + Executable to run. Required. + +*When =* PreTransaction|PostTransaction:: + When to run the hook. Required. + +*Depends =* package:: + Packages that must be installed for the hook to run. May be specified + multiple times. + +*AbortOnFail*:: + Causes the transaction to be aborted if the hook exits non-zero. Only + applies to PreTransaction hooks. + +OVERRIDING HOOKS +---------------- + +Hooks may be overridden by placing a file with the same name in a higher +priority hook directory. Hooks may be disabled by overriding them with +a symlink to /dev/null. + +EXAMPLES +-------- + + # Force disks to sync to prevent data corruption + + [Trigger] + Operation = Sync + Type = Package + Target = * + + [Trigger] + Operation = Remove + Type = Package + Target = * + + [Action] + Depends = coreutils + When = PostTransaction + Exec = /usr/bin/sync + +CAVEATS +------- + +There is no way to guarantee that the trigger operation was actually performed +for file triggers. Removal triggers will match even if the file did not +actually exist on the file system when the transaction begin.
began
Sync triggers +may be extracted as a .pacnew file, leaving the trigger path unmodified. +
Does that mean /etc/foo.pacnew will not match a Trigger /etc/foo? Or will it match despite the file not being modified? That section needs to be clearer.
+include::footer.txt[]