pd.if.org Git - zpackage/blob - doc/zpm-script.8

   1 .TH zpm-script 8 2019-03-06 "ZPM 0.7.0"
   2 .SH NAME
   3 zpm-script \- run, set, or list package scripts
   4 .SH SYNOPSIS
   5 .B zpm script
   6 [
   7 .B -Fhql
   8 ]
   9 [
  10 .BI -f " pkgfile"
  11 ]
  12 [
  13 .BI -p " phase"
  14 ]
  15 [
  16 .BI -R " rootdir"
  17 ]
  18 [
  19 .BI -o " path"
  20 ]
  21 [
  22 .BI -S " script"
  23 ]
  24 .I package
  25 [
  26 .I arg
  27 ]
  28 .SH DESCRIPTION
  29 \fBzpm-script\fR
  30 runs, sets, or lists package scripts for a package.  The package is a package
  31 id, which may be abbreviated.  Despite the name, scripts can be any
  32 arbitrary program, though they are usually posix shell scripts.
  33 .PP
  34 zpm-script runs in one of three modes, run, list, and set.
  35 .SS Run Mode
  36 In run mode, a script for a given phase is run if it exists.  It is not
  37 an error if there is no script for the given package and phase unless
  38 the \-F option is given.  Standard output from the script will be redirected
  39 to /var/tmp/zpm-script.out, or as specified by the -o option.
  40 .PP
  41 The script itself will be extracted to /var/tmp/zpm-script, set as executable,
  42 and then run.  The script is run with one or two arguments.  The
  43 first argument is the package id being installed, removed, or configured.
  44 If given \fIarg\fR is passed to the script as a second argument.
  45 For a package version update (or downgrade) this is the previous version of the
  46 package.
  47 .PP If the script fails (i.e. any non-zero exit status), the output will
  48 be imported into the database and a note will be added.
  49 .TP
  50 An example script
  51 .EX
  52 #!/bin/sh
  53
  54 echo example and test zpm stage script
  55 echo args: "$*"
  56 .EE
  57 .SS Set Mode
  58 Set mode will set the script for a given package and phase to the
  59 path given as an additional argument.  If the -h is given, the script
  60 is interpreted as a hash to be set directly, and nothing is taken
  61 from the filesystem.
  62 .SS List Mode
  63 If a phase is given with \-p the script will be printed to stdout (or
  64 wherever \-o specifies).  If no phase is given, a list of scripts for
  65 the package will be printed to stdout.
  66 .SH OPTIONS
  67 .TP
  68 .B \-l
  69 Run in list mode.
  70 .TP
  71 .B \-r
  72 Run in run mode.  This is the default.
  73 .TP
  74 .B \-s
  75 Run in set mode.
  76 .TP
  77 .BI \-p phase
  78 Specify the script phase.  This defaults to all phases for list mode,
  79 and configure for running or setting scripts.
  80 .TP
  81 .B \-n
  82 Do not create notes.  Overrides other note options.
  83 .TP
  84 .B \-N
  85 Create notes only if the database is writable, otherwise send
  86 output to stdout.
  87 .TP
  88 .B \-a
  89 Make a note for all output, regardless of the exit status.
  90 .TP
  91 .B \-e
  92 Allow empty notes to be created for the \-a option.
  93 Normally if the output is empty and the script succeeded, the \-a option
  94 will not cause a note to be created.
  95 .TP
  96 .B \-f
  97 specify the package file to find packages in
  98 .TP
  99 .B \-h
 100 When setting a script, the script is taken as a hex encoded hash, rather
 101 than a path to a script.
 102 .TP
 103 .B \-q
 104 Run quietly.
 105 .TP
 106 .B \-v
 107 Send any output to stdout.
 108 .TP
 109 .BI \-R " rootdir"
 110 The current directory will be changed to \fIrootdir\fR before
 111 running the script.  Defaults to '/'.  No chroot is done
 112 before running the script, so scripts should be aware of this
 113 and generally use relative paths.  If neccessary and possible
 114 the script itself can chroot.  Calling chroot(2) requires superuser
 115 privileges, so it would be impossible to run the scripts as a non
 116 root user if chroot was attempted.
 117 .SH EXAMPLES
 118 .TP
 119 zpm script -f foo-1.0-1.zpm foo
 120 Run the configure script for the foo package found in the foo-1.0-1.zpm
 121 file.
 122 .TP
 123 zpm script foo
 124 Run the configure script for the (most recent) foo package found
 125 in the local database.
 126 .TP
 127 zpm script -l foo
 128 List all scripts for the foo package.
 129 .SH EXIT STATUS
 130 0 on success non zero on failure
 131 .SH FILES
 132 /var/lib/zpm/local.db
 133 .SH ENVIRONMENT
 134 ZPMDB
 135 .SH AUTHOR
 136 Nathan Wagner
 137 .SH SEE ALSO
 138 .BR zpm (8)