Task Guide

List the shell commands. This task does not provide any further options or filters.

Lists configurations keys and values. For print mode ansi, some of the values are color-coded or printed in bold or italic, for example:

In table mode, a color coded status indicates from where a setting was taken.

The task offers a number of filters. They all relate to the original source from which a configuration value was set: command line, environment, configuration file, default value, or internally.

This task can take the list of items from the framework or application cache. If CACHE_DIR is set to a directory that contains cached command information (map), this information is used.

Lists dependencies with name and description. Table mode shows two more aspects of dependencies: the origin of its declaration (framework or application) and the load status (color coded).

Provided filters:

This task can take the list of items from the framework or application cache. If CACHE_DIR is set to a directory that contains cached dependency information (map), this information is used.

Lists exit status codes with their number and description. Table mode shows two more aspects: the origin (of an error: all, application, framework, loader, shell, tasks) and an indicator of the problem (internal for a bug, external for a configuration problem). Provided filters focus on the origin of the problem.

This task can take the list of items from the framework or application cache. If CACHE_DIR is set to a directory that contains cached exit status information (map), this information is used.

Lists command line options with name, short name, if required a parameter, and a description. Table mode also shows the type of option, being either an exit option or a runtime option. Provided filters focus on the option type.

This task can take the list of items from the framework or application cache. If CACHE_DIR is set to a directory that contains cached option information (map), this information is used.

Lists parameters with their name and description. Table mode shows three more aspects of parameters: the origin of its declaration (framework or application), an indicator for a defined default value (red cross for not defined, green ok for defined), and a color coded load status.

The task also provides a second table. This table shows the parameter names with their declared default value.

Provided filters are:

This task can take the list of items from the framework or application cache. If CACHE_DIR is set to a directory that contains cached parameter information (map), this information is used.

Lists scenarios with their name, short name, and a description. Table mode shows a few more aspects of scenarios:

Provided filters are:

This task can take the list of items from the framework or application cache. If CACHE_DIR is set to a directory that contains cached scenario information (map), this information is used.

Lists tasks with their name, short name, and a description. Table mode shows a few more aspects of tasks:

Provided filters are:

This task can take the list of items from the framework or application cache. If CACHE_DIR is set to a directory that contains cached task information (map), this information is used.

Describe application aspects from the manual. The provided filters focus on the different aspects. If filters are used, only aspects specified will be shown. If no filters are used, all aspects are shown.

The text is taken from the manual. This MANUAL_SRC must point to valid manual sources.

Describes one or more commands. The id filter can be used to show only a specific command. For the id, the long or the short form of the command can be used.

Describes one or more dependencies. Provided filters are:

Describes framework and application element types, e.g. task, parameter, and description. The text is the same as used in the manual as introduction to the elements. The provided filters focus on the different element types. If filters are used, only types specified will be shown. If no filters are used, all types are shown.

The text is taken from the manual. This MANUAL_SRC must point to valid manual sources.

Describes one or more exit status codes. The id filter can be used to show only a specific status code.

Describes one or more command line options. The id filter can be used to show only a specific option. For the id, the long or the short form of the option can be used. The other filters focus on the option type, being either exit options or runtime options.

Describes one or more parameters. The following filters are provided:

This task can also be used to show debug information, rather than descriptions. Using the debug option will print all information about one or more parameters (depending on the used filters).

Describes one or more scenarios. Provided filters are:

This task can also be used to show debug information, rather than descriptions. Using the debug option will print all information about one or more dependencies (depending on the used filters).

Describes one or more tasks. Provided filters are:

This task can also be used to show debug information, rather than descriptions. Using the debug option will print all information about one or more tasks (depending on the used filters).

The task does not have any special options.

Simply running the task will count the lines of code of an installation. The following is the output of running this task on the SKB-Framework in an earlier version.

The count shows the two ANT files (build file and macro file) as ANT and XML language files. All ADOC files are shown as AsciiDoc language files The HTML file is the framework’s HTML manual. The top line shows the lines of code for all bash scripts in the installation, including all tasks and .id files.

The task requires the tool cloc being installed. The dependency is called by the same name: cloc. If cloc is not installed, the task will print an error.

The following example executes ls in the current directory (where the application was started from).

The following example executes ls in the current directory (where the application was started from). It runs ls in the background, which causes an error since ls takes the added ampersand & as an argument.

The following example starts the editor vi with the file build.sh in a new XTerm.

To start a program in a new XTerm, the task start-xterm must be available. This task has its own configuration settings, e.g. to set the XTerm executable.

The task requires the manual being build in the application home directory. If a requested manual version is not found, an error will be thrown.

To show HTML and PDF versions, this task uses the tasks start-browser and start-pdf-viewer, respectively. Both tasks have their own configuration requirements, please see their documentation for details.

The option scenario should be used to identify the scenario to repeat. The scenario must be loaded. For this option, the long or short name of the scenario can be used.

