skb-framework(1) Manual Page

Sets the command to start a web browser, for instance Firefox, with a URL. The setting should contain the string %URL%, which will be substituted with the actual URL at runtime. To start for instance Firefox, this variable should be set to firefox --new-tab %URL%. The browser can be given as simple command (then it needs to be in the PATH) or as absolute command.

Sets the cache directory, used by the task build-cache and then also the loader. Caching parts of the application elements (or even all tasks) can speed up the load of an application as well as runtime behavior, such as help on a task. This feature is useful for slower systems, such as a Raspberry PI or a Cygwin environment.

This parameter should provide a list of directories that contain an skb-ts.id file to run task sets. Use whitespaces to separate directories. Tasks that run task sets, such as make-arget-sets will use this parameter to find the identifier files. If not present, these tasks will not execute.

Sets the path for source files to build the application manual. For standard applications, the default value should be sufficient. In case one wants different manuals for different application modes (e.g. one for build and one for use), this parameter can be used.

This parameter should provide a list of directories that contain POM files to generate Maven sites. Use whitespaces to separate directories. Tasks that build Maven sites, such as build-mvn-site will use this parameter to find POM files. If not present, these tasks will not execute.

Sets the command to start a PDF viewer with a given PDF file. The setting should contain the string %%, which will be substituted with the PDF file at runtime. To start for instance Evince, this variable should be set to evince %FILE%. The PDF viewer can be given as simple command (then it needs to be in the PATRH) or as absolute command.

This parameter should provide a list of directories where the application can find scenarios. Use whitespaces to separate directories. If set, each directory will be parsed to load scenarios during the load of the application. All found scenarios are available to be executed at runtime.

This parameter can be used to set the prompt the shell should use. It can be set to anything that the shell can execute, including the console functions of the framework. It is for instance possible to use the function PrintColor to create a prompt with colored text.

This option points to the SKB Framework Tool. This tool is an executable JAR. It is used to convert paragraphs and lists into justified text with pre-defined margins and other parameters. This is done using the SKB asciiparagraph and asciilist implementations. This setting is required to build the manual sources (text files) from the original ADOC files. In a standard installation, the JAR should be available in the lib/java folder of the framework.

This parameter sets the target directory, where artifacts should be created in, similar to the target directory in Maven or the build directory in Gradle. If set, the directory will be tested for create and delete. Some tasks, such as clean will remove the given directory and everything in it.

This option points to a default ANT build file used by the task set-file-versions. The default value points to the build file in the framework distribution.

This option points to a default ANT macro file used by the task set-file-versions. The default value points to the macro file in the framework distribution.

Sets the command to start a new X terminal (Xterm) with substitution strings for title and command. The title substitution string is %TITLE%. The command substitution string is %COMMAND%. For most X terminals, it is best to use an open ended CLI option for the program, i.e. a CLI option that takes everything until the end of the command line. Most X terminal variants can be started using xterm -T %TITLE% -e %COMMAND%. For mintty on Cygwin this variable should be mintty -t %TITLE% %COMMAND%. For an XFCE4 terminal, e.g. on Ubuntu, this variable should be xfce4-terminal --disable-server --title='%TITLE%' -x %COMMAND%.

This task builds a cache for an application with various options for targets. It uses the parameter CACHE_DIR for the cache location. A cache of application elements can speed-up the loader. A cache of task can speed-up the help function of tasks. While on native UNIX/LINUX system on good-powered machines the cache might not make much of a difference, on other machines it can improve the application’s runtime behavior.

This task builds the main help files for the application. It should only be run when an application distribution (e.g. DEB or RPM) is created.

This tasks builds the application manual. It comes with various options for targets (manual formats) and filters (manual content). There are two primary targets: text and adoc. Here, text can be ANSI text (with colors and effects), plain text (just text), or annotated text (using ASCII characters for some formatting). The adoc target creates an Asciidoctor file. This file is then used to create secondary targets, such as a manpage, a HTML file, or a PDF file. Other secondary targets can be added, as long as they are supported by the Asciidoctor tool chain.

This task will build Maven sites. It uses Apache Maven for the build process. The sites need to be provided by he parameter MVN_SITES. Several options are available to control the build process.

