The Autopackage API

Miscellaneous functions

Functions in this category

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

Details

chewArgument
Syntax: chewArgument
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)


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.
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
Pops the stack for the shell option e. See pushOptE for more details ## START POPOPTE ## Function is substituted from apkg-bashlib.


pushOptE
Syntax: pushOptE
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
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
Terminates the frontend.


uninstallFromLog
Syntax: uninstallFromLog
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


assertNotReached
Syntax: assertNotReached
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


suppressNextErr
Syntax: suppressNextErr
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.
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.


warn
Syntax: warn <MESSAGE>
MESSAGE: The message you wish to be printed to stdout and logged to file.
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.


err
Syntax: err <MESSAGE>
MESSAGE: The message you wish to be printed to the terminal and logged to file.
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.
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.