Command Line Tools

Purpose

Package processing command line tools are needed mainly for validating and packaging APS projects as well as for signing and localizing them.

Meet Prerequisites

Make sure the following packages are installed on the system:

• JRE or JDK version 6(1.6) or higher

• APS PHP Runtime is required if the application custom APS types are defined inside the application PHP files.

Download

Download the latest version of the package containing the APS tools and install it on your local computer as the next sections explain.

Installation

YUM based Linux (Red Hat / CentOS)

Use the typical rpm command to install the downloaded package, for example:

# rpm -ivh apstools-2.2-408.noarch.rpm

Windows

Run the downloaded executable file, for example, apstools-2.2-408.exe and follow its instructions to complete the operations.

Other OS

For OS other than the above mentioned, pay attention to the APS tools specifics to install the package correctly. Look inside the aps executable runner explained in the Commands section and you will find that it contains a small shell script that calls the main function in the apstools.jar Java archive:

#!/bin/sh
java -Xms32m -Xmx512m -jar /usr/lib/aps/lib/apstools.jar "$@"

As follows from this fact, the package setup looks like a set of unzip and copy steps:

1. Unzip the downloaded ZIP file, for example, apstools-2.2-408.zip to a local folder.

2. Copy all JAR files from that folder to a system folder you have write permission. In accordance with the aps script, the best way is to copy JAR files to the /usr/lib/aps/lib/ folder. If you do not have write permissions to that folder, copy them to another one, for example:

   $ sudo cp ~/Downloads/usr/lib/aps/lib/* /usr/local/lib/aps/lib/
   

   Note

   Ensure, the aps script calls the asp.tools.jar using the correct path. Edit it if necessary.

3. Copy all shell executable scripts to a folder that is in the PATH environment variable, for example, to /usr/local/bin/. Ensure the executable attribute is assigned to them. For example:

   $ sudo cp ~/Downloads/usr/bin/* /usr/local/bin/
   $ sudo chmod 555 /usr/local/bin/aps*
   

   Note

   Usually those shell scripts are not changed from version to version. That is why, when you update an older version of APS tools, usually you do not need to update the scripts.

4. Verify if the new version of APS tools is available for you:

   $ aps
   
   APS Command Line Tools 2.2 (build 2.2.408)
   ...
   

Commands

After installing the tools in your development environment, you will be able to process APS packages as described in this section. APS tool set contains the aps utility implementing a number of commands, such as build and lint.

Command	Description	Examples
aps build	Build and sign package from package directory or re-sign package	aps build VPScloud/
aps lint	Validate APS package archive or package directory against APS Specification	aps lint VPScloud/
aps msgmake	Extract message strings from APS package directory for translation	aps msgmake -l es_ES VPScloud/
aps msgfmt	Create JSON message catalogs from textual description of translations in PO files	aps msgfmt VPScloud/

Building Package

With the aps build command you can build an APS package and, if necessary, sign it by a valid application vendor certificate (-c option). The command syntax is as follows:

aps build [options] [argument]

• The [argument] is a package directory, containing the APP-META.xml file, or a package archive - an APS package with the app.zip extension.

• The [options] are presented in the following list:

  • –help -h -? - Show usage information

  • –certificate -c value - Sign a package with the specified PFX/PKCS12 certificate file

  • –outdir -O value - Write the resulting package to the specified directory

  • –output -o value - Write the resulting package to the specified file

  • –version -V - Show version information

  • –skip-js-errors - Build the package even if JavaScript errors were detected

    Warning

    Use this option in exclusive cases only and never use it when packaging an application that you are going to certify.

  • –package-files -L - File with a list of files to be included into the package;

    when the file is specified as ‘-‘, STDIN is used to read a list of files

The following example illustrates how to build a package from the VPScloud folder:

aps build VPScloud/ - build a package from the VPScloud folder

To sign a package, you can use the following example:

aps build -c cert.p12 VPS_Cloud-1.0-1.app.zip - sign the existing package

When building a package the tool validates it using the same criteria as in the aps lint tool.

• If an error is detected, the tool cannot build the package and print out an error message.

• If there is a warning message, the building process still continues.

To avoid validation of 3rd party libraries when building your APS package using the APS command line tools, place those libraries to the ui/js/lib/ folder in the project you build.

Package Validation

The aps lint command validates the package archive or package folder against the APS Specification.

The utility validates the following:

• File format

• Package structure

• Metadata

• JavaScript code in the ui folder and its sub-folders as specified in Package Structure.

Note

The utility does not validate files in the ui/js/lib/ folder as this folder must contain third party JavaScript files.

As a result, the utility outputs the following data:

• Error messages indicating why a package fails to conform to the APS

• Error messages indicating requirements that a package must satisfy to get certified

• Total number of errors; if 0 errors occur, the package is successfully validated

The command syntax looks as follows:

aps lint [options] [argument]

• The [argument] is a package directory, containing the APP-META.xml file, or a package archive - an APS package with the app.zip extension.

• The [options] are presented in the following list:

  • –help -h -? - Show usage information

  • –apsc-version - Show APS version used for validation

  • –basic -b - Turn off certification check

  • –out -o value - Send XML validation report to the given file

  • –quiet -q - Perform validation quietly

  • –skip-js-errors - Treat JavaScript errors as warnings

  • –verbose -v - Print debug information to standard output;

    do not use along with -q –quiet option

  • –version -V - Show the tool version

To validate a package archive, you can use the following example:

aps lint -l Basic VPS_Cloud-1.0-1.app.zip

The following command validates a package in the folder:

aps lint VPScloud/

When validating a package the tool validates JavaScript and HTML codes using jshint validation against the following criteria:

• Prohibit variable use before definition

• Prohibit declaration of variables that are not used in the code

• Require capitalization of all constructor functions, for example, new F()

• Prohibit trailing white spaces

• Prohibit debugger statements, for example, browser breakpoints

• Prohibit function eval()

• Prohibit missing semicolons when it is omitted for the last statement in a one-line block

• Prohibit unsafe line breaks, for example, return [n] x without semicolons

• Prohibit usage of the __iterator__ property

• Prohibit the deprecated __proto__ property

• Prohibit definitions like new function () { … }; and new Object;

• Prohibit the use of this in a non-constructor function when the strict mode is on

• and other

Note

Please refer to JSHint Options for more details regarding the above restrictions.

Internationalization Helpers

The aps msgmake and aps msgfmt commands help you make your APS packages international by adding and processing files with translated messages.

In the following example, the aps msgmake command creates a new es_ES.po file or updates the existing one in the VPScloud/i18n/ folder with messages that can be translated after that into Spanish:

aps msgmake -l es_ES VPScloud/

Note

To get the list of languages supported on your system, run the locale -a command.

If you need to update all existing PO files in the package folder, run the same command without -l attribute, as in the following example:

aps msgmake VPScloud/

The detailed process of making packages international is presented in the Internationalization and Localization chapter.

In rare cases, for example, during debugging processes, when you need to create a JSON message catalog (JSON files) from PO files, the aps msgfmt command should be useful. In normal cases, the catalog is created automatically by the aps build command. The following example illustrates how you can generate the JSON catalog from all PO files in a folder:

aps msgfmt VPScloud

The following command will request to generate the JSON catalog for the specified PO file only:

aps msgfmt VPScloud/i18n/de_DE.po

← Development Tools

APS PHP Runtime →