Previous topic

PHP Runtime Library

Next topic

APS Fiddle

DOCUMENTATION
Last updated 18-May-2016

Command Line Tools

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

Installation

APS tools require the following packages preinstalled on your computer.

You can download and install the latest version of the tools following this list:

Platform Version Download Link
Windows 2.2-248 apstools-2.2-248.exe
MacOS X 2.2-248 apstools-2.2-248.dmg
Linux (rpm) 2.2-248 apstools-2.2-248.noarch.rpm
Universal (java) 2.2-248 apstools-2.2-248.zip

After installing the tools in your development environment, you will be able to process APS packages as described in Utilization.

Utilization

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 (in APS IDE or by means of 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 APS 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, e.g. new F()
  • Prohibit trailing white spaces
  • Prohibit debugger statements, e.g. 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, e.g. 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, e.g. 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