PWIZ core contains functions for core functionality. No guesses and knowledges are here, only engine skeleton, initialization and main loop.
string: string to be echoed
Alias for echo to stderr.
string: string to be echoed
Alias for verbose echo. Echo only in verbose mode.
string: string to be echoed
Alias for more verbose echo. Echo only in more verbose mode.
string: string to be echoed
Alias for very verbose echo. Echo only in very verbose mode.
name: Feature name.
desc: short description of feature
longdesc: long description of feature
Define debug features (class of debug messages for --enable-debug).
To simplify coding and make code faster, do a redirection of standard streams instead of redirection for particular commands. When using these functions, channels 5-7 are reserved for saving original redirection.
file: File from which redirect.
Redirect standard input from file. Close by pwiz_redirect_stdin_close.
file: File to which redirect.
Redirect standard output to file. Close by pwiz_redirect_stdout_close.
file: File to which redirect stderr. Close by pwiz_redirect_stderr_close.
Redirect error output to file.
file: File to which redirect.
Appending redirect standard output to file with. Close by pwiz_redirect_stdout_close.
file: File to which redirect stderr.
Appending redirect error output to file with. Close by pwiz_redirect_stderr_close.
Revert redirection created by by pwiz_redirect_stdin and close file.
Revert redirection created by by pwiz_redirect_stdout and close file.
Revert redirection created by by pwiz_redirect_stdout, but don't close file.
Restore redirection created by by pwiz_redirect_stdout and suspended by pwiz_redirect_stdout_suspend.
Revert redirection created by by pwiz_redirect_stderr and close file.
returns: return_code
Helper, which only sets return code.
filename: Name of file in arbitrary form.
returns $pwiz_result: Canonical form of file name.
Converts file names to canonical form, i. e. no "//", "/../", "/./".
NOTE: Does not canonize relative paths.
NOTE: Function is relatively slow. Use C alternative for large amount of file names.
path: Directory, where tu start searching.
path_prefix: Path prepended to all searched directories, but not to output values. Must have trailing slash, if used.
callback_argument_2: Arbitrary argument to callback function.
uses: $pwiz_callback path callback_argument_2: callback function. Default is echo.
A Bash alternative to simple recursive find for all files and links.
WARNING: If you want really all files, you must turn on dot globbing (shopt -s dotglob).
path: Directory, where tu start searching.
path_prefix: Path prepended to all searched directories, but not to output values. Must have trailing slash, if used.
callback_argument_3: Arbitrary argument to callback function.
uses: $pwiz_callback path type callback_argument_3: callback function. Default is echo, type is either 'file' or 'dir'.
A Bash alternative to simple recursive find for all dirs, files and links.
WARNING: If you want really all files, you must turn on dot globbing (shopt -s dotglob).
initialize work directories for project.
Call it every time you change $pwiz_project_* variables
If not stated anything else, separate directory is created for each project. Can be redefined by callback from packaging engine (see lower).
Temporary directory for PWIZ modules, which is not cleaned after termination. It can be cleaned by user. Mostly for storing downloaded files.
WARNING: $PWIZ_CACHEDIR is common for all projects!
WARNING: Do not access here from pwiz_run
NOTE: Use module name as prefix for all file names here.
Temporary directory for PWIZ modules.
WARNING: Do not access here from pwiz_run.
NOTE: To prevent name clashes, use module name as prefix for all file names here.
Temporary directory for PWIZ source codes.
WARNING: Do not write here from pwiz_run.
Temporary directory for unpacked sources.
WARNING: Do not use this before SOURCE stage.
WARNING: In separate build dir mode do not write here after unpack stage.
WARNING: Do not write here from outside pwiz_run.
Temporary directory for PWIZ build.
WARNING: Do not use this before PREPARE stage.
WARNING: Do not write here from outside pwiz_run.
Temporary directory for PWIZ installation root.
WARNING: Do not use this before INSTALL stage.
WARNING: Do not write here before INSTALL stage.
WARNING: Do not write here from outside pwiz_run.
Directory for PWIZ results.
path: path to be appended to directory itself (project subdirecttory)
Initialize work directories for project - array of callback functions.
Callback can redefine following variables: $PWIZ_SOURCESDIR, $PWIZ_SRCDIR, $PWIZ_BUILDDIR, $PWIZ_INSTALLROOT.
Use pwiz_array_add to add item to this array.
item: value to be added to the array
Add an item as last element of non-sparse array.
This is only simplification of array[${#array[@]}]=item
NOTE: array_name is without leading '$' sign.
pwiz_run: Command called by user to start protected command.
pwiz_run_prepare: One function defined by build environment system (rpm).
pwiz_run_wrappers: Chain of run wrappers defining environment protection (install watchers, sandboxing, run trace).
pwiz_run_core: One function defined by build environment system, which does execution and sets $pwiz_run_rc.
function: Function to be registered.
Register wrapper for pwiz_run. Wrapper uses pwiz_run_wrap for subsequent call.
Wrapper function skeleton:
function mywrapper { do_something_here # you can for example delete or modify some arguments there operate_on "@" # returns ${result[@]} pwiz_run_wrap "${result[@]}" # or simply: pwiz_run_wrap "$@" do_the_rest } pwiz_run_wrapper_register mywrapper
Call next registered wrapper. Functions is used inside run wrapper function.
Immediatelly calls its arguments.
This function can be redefined by packaging engine to to something else.
Top level wrapper.
After preparation calls $pwiz_run_function "$@"
Immediatelly calls its arguments.
This function can be redefined by packaging engine to to something else.
Run prepare function skeleton:
function myprepare { do_something $pwiz_run_function "$@" }
returns $pwiz_run_rc: Return code of executed stage command.
returns: Don't use return code. Use $pwiz_run_rc to get return code of protected command.
Run command in protected build environment.
$pwiz_run_rc is restored before next pwiz_run.
WARNING: Direct calling of pwiz_run without adding it to phase engine is not listed in query mode. If you want to have command in resulting package, you must not use pwiz_run directly!
WARNING: Do not alter pwiz_run_rc!
string: arbitrary string
Remark function. Action will appear in stage list, but is not executed.
Primarily intended for exporting comments to final build script.
string: string to be echoed
rc: return code
Abort PWIZ after fatal error.
function: function to be executed on exit
Register function to be executed on PWIZ exit.
rc: PWIZ return code
Exit PWIZ.
Tags are used to simplify calls of functions with many optional arguments. Idea is simple: Instead of positional arguments you are using format tag=value or tag[number]=value. To protect second format from expansion, functions using tags sets shell option noglob before parsing arguments.
Read tags to variables.
Tags are values entered as an argument of some functions in form: tag='value' other_tag[1]='other value' This alias reads them to variables pwiz_tag_tag='value' pwiz_tag_other_tag[1]='other value' It uses special Bash tricks to prevent expansion or word splitting of tags. To use it, you probably need to prevent expansion at all, expecially in nullglob mode (otherwise tag[number] is expanded to empty string) use set -o noglob in function alias.
WARNING: This function uses global variables, not local! Local variables in Bash are inherited to all functions called from inside functions, where variable is visible, unless you define your own instance. There is no chance to reset it back to global ones. If we want to recurse without variable inheritance, there is no chance to use local variables, so this function uses global ones.
Example of function with globbing prevention:
alias my_function="set -o noglob ; my_function_f" function my_function_f { set +o noglob pwiz_read_tags ... }
uses $tags: variable with tags
Read tags from $tags to variables.
Does the same as pwiz_read_tags, but reads values from $tags instead of $@. User does not need to care about globbing.
Tags are values entered as an argument of some functions in form: tag='value' other_tag[1]='other value' This alias reads them to variables pwiz_vtag_tag='value' pwiz_vtag_other_tag[1]='other value' It uses special Bash tricks to prevent expansion or word splitting of tags.
WARNING: This function resets noglob shell option.
Read tags from argument of a function.
Does the same as pwiz_read_tags, but reads values are read to local variables pwiz_local_tag_tag='value'.
WARNING: This function resets noglob shell option.
Alias for unsetting all tag variables. Prevent inheritance of tags to functions called from inside other function, where tag is defined.
WARNING: This function reset all variables named pwiz_tag_*!
Alias for unsetting all vtag variables. Prevent inheritance of tags to next function call.
WARNING: This function reset all variables named pwiz_vtag_*!
pwiz_tag_tag=value: command to reset tags
Because pwiz_read_tags use global variables and functions need to recurse, there is no chance for simple predefining default value for tag as global variable. You have to use this function.
Register default tag value.
After calling pwiz_reset_tags, no tags are defined. To define default values, use this function.
PWIZ error code for not implemented functions (6).
Engine is a piece of bash code, sourced from PWIZ core. It typically implements an independent interface for communication with outer world.
command: Command for engine.
Run engine with command.
Available commands:
no command: Load engine.
desc: show description and return
longdesc: show long description and return
engine_class: class of engine (only one in each class can be active)
engine_name: name of engine (implementation of engine class)
Engine must define all class specific functions defined by pwiz_engine_interface plus init and quit.
Engine functions are not called directly, but using pwiz_{engine_class}_{command} [ optional arguments ].
engine_class: class of engine (only one in each class can be active)
engine_name: name of engine (implementation of engine class)
Show description of engine implementation.
engine_class: class of engine (only one in each class can be active)
engine_name: name of engine (implementation of engine class)
Show long description of engine implementation.
engine_class: class of engine (only one in each class can be active)
engine_name: name of engine (implementation of engine class)
Source engine (load function definitions to PWIZ) and define calling functions to use this engine.
engine_class: class of engine (only one in each class can be active)
engine_name: name of engine (implementation of engine class)
Source engine (load function definitions to PWIZ) and define calling functions to use this engine.
engine_class: class of engine (only one in each class can be active)
returns: list of engines to stdout (FIXME will change to $pwiz_result in future versions)
List all available engines of defined class.
engine_class: class of engine (only one in each class can be active)
function...: Required functions in defined engine_class.
While defining new engine class, using pwiz_engine_interface you define a list of function, which shall be provided by each engine of this class.
Cache engine is designed for writing and reading answers and other useful information (tags) in per-package/version/product etc. basis. Address space is defined by keys. Keys are similar to filesystem paths. All functions returns result in $pwiz_result, if any
WARNING: Cache engine functions are "low level" and not recommended for direct use by programmers. Use cache interface functions instead.
key: key for data you want to read from cache
Read data associated with key from cache.
key: key for data you want to read from cache
Read tags associated with key from cache.
key: key for data you want to write to cache
value: data to be written
tags: tags to be written
Write data and tags to cache (associate data and tags with key).
key: key for data you delete from cache
Delete data and tags from cache (unassociate data and tags with key).
pattern: pattern for keys you want to query
returns ${pwiz_result[@]}: array of keys found (can be empty)
Find all keys in cache which corresponds to defined pattern.
NOTE: Patterns are standard path-element patterns (for globbing over more key elements you need to use more askerisks).
WARNING: Implementation must support subpatterns at least for q element (i. e. not only "/*/", but also "/subkey*/".
returns ${q tag}: value is stored to environment variable named as q tag
uses tag q: question ID (required)
uses tag credit: credit of saved value (default 100 - diffferent default from other functions!)
uses tag valid: validity range (see pwiz_cache_validity_{name}) (default=exact)
Fuction for saving value to cache. Uses the same tag naming style as ask interface uses. You only have to specify q tag.
uses tag q: question ID (required)
uses tag valid: validity range (see pwiz_cache_validity_{name}) (default=exact)
Fuction for deleting value from cache. Uses the same tag naming style as ask interface uses. You only have to specify q tag.
returns ${pwiz_guesses[@]}: array of all acceptablee guesses found
returns ${pwiz_credits[@]}: array of credits of guesses
returns $pwiz_guess_best: index of most credible guess
returns $pwiz_guess_best_value: value of most credible guess ("@PWIZ_UNDEFINED@" if none)
returns $pwiz_guess_best_credit: credit of best guess
returns ${pwiz_strings[@]}: array of string values of guesses (optional - array can be sparse)
returns ${pwiz_hotkeys[@]}: array of guess hotkeys (optional - array can be sparse)
returns $pwiz_cache_key_value: cache value for exact match ("@PWIZ_UNDEFINED@" if none)
returns $pwiz_cache_key_tags: cache tags for exact match (undefined if none)
returns $pwiz_cache_key_credit: cached credit for exact match
uses tag q: question ID (required)
uses tag credit: credit of saved value (default 100 - diffferent default from other functions!)
uses tag valid: validity range (see pwiz_cache_validity_{name}) (default=exact)
uses tag default: default value, used if no cached guess is available
Fuction for reading value from cache. Uses the same tag naming style as ask interface uses, including guessing and answer credit. You have to specify q tag.
WARNING: In difference to ask interface and pwiz_cache_save, value is not cached in local variable. It is because you can want read best guess or exact guess.
For some answers, it's wise to attach credit only if next phases are successfully completed. For this purpose, delayed caching functions are available.
Delayed write is a mechanism, when answer is cached, but the credit is set to -2 (delayed invalid) until defined command completes.
The basic difference between delayed caching and standard phases are:
- argument parsing style does not require quote ascaping
- easy searching for cached values
phase: phase to delay credibilization to
pwiz_cache_write_args: arguments for later execution of pwiz_cache_write command
Function for delayed write. First argument is phase name, when credit will become valid, the rest are arguments for pwiz_cache_write.
phase: phase to delay credibilization to
This engine provides interface with package database on destination system.
file: queried file
returns: 0: OK, 1: problem
returns ${pwiz_result[@]}: array of owning packages
Ask package database, which of installed packages owns file.
Question engine is interface for communication with users. Engine asks user and waits for response.
Any question can contain callback functions (which can be implementation alternative interface for "enter manually").
WARNING: This is an internal class of engines and programmers should not use these functions directly. Use pwiz_ask_{function} instead. Those functions do additional answer caching and guess evaluation.
initial_value: initial value of string
returns $pwiz_answer: user's answer
can use tag prompt: prompt for manual answer (default "Your value: ")
Prompt user for string.
returns $pwiz_answer: user's answer
returns $pwiz_fallback_answer: user selected default answer (default false)
uses tag no_default: no preselected default - user have to respond (default false)
can use tag multiline: allow multiple-line strings (default false)
Interface to ask user for string. Alternating this interface, you can also obtain radio: allow_new=false, yes/no: yesno=true.
returns $pwiz_answer: user's answer
returns $pwiz_fallback_answer: user selected default answer (default false)
uses tag allow_new: if set to false, "enter manually" is disabled (default true)
uses tag askmenu_hook: hook function for adding items to askmenu (default is nop)
uses tag no_default: no preselected default - user have to respond (default false)
uses tag callback: callback function for "enter manually" (returns $pwiz_answer) (default string)
uses tag item_type: type of item for asking "new item" (default string)
Interface to ask user for a selection from list.
Cache keys are used for addressing entries in cache.
List of keys for question id (in order). Currently "project subproject version patchlevel vendor build".
NOTE: For cache queries, first path item is question id.
Name of project (package).
Name of subproject. Normally unused ("-"), but can contain subpackage or partial project name.
Version of source codes.
Patch level. Additional resolution above source version.
Vendor+product string. Needed to discriminate between different packaging solutions for different vendors and products.
Build number. Needed to discriminate exact environment used for build (other package was updated, change in package is needed).
Alias for cloning global variables $pwiz_project_{key} to local variables ${key}. It is used by functions, which need to alter these values internally.
When searching guess for question, PWIZ needs to run through all similar answers. Question has its validity range. If asked again, and valid keys are identical, answer is considered as valid.
returns: "@" in key variables considered invalid for range
Validity ranges can be defined by programmers of modules. To define validity range name (used in tags as "valid={name}"), you should define function pwiz_cache_validity_{name}.
Remove cahe keys, where exact match will be required. Removes values unappropriate for defined validity range - if there is no function to compare similarity, key is removed and exact key match will be required.
Exact match in query is required. Use "valid=exact" in question to use this validity range (this is the default).
Match for all keys using the same source codes. Valid are all keys except patchlevel, vendor and build. Useful for checking of unpacked sources. Use "valid=source" in question to use this validity range.
Value for PWIZ setup. No keys are valid. Used for PWIZ preferences. Use "valid=setup" in question to use this validity range.
Per-project information, independent on vendor. Only key project is valid. Use "valid=project" in question to use this validity range.
Project state information, dependent on vendor. Keys project, subproject and vendor are valid. Use "valid=projectstate" in question to use this validity range. Used for special purposes, like storing patchlevel.
Vendor's policy, independent on project (package). Only key vendor is valid. Use "valid=vendor" in question to use this validity range.
Vendor's policy for project (package). Valid keys are project and vendor. Use "valid=product" in question to use this validity range.
Outside validity range, answer cannot be considered as fully credible. But not taking such answer in account means repeated answering the same question for all version. That's why there is credit inheritance. Answer is accepted, but its credit is decreased.
Guess credit level functions are functions define ability to trust answers, which based on comparison of particular keys of both questions.
returns $pwiz_credit: inherited credibility
uses $pwiz_project_{key}: key for current project
uses $pwiz_item_{key}: key for cached project
Iherited credibility functions can be defined by programmers of modules. To define own guess credit level function, you need to define function pwiz_guess_credit_{key}. Credit level function has access to other key values, which can be used for guess, too.
Function compares keys in variables $pwiz_project_{key} and $pwiz_item_{key}.
Returns value 0-100 in $pwiz_credit.
Return value for inherited credibility value.
returns $pwiz_credit: inherited credibility
uses tag inherit: inheritance between versions (default 80)
Credit inheritance level between versions. Using tag inherit you can increase or decrease default credibility of answer done in other version.
returns ${pwiz_guesses[@]}: array of all acceptablee guesses found
returns ${pwiz_credits[@]}: array of credits of guesses
returns $pwiz_guess_best: index of most credible guess
returns $pwiz_guess_best_value: value of most credible guess
returns $pwiz_guess_best_credit: credit of best guess
returns $pwiz_guess_failed_delay: was there a failed delayed save for this item? (boolean)
returns ${pwiz_strings[@]}: array of string values of guesses (optional - array can be sparse)
returns ${pwiz_hotkeys[@]}: array of guess hotkeys (optional - array can be sparse)
returns $pwiz_cache_key_value: cache value for exact match ("@PWIZ_UNDEFINED@" if none)
returns $pwiz_cache_key_tags: cache tags for exact match (undefined if none)
returns $pwiz_cache_key_credit: cached credit for exact match (without cache source credit applied) (undefined if none)
uses tag q: question ID
uses tag default[@]: predefined defaults
uses tag c[@]: credits of predefined defaults (optional - array can be sparse)
uses tag string[@]: string value for predefined defaults (optional - array can be sparse)
uses tag hotkey[@]: guess hotkey for predefined defaults (optional - array can be sparse)
uses tag valid: validity range (see pwiz_cache_validity_{name}) (default exact)
uses tag yesno: tag for boolean questions (default false)
uses $pwiz_cache_key: cache key name, where answer should be cached (required)
uses ${pwiz_guess_default_{tag q}[@]}: predefined defaults in variables
uses ${pwiz_guess_c_{tag q}[@]}: credits of predefined defaults in variables (optional - array can be sparse)
uses ${pwiz_guess_string_{tag q}[@}]: string value for predefined defaults in variables (optional - array can be sparse)
uses ${pwiz_guess_hotkey_{tag q}[@]}: guess hotkey for predefined defaults in variables (optional - array can be sparse)
This function collects all available guesses. Function is used internally by pwiz_ask_core and pwiz_cache_load.
NOTE: Tags must be already read before calling this function.
guess: value of guess
credit: credit of guess (can be empty string)
string: string value for guess (can be empty string)
hotkey: guess hotkey (can be empty string)
This internal function evaluates guess and optionally adds it to guess array in pwiz_guess.
q: question ID (corresponds to tag q)
guess: value of guess
credit: credit of guess (can be empty string)
string: string value for guess (can be empty string)
hotkey: guess hotkey (can be empty string)
Add a guess to environment variables ${pwiz_guess_default_{q}}, ${pwiz_guess_c_{q}}, ${pwiz_guess_p_{q}} and ${pwiz_guess_string_{q}}. Later pwiz_guess can take it in account.
NOTE: Credit is considered as absolute. No user credibility is evaluated.
key: cache key to parse
returns pwiz_item_{key}: particular keys
Parses cache key to its elements and assigns it to variables $pwiz_item_q and $pwiz_item_{key}, where key is from $pwiz_key_list.
Askmenu is a structure between question interface and question backend. It helps with menu construction and processing answer.
Expanation of variables:
${pwiz_askmenu_callbacks[@]}: Callbacks, called when menu item is selected. Used internally. Must be defined.
${pwiz_askmenu_ids[@]}: id for preselection and postselection callbacks (can be empty string)
${pwiz_askmenu_strings[@]}: Strings to be displayed by question back-end. Should not be empty.
${pwiz_askmenu_hotkeys[@]}: Hotkeys. Displayed by question back-end. Used by pwiz_preselection_callback_default for hotkey (abbreviation) recognition. Other preselection callbacks can use it in other way (or not at all), but string contents can be still displayed by question back-end.
${pwiz_askmenu_preselection_callbacks[@]}: Callback called to decide, whether user selected this menu item. Default is
${pwiz_askmenu_preselection_numbers[@]}: Order numbers for ordered items.
${pwiz_askmenu_preselection_number_indexes[@]}: Reverse index, which maps ordered list index to askmenu index.
Minimal example of building menu with menu hook and processing answer:
function help_func { echo "This is a help text for $1." # We want to display question again. return 1 } function help_hook { pwiz_askmenu_add help_func test_dialog Help h } pwiz_askmenu_add_hook help_hook pwiz_askmenu_reset pwiz_askmenu_add echo reply_was_bottom Bottom "" pwiz_askmenu_add echo reply_was_fallback Fallback "" pwiz_preselection_callback_fallback_default tail pwiz_askmenu_add echo reply_was_1 One a "" head pwiz_askmenu_add echo reply_was_2 Two b "" is_default head pwiz_askmenu_add echo reply_was_3 Strange cc "" head no_number pwiz_askmenu_complete for (( count=0 ; count < ${#pwiz_askmenu_callbacks[@]} ; count++ )) ; do echo -n "$count, ${pwiz_askmenu_hotkeys[count]}: ${pwiz_askmenu_strings[count]}" if test $count = $pwiz_askmenu_default ; then echo -n " (default)" fi echo done read -p "Please answer: " pwiz_askmenu_process "$REPLY" case $? in 0 ) echo OK ;; 1 ) echo menu should be displayed again ;; 2 ) echo failed esac
{pwiz_askmenu_function}: function, which will be called, if user selects this item
id: identification of askmenu item (can be empty string, if {pwiz_askmenu_function} does not require it)
string: short description of feature (must not be empty)
hotkey: guess hotkey (can be empty string)
{preselection_callback}: callback called while evaluating answer (can be empty string, then pwiz_preselection_callback_default is used; can be pwiz_preselection_callback_fallback_default, then all answers will be accepted - useful only for tail element)
flags: "is_default": this menu entry is default, "head": show in first part of the list, "tail": show in last part of the list, "no_number": entry is not numbered
Add an item to ask menu. If item is selected by user, {pwiz_askmenu_function} is called.
id: identification of askmenu item from pwiz_askmenu_add (can be empty string)
answer: user's answer
returns: 0: processed, 1: menu should be displayed again
This function is called, if user selects this item.
id: identification of askmenu item from pwiz_askmenu_add (can be empty string)
index: current index in following arrays: ${pwiz_askmenu_callbacks[@]}, ${pwiz_askmenu_ids[@]}, ${pwiz_askmenu_strings[@]}, ${pwiz_askmenu_hotkeys[@]}, ${pwiz_askmenu_numbers[@]}, ${pwiz_askmenu_preselection_callbacks[@]}
answer: user's answer
returns: 0: it is item selected by user, 1: it is not item selected by user
Callback function, called during evaluation of user answer. Default callback is pwiz_preselection_callback_default.
{pwiz_askmenu_hook}: hook function, which calls pwiz_askmenu_add on its own
Add hook function, which is called every time pwiz wants to create ask menu.
uses: $pwiz_tags_{tag}: tags are already read to variables using pwiz_read_tags.
This function is called every time ask menu is created. Hook function can look at tags and decide, whether to display any menu item and call pwiz_askmenu_add.
Reset ask menu values. Called before building ask menu, Then appropriate pwiz_askmenu_add are called. Process is finished by pwiz_askmenu_complete.
"no_hooks": set if hooks should not be executed
returns ${pwiz_askmenu_strings[@]}: array of ask menu strings
returns ${pwiz_askmenu_hotkeys[@]}: array of ask menu hotkeys
returns ${pwiz_askmenu_callbacks[@]}: array of ask menu callbacks (internal)
returns ${pwiz_askmenu_ids[@]}: ids for ask menu callbacks and preselection callbacks
returns ${pwiz_askmenu_preselection_callbacks[@]}: array of ask menu preselection callbacks (internal)
returns ${pwiz_askmenu_numbers[@]}: array of ordered item numbers
returns ${pwiz_askmenu_number_indexes[@]}: reverse mapping of item numbers to askmenu indexes
returns $pwiz_askmenu_default: index of default ask menu item
returns $pwiz_askmenu_count: number of last numbered item plus 1
Finishes ask menu building process. Called after pwiz_askmenu_reset and all appropriate pwiz_askmenu_add.
id: identification of askmenu item from pwiz_askmenu_add (can be empty string, usused)
index: current index in following arrays: ${pwiz_askmenu_callbacks[@]}, ${pwiz_askmenu_ids[@]}, ${pwiz_askmenu_strings[@]}, ${pwiz_askmenu_hotkeys[@]}, ${pwiz_askmenu_numbers[@]}, ${pwiz_askmenu_preselection_callbacks[@]}
answer: user's answer
returns: 0: it is item selected by user, 1: it is not item selected by user
Default {preselection_callback} function. If user answers proper number or hotkey or answer is default and string is empty, answer is accepted.
id: identification of askmenu item from pwiz_askmenu_add (can be empty string)
index: current index in following arrays: ${pwiz_askmenu_callbacks[@]}, ${pwiz_askmenu_ids[@]}, ${pwiz_askmenu_strings[@]}, ${pwiz_askmenu_hotkeys[@]}, ${pwiz_askmenu_numbers[@]}, ${pwiz_askmenu_preselection_callbacks[@]} (unused)
answer: user's answer
id: identification of askmenu item from pwiz_askmenu_add (can be empty string, usused)
uses $pwiz_preselection_callback_cnumber_maxval: maximal number, which is acccepted plus 1 (-1=no limit)
returns: 0: it is item selected by user, 1: it is not item selected by user
This {preselection_callback} allows to use hotkeys in form {{character}{number}}. function. If user answers proper number, answer is accepted. Number must be non-negative integer. Answer cannot be default (default does not contain number).
index: current index in following arrays: ${pwiz_askmenu_callbacks[@]}, ${pwiz_askmenu_ids[@]}, ${pwiz_askmenu_strings[@]}, ${pwiz_askmenu_hotkeys[@]}, ${pwiz_askmenu_numbers[@]}, ${pwiz_askmenu_preselection_callbacks[@]}
answer: user's answer
returns: 0: it is item selected by user
Fallback {preselection_callback}, which accepts all answers. Useful only for tail menu element.
answer: answer from backend
returns: 0: OK, 1: menu should be displayed again, 2: unknown selection
After returning from backend, pwiz_askmenu_process is started to process selected value.
desc: short description of feature
longdesc: long description of feature
tags: optional tags
Functions for asking user. These function are intended for module programmers.
NOTE: During parsing of arguments of pwiz_ask_{function}, globbing is temporarilly turned off. It prevents accidental expansion of "tag[number]=*", especially in nullglob mode.
desc: short description of feature
longdesc: long description of feature
tags: optional tags
returns: 0: yes, 1: no
Functions boolean question. This function is intended for module programmers.
NOTE: During parsing of arguments of pwiz_ask_yesno, globbing is temporarilly turned off. It prevents accidental expansion of "tag[number]=*", especially in nullglob mode.
desc: short description of feature
longdesc: long description of feature
tags: optional tags
uses tag callback: callback function for "enter manually" (returns $pwiz_answer) (default string)
uses tag allow_new: if set to false, "enter manually" is disabled (default true)
uses tag askmenu_hook: hook function for adding items to askmenu (default is nop)
uses tag no_default: no preselected default - user have to respond (default false)
String prompt. This function is intended for module programmers. With tag allow_new=false, it can be used as radio switch.
NOTE: During parsing of arguments of pwiz_ask_string, globbing is temporarilly turned off. It prevents accidental expansion of "tag[number]=*", especially in nullglob mode.
question_function: function from question engine
desc: short description of feature
longdesc: long description of feature
tags: optional tags
returns $pwiz_answer: question result
returns ${q tag}: answer is also stored to environment variable named as q tag
uses tag q: question ID
uses tag importance: answer importance (i. e. whether can pwiz continue with default)
uses tag default[@]: predefined defaults
uses tag c[@]: credits of predefined defaults (optional - array can be sparse)
uses tag string[@]: string value for predefined defaults (optional - array can be sparse)
uses tag hotkey[@]: guess hotkey for predefined defaults (optional - array can be sparse)
uses tag valid: validity range (see pwiz_cache_validity_{name}) (default=exact)
uses tag yesno: tag for boolean questions (default false)
uses tag callback: callback function for "enter manually" (returns $pwiz_answer) (default string)
uses tag allow_new: if set to false, "enter manually" is disabled (default true)
uses tag force_overwrite: if set to true, old answer will be overwritten by new one without any prompt (defult false)
uses tag askmenu_hook: hook function for adding items to askmenu (default is nop)
uses tag no_default: no preselected default - user have to respond (default false)
uses tags knowledge: knowledge type required for answer (default general)
uses tag guesslevel: guess level of user's answer (default ask user)
Internal core function for making a guess and asking user. Used by pwiz_ask_{function}. Uses pwiz_guess.
id: identification of askmenu item from pwiz_askmenu_add (${pwiz_guesses[@]})
answer: user's answer (unused)
returns: 0
Call question function for enter manually (internal function for pwiz_ask_core).
id: identification of askmenu item from pwiz_askmenu_add (unused)
answer: user's answer (unused)
returns $pwiz_answer: user's answer
returns: 0
Call question function for enter manually (internal function for pwiz_ask_core).
id: identification of askmenu item from pwiz_askmenu_add
answer: user's answer
returns $pwiz_answer: user's answer
returns: 0: OK, 1: Uses selected numbered item not corresponding to guess.
Call question function for enter manually (internal function for pwiz_ask_core).
incr: patchlevel increment
Set patchlevel. Reads patchlevel from cache and sets it. Must be called (done by package module). Can optionally increment patchlevel.
name: name of knowledge type
desc: short description knowledge type
longdesc: long description of knowledge type
Knowledge features description. This function is used to add new type of knowledge. It can be later used in tag knowledge. The same feature can be defined more times.
knowledge_tag: knowledge tag
returns $pwiz_answer: knowledge value
Internal function to get knowledge credibility for specific knowledge type. If required, asks user for response. Special value knowledge=total prevents asking user and consider answer as fully credible, knowledge=none prevents asking user and consider answer as fully incredible.
returns $pwiz_answer: guess level value
Internal function to get guess level for just answered question. If required, asks user for response.
desc: short description of feature
longdesc: long description of feature
tags: optional tags
uses tag q: question ID
uses tag importance: answer importance (i. e. whether can pwiz continue with default)
uses tag default[@]: predefined defaults
uses tag c[@]: credits of predefined defaults (optional - array can be sparse)
returns ${pwiz_list_all[@]}: string with list of available items (used by backend (in form ${q}_${list_item})
returns ${pwiz_list_c_{tag q}[@]}: credits of selectable items in variables (optional - array can be sparse)
returns ${pwiz_list_string_{tag q}[@]}: strings value of selectable items in variables (optional - array can be sparse)
returns ${pwiz_list_c_{tag q}[@]}: guess hotkey of selectable items in variables (optional - array can be sparse)
returns $pwiz_answer: question result
uses ${pwiz_list_item_{tag q}[@]}: predefined selectable items in variables
uses ${pwiz_list_item_c_{tag q}[@]}: credits of selectable items in variables (optional - array can be sparse)
uses ${pwiz_list_item_string_{tag q}[@}]: string value for selectable items in variables (optional - array can be sparse)
uses ${pwiz_list_item_hotkey_{tag q}[@]}: guess hotkey for selectable items in variables (optional - array can be sparse)
uses tag item[@]: available selectable items
Function for asking user for unordered selection from list. This function is intended for module programmers.
For more available variables and tags see pwiz_ask_core.
NOTE: During parsing of arguments of pwiz_ask_list, globbing is temporarilly turned off. It prevents accidental expansion of "tag[number]=*", especially in nullglob mode.
NOTE: defaults different from best guess are ignored. There can be only one default preset is available.
item: list item
credit: credit of guess (can be empty string)
string: string value for guess (can be empty string)
hotkey: guess hotkey (can be empty string)
This internal function evaluates list item and optionally adds it to list item array. Used by pwiz_ask_list.
id: list question ID (corresponds to tag q)
credit: credit of item (can be empty string)
string: string value for item (can be empty string)
hotkey: item hotkey (can be empty string)
Add predefined list item to environment variables ${pwiz_list_item_{q}}, ${pwiz_list_item_c_{q}}, ${pwiz_list_item_p_{q}}, ${pwiz_list_item_string_{q}} and ${pwiz_list_item_string_{q}}. Later pwiz_ask_list can take it in account and offer it to user.
NOTE: Credit is considered as absolute. No user credibility is evaluated.
tags: optional tags
returns $pwiz_answer: result of question
Callback function, which is called, if tag callback is set.
phase_id: id of new phase
{ "after" | "before" } existing_phase: position of phase
"ok": return ok, if phase already exists
Adds new phase to phase engine. You have to specify, after or before which phase to add new one. If phase already exists, PWIZ aborts, unless 4th arguments is "ok".
returns: lists all existing phases (FIXME will change to $pwiz_result in future versions)
List of all existing phases.
phase: existing phase
action: contents of action to be added, optionaly containing undo hooks
uses tag nominal: if your action includes reversibility hooks to your stage contents, you probably don't want to see them in final package. Use nominal to record action differently for package (should have the same function as contents, but without undo hooks)
uses tag fast_revert: unsafe, but fast undo action
uses tag revert: potentionally unsafe but generally reasonable undo action (implies fast_revert, if not specified)
uses tag safe_revert: Safe undo action (implies fast_revert and revert, if not specified)
Adds an action as a last action of a phase. Specify undoability in tags.
NOTE: It is recommended to add revert tags. Missing revert tags increases cost of undo.
NOTE: If your command needs quotes and special characters, you have to escape them to prevent double bash expansion.
phase: existing phase
arg: argument to function
Add call to function module_phase with arguments arg to phase to be used in module initialization.
It is the simplification of:
pwiz_phase_add {phase} "{module}_{phase} {arg}"
NOTE: If your arguments needs quotes and special characters, you have to escape them to prevent double bash expansion.
WARNING: This function cannot be called outside module init.
condition: variable name, where condition is stored (i. e. without leading $)
phase: existing phase
arg: argument to function
Add call to function module_phase with arguments arg to phase to be used in module initialization, but execute it only if condition variable in time of execution is true.
It is the simplification of:
pwiz_phase_add {phase} "if ${condition} ; then {module}_{phase} {arg} ; fi"
NOTE: If your arguments needs quotes and special characters, you have to escape them to prevent double bash expansion.
WARNING: This function cannot be called outside module init.
phase_id: id of new phase
{ "after" | "before" } existing_phase: position of phase
arg: argument to function
Create new phase and add a call to function module_phase with arguments arg to this phase. This function can be used in module initialization.
It is the simplification of:
pwiz_phase_new {phase} {after|before} {existing_phase} pwiz_phase_add {phase} "{module}_{phase} {arg}"
NOTE: If your arguments needs quotes and special characters, you have to escape them to prevent double bash expansion.
WARNING: This function cannot be called outside module init.
phase_id: id of new phase
{ "after" | "before" } existing_phase: position of phase
arg: argument to function
Create all needed for three phase structure: set data ({phase}_prepare), allow user to modify ({phase}) and use data ({phase}_set). This structure is widely used by PWIZ to allow modification of any decission by third party modules. It also defines function {phase}_provider, which can be used in third party modules (it's equivalent to pwiz_phase_add_callme {phase} - without {arg})
It is the simplification of:
pwiz_phase_new {phase}_prepare {after|before} {existing_phase} pwiz_phase_new {phase} after {phase}_prepare pwiz_phase_new {phase}_set after {phase} pwiz_phase_add {phase}_prepare "{module}_{phase}_prepare {arg}" pwiz_phase_add {phase}_set "{module}_{phase}_set {arg}" function {phase}_provider { pwiz_phase_add_callme_cond {phase}_condition {phase} }
{phase}_condition is set to true by default.
NOTE: If your arguments needs quotes and special characters, you have to escape them to prevent double bash expansion.
WARNING: Optional argument {arg} is not used in {phase}_provider.
WARNING: This function cannot be called outside module init.
Function created by pwiz_phase_new_3.
It's equivalent of:
pwiz_phase_add_callme {module}
WARNING: This function cannot be called outside module init.
phase_id: id of new phase
{ "after" | "before" } existing_phase: position of phase
arg: argument to function
Create all needed for three phase structure (it does everything, what pwiz_phase_new_3 does) and create function {phase}_guess to register new guess for question with q={phase} (see {phase}_guess).
It is the simplification of:
pwiz_phase_new_3 {phase} {after|before} {existing_phase} {arg} function $1_guess { pwiz_guess_add {phase} "$@" }
NOTE: If your arguments needs quotes and special characters, you have to escape them to prevent double bash expansion.
WARNING: This function cannot be called outside module init.
guess: value of guess
credit: credit of guess (can be empty string)
string: string value for guess (can be empty string)
hotkey: guess hotkey (can be empty string)
Guess function, as created by pwiz_phase_new_3 (see pwiz_guess_add for more).
phase: existing phase
contents: contents of action to be added for execution
Adds protected run command (see also pwiz_phase_add).
Equivalent of:
pwiz_phase_add phase "pwiz_run contents"
NOTE: Commands beginning by "pwiz_run" are evaluated in phase engine in a special way preventing double expansion.
phase: existing phase
contents: contents of action to be inserted
Adds a comment to protected command list (see also pwiz_phase_add).
Equivalent of:
pwiz_phase_add phase "pwiz_rem contents"
NOTE: Commands beginning by "pwiz_rem" are evaluated in phase engine in a special way preventing line splittion. You can add multiple lines using single command using pwiz_phase_add_rem.
returns: 0: OK, 1: no next stage
Go to next stage.
returns: 0: OK, 1: no previous stage
Go to previous stage.
stage: stage number
returns: 0: OK, 1: no such stage
Goto any stage.
returns: 0: OK, 1: no next phase
Go to next phase.
returns: 0: OK, 1: no previous phase
Go to previous phase.
WARNING: sets stage counter to first stage of phase, not last!
WARNING: If previous phase is empty, it skips back to current. It is not reverse function to pwiz_phase_next.
phase: phase name
returns: 0: OK, 1: no such phase
Goto any phase.
WARNING: sets stage counter to first stage, not last!
WARNING: If phase is empty, it skips forward.
returns: 0: OK, 1: no next stage and phase
Goto next action in phase engine. Error means, that END was reached.
"query": query action in next argument, not execute
returns $pwiz_result: in query mode, stage action is returned in this variable
"run": standard action, optionaly containing undo hooks
"nominal": if your action includes reversibility hooks to your stage contents, you probably don't want to see them in final package. Use nominal to record action differently for package (should have the same function as contents, but without undo hooks)
"fast_revert": unsafe, but fast undo action
"revert": potentionally unsafe but generally reasonable undo action (implies fast_revert, if not specified)
"safe_revert": Safe undo action (implies fast_revert and revert, if not specified)
returns $pwiz_rc: in run mode, it contains result code of command (if any)
returns: 0: phase and stage exists and executed, 1: no next stage and phase
Standard step of phase engine.
NOTE: pwiz_step first increments counters, then executes, to enable roll-ons (commands adding action immediatelly after current stage).
WARNING: Return code is not return code of executed stage!
returns: 0: phase and stage exists and executed, 1: no next stage and phase
Standard step of phase engine.
Reset phase engine (go to phase BEGIN, stage 0). Needed for switching between query and run mode (see pwiz_step).
Save phase engine status. Needed for switching between query and run mode (see pwiz_step).
Restore phase engine status. Needed for switching between query and run mode (see pwiz_step).
command: Command for module.
Run module with command.
Available commands:
desc: show description and return
longdesc: show long description and return
init: initialize engine (during initialization, variable $pwiz_module_current is available)
version: show module version
This variable is defined during module initialization (see {module_name}.pwm).
returns: list of engines to stdout (FIXME will change to $pwiz_result in future versions)
List all available modules.
Load all available modules (internal function).
module: name of module
Prints module description.
module: name of module
Prints module long description.
module: name of module
Load a module. In normal conditions, there is no need to call this functions explicitly, use pwiz_module_needs instead). It has a protection against multiple loading.
module: name of module
Immediatelly load a module. Internal function, used by pwiz_module_load).
module: module to be loaded
Loads needed modules. Used by module init.
NOTE: You need it only for modules required for module init, otherwise pwiz_module_uses is enough.
module: used module
Checks, whether needed modules are available. Modules itself can be loaded later.
WARNING: Do not use this function for modules needed during initialization.
Phase skeleton is a set of phases available unconditionally in all PWIZ instances. There is a list with explanation of expected usage.
basic phase descriptions:
BEGIN
> special general actions
START
> general actions only, $pwiz_project_* attributes are not defined
PROJECT
> project and version selection process, here you can set $pwiz_project_*
SETUP
> set up pwiz for work with known project, access where appropriate ($PWIZ_TMPSDIR)
SOURCE
> get sources, set extended project attributes, $pwiz_project_* are set, access to $PWIZ_SOURCESDIR
PREPARE
> prepare source code (unpack, patch), access to $PWIZ_SRCDIR
subphases: PREPARE_CLEAN PREPARE_PREUNPACK PREPARE_UNPACK PREPARE_POSTUNPACK PREPARE_CHECK PREPARE_PATCH PREPARE_RECHECK
BUILD
> build project (configure, compile), access to $PWIZ_BUILDDIR
subphases: BUILD_SETENV BUILD_CONF BUILD_POSTCONFHACK BUILD_PRECOMPILE BUILD_COMPILE BUILD_POSTCOMPILE
PREINSTALL
> special actions before installation to install root, keep empty if possible
WARNING: use premerge for standard pre-installation processes
INSTALL
> install project, access to $PWIZ_INSTALLROOT
subphases: INSTALL_PREPARE INSTALL_PREACTION INSTALL_ACTION INSTALL_POSTACTION INSTALL_CHECK INSTALL_POSTCHECK
CHECKINSTALL
> Check all installed things. Read access.
PREMERGE
> actions before install, access to live system only special actions
MERGE
> merge project for live system, access to live system
CLEAN
> clean project buld environment, access to all temporary dirs
POSTINSTALL
> post installation actions, access to live system
RUNTEST
> tests for instaled package, access to live system
PREUNINSTALL
> special actions before package uninstallation
UNMERGE
> perform uninstallation, access to live system
POSTUNINSTALL
> special actions after package uninstallation, access to live system
RESULTS
> very last actions, access to $PWIZ_RESULTDIR
FINISH
> very last actions, access nowhere
END
Each phase has counterpair {phase}_LAST for simple and portable adding to the end of actions.
NOTE: Recommendation for custom phases: Use lowecase. Take these ones as "constants".
NOTE: If your action surely does not need any action before it in the same range, you can use listed phases, otherwise create own phase.
WARNING: For listed major phases, avoid if possible: pwiz_phase_add before PHASE
WARNING: For listed major phases, avoid if possible: pwiz_phase_add after PHASE_LAST
Creates phases in skeleton (internal function).