This task will clean, i.e. remove all create artifacts. It starts calling the --clean option of all tasks starting with build- and compile-. Then it will remove the target directory set by the parameter TARGET.

This task uses CLOC (Count Lines of Code) to count the lines of code in different languages of the application.

This tasks describes a few aspects of the application. Availabel filters are: description, authors, bugs, copying, resources, and security information.

This task describes one or more shell commands. If a specific command is requested, only this command is described. Otherwise, all commands are described.

This task describes one or more dependencies. If a specific dependency is requested, only this dependency will be described. Otherwise, all dependencies are described. Filters can be applied for a complete description, such as a specific origin or status.

This task provides the general descriptions of application elements. By default, all of those descriptions are shown. Otherwise, the task filters can be used to exclude parts of them.

This task describes one or more exit status. If a specific exit status is requested, it will be described. Otherwise, all exit status codes will be described.

This task describes one or more CLI options of the application. If a specific option is requested, only this option is described. Otherwise, all options are described. Filters can be applied to the description of all options.

This task describes one or more parameters. If a specific parameter is requested, only this parameter is described. Otherwise, all parameters are described. Filters can be applied to the description of all parameters, for instance only a specific origin or status.

This task describes one or more scenarios. If a specific scenario is requested, only this scenario is described. Otherwise, all scenario are described. Filters can be applied to the description of all scenarios, for instance only a specific origin or status.

This task describes one or more tasks. If a specific task is requested, only this task is described. Otherwise, all tasks are described. Filters can be applied to the description of all tasks, for instance only a specific origin or status.

This task downloads the SKB Framework Tool. This tool is an executable Java JAR file. It provides mechanisms to convert plain text into formatted text. The tool is for instance used by the task build-manual to convert ADOC sources into formatted plain text.

Executes a program with various options. The program can be started in the background or in a new XTerm.

This task lists commands in simple list or table form.

This task lists the current configuration in simple list or table form. The table form provides additional information for each configuration item. Filters can be applied to the list.

This task lists dependencies in simple list or table form. The table form provides additional information for each dependency. Filters can be applied to the list.

This task lists application exit status in simple list or table form. The table form provides additional information for each exit status. Filters can be applied to the list.

This task lists CLI options in simple list or table form. The table form provides additional information for each options. Filters can be applied to the list.

This task lists parameters in simple list or table form. The table form provides additional information for each parameter. Filters can be applied to the list.

This task lists scenarios in simple list or table form. The table form provides additional information for each scenario. Filters can be applied to the list.

This task lists tasks in simple list or table form. The table form provides additional information for each task. Filters can be applied to the list.

This task will execute so called Target Sets (TS). It requires a file skb-ts.id to define the target set and an associated file skb-ts-scripts.skb with the function to run. The task then takes required targets as argument and runs them in the right order. The target sets need to be provided by he parameter MAKE_TARGET_SETS.

This task shows the application manual. The default is to show the text version for the current print mode. Other formats, such as HTML and PDF or manpage, can be selected using task options.

This task will repeat a given scenario. The repetition can be configured in terms of: times (how often to re-run the scenario) and wait (how long to wait between repetitions).

This task will repeat a given task. The repetition can be configured in terms of: times (how often to re-run the task) and wait (how long to wait between repetitions). The task, including parameters, should be provided after -- in the command line. For example, to repeat the task t1 5 times, use: repeat-task --times 5 — t1.

This task changes version information in source file headers. It runs Apache ANT using a simple build script, which in turn calls a macro that changes the version line. The default build and macro files change java files and all relevant framework files. These files can be used as template for writing other substitutions, if required.

This task allows to change selected runtime settings. Changeable settings include: shell and task level, strict mode, no prompt for the shell, and print mode.

Starts a web browser using the setting from the parameter BROWSER. The URL option of the task sets theURL to be loaded in the browser.

Starts a PDF viewer using the setting from the parameter PDF_VIEWER. The file option of the task sets the PDF file to be loaded in the viewer.

Starts a new XTerm using the setting from the parameter XTERM. The title can be set using the task options.

This task shows statistics of the applications and loaded or processed elements. The statistics can be filtered per element class, for instance tasks or parameters.