The other options determine how often the scenario should be repeated (times) and how long the task should wait between repetisions (wait). Only positive integers are allowed for both options. The default value for both options is 1. So when only provided with a scenario, the task will run it once.

The example below will repeat the scenario S1 four times, waiting for 2 seconds between repetitions.

The example below will execute the task list-tasks with the arguments -T --no-a three times and wait for two seconds between repetitions.

The example below will do the exact same. It simply uses the long name of the task and the long form of its arguments

The actual command for starting a browser must be provided in BROWSER. If this parameter is not set, the task will print an error and exit. Examples for setting BROWSER are:

More information on the parameter BROWSER can be found in the framework manual.

The actual command for starting a PDF viewer must be provided in PDF_VIEWER. If this parameter is not set, the task will print an error and exit. Examples for setting PDF_VIEWER are:

More information on the parameter PDF_VIEWER can be found in the framework manual.

Start an XTerm, use the default title, and run ls | more as command.

The actual command for starting an XTerm must be provided in XTERM. If this parameter is not set, the task will print an error and exit. Examples for setting XTERM are:

More information on the parameter XTERM can be found in the framework manual.

Using filters will provide more detailed information. Any number of filters can be used in any sequence, the tasks will print the output always in the same order:

The following example requests statistics for the target overview --ov and tasks --task.

The actual output depends of course on the declared and processed tasks. An earlier version of the framework shows the following statistics.

By default, the task will validate all targets. If one or more targets are requested, only those targets will be validated.

The following conditions are validated:

The option seconds takes a positive integer as argument for the number of seconds to wait. The default, without this option, is 1.

The actual wait time depends on the underlying system. Since wait is a task, a new bash instance is created to execute it. This creation does take time, less on powerful UNIX hosts than for instance on Cygwin or a Raspberry PI. On native UNIX systems the creation time should not be significant. The actual wait time will be printed when the task finishes.

Since bash does not support floating point or double integer values, only positive integers can be used.

The example below will wait for 3 seconds, plus the time it takes to execute the wait task itself.

The task can be configured with two parameters:

The general text for the manual is located in the directory pointed to by the parameter MANUAL_SRC. This directory must have the following layout and contents:

Following the SKB-Framework convention, the task has two main options: clean to remove built manual artifacts and build to build them. When build is used, other general options and filters can be used to direct the build:

Targets can also be selected individually. The target options can be used in any sequence in the command line, the task will automatically generate all manual artifacts in the correct order. For the secondary targets that require adoc to be build, the task will also automatically generate adoc if the file does not exist. Text sources (target src) are not created automatically, only on request.

Some parts of the manual list application elements. For selected element types, the element list filters can be used to direct what these lists contain:

These filters are negative filters to exclude general (application related) parts of the manual. The option name corresponds to the heading in the general manual structure described above. The default behavior is to include all general parts.

These filters are negative filters to exclude element description or element lists. By default, all element descriptions and all element lists are included in the manual. To no show a list, use the no-*-list options. To now show any description for an element type, use the no-* options (without -list).

To give an example: to show all information about tasks do not use any of these filters. To show the general text, but no task list, use --no-task-list. To no show any information about tasks, use --no-tasks.

The following example will use the framework tool to convert adoc sources into well-formatted plain text.

The following examples builds the targets adoc, text, manp, html, and pdf. All tasks and scenarios will be listed. Only requested dependencies and parameters will be listed.

The task has the following requirements:

The task will automatically test of the required directories exist. If not, they need to be created manually, since the task does not create any directories:

A few standard framework tasks are also required (all of them are mandatory and included in a standard framework installation):

This task will change directories and files in the application (or framework) installation. Sufficient permissions must exist to run this task successfully.

The task can build a Maven site for several targets:

There is no default target.

Filters allow to specify which of the loaded (and available) sites should be built:

There is no default filter.

Further options exist to configure the runtime behavior of Maven:

The framework’s own site can be build using this task. When correctly configured, the site can be listed

This will show (with a real path instead of SOME_PATH)

The site can then be build using

The task and Maven output will be similar to:

Setting the task level to info will provide more information on the task’s progress.

As mentioned above, a site suitable for this task should provide a file with its metadata and might provide a file with scripts to be used in the build. Both files must be located in the same directory as the POM file.

The metadata file must be named skb-site.id. It must contain the following information:

The source block below shows the file for the frameworks' site.

The file skb-site-scripts.skb could be provided. If it does not exist, the task will build the site purely using Maven. If it does exist, the task will source the file and call two functions the file must provide. This means that the file can

The following code block shows the standard contents of the script file with the two required functions:

To see an example have a look at the framework’s script file. The current file can be found in the Github repository: skb-site-scripts.skb. Here, the function MvnSitePreScript executes framework tasks to create files for the site. The function MvnSitePostScript calls tools from the AsciiDoctor tool chain to create documents. It also uses the framework’s API function MvnSiteFixAdoc, which helps to fix some AsciiDoctor problem in generated HTML files in the site.

