PWIZ Core

PWIZ core contains functions for core functionality. No guesses and knowledges are here, only engine skeleton, initialization and main loop.

Debugging

eecho string

string: string to be echoed

Alias for echo to stderr.

vecho string

string: string to be echoed

Alias for verbose echo. Echo only in verbose mode.

vvecho string

string: string to be echoed

Alias for more verbose echo. Echo only in more verbose mode.

vvvecho string

string: string to be echoed

Alias for very verbose echo. Echo only in very verbose mode.

pwiz_debug_feature name desc longdesc

name: Feature name.

desc: short description of feature

longdesc: long description of feature

Define debug features (class of debug messages for --enable-debug).

Fast redirection

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.

pwiz_redirect_stdin file

file: File from which redirect.

Redirect standard input from file. Close by pwiz_redirect_stdin_close.

pwiz_redirect_stdout file

file: File to which redirect.

Redirect standard output to file. Close by pwiz_redirect_stdout_close.

pwiz_redirect_stderr file

file: File to which redirect stderr. Close by pwiz_redirect_stderr_close.

Redirect error output to file.

pwiz_redirect_stdout_append file

file: File to which redirect.

Appending redirect standard output to file with. Close by pwiz_redirect_stdout_close.

pwiz_redirect_stderr_append file

file: File to which redirect stderr.

Appending redirect error output to file with. Close by pwiz_redirect_stderr_close.

pwiz_redirect_stdin_close

Revert redirection created by by pwiz_redirect_stdin and close file.

pwiz_redirect_stdout_close

Revert redirection created by by pwiz_redirect_stdout and close file.

pwiz_redirect_stdout_suspend

Revert redirection created by by pwiz_redirect_stdout, but don't close file.

pwiz_redirect_stdout_restore

Restore redirection created by by pwiz_redirect_stdout and suspended by pwiz_redirect_stdout_suspend.

pwiz_redirect_stderr_close

Revert redirection created by by pwiz_redirect_stderr and close file.

General helpers

pwiz_set_rc return_code

returns: return_code

Helper, which only sets return code.

pwiz_canonize filename

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.

File searching

pwiz_find path [ path_prefix ] [ callback_argument_2 ]

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).

pwiz_find path [ path_prefix ] [ callback_argument_3 ]

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).

pwiz_projectdirs_init

initialize work directories for project.

Call it every time you change $pwiz_project_* variables

Work directories for project.

If not stated anything else, separate directory is created for each project. Can be redefined by callback from packaging engine (see lower).

$PWIZ_CACHEDIR

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.

$PWIZ_TMPDIR

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.

$PWIZ_SOURCESDIR

Temporary directory for PWIZ source codes.

WARNING: Do not write here from pwiz_run.

$PWIZ_SRCDIR

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.

$PWIZ_BUILDDIR

Temporary directory for PWIZ build.

WARNING: Do not use this before PREPARE stage.

WARNING: Do not write here from outside pwiz_run.

$PWIZ_INSTALLROOT

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.

$PWIZ_RESULTDIR

Directory for PWIZ results.

pwiz_projectdirs_init_callback path

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.

pwiz_array_add array_name item

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.

Order of pwiz_run execution

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.

pwiz_run_wrapper_register function

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

pwiz_run_wrap [ arguments ... ]

Call next registered wrapper. Functions is used inside run wrapper function.

pwiz_run_core [ arguments ... ]

Immediatelly calls its arguments.

This function can be redefined by packaging engine to to something else.

pwiz_run_prepare [ arguments ... ]

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 "$@"
}

pwiz_run [ arguments ... ]

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!

pwiz_rem string

string: arbitrary string

Remark function. Action will appear in stage list, but is not executed.

Primarily intended for exporting comments to final build script.

pwiz_fatal string rc

string: string to be echoed

rc: return code

Abort PWIZ after fatal error.

pwiz_add_exit function

function: function to be executed on exit

Register function to be executed on PWIZ exit.

pwiz_exit rc

rc: PWIZ return code

Exit PWIZ.

Tags

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.

pwiz_read_tags

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
    ...
}