This task validates the application installation. Validation here means that all required files, including documentation files, will be checked. The validation can be run in strict mode, which means that strict warnings become errors. The task can be configured with targets, determining what the validation should focus on.

Wait for the given number of seconds before the next command is executed. The action here is a simple sleep.

Apache Ant is required by some tasks to build or manipulate artifacts. One example is the task set-file-versions, which can be used to automatically set version information in source files. For Ant documentation and installation see https://ant.apache.org/.

Asciidoctor is a tool (or rather tool chain) that takes files written in AsciiDoc (or ADOC) and produces various output formats. These formats are supported by backends. Standard backends are PDF and HTM. Others are supported by plugins. For details on Asciidoctor and its installation see https://asciidoctor.org/ .

PDF plugin for Asciidoctor to create PDF output.

This dependency checks for the tool CLOC, or Count Lines Of Code. This tool is used to count lines of code for a variety of languages. For details on CLOC see the Github repo at https://github.com/AlDanial/cloc.

This checks for the availability of the curl command. Curl is a library and command-line tool for transferring data using various protocols. It can be used by tasks to download artifacts.

This is the dependency for a Java development environment, or JDK. The exact version of the JDK cannot be specified, since there is not standardized version string across the multiple options (e.g. Oracle Java, Open JDK).

This is the dependency for a Java runtime environment, or JRE. The exact version of the JRE cannot be specified, since there is not standardized version string across the multiple options (e.g. Oracle Java, Open JRE).

Apache Maven is required by some tasks to build artifacts. One example is the SKB site, which is build using the Maven site plugin. The dependency here requires an installed version 3 or lager of Apache Maven. For Maven documentation and installation see https://maven.apache.org/.

Exits the shell and the application. The temporary configuration file will be removed. The exit status is 0.

Clears the screen, same effect as cls in the command prompt or ^L in a login shell.

Prints the current configuration as a simple list of configuration keys and their current value. Some of the keys are internally set, for some the values are taken from the environment or a configuration file. In print mode ansi, some values are printed in color (e.g. red for a value error) or text effects (e.g. bold for the flavor). The task list-configuration provides more options for printing the configuration.

Executes a scenario, i.e. runs all commands (tasks) in a scenario file. The given scenario must be loaded. Use the task list-scenarios for loaded, available scenarios.

Exits the shell and the program. The temporary configuration file will be removed. The exit status is 0.

Shows a help screen with all shell commands. The commands are alphabetically sorted and shown as: short name, long name, and description. The task list-commands provides more options to list commands.

Shows the history of shell commands. Each command, once executed, is automatically added to the history, if the previous command was not exactly the same. The history accepts an optional parameter NUMBER. When a number (an integer) is given, the command with that number in the history will be executed. If the number does not exist in the history, an error is printed.

Exits the shell and the program. The temporary configuration file will be removed. The exit status is 0.

Prints tables with simple statistics of application elements, such as tasks and parameters. For more options on statistics and more detailed statistics see the task statistics.

Shows the list of loaded (i.e. available) tasks. The task are presented with their long name, short name, and a description. They are alphabetically sorted (long name). For more options to list tasks see the task list-tasks.

Shows the list of loaded (i.e. available) tasks with origin application. The task are presented with their long name, short name, and a description. They are alphabetically sorted (long name). For more options to list tasks see the task list-tasks.

Prints the current time as HH:mm:ss.

Success. If any command line option was used, then processing this option was successful. If the shell was started, then it terminated successfully.

An application did not find the SKB Framework executable. The framework installation was found, but no executable framework file. This is very likely a permission problem of the framework installation.

The application did not find the SKB Framework installed.

The environment $SKB_FRAMEWORK_HOME was set and pointed to an existing directory. However, there was no executable skb-framework found in this directory. This might be a permission problem on the framework executable.

The setting for $SKB_FRAMEWORK_HOME was found in the environment, but it does not point to an existing directory. Try to unset SKB_FRAMEWORK_HOME from the environment, or set to an existing directory.

The application is not able to set the application home directory. It has tried all implemented options (environment, readlink, dirname). Fix this problem by setting the application home in the environment.

