9. CLI

Parts of this document may be outdated.

9.1. Headless Compiler

The headless compiler is provided as a separate tool, coming as a single jar file n4jsc.jar. It is to be invoked via

java -jar n4jsc.jar

Simply invoking the headless compiler with no further arguments will print out a description of command line options.

The headless compiler works in three major modes (given as arguments to the switch -bt):

  • compilation of single files (-bt singlefile, default),

  • compilation of given projects (-bt projects) or

  • compilation of all projects (-bt allprojects)

The command-line invocation usually has the form of

java -jar n4jsc.jar  ^$[options]$^  file1 file2 ...

Standard compiler options:

--buildType , -bt mode

With mode as exactly one of

singlefile

only the source files given by file1, file2, …​ are compiled.

projects

file1, file2, …​ denote projects (folders containing a manifest.n4mf). These projects will be compiled.

allprojects

All project found under the project-root(s) are compiled. There should be no file…​ given.

dontcompile

Nothing will be compiled. There should be no file…​ given. (This is the default if no -t option is given).

--projectlocations (-pl) path

provide folder(s) to search for projects. If not set, the base folder of the running JVM will be taken as the location. Multiple folders are separated by the systems path-separator (’:’ on Mac / Unix and ’;’ on Windows). Only direct subfolders will be queried for projects. A subfolder is assumed to be a N4JS-project if it contains a manifest.n4mf file. All found projects are taken into consideration for dependency-resolution. Example on Linux:
-pl  /rootA/: /rootB:/some/absolute/path/to/projects.

Advanced compiler options (optional):

--notests

turn off compilation of code in test-folders. Can not be combined with –testonly

--testonly

only compile test code. Externals and sources will not be compiled. Can not be combined with –notests

--keepCompiling

try to compile even if some errors occur.

--preference file

uses file as there internal preferences-store similar to the preferences internally stored by the N4IDE.

Additional command line options (optional):

--help , -h

prints out help to the console and exits.

--verbose , -v

verbose output during build

--debug

before executing, summarises the information of the current setup like resolved pathnames and other information, carries on with normal workflow and prints additional status information about loading and unloading projects and processing each resource.

--log

write a log file n4jsc.log to the base folder. (Change filename with –logfile filename)

9.2. Headless Dependnecies

Compiler can manage dependencies of the processed projects:

--installMissingDependencies , -imd

alnalyzes available projects and installs missing dependencies

--targetPlatformInstallLocation , -tl

location to which dependencies will be installed, if not provided temporal location will be used

--npmrcRootLocation

location of the .npmrc file to be used in npm invocations

9.3. Headless Execution

For headless compiling, running and testing of N4JS code a general command line tool is provided. Many parameters of the different use cases are shared. Although you can combine the use cases each of them is described in its own section. This section is about running compiled code.

For compiling refer to Headless Compiler for executing tests refer to Tests.

9.3.1. Cleaning Headlessly

It is possible to use the headless compiler to clean projects by using the following option

--clean (-c)

When this option is used. The headless compiler only cleans projects without compilation. Moreover, the use of this option requires that the option -t must be specified and must be either -t projects or -t allprojects.

For instance, n4jsc --clean -t allprojects -pl path/to/project or n4jsc --clean -t projects project1 project2 are valid use while n4jsc --clean -t singlefile file1 file2 is invalid. After the calling the command with --clean (-c`), the output folders of the specified projects (e.g. src-gen folders) are cleaned.

9.3.2. Running Headlessly

Running code from the command line requires basically three different pieces of information:

  1. The locations where projects, libraries and environments can be found must be given.

  2. The starting point of execution must be given by pointing to a module.

  3. Since there are multiple different project types, an adequate Runner has to be selected.

The follwing command line switches are used to provide this information:

--projectlocations (-pl) path

path of locations to search for projects (c.f. Headless Compiler ,Project Locations)

--runWith (-rw) VAL

denotes the runner-id (as listed with --list-runners) or at least the last segment of it

--run (-r) FILE

source-module to run. Note you should point to the full location of the source file (*.n4js). The runner is responsible to determine the compiled file. It is not sufficient to give a project-relative path, it always needs to be a full path to the source file.

It is possible to compile and run with a single CLI line. Compilation always precedes the execution. It the compilation fails the runner will not be started.

To ease the usage of different runners it is allowed to provide the last segment(s) of the runner-id in a case-insensitive way, e.g. one can use the runner with id org.eclipse.n4js.runner.nodejs.NODEJS as follows:

.. --runWith org.eclipse.n4js.runner.nodejs.NODEJS ..

or in short

.. --rw NODEJS ..

or even lower-cased with

.. --rw nodejs ..

Assume having a common workspace location ’wsp’ with a project ’P1’ containing the module ’A’. The following line shows how to run this code:

java -jar n4jsc.jar -pl wsp -rw nodejs -r wsp/P1/src/A.n4js

9.3.3. Information about running headlessly

Available runner-ids can be actively queried:

--listRunners (-lr)

prints out a list of all available command-line runners

9.3.4. Testing Headlessly

Testing code from the command line requires basically three different pieces of information:

  1. The locations where projects, libraries and environments can be found must be given.

  2. The starting point of test execution must be given by pointing to what is supposed to be tested (single file / whole project)/

  3. Since there are multiple different project types, an adequate Tester has to be selected.

The follwing command line switches are used to provide this information:

--projectlocations (-pl) path

path of locations to search for projects (c.f. Headless Compiler ,Project Locations)

--testWith (-tw) VAL

denotes the tester-id (as listed with --list-testers) or at least the last segment of it

--test (-t) FILE

source-module to run. Note you should point to the full location of the project with tests, specific folder inside project with tests or the test source file (*.n4js). It is not sufficient to give a project-relative path, it always needs to be a full path to the source file.

It is possible to compile and run with a single CLI line. Compilation always precedes the execution. It the compilation fails the tester will not be started.

To ease the usage of different testers it is allowed to provide the last segment(s) of the tester-id in a case-insensitive way, e.g. one can use the runner with id org.eclipse.n4js.tester.nodejs.NODEJS_MANGELHAFT as follows:

.. --runWith org.eclipse.n4js.tester.nodejs.NODEJS_MANGELHAFT ..

or in short

.. --rw NODEJS_MANGELHAFT ..

or even lower-cased with

.. --rw nodejs_mangelhaft ..

Assume having a common workspace location ’wsp’ with a project ’P1’ containing the module ’TestA’. The following line shows how to execute this test code:

java -jar n4jsc.jar -pl wsp -tw nodejs_mangelhaft -t wsp/P1/src/TestA.n4js

9.3.5. Information about testing headlessly

Available tester-ids can be actively queried:

--listTesters (-lt)

prints out a list of all available command-line testers