The Autopackage API

Miscellaneous functions

Functions in this category

Name Parameters
assertNotReached
chewArgument
clearResults
err <MESSAGE>
fixme <MESSAGE>
launchInTerminal [--title TITLE] <COMMAND> [ARGUMENTS]
popOptE
pushOptE
registerRepository <ROOTNAME> <URL>
terminateFE
uninstallFromLog
suppressNextErr
trace <MESSAGE>
waitForHELLO <NAME>
warn <MESSAGE>

Details

assertNotReached
Syntax: assertNotReached
Since: 1.0
Deprecated: N/A

This function prints an error message, and terminates the current shell. It should be used when you know that a section of code should never be reached, and if it is then something went badly wrong.

If the $ASSERTION_TOPLEVEL_SHELL_PID environment variable is defined, it will do a kill on that pid after printing the error. Otherwise, it calls exit 1


chewArgument
Syntax: chewArgument
Since: 1.0
Deprecated: N/A

process an argument value of the form --key=value, --key value, -k value and spits out the value on stdout

Example:
chewArgument --prefix=/usr/local  # => /usr/local
chewArgument --key value          # => value
chewArgument "--three four"       # => four (you can quote the input ok)

clearResults
Syntax: clearResults
Since: 1.0
Deprecated: N/A

You should call this after copying whatever information you need into local variables from functions that use the $result calling convention. Most functions in autopackage output their results to stdout, which allows for clear code:

foo=$( someFunc $1 $2 )

Unfortunately this calling convention has a downside: it's slow, and it's limiting - you can only return one piece of data.

To deal with this, new functions may return data by setting global variables starting with the prefix "result_": for instance, $result_whatever may contain information after calling whateverFunc.

Once you no longer need any information returned, call this function to delete the variables from the global namespace. It should be called either after you use the function, or before returning from whatever code is executing.

Since 1.2

Example:
foobarFunc "boing" "bonk"
echo $result_whizz
local wonk="$result_bonk"
clearResults
# $result_whizz and $result_bonk are no longer valid

err
Syntax: err <MESSAGE>
MESSAGE: The message you wish to be printed to the terminal and logged to file.
Since: 1.0
Deprecated: N/A

err will print out the current function and the given message in red. It is part of the logging framework and will always give output to stdout.


fixme
Syntax: fixme <MESSAGE>
MESSAGE: The message you wish to be printed to the terminal and logged to file.
Since: 1.0
Deprecated: N/A

This function is used by the autopackage developers to remind us of things we need to fix. It is part of the logging framework and will only give stdout when DEBUGLEVEL is >= 2.


launchInTerminal
Syntax: launchInTerminal [--title TITLE] <COMMAND> [ARGUMENTS]
ARGUMENTS: Arguments to pass to COMMAND.
COMMAND: A command.
--title: A title for the terminal.
Returns: 0 on success, 1 on failure.
Since: 1.0
Deprecated: N/A

Launch COMMAND in an X terminal emulator, selected according to currently running desktop environment. Known terminal emulators include Konsole, gnome-terminal (both v1 and v2), and xterm.


popOptE
Syntax: popOptE
Since: 1.0
Deprecated: N/A

Pops the stack for the shell option e. See pushOptE for more details ## START POPOPTE ## Function is substituted from apkg-bashlib.


pushOptE
Syntax: pushOptE
Since: 1.0
Deprecated: N/A

Pushes the shell option e onto a stack. The e option controls whether a script should exist on the first line that fails. If you write a function that might be called from a script with option set, and you don't want this to affect the functions operation, you can push the option using this function, then run `set +e` to clear the flag. When leaving the function, popping the stack returns the option to the state it was in before.

Example:
function foo() {
  pushOptE; set +e;
  (perform some code that may return a non-zero exit code)
  popOptE
}
## START PUSHOPTE
## Function is substituted from apkg-bashlib.

registerRepository
Syntax: registerRepository <ROOTNAME> <URL>
URL: the absolute URL of the XML repository description. In autopackage 1.0, this must be an HTTP URL
ROOTNAME: the unversioned root name of the package you wish to registry a repository for
Since: 1.0
Deprecated: N/A

Each package (identified by an unversioned root name) has a list of remote repositories that should be attempted in order, in the case that the package is not present and must be retrieved from the network.

A repository registration is scoped local to this autopackage session, ie once the install/removal/upgrade has finished, the registrations are lost.

When a package must be retrieved from the network, each repository in the list is tried in order from first registered to last registered. The first that provides a successful match is used.

If a skeleton includes a "Repository" key in its meta section, then this URL will registered just before the Retrieval section is run, so you will usually not need to use this function. It's useful when for whatever reason you feel compelled to break the Golden Rule and have packaged the dependencies of your package yourself. Placing the URL to your collection in the skeleton file would be the wrong approach as the skeleton is supposed to be independent of any one persons particular packaging. Instead, you should register the dependencies in your packages prepare script so your repository will be tried first.

Example:
registerRepository @foo.org/bar http://myproject.sourceforge.net/myproject-packages.xml
registerRepository @fee.org/fifofum http://myproject.sourceforge.net/myproject-packages.xml

terminateFE
Syntax: terminateFE
Since: 1.0
Deprecated: N/A

Terminates the frontend.


uninstallFromLog
Syntax: uninstallFromLog
Since: 1.0
Deprecated: N/A

Process the uninstall log that was generated by the autopackage file installation functions. The contents of the log must be in the $log variable.

Example:
# This is part of an autopackage specfile
[Install]
copyFiles share/* "$PREFIX/share"
installLib lib/*

[Uninstall]
uninstallFromLog

suppressNextErr
Syntax: suppressNextErr
Since: 1.0
Deprecated: N/A

Increments a suppression count. For each time you call this function, an err() log message will be suppressed. For instance, if you call it twice, the next two calls to err() will be ignored. Use it in unit tests where you know a given situation will give a certain number of errors and don't want them to appear.


trace
Syntax: trace <MESSAGE>
MESSAGE: The message you wish to be printed to stdout and logged to file.
Since: 1.0
Deprecated: N/A

trace will print out the current function and the given message. It is part of the logging framework and will only give stdout when DEBUGLEVEL is >= 3.


waitForHELLO
Syntax: waitForHELLO <NAME>
NAME: The name of the package (just used to label the frontend with).
Since: 1.0
Deprecated: N/A

Establish communication with the frontend.


warn
Syntax: warn <MESSAGE>
MESSAGE: The message you wish to be printed to stdout and logged to file.
Since: 1.0
Deprecated: N/A

warn will print out the current function and the given message. It is part of the logging framework and will only give stdout when DEBUGLEVEL is >= 2.