The framework is not able to set the home directory, here $SF_HOME. It tried the environment, readlink, and dirname. This problem is an internal problem, probably am incorrect installation or a bug in starting the application.

The framework did find its home directory, but not the application loader script. This error points to a serious problem with the framework installation, or a permission problem on starting the loader.

The program was not executed with bash version 4 (or later). Since it uses associative arrays, bash 4 is a requirement to run the program. Please install bash version 4 or later.

The application did not find GNU getopt. This software is required for command line argument parsing in the framework and many tasks. Please install the correct getopt version.

The loader did not find the tool bc being installed. This tool is required for a number of calculations of the application. Please install bc on your system.

The loader did not find the tool mktemp being installed. This tool is required for creating temporary files. Please install mktemp on your system.

Unknown base name or flavor. The start script is used for multiple programs. At the beginning of the initialization, it detects the current flavor (using the script name). If the flavor found is not known, it will exit with this status. This should not happen in an installed version. If it does, than the installation was broken (build) or manipulated (after installation).

The program requires a setting for its home directory. The setting can be done in the environment or via a configuration file. If the setting is not found, the initialization will terminate with this code. See parameters (HOME) for details.

No home directory found. The setting for home directory did either not point to a directory or the directory is not accessible. Check the setting or the directory.

This is an internal loader error: the script name of the application was not set. This error is pointing to an application bug.

This is an internal loader error: the application name was not set. This error is pointing to an application bug.

The loader did not find a required version file, for either the application or the framework. The application version file should be $APP_HOME/etc/version.txt. The framework version file should be $FW_HOME/etc/version.txt. Each of these file must contain a single line with the version, usually using semantic versioning. This error points to an application bug or installation error.

The loader attempted to create a temporary directory for the application. This attempt failed. Please check the permissions for the temporary directory.

The loader did find or could create the temporary directory, but then could not write to it. Please check the permissions for the temporary directory.

The loader did experience errors while declaring parameters. This error points to an application bug or installation error. It should only happen when one or more parameter declarations are faulty.

The loader did experience errors while declaring CLI options. This error points to an application bug or installation error. It should only happen when one or more option declarations are faulty.

Internal error: unresolved CLI options. This error points to a bug in the software. It means that the shell or a task were presented with unexpected CLI options. Those options should have been processed by the program.

The loader did experience errors while declaring shell commands. This error points to an application bug or installation error. It should only happen when one or more command declarations are faulty.

The loader did experience errors while declaring exit status. This error points to an application bug or installation error. It should only happen when one or more exit status declarations are faulty.

The loader did experience errors while declaring dependencies. This error points to an application bug or installation error. It should only happen when one or more dependency declarations are faulty.

The loader did experience errors while declaring tasks. This error points to an application bug or installation error. It should only happen when one or more task declarations are faulty.

Available tasks (from bin/tasks in the program home directory) are loaded. Several tests are run for each task while loading. If any of those tests failed, this error code will be used on exit. Any error here is a development issue (or bug). Detailed error messages with have been printed.

The loader did experience errors while declaring scenarios. This error points to an application bug or installation error. It should only happen when one or more scenario declarations are faulty.

The process of one or more scenarios failed, i.e. some scenario requirements could not be fulfilled.

The loader got an unknown loader level from a CLI command.

The loader got an unknown shell level from a CLI command.

The loader got an unknown task level from a CLI command.

Internal error: unresolved CLI options. This error points to a bug in the software. It means that the shell or a task were presented with unexpected CLI options. Those options should have been processed by the program.

A task was started outside the framework or an application. This errors occurs if no temporary configuration file was provided for a task execution. Please do not execute a task outside the framework or application.

A task found an error while parsing its CLI arguments. This error points to a bug in the task implementation.

A task has found an error in its command line. This happens when a task is parsing the command line and detects one or more unknown options. Detailed error messages should have been printed.

This scenario will create all required artifacts for building a framework distributions. It can be used in the dev application mode, though the framework should be started with option --all-mode to catch all tasks. The scenario calls the tasks build-manual and build-help. Since it builds all artifacts, it has all requirements as these two tasks, including JRE8 (for tool execution).