pwiz_read_vtags

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.

pwiz_reset_tags

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_*!

pwiz_reset_vtags

Alias for unsetting all vtag variables. Prevent inheritance of tags to next function call.

WARNING: This function reset all variables named pwiz_vtag_*!

pwiz_register_tag_default pwiz_tag_tag=value

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.

pwiz_default_tags

After calling pwiz_reset_tags, no tags are defined. To define default values, use this function.

$not_implemented

PWIZ error code for not implemented functions (6).

Engine description

Engine is a piece of bash code, sourced from PWIZ core. It typically implements an independent interface for communication with outer world.

{engine_class}/{engine_name}.pwe [ command ]

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

pwiz_engine_{engine_class}_{engine_name}_{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)

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 ].

pwiz_engine_desc engine_class engine_name

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.

pwiz_engine_longdesc engine_class engine_name

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.

pwiz_engine_load engine_class engine_name

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.

pwiz_engine_load engine_class engine_name

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.

pwiz_engine_list engine_class

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.

pwiz_engine_interface engine_class function1 [ function2 ... ]

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

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.

pwiz_cache_read key

key: key for data you want to read from cache

Read data associated with key from cache.

pwiz_cache_read_tags key

key: key for data you want to read from cache

Read tags associated with key from cache.

pwiz_cache_write key value [ tags ]

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).

pwiz_cache_delete key

key: key for data you delete from cache

Delete data and tags from cache (unassociate data and tags with key).

pwiz_cache_list pattern

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*/".

Cache interface

pwiz_cache_save value [ tags ... ]

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.

pwiz_cache_remove value [ tags ... ]

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.

pwiz_cache_load value [ tags ... ]

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.

Pkgdb engine

This engine provides interface with package database on destination system.

pwiz_pkgdb_what_owns file [ ... ]

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

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.

pwiz_question_string desc longdesc [ tags ... ]

returns $pwiz_answer: user's answer

returns $pwiz_fallback_answer: user selected default answer (default false)

uses tag yesno: tag for boolean questions (default false)

uses tag allow_new: if set to false, "enter manually" is disabled (default true)

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)

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.

pwiz_question_list desc longdesc [ tags ... ]

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 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

Cache keys are used for addressing entries in cache.

$pwiz_key_list

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.

project

Name of project (package).

subproject

Name of subproject. Normally unused ("-"), but can contain subpackage or partial project name.

version

Version of source codes.

patchlevel

Patch level. Additional resolution above source version.

vendor

Vendor+product string. Needed to discriminate between different packaging solutions for different vendors and products.

build

Build number. Needed to discriminate exact environment used for build (other package was updated, change in package is needed).

pwiz_keys_set

Alias for cloning global variables $pwiz_project_{key} to local variables ${key}. It is used by functions, which need to alter these values internally.

Cache validities

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.

pwiz_cache_validity_{name}

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}.

pwiz_cache_validity_apply

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.

pwiz_cache_validity_exact

Exact match in query is required. Use "valid=exact" in question to use this validity range (this is the default).

pwiz_cache_validity_source

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.

pwiz_cache_validity_setup

Value for PWIZ setup. No keys are valid. Used for PWIZ preferences. Use "valid=setup" in question to use this validity range.

pwiz_cache_validity_project

Per-project information, independent on vendor. Only key project is valid. Use "valid=project" in question to use this validity range.

pwiz_cache_validity_projectstate

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.

pwiz_cache_validity_vendor

Vendor's policy, independent on project (package). Only key vendor is valid. Use "valid=vendor" in question to use this validity range.

pwiz_cache_validity_product

Vendor's policy for project (package). Valid keys are project and vendor. Use "valid=product" in question to use this validity range.

Inherited credibility

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.

pwiz_guess_credit_{key}

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.

$pwiz_credit

Return value for inherited credibility value.

pwiz_guess_credit_version

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.

pwiz_guess [ tags ]

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_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.

pwiz_guess_eval guess credit string hotkey

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.

pwiz_guess_add id guess credit string hotkey

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.

pwiz_key_parse key

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.

