The command-line interface is the starting point for developing IBM® WebSphere® sMash modules.
The command-line interface is itself a module complete with an ivy.xml file that declares
its dependencies. The first time a command is executed using command-line a bootstrap process is
initiated. The bootstrap process resolves the ivy.xml file and downloads the required modules into a
local repository. The module zero.cli.tasks
provides the base set of
commands available through the command-line interface. The command-line
is implemented using WebSphere sMash features like event processing
and virtual directories, that allow the
command-line interface to be extensible. See Extending the command-line for
more information about providing new commands.
The command-line interface allows a module to be resolved against a module group. A module group is a repository of modules, typically retrieved from remote repositories. The support for module groups is important to allow separating modules that are retrieved from different repositories. The initial support came about to allow developers using the stable repositories of WebSphere sMash to also have the opportunity to experiment with the latest modules from the Project Zero site. A module could be resolved against a module group from the stable repositories, while other modules are developed against a module group with modules from the Project Zero repository. This environment can be supported with a single installation of the command-line interface. The typical user will probably have one or the other module group configured. The support can be powerful for developing modules against a stable repository, and then with a couple of simple commands re-resolve against the latest from experimental modules from Project Zero.
The typical usage is to download WebSphere sMash command-line and start developing against the default module group. The default module group is configured in the config/bootstrap.properties file under the install directory of the command-line. Additional module groups can be created as needed using the modulegroup commands.
The known module groups are the stable module group, which retrieves officially released modules from the WebSphere sMash repository and the experimental module group, which retrieves the latest modules from the Project Zero repository.
Product | Known module groups |
---|---|
WebSphere sMash | stable |
WebSphere sMash DE | experimental, stable(default) |
Project Zero | experimental |
The command-line has defaults configured for the module group and the location of local repository. For most these defaults should be sufficient, but if there is a desire to change them, it is best to change them before bootstrapping the command-line. The default module group is configured based on which the command-line zip was downloaded. The default repository location is ${zerohome}/zero-repository, where ${zerohome} is the location where the command-line was installed.
The repository location can be changed by modifying the repo.root
variable in
the config/local.properties file. A reason for changing the repository location can be if the
user's do not have write access to the location where the command-line interface is installed.
In this case, ${user.home}, or a fully qualified path might be more appropriate.
There are two special variables that are substituted when the local.properties file is loaded. The first is ${zerohome}, which is the location where the command-line is installed. The second variable is ${user.home}, which is substituted with the user's home directory. Shell substitution variables like the tilde are not supported at this time.
DBCS characters are not currently supported for the repo.root location.
The local.properties file also allows configuring the timeout for connecting to remote repositories. There are two configurable timeouts and the units for both are in seconds. The connect timeout is the amount of time for establishing a connection with the host. The read timeout is the amount of time to start to read from the input stream for the connection. A value of 0 is an infinite timeout.
# connect timeout is in seconds, default is 1 minute(s) http.connect.timeout=60 # read timeout is in seconds, default is 30 seconds http.read.timeout=30
The command-line retrieves modules from remote repositories, so the JDK must be able to access to the internet. If your connection to the external Web sites requires a proxy to be configured, then you need to configure those proxy settings. The first time any command is executed with the command-line the bootstrap process will display an unknown host error if the proxy is required and has not been configured.
Java™ provides a default proxy selector that can use proxy settings configured through certain operating systems. The support can be enabled by setting the system property java.net.useSystemProxies to true. This feature is enabled by default, but can be turned off by editing the local.properties file and setting use.system.proxies to false.
The scripts allow setting system properties through the ZERO_OPTS environment variable. The ZERO_OPTS variable can be set in two ways. The first is set the environment variable through the command shell, and the zero scripts will pass the value through on the Java™ invocation. The second way is edit the appropriate zero script set the value for ZERO_OPTS in the script. The script for Windows™ is zero.bat, and the script for Linux™ and Mac is zero.
The proxy support can also be configured by setting the following system properties:
The WebSphere sMash command-line scripts contain a commented example to help set the proxy properties. For example, in the zero shell script the following lines should not be commented out, and they should be updated with the appropriate proxy values.
ZERO_OPTS="${ZERO_OPTS} -Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=myproxyport -Dhttps.proxyHost=myproxyhost -Dhttps.proxyPort=myproxyport" export ZERO_OPTS
The command-line allows invoking commands provided through a WebSphere sMash module. The base
commands are provided through the module zero.cli.tasks
and
available to all modules. Additional commands can be available if the module declares a dependency on a
module that provides commands. A command can have arguments and options. The arguments are passed to the
command and are order dependent. An example of an argument is myapp
for the create command:
zero create myapp
A command can also be passed an option. An option starts with a dash, -. An example of an option is the -overwrite option with the package command:
zero package -overwrite
An option can also have a value, like the following example.
zero publish -f=mypackage.zip
Certain arguments for the command-line need to be quoted so they are not automatically expanded or parsed incorrectly. The first argument is an argument that contains spaces. If for example, you want to create a module at c:/my path/test, the argument must be quoted because of the space in the path. The command in this case would be:
zero create "c:/my path/test"
The second argument that needs to be quoted is the star, *. If the * is not quoted then it is replaced with
the names of all the files in the current directory. The * can be prevented from getting expanded
by quoting the argument, this is required on all supported platforms. An example of when the * needs to be
quoted is with the command zero modulegroup get
. One way to get all the modules from a zero
repository is to use zero modulegroup get "*"
.
The command zero modulegroup get also supports the argument all to get all modules.
If an argument requires a % character, then the % character needs to be escaped as %%.
Each of the individual commands provide documentation on the supported options, but there are some
common options for all commands. The logging feature is implemented using these common options for the
command-line. The default logging is console-only for all commands except run. The
logging.properties file will be inherited from the module zero.kernel
, unless the module
provides one of it's own. The logging feature provides the -logfile
and -loglevel
options. The -logfile=file
option redirects the logging output to the specified file. The
-loglevel=level
option will control the logging level. The levels are the
java.util.logging.levels including SEVERE, WARNING, INFO, FINE, FINER, and FINEST.
The -logfile
and -loglevel
options must be specified before the command name.
For example, zero -loglevel=FINE resolve
.
The command-line allows configurations for multiple module groups. The configured module groups for the command-line can affect existing applications when changing to a new command-line. Consider the situation where the WebSphere sMash command-line is used to develop an application using the stable module group. If you then later decide to update to the latest command-line from the Project Zero site, then only the experimental module group is available by default. If the application is resolved a failure message will be displayed that the stable module group has not been configured. The reason is the history file for the application maintains the module group and the revisions of all the dependencies. The new command line from Project Zero is not configured with stable.
There are two options to fix up the existing stable application. The first is to use the zero switch command to switch the application to the experimental module group, which is configured. The second choice is create the stable module group for the new command-line interface using zero modulegroup create stable <stable_url>. The stable_url needs to be supplied because it has not been configured in the config/bootstrap.properties file for the command-line from Project Zero The supplied url can be the same one used by the experimental module group, or the urls can be determined from an existing stable command-line.
The command-line scripts on windows exit with exit /b exit_code so the current command prompt is not closed. However, if the script is invoked programmatically with cmd /c for example, then the exit code is always success, 0. The environment property ZERO_EXIT_CMD was introduced so that the script can exit with exit exit_code and the correct exit code value can be retrieved. The environment property ZERO_EXIT_CMD should be set to "true" before invoking the script.