The task takes the sites it should load and build from the parameter MVN_SITES. If no sites are provided, or no sites could be loaded (due to a missing side identifier file), the task will throw an error.

Building a Maven site of course requires Maven (dependency maven), which in turn requires a JDK to be installed on the host as well.

Testing a site is done by starting a web browser with the site’s index.html file. This requires the task start-browser to be loaded and well-configured. Without this task be available, sites cannot be tested.

The option simulate can be used to simulate a clean. Here, not task will be executed and the directory TARGET will not be removed either. Instead, the task will simply print what commands it would run.

The default command to remove the TARGET directory is rm -frI. This is an additional safety feature to prevent accidental removal of the directory. The option force can be used to remove the directory forced, i.e. using rm -fr instead. simulate will overwrite force.

The task can build a Maven site for several targets:

There is no default target.

Filters allow to specify which of the loaded (and available) sites should be built:

There is no default filter.

Further options exist to configure the runtime behavior of Maven:

The framework’s own site can be build using this task. When correctly configured, the site can be listed

This will show (with a real path instead of SOME_PATH)

The site can then be build using

The task and Maven output will be similar to:

Setting the task level to info will provide more information on the task’s progress.

As mentioned above, a site suitable for this task should provide a file with its metadata and might provide a file with scripts to be used in the build. Both files must be located in the same directory as the POM file.

The metadata file must be named skb-site.id. It must contain the following information:

The source block below shows the file for the frameworks' site.

The file skb-site-scripts.skb could be provided. If it does not exist, the task will build the site purely using Maven. If it does exist, the task will source the file and call two functions the file must provide. This means that the file can

The following code block shows the standard contents of the script file with the two required functions:

To see an example have a look at the framework’s script file. The current file can be found in the Github repository: skb-site-scripts.skb. Here, the function MvnSitePreScript executes framework tasks to create files for the site. The function MvnSitePostScript calls tools from the AsciiDoctor tool chain to create documents. It also uses the framework’s API function MvnSiteFixAdoc, which helps to fix some AsciiDoctor problem in generated HTML files in the site.

The task takes the sites it should load and build from the parameter MVN_SITES. If no sites are provided, or no sites could be loaded (due to a missing side identifier file), the task will throw an error.

Building a Maven site of course requires Maven (dependency maven), which in turn requires a JDK to be installed on the host as well.

Testing a site is done by starting a web browser with the site’s index.html file. This requires the task start-browser to be loaded and well-configured. Without this task be available, sites cannot be tested.

Target options can be used to set specific cache targets.

Beside the general targets, the task can also be run with very specific targets, shown below. Here, declaration and table caches can be requested for each element type.

This task requires the parameter CACHE_DIR to be set. Since this parameter has the default value of /var/cache/$APP_NAME it is always set.

This task will change directories and files in the cache directory. Sufficient permissions must exist to run this task successfully.

Care should be taken when using specific configurations for CACHE_DIR. Since there can be any number of SKB application installed on a single system, the cache directory should be different per application. Otherwise there can be unexpected behavior, especially for the declaration caches.

When declarations of cached elements (for instance a task) are changed, the cache is not automatically changed. This means, the changes will have no effect on the application load. This can lead to unexpected behavior. If caches are used, they should be cleared and rebuild whenever declarations change.

The task requires an installation of the framework. It also requires the tasks list-options and list-commands being loaded (this should be the default).

This task will change directories and files in the framework installation. Sufficient permissions must exist to run this task successfully.

The option simulate can be used to simulate all task actions. In this mode, the task will only print what it would do. The option force can be used to force a download even if the JAR file already exists. simulate will overwrite force.

The following example will change the version in all files in the directory src to 0.1.0. It will use the default build and macro file.

The task requires Apache ANT (dependency ant). It also needs the parameters VERSIONS_BUILD_FILE and VERSIONS_MACRO_FILE to be set. Both parameters come with default values (the build and macro file provided by the framework). Settings these parameters will make the task using different build or macro files.

The build file is a file called build.xml with information for ANT on what to build, and how. The default build file provided by the framework should be sufficient for all use cases. The XML below shows the default build file.

The build file is kept very simple. The version string is provided by the setting moduleVersion, which is translated into the property module.version. The macro file is either provided by a setting macroFile or as the default value macro.xml. If the default value is used, the macro file must be in the same directory as the build file.

The build file then define its only target skb-set-versions. For the actual substitution of strings, the build file calls a macro push-version The start directory is provided by the setting moduleDir, which is translated into a property module.dir for the macro.

Line 3 shows an example use of the build file from the command line.

The macro file is called macro.xml (default) or defined in the build file (see above). The actual macro then must be called push-version. The following source block shows the default macro file provided by the framework.

The main functionality is a sequential execution of a regular expression replacement (replaceregexp), for all files satisfying the given filters. Replacements are done en block (i.e. not by line). The encoding is always UTF-8, For each replacement:

The following examples show a number of standard patterns and substitution expressions.