Asking user

pwiz_ask_{function} desc longdesc [ tags ]

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.

pwiz_ask_yesno desc longdesc [ tags ]

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.

pwiz_ask_string desc longdesc [ tags ]

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 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.

pwiz_ask_core question_function desc longdesc [ tags ]

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 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.

pwiz_patchlevel_set [ incr ]

incr: patchlevel increment

Set patchlevel. Reads patchlevel from cache and sets it. Must be called (done by package module). Can optionally increment patchlevel.

pwiz_knowledge_feature name desc longdesc

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.

pwiz_get_knowledge knowledge_tag

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.

pwiz_get_guesslevel

returns $pwiz_answer: guess level value

Internal function to get guess level for just answered question. If required, asks user for response.

Asking for selection from list

pwiz_ask_list question_function desc longdesc [ tags ]

question_function: function from question engine

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.

pwiz_list_eval item credit string hotkey

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.

pwiz_list_add id item credit string hotkey

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.

{callback} [ tags ]

tags: optional tags

returns $pwiz_answer: result of question

Callback function, which is called, if tag callback is set.

pwiz_phase_new phase_id { "after" | "before" } existing_phase [ "ok" ]

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".

pwiz_phase_list

returns: lists all existing phases (FIXME will change to $pwiz_result in future versions)

List of all existing phases.

pwiz_phase_add phase contents

phase: existing phase

contents: contents of action to be added

Adds an action as a last action of a phase.

NOTE: If your command needs quotes and special characters, you have to escape them to prevent double bash expansion.

pwiz_phase_add_callme phase [ arg ]

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.

pwiz_phase_new_call phase_id { "after" | "before" } existing_phase [ arg ]

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.

pwiz_phase_new_3 phase_id { "after" | "before" } existing_phase [ arg ]

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 {phase}
}

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.

{phase}_provider

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.

pwiz_phase_new_3_guess phase_id { "after" | "before" } existing_phase [ arg ]

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.

{phase}_guess guess credit string hotkey

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).

pwiz_phase_add_run phase contents

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.

pwiz_phase_add_rem phase contents

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.

pwiz_stage_next

returns: 0: OK, 1: no next stage

Go to next stage.

pwiz_stage_prev

returns: 0: OK, 1: no previous stage

Go to previous stage.

pwiz_stage_goto stage

stage: stage number

returns: 0: OK, 1: no such stage

Goto any stage.

pwiz_phase_next

returns: 0: OK, 1: no next phase

Go to next phase.

pwiz_phase_prev

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.

pwiz_phase_goto phase

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.

pwiz_next

returns: 0: OK, 1: no next stage and phase

Goto next action in phase engine. Error means, that END was reached.

pwiz_step action { "query" | "run" }

returns: 0: phase and stage exists and executed, 1: no next stage and phase

"query": query action, not execute

returns $pwiz_result: in query mode, stage action is returned in this variable

"run": execute action

returns $pwiz_rc: in run mode, it contains result code of command (if any)

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!

pwiz_phase_reset

Reset phase engine (go to phase BEGIN, stage 0). Needed for switching between query and run mode (see pwiz_step).

pwiz_phase_save

Save phase engine status. Needed for switching between query and run mode (see pwiz_step).

pwiz_phase_restore

Restore phase engine status. Needed for switching between query and run mode (see pwiz_step).

{module_name}.pwm [ command ]

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

$pwiz_module_current

This variable is defined during module initialization (see {module_name}.pwm).

pwiz_modules_list

returns: list of engines to stdout (FIXME will change to $pwiz_result in future versions)


List all available modules.

pwiz_modules_load

Load all available modules (internal function).

pwiz_module_desc module

module: name of module

Prints module description.

pwiz_module_longdesc module

module: name of module

Prints module long description.

pwiz_module_load module

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.

pwiz_module_source module

module: name of module

Immediatelly load a module. Internal function, used by pwiz_module_load).

pwiz_module_needs module ...

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.

pwiz_module_uses module ...

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

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

init_phase_skeleton

Creates phases in skeleton (internal function).