design/execution.html - gerrit/www.eclipse.org/n4js - Git at Google

 <!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="UTF-8">
 <!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <meta name="generator" content="Asciidoctor 1.5.5">
 <meta name="author" content="2019-08-08 13:15:33 CEST">
 <title>N4JS Design Specification</title>
 <link rel="stylesheet" href="styles/spec.min.css">
 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css">
 <!-- ************* docinfo ******************************************************************* -->


 <!-- ************* Favicon ************-->
 <link rel="icon" href="images/favicon.ico" />

 <!-- ************* Back-to-top JQuery ************* -->
 <script src="https://code.jquery.com/jquery-1.12.4.js"></script>
 <script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script>


 <link href="styles/prism.min.css" rel="stylesheet" />
 <script type="text/javascript" async
   src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-MML-AM_CHTML">
 </script>

 <!-- ************* Styles ************* -->
 <link rel="stylesheet" type="text/css" href="styles/n4jsspec-adoc.css">


 <!-- ****************** NavBar ****************** -->
 <div id="menubar">
 	<div class="banner">
         <a href="https://www.eclipse.org/n4js/#"><img id="logo" src="images/n4js-logo.png" alt="Eclipse N4JS"></a>
     </div>
 <ul>
   <li><a href="index.html">Index</a></li>
 </ul>
 </div>
 <!-- ************* docinfo ******************************************************************* -->
 <style>
       .admonitionblock td.icon .icon-todo:before{content:"\f249";color:#f4ee42}
     </style>
 </head>
 <body class="book toc2 toc-left">
 <div id="header">
 <h1>N4JS Design Specification</h1>
 <div class="details">
 <span id="author" class="author">2019-08-08 13:15:33 CEST</span><br>
 <span id="revnumber">version 0.9</span>
 </div>
 <div id="toc" class="toc2">
 <div id="toctitle">Table of Contents</div>
 <ul class="sectlevel1">
 <li><a href="introduction.html#_introduction">1. Introduction</a>
 <ul class="sectlevel2">
 <li><a href="introduction.html#notation">1.1. Notation</a></li>
 <li><a href="introduction.html#sec:IDE_Overview">1.2. IDE Components</a>
 <ul class="sectlevel3">
 <li><a href="introduction.html#sec:Naming_Conventions">1.2.1. Naming Conventions</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="eclipse_setup.html#_eclipse-setup">2. Eclipse Setup</a>
 <ul class="sectlevel2">
 <li><a href="eclipse_setup.html#_system-requirements">2.1. System Requirements</a></li>
 <li><a href="eclipse_setup.html#_contribute">2.2. Contribute</a>
 <ul class="sectlevel3">
 <li><a href="eclipse_setup.html#_eclipse-installer">2.2.1. Eclipse Installer</a>
 <ul class="sectlevel4">
 <li><a href="eclipse_setup.html#_changing-the-setup-script">2.2.1.1. Changing the Setup Script</a></li>
 </ul>
 </li>
 <li><a href="eclipse_setup.html#_manual-ide-configuration">2.2.2. Manual IDE Configuration</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="release_engineering.html#_release-engineering">3. Release Engineering</a>
 <ul class="sectlevel2">
 <li><a href="release_engineering.html#_nightly-build-on-eclipse-infrastructure">3.1. Nightly build on Eclipse infrastructure</a></li>
 <li><a href="release_engineering.html#_build-the-n4js-ide-from-command-line">3.2. Build the N4JS IDE from command line</a>
 <ul class="sectlevel3">
 <li><a href="release_engineering.html#_publish-maven-tooling-code-org-eclipse-n4js-releng-util-code">3.2.1. Publish maven-tooling <code>org.eclipse.n4js.releng.util</code></a></li>
 <li><a href="release_engineering.html#sec:test-verdaccio">3.2.2. Test Verdaccio containing n4js-libs</a></li>
 <li><a href="release_engineering.html#_generation-of-eclipse-help-for-spec-and-design-document">3.2.3. Generation of Eclipse help for spec and design document</a></li>
 </ul>
 </li>
 <li><a href="release_engineering.html#_updating-frameworks-and-dependencies">3.3. Updating frameworks and dependencies</a>
 <ul class="sectlevel3">
 <li><a href="release_engineering.html#_update-of-eclipse-emf-xtext-etc">3.3.1. Update of Eclipse, EMF, Xtext, etc.</a></li>
 <li><a href="release_engineering.html#_update-of-the-embedded-jre">3.3.2. Update of the embedded JRE</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="tips_and_tricks.html#_tips-and-tricks">4. Tips and Tricks</a>
 <ul class="sectlevel2">
 <li><a href="tips_and_tricks.html#_naming">4.1. Naming</a></li>
 <li><a href="tips_and_tricks.html#_logging">4.2. Logging</a></li>
 <li><a href="tips_and_tricks.html#_cancellation-handling">4.3. Cancellation Handling</a></li>
 <li><a href="tips_and_tricks.html#_caching">4.4. Caching</a></li>
 <li><a href="tips_and_tricks.html#_dependency-injection">4.5. Dependency Injection</a></li>
 <li><a href="tips_and_tricks.html#_miscellaneous">4.6. Miscellaneous</a></li>
 </ul>
 </li>
 <li><a href="parser.html#_parser">5. Parser</a>
 <ul class="sectlevel2">
 <li><a href="parser.html#sec:Parser_Overview">5.1. Overview</a></li>
 <li><a href="parser.html#sec:N4JS_Parser">5.2. N4JS Parser</a></li>
 <li><a href="parser.html#sec:Parser_Generation_Post_Processing">5.3. Parser Generation Post-Processing</a>
 <ul class="sectlevel3">
 <li><a href="parser.html#sec:Automatic_Semicolon_Insertion">5.3.1. Automatic Semicolon Insertion</a>
 <ul class="sectlevel4">
 <li><a href="parser.html#sec:Injected_code_in_the_Antlr_grammar_file">5.3.1.1. Injected code in the Antlr grammar file</a></li>
 <li><a href="parser.html#sec:Customized_error_recovery">5.3.1.2. Customized error recovery</a></li>
 </ul>
 </li>
 <li><a href="parser.html#sec:_No_line_terminator_allowed_here__handling">5.3.2. Async and <code>No line terminator allowed here</code> Handling</a></li>
 <li><a href="parser.html#sec:Regular_Expression">5.3.3. Regular Expression</a></li>
 <li><a href="parser.html#sec:Unicode">5.3.4. Unicode</a></li>
 <li><a href="parser.html#sec:Literals">5.3.5. Literals</a></li>
 </ul>
 </li>
 <li><a href="parser.html#sec:Modifiers">5.4. Modifiers</a></li>
 <li><a href="parser.html#sec:Conflict_Resolutions">5.5. Conflict Resolutions</a>
 <ul class="sectlevel3">
 <li><a href="parser.html#sec:Reserved_Keywords_vs__Identifier_Names">5.5.1. Reserved Keywords vs. Identifier Names</a></li>
 <li><a href="parser.html#sec:Operators_and_Generics">5.5.2. Operators and Generics</a></li>
 </ul>
 </li>
 <li><a href="parser.html#sec:Content_Assist_Parser">5.6. Content-Assist Parser</a></li>
 </ul>
 </li>
 <li><a href="type_system.html#_type-system">6. Type System</a>
 <ul class="sectlevel2">
 <li><a href="type_system.html#sec:Type_Model_and_Grammar">6.1. Type Model and Grammar</a>
 <ul class="sectlevel3">
 <li><a href="type_system.html#sec:Type_Model_Overview">6.1.1. Type Model Overview</a></li>
 <li><a href="type_system.html#sec:Built_in_Types">6.1.2. Built-in and Primitive Types</a></li>
 <li><a href="type_system.html#sec:Type_Model_DSL">6.1.3. Type Model DSL</a></li>
 </ul>
 </li>
 <li><a href="type_system.html#sec:Type_System_Implementation">6.2. Type System Implementation</a></li>
 <li><a href="type_system.html#sec:Type_Inference_combined_with_AST_Traversal">6.3. Type Inference of AST</a>
 <ul class="sectlevel3">
 <li><a href="type_system.html#sec:Type_Inference_combined_with_AST_Traversal__Background">6.3.1. Background</a></li>
 <li><a href="type_system.html#sec:Triggering_Type_Inference_of_AST">6.3.2. Triggering</a></li>
 <li><a href="type_system.html#sec:Traversal_Order_During_Type_Inference_of_AST">6.3.3. Traversal Order</a></li>
 <li><a href="type_system.html#sec:Cross_References_During_Type_Inference_of_AST">6.3.4. Cross-References</a></li>
 <li><a href="type_system.html#sec:Function_Accessor_Bodies_During_Type_Inference_of_AST">6.3.5. Function/Accessor Bodies</a></li>
 <li><a href="type_system.html#sec:Poly_Expressions_During_Type_Inference_of_AST">6.3.6. Poly Expressions</a></li>
 <li><a href="type_system.html#sec:Constraint_Solver_used_During_Type_Inference_of_AST">6.3.7. Constraint Solver</a></li>
 <li><a href="type_system.html#sec:Type_Guards_During_Type_Inference_of_AST">6.3.8. Type Guards</a></li>
 </ul>
 </li>
 <li><a href="type_system.html#sec:Structural_Typing">6.4. Structural Typing</a></li>
 </ul>
 </li>
 <li><a href="type_index.html#_type-index">7. Type Index</a>
 <ul class="sectlevel2">
 <li><a href="type_index.html#sec:Type_Index_Design_Rationale">7.1. Design Rationale</a>
 <ul class="sectlevel3">
 <li><a href="type_index.html#sec:Getting_the_Xtext_Index_Content_IResourceDescriptions">7.1.1. Getting the Xtext Index (<code>IResourceDescriptions</code>) Content</a></li>
 </ul>
 </li>
 <li><a href="type_index.html#sec:Design_Overview">7.2. Design Overview</a></li>
 <li><a href="type_index.html#sec:N4JS_Resource_Load_States">7.3. N4JS Resource Load States</a></li>
 <li><a href="type_index.html#sec:Type_Builder">7.4. Types Builder</a>
 <ul class="sectlevel3">
 <li><a href="type_index.html#sec:Type_Inference_not_allowed_in_Type_Builder">7.4.1. Type Inference not allowed in Types Builder</a></li>
 <li><a href="type_index.html#sec:ComputedTypeReferences">7.4.2. Deferred Type References</a></li>
 <li><a href="type_index.html#sec:Use_cases_of_ComputedTypeRef">7.4.3. Use cases of DeferredTypeRef</a></li>
 </ul>
 </li>
 <li><a href="type_index.html#sec:Incremental_Builder_Overview">7.5. Incremental Builder (Overview)</a>
 <ul class="sectlevel3">
 <li><a href="type_index.html#sec:Incremental_Builder_Overview__XtextBuilder">7.5.1. XtextBuilder</a></li>
 <li><a href="type_index.html#sec:Incremental_Builder_Overview__IBuilderState">7.5.2. IBuilderState</a>
 <ul class="sectlevel4">
 <li><a href="type_index.html#copy-and-update-xtext-index">7.5.2.1. Copy and Update Xtext Index</a></li>
 <li><a href="type_index.html#build-state-setup-phase">7.5.2.2. Build State Setup Phase</a></li>
 <li><a href="type_index.html#process-queued-uris">7.5.2.3. Process Queued URIs</a></li>
 <li><a href="type_index.html#queueing-affected-resources">7.5.2.4. Queueing Affected Resources</a></li>
 </ul>
 </li>
 <li><a href="type_index.html#sec:Incremental_Builder_Overview__Example">7.5.3. Example</a></li>
 </ul>
 </li>
 <li><a href="type_index.html#dirty-state-handling">7.6. Dirty state handling</a>
 <ul class="sectlevel3">
 <li><a href="type_index.html#use-case-restoring-types-from-user-data">7.6.1. Use case: Restoring types from user data</a></li>
 <li><a href="type_index.html#use-case-updating-the-xtext-index">7.6.2. Use case: Updating the Xtext index</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="project_model.html#_project-model">8. Project Model</a>
 <ul class="sectlevel2">
 <li><a href="project_model.html#sec:Package_json">8.1. Package.json File</a></li>
 <li><a href="project_model.html#_accessing-project-information">8.2. Accessing Project Information</a>
 <ul class="sectlevel3">
 <li><a href="project_model.html#sec:IN4JSCore">8.2.1. IN4JSCore</a></li>
 <li><a href="project_model.html#sec:N4JSModel">8.2.2. N4JSModel</a></li>
 <li><a href="project_model.html#sec:N4JSWorkspace">8.2.3. N4JSWorkspace</a></li>
 <li><a href="project_model.html#sec:N4JSProject">8.2.4. N4JSProject</a></li>
 <li><a href="project_model.html#sec:SourceContainer">8.2.5. SourceContainer</a></li>
 <li><a href="project_model.html#sec:N4JSProjectsStateHelper">8.2.6. N4JSProjectsStateHelper</a></li>
 </ul>
 </li>
 <li><a href="project_model.html#sec:Caching">8.3. Caching</a>
 <ul class="sectlevel3">
 <li><a href="project_model.html#_caching-of-externallibraryworkspace">8.3.1. Caching of ExternalLibraryWorkspace</a></li>
 <li><a href="project_model.html#_caching-of-n4jsprojectsstatehelper">8.3.2. Caching of N4JSProjectsStateHelper</a></li>
 </ul>
 </li>
 <li><a href="project_model.html#sec:WildcardPathFilter">8.4. WildcardPathFilter</a></li>
 <li><a href="project_model.html#sec:ProjectUtils">8.5. ProjectUtils</a></li>
 </ul>
 </li>
 <li><a href="binding.html#_binding">9. Binding</a>
 <ul class="sectlevel2">
 <li><a href="binding.html#sec:Binding_Design_Rationale">9.1. Design Rationale</a></li>
 <li><a href="binding.html#sec:Binding_to_Members">9.2. Binding to Members</a></li>
 <li><a href="binding.html#sec:Binding_Getter_Setter">9.3. Getter / Setter Binding</a></li>
 <li><a href="binding.html#chap:Statics">9.4. Static Member Binding</a></li>
 <li><a href="binding.html#sec:Binding_Enumeration">9.5. Enumeration Literals Binding</a></li>
 <li><a href="binding.html#sec:Accessibility_of_types_and_members">9.6. Accessibility of types and members</a></li>
 <li><a href="binding.html#sec:Member_Scope_Example">9.7. Member Scope Example</a></li>
 <li><a href="binding.html#sec:Scoping_for_Members_of_Composed_Type_Explained">9.8. Scoping for Members of Composed Type (Union/Intersection) Example</a></li>
 <li><a href="binding.html#sec:Binding_of_Structurally_References_Types">9.9. Structurally References Types</a></li>
 <li><a href="binding.html#sec:Building">9.10. Building</a>
 <ul class="sectlevel3">
 <li><a href="binding.html#sec:Build_Phases">9.10.1. Build Phases</a></li>
 <li><a href="binding.html#sec:Build_Scenarios">9.10.2. Build Scenarios</a></li>
 <li><a href="binding.html#sec:Lazy_linking_problem">9.10.3. Lazy linking problem</a></li>
 </ul>
 </li>
 <li><a href="binding.html#sec:Proxies_and_Proxy_Resolution">9.11. Proxies and Proxy Resolution (Overview)</a>
 <ul class="sectlevel3">
 <li><a href="binding.html#xtexts-lazy-linking-proxies">9.11.1. Xtext’s Lazy Linking Proxies</a></li>
 <li><a href="binding.html#standard-emf-proxies">9.11.2. Standard EMF Proxies</a></li>
 <li><a href="binding.html#_how-is-proxy-resolution-triggered">9.11.3. How is Proxy Resolution Triggered?</a></li>
 <li><a href="binding.html#_when-is-proxy-resolution-allowed">9.11.4. When is Proxy Resolution Allowed?</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="validation.html#_validation">10. Validation</a>
 <ul class="sectlevel2">
 <li><a href="validation.html#sec:validation_overview">10.1. Validation overview</a></li>
 <li><a href="validation.html#sec:validation_control_flow">10.2. Validation control flow</a></li>
 <li><a href="validation.html#sec:validation_issue_ids">10.3. Issue IDs and Messages</a></li>
 <li><a href="validation.html#sec:validation_usage_patterns">10.4. Usage Pattern</a></li>
 <li><a href="validation.html#sec:validation_links">10.5. Links</a></li>
 </ul>
 </li>
 <li><a href="references.html#_references">11. References</a>
 <ul class="sectlevel2">
 <li><a href="references.html#sec:usecases">11.1. Use cases</a></li>
 <li><a href="references.html#sec:calculation_algorithm">11.2. Calculation algorithm</a>
 <ul class="sectlevel3">
 <li><a href="references.html#sec:Xtext_default_implementation">11.2.1. Xtext default implementation</a></li>
 <li><a href="references.html#sec:N4_implementation">11.2.2. N4JS implementation</a></li>
 </ul>
 </li>
 <li><a href="references.html#sec:PerformanceOfDependencyCalculation">11.3. Performance Of Dependency Calculation</a></li>
 <li><a href="references.html#sec:kinds_of_references">11.4. Kinds of references</a>
 <ul class="sectlevel3">
 <li><a href="references.html#sec:Cross_References_to_be_ignored">11.4.1. Cross References to be ignored</a></li>
 <li><a href="references.html#sec:Cross_References_to_be_handled">11.4.2. Cross References to be handled</a></li>
 </ul>
 </li>
 <li><a href="references.html#sec:transitive_dependencies">11.5. Transitive dependencies</a></li>
 <li><a href="references.html#sec:find-references">11.6. Find references</a>
 <ul class="sectlevel3">
 <li><a href="references.html#_background">11.6.1. Background</a></li>
 <li><a href="references.html#_how-find-references-work">11.6.2. How Find References Work</a>
 <ul class="sectlevel4">
 <li><a href="references.html#_step-1-convert-cursor-position-to-declared-element">11.6.2.1. Step 1: Convert Cursor Position to Declared Element</a></li>
 <li><a href="references.html#_step-2-convert-declared-element-to-target-uris">11.6.2.2. Step 2: Convert Declared Element to Target URIs</a></li>
 <li><a href="references.html#_step-3-filter-potential-resources">11.6.2.3. Step 3: Filter Potential Resources</a></li>
 <li><a href="references.html#_step-4-search-references-in-resource">11.6.2.4. Step 4: Search References in Resource</a></li>
 <li><a href="references.html#_limitations-and-possible-enhancements">11.6.2.5. Limitations and Possible Enhancements</a></li>
 </ul>
 </li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="compilation.html#_compilation">12. Compilation</a>
 <ul class="sectlevel2">
 <li><a href="compilation.html#chap:compilation">12.1. Introduction</a>
 <ul class="sectlevel3">
 <li><a href="compilation.html#sec:general_design_rationals">12.1.1. General design rationals</a>
 <ul class="sectlevel4">
 <li><a href="compilation.html#sec:logging_and_error_reporting">12.1.1.1. Logging and error reporting</a></li>
 <li><a href="compilation.html#sec:progress_monitor">12.1.1.2. Progress monitor</a></li>
 </ul>
 </li>
 <li><a href="compilation.html#sec:Xtext_Integration">12.1.2. Xtext Integration</a>
 <ul class="sectlevel4">
 <li><a href="compilation.html#sec:xtext_default_behaviour">12.1.2.1. Xtext default behaviour</a></li>
 <li><a href="compilation.html#sec:n4js_requirements">12.1.2.2. N4JS requirements</a></li>
 <li><a href="compilation.html#sec:compiler_discovery_in_ui">12.1.2.3. Compiler discovery in UI</a></li>
 <li><a href="compilation.html#sec:compiler_discovery_in_headless">12.1.2.4. Compiler discovery in headless</a></li>
 <li><a href="compilation.html#sec:general_generator_implementation">12.1.2.5. General generator implementation</a></li>
 <li><a href="compilation.html#sec:general_generator_activation">12.1.2.6. General generator activation</a></li>
 </ul>
 </li>
 <li><a href="compilation.html#sec:Overview_of_Input_Models">12.1.3. Overview of the Input Models</a></li>
 </ul>
 </li>
 <li><a href="compilation.html#sec:Core_Generator">12.2. Generators</a>
 <ul class="sectlevel3">
 <li><a href="compilation.html#sec:Compiler_Components">12.2.1. Generator Components</a></li>
 <li><a href="compilation.html#sec:Generator_architecture">12.2.2. Generator architecture</a></li>
 <li><a href="compilation.html#sec:Unified_Compiler_Configuration">12.2.3. Unified Compiler Configuration</a></li>
 </ul>
 </li>
 <li><a href="compilation.html#sec:Transpilers">12.3. Transpilers</a>
 <ul class="sectlevel3">
 <li><a href="compilation.html#sec:Phases">12.3.1. Overview</a></li>
 <li><a href="compilation.html#relation-between-ast-and-im">12.3.2. Relation between AST and IM</a></li>
 <li><a href="compilation.html#implementation-overview">12.3.3. Implementation Overview</a></li>
 <li><a href="compilation.html#sec:Guidelines_for_Implementing_Transformations">12.3.4. Guidelines for Implementing Transformations</a></li>
 <li><a href="compilation.html#symbol-table-in-the-im">12.3.5. Symbol Table in the IM</a></li>
 </ul>
 </li>
 <li><a href="compilation.html#sec:N4JS_to_EcmaScript_Transpiler">12.4. N4JS-to-EcmaScript Transpiler</a>
 <ul class="sectlevel3">
 <li><a href="compilation.html#sec:Overview_of_Transformations">12.4.1. Overview of Transformations</a></li>
 <li><a href="compilation.html#sec:Transpiling_members">12.4.2. Transpiling members</a>
 <ul class="sectlevel4">
 <li><a href="compilation.html#sec:Transpiling_members__Delegating_members">12.4.2.1. Techniques for special member handling</a></li>
 <li><a href="compilation.html#sec:Transpiling_members__Partial_shadowing_of_getter_setter_pairs">12.4.2.2. Partial shadowing</a></li>
 <li><a href="compilation.html#sec:Transpiling_members__Consuming_or_inheriting_members_of_an_interface">12.4.2.3. Consuming or inheriting members of an interface</a></li>
 <li><a href="compilation.html#sec:Transpiling_members__Static_polyfill">12.4.2.4. Static polyfill</a></li>
 <li><a href="compilation.html#sec:Transpiling_members__API_implementation_stubs">12.4.2.5. API / implementation stubs</a></li>
 </ul>
 </li>
 <li><a href="compilation.html#sec:Support_for_incomplete_API_implementation_testing_in_the_N4JS_to_EcmaScript_5_Transpiler">12.4.3. Support for incomplete API implementation testing</a>
 <ul class="sectlevel4">
 <li><a href="compilation.html#sec:Modifications_in_Impl_projects">12.4.3.1. Modifications in Impl projects</a></li>
 <li><a href="compilation.html#sec:Implementation_of_stub_generation">12.4.3.2. Implementation of stub-generation</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="compilation.html#sec:n4jsc_Headless_Compiler_Interface">12.5. n4jsc Headless Compiler Interface</a>
 <ul class="sectlevel3">
 <li><a href="compilation.html#sec:building_the_headless_compiler">12.5.1. building the headless compiler</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="#_execution">13. Execution</a>
 <ul class="sectlevel2">
 <li><a href="#sec:N4JS_Project_Execution_And_Linking_Model">13.1. N4JS Project Execution And Linking Model</a>
 <ul class="sectlevel3">
 <li><a href="#subsec:N4JS_Execution_With_NodeJS">13.1.1. N4JS Execution With NodeJS</a></li>
 </ul>
 </li>
 <li><a href="#sec:N4JS_Execution_And_Linking_File">13.2. N4JS Execution And Linking File</a>
 <ul class="sectlevel3">
 <li><a href="#subsec:NodeJS_Specific_ELF">13.2.1. NodeJS Specific ELF</a></li>
 </ul>
 </li>
 <li><a href="#sec:Runners-execution">13.3. Runners</a>
 <ul class="sectlevel3">
 <li><a href="#subsec:N4_Runtime_Environments_Convention">13.3.1. N4 Runtime Environments Convention</a></li>
 <li><a href="#subsec:Passing_Information_from_IDE_to_Execution_Code_in_Runtime_Environment">13.3.2. Passing Information from IDE to Execution Code in Runtime Environment</a></li>
 <li><a href="#subsec:Runners_Design">13.3.3. Runners Design</a></li>
 </ul>
 </li>
 <li><a href="#sec:Legacy_Execution_Engine">13.4. Legacy Execution Engine</a></li>
 <li><a href="#sec:Design">13.5. Design</a>
 <ul class="sectlevel3">
 <li><a href="#sec:Usage_Outside_N4JSIDE">13.5.1. Usage Outside N4JSIDE</a>
 <ul class="sectlevel4">
 <li><a href="#sec:Use_Node_with_Maven">13.5.1.1. Use Node with Maven</a></li>
 </ul>
 </li>
 <li><a href="#sec:Usage_Inside_N4JSIDE">13.5.2. Usage Inside N4JSIDE</a></li>
 </ul>
 </li>
 <li><a href="#sec:Runtime_Injection">13.6. Runtime Injection</a>
 <ul class="sectlevel3">
 <li><a href="#sec:Running_String_Code">13.6.1. Running String Code</a></li>
 <li><a href="#sec:Running_File_Code">13.6.2. Running File Code</a></li>
 <li><a href="#sec:Injection_Code_Example">13.6.3. Injection Code Example</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="tests.html#_tests">14. Tests</a>
 <ul class="sectlevel2">
 <li><a href="tests.html#sec:Performance_Tests">14.1. Performance Tests</a>
 <ul class="sectlevel3">
 <li><a href="tests.html#sec:Synthetic_Performance_Tests">14.1.1. Synthetic Performance Tests</a>
 <ul class="sectlevel4">
 <li><a href="tests.html#sec:Design_of_Generator">14.1.1.1. Design of Generator</a></li>
 <li><a href="tests.html#sec:Design_of_Performance_Test_Execution">14.1.1.2. Design of Performance Test Configuration and Execution</a></li>
 <li><a href="tests.html#sec:JUnit_Configuration">14.1.1.3. JUnit Configuration</a></li>
 <li><a href="tests.html#sec:JUnitBenchmark_Test_Configuration">14.1.1.4. JUnitBenchmark Test Configuration</a></li>
 <li><a href="tests.html#sec:JUnitBenchmark_Report_Configuration">14.1.1.5. JUnitBenchmark Report Configuration</a></li>
 <li><a href="tests.html#sec:JUnitBenchmark_Run_Configuration">14.1.1.6. JUnitBenchmark Run Configuration</a></li>
 <li><a href="tests.html#sec:JUnitBenchmark_Example">14.1.1.7. JUnitBenchmark Example</a></li>
 <li><a href="tests.html#sec:Note_on_Jenkins_Job">14.1.1.8. Note on Jenkins Job</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="tests.html#sec:ECMA_Tests">14.2. ECMA Tests</a>
 <ul class="sectlevel3">
 <li><a href="tests.html#sec:Grammar_Tests">14.2.1. Grammar Tests</a>
 <ul class="sectlevel4">
 <li><a href="tests.html#sec:Negative_Tests">14.2.1.1. Negative Tests</a></li>
 <li><a href="tests.html#sec:Test_Exclusion">14.2.1.2. Test Exclusion</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="tests.html#sec:Integration_Tests">14.3. Integration Tests</a></li>
 <li><a href="tests.html#sec:Test_Helpers">14.4. Test Helpers</a>
 <ul class="sectlevel3">
 <li><a href="tests.html#sec:Parameterized_N4JS_Tests">14.4.1. Parameterized N4JS tests</a>
 <ul class="sectlevel4">
 <li><a href="tests.html#sec:ParameterizedXtextRunner">14.4.1.1. ParameterizedXtextRunner</a></li>
 <li><a href="tests.html#sec:TestCodeProvider">14.4.1.2. TestCodeProvider</a></li>
 <li><a href="tests.html#sec:Example_Of_Parameterized_Parser_Test">14.4.1.3. Example of parameterized parser test</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="tests.html#sec:Issue_Suppression">14.5. Issue Suppression</a></li>
 <li><a href="tests.html#sec:Xpect_Tests">14.6. Xpect Tests</a>
 <ul class="sectlevel3">
 <li><a href="tests.html#sec:Xpect_Test_Setup">14.6.1. Xpect Test Setup</a></li>
 <li><a href="tests.html#sec:Xpect_Issue_Suppression">14.6.2. Xpect Issue Suppression</a></li>
 <li><a href="tests.html#sec:Xpect_Provided_Test_Methods">14.6.3. Xpect Provided Test Methods</a>
 <ul class="sectlevel4">
 <li><a href="tests.html#errors">14.6.3.1. errors</a></li>
 <li><a href="tests.html#warnings">14.6.3.2. warnings</a></li>
 </ul>
 </li>
 <li><a href="tests.html#sec:N4JS_Specific_Xpect_Test_Methods">14.6.4. N4JS Specific Xpect Test Methods</a>
 <ul class="sectlevel4">
 <li><a href="tests.html#sec:XPECT_noerrors">14.6.4.1. noerrors and nowarnings</a></li>
 <li><a href="tests.html#sec:XPECT_scope">14.6.4.2. scope</a></li>
 <li><a href="tests.html#sec:XPECT_scopeWithPosition">14.6.4.3. scopeWithPosition</a></li>
 <li><a href="tests.html#sec:XPECT_scopeWithResource">14.6.4.4. scopeWithResource</a></li>
 <li><a href="tests.html#sec:XPECT_binding">14.6.4.5. binding</a></li>
 <li><a href="tests.html#sec:XPECT_linkedPathname">14.6.4.6. linkedPathname</a></li>
 <li><a href="tests.html#sec:XPECT_type_of">14.6.4.7. type of</a></li>
 <li><a href="tests.html#sec:XPECT_expectedType">14.6.4.8. expectedType</a></li>
 <li><a href="tests.html#sec:XPECT_elementKeyword">14.6.4.9. elementKeyword</a></li>
 <li><a href="tests.html#sec:XPECT_accessModifier">14.6.4.10. accessModifier</a></li>
 <li><a href="tests.html#sec:XPECT_compileResult">14.6.4.11. compileResult</a></li>
 <li><a href="tests.html#sec:XPECT_output">14.6.4.12. output</a></li>
 <li><a href="tests.html#sec:XPECT_outputRegEx">14.6.4.13. outputRegEx</a></li>
 <li><a href="tests.html#sec:XPECT_calculatedAccessModifier">14.6.4.14. calculatedAccessModifier</a></li>
 <li><a href="tests.html#sec:XPECT_spec">14.6.4.15. spec</a></li>
 <li><a href="tests.html#sec:XPECT_deadCode">14.6.4.16. deadCode</a></li>
 <li><a href="tests.html#sec:XPECT_returnOrThrows">14.6.4.17. returnOrThrows</a></li>
 <li><a href="tests.html#sec:XPECT_lint">14.6.4.18. lint</a></li>
 <li><a href="tests.html#sec:XPECT_lintFails">14.6.4.19. lintFails</a></li>
 </ul>
 </li>
 <li><a href="tests.html#sec:FIXME_Xpect_modifier">14.6.5. FIXME Xpect modifier</a></li>
 <li><a href="tests.html#sec:Expectmatrix_Xpect_Test_Methods">14.6.6. Expectmatrix Xpect tests</a></li>
 <li><a href="tests.html#xpect-lint-tests">14.6.7. Xpect Lint Tests</a></li>
 </ul>
 </li>
 <li><a href="tests.html#xpect-proposal-tests">14.7. Xpect Proposal Tests</a>
 <ul class="sectlevel3">
 <li><a href="tests.html#sec:Validation_vs__Non_Validation">14.7.1. Validation vs. Non-Validation</a></li>
 <li><a href="tests.html#sec:General_Proposal_Test_Features">14.7.2. General Proposal Test Features</a>
 <ul class="sectlevel4">
 <li><a href="tests.html#sec:Test_Variables">14.7.2.1. Test Variables</a></li>
 <li><a href="tests.html#sec:Location_and_Selection">14.7.2.2. at – Location and Selection</a></li>
 <li><a href="tests.html#sec:Multi_Line_Expectations_in_Proposal_Tests">14.7.2.3. Multi Line Expectations in Proposal Tests</a></li>
 <li><a href="tests.html#sec:Timeout">14.7.2.4. Timeout and Performance</a></li>
 </ul>
 </li>
 <li><a href="tests.html#proposals-verify-existence-of-proposals">14.7.3. proposals – Verify Existence of Proposals</a></li>
 <li><a href="tests.html#sec:Verify_displayed_string">14.7.4. display – Verify displayed string</a></li>
 <li><a href="tests.html#sec:Apply_Proposal">14.7.5. apply – Apply Proposal</a>
 <ul class="sectlevel4">
 <li><a href="tests.html#resource-application-in-other-files">14.7.5.1. resource – application in other files</a></li>
 </ul>
 </li>
 <li><a href="tests.html#sec:Content_Assist_Cycling">14.7.6. kind – Content Assist Cycling</a></li>
 <li><a href="tests.html#fileValidVerify-validation-status">14.7.7. fileValid – Verify validation status</a></li>
 </ul>
 </li>
 <li><a href="tests.html#sec:Apply_Proposal_And_Execute_Tests">14.8. Apply Proposal And Execute Tests</a></li>
 <li><a href="tests.html#sec:Organize_Imports_Test">14.9. Organize Imports Test</a>
 <ul class="sectlevel3">
 <li><a href="tests.html#organizeimports">14.9.1. organizeImports</a></li>
 </ul>
 </li>
 <li><a href="tests.html#sec:Access_Control_Test">14.10. Access Control Test</a>
 <ul class="sectlevel3">
 <li><a href="tests.html#test-scenarios">14.10.1. Test Scenarios</a></li>
 <li><a href="tests.html#n4js-code-generator">14.10.2. N4JS Code Generator</a></li>
 <li><a href="tests.html#xtext-issue-matcher">14.10.3. Xtext Issue Matcher</a></li>
 </ul>
 </li>
 <li><a href="tests.html#sec:Smoke_Tests">14.11. Smoke Tests</a>
 <ul class="sectlevel3">
 <li><a href="tests.html#how-to-handle-smoke-test-errors">14.11.1. How to handle smoke test errors?</a></li>
 <li><a href="tests.html#smoketester-and-exceptionanalyzer">14.11.2. SmokeTester and ExceptionAnalyzer</a></li>
 </ul>
 </li>
 <li><a href="tests.html#sec:UI_Tests_with_SWTBot">14.12. UI Tests with SWTBot</a>
 <ul class="sectlevel3">
 <li><a href="tests.html#writing-swtbot-tests">14.12.1. Writing SWTBot Tests</a></li>
 <li><a href="tests.html#running-swtbot-tests">14.12.2. Running SWTBot Tests</a></li>
 </ul>
 </li>
 <li><a href="tests.html#sec:Debugging_UI_Tests">14.13. Debugging UI Tests</a>
 <ul class="sectlevel3">
 <li><a href="tests.html#sec:Connecting_to_the_X_server_on_the_build_node">14.13.1. Connecting to the X-server on the build-node</a></li>
 <li><a href="tests.html#sec:Tools_to_investigate_the_java_stack">14.13.2. Tools to investigate the java-stack</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="ui_concepts.html#_ui-concepts">15. UI Concepts</a>
 <ul class="sectlevel2">
 <li><a href="ui_concepts.html#sec:User_Interface_Concepts">15.1. User Interface Concepts</a>
 <ul class="sectlevel3">
 <li><a href="ui_concepts.html#sec:Eclipse_UI_Concepts">15.1.1. Eclipse UI Concepts</a>
 <ul class="sectlevel4">
 <li><a href="ui_concepts.html#sec:Label_Provider">15.1.1.1. Label Provider</a></li>
 <li><a href="ui_concepts.html#sec:Markers">15.1.1.2. Markers</a></li>
 <li><a href="ui_concepts.html#sec:Commands__Toolbar_and_Menus">15.1.1.3. Commands, Toolbar and Menus</a></li>
 <li><a href="ui_concepts.html#sec:Content_Assist">15.1.1.4. Content Assist</a></li>
 <li><a href="ui_concepts.html#sec:Quick_Fixes">15.1.1.5. Quick Fixes</a></li>
 <li><a href="ui_concepts.html#sec:Quick_Assist">15.1.1.6. Quick Assist</a></li>
 <li><a href="ui_concepts.html#sec:Clean_Up_Actions">15.1.1.7. Clean Up Actions</a></li>
 <li><a href="ui_concepts.html#sec:Save_Actions">15.1.1.8. Save Actions</a></li>
 <li><a href="ui_concepts.html#sec:Auto_Edit">15.1.1.9. Auto Edit</a></li>
 <li><a href="ui_concepts.html#sec:Template_Proposals">15.1.1.10. Template Proposals</a></li>
 <li><a href="ui_concepts.html#sec:Outline_View___Quick_Outline">15.1.1.11. Outline View / Quick Outline</a></li>
 <li><a href="ui_concepts.html#sec:Navigator__Package_Explorer__Project_Explorer">15.1.1.12. Navigator, Package Explorer, Project Explorer</a></li>
 <li><a href="ui_concepts.html#sec:Hyperlinking_and_Navigation">15.1.1.13. Hyperlinking and Navigation</a></li>
 <li><a href="ui_concepts.html#sec:Syntax_and_Semantic_Coloring">15.1.1.14. Syntax and Semantic Coloring</a></li>
 <li><a href="ui_concepts.html#sec:Code_Formatter">15.1.1.15. Code Formatter</a></li>
 <li><a href="ui_concepts.html#sec:Wizards">15.1.1.16. Wizards</a></li>
 <li><a href="ui_concepts.html#sec:Cheat_Sheets">15.1.1.17. Cheat Sheets</a></li>
 <li><a href="ui_concepts.html#sec:Context_sensitive_Help">15.1.1.18. Context-sensitive Help</a></li>
 <li><a href="ui_concepts.html#sec:Hovers">15.1.1.19. Hovers</a></li>
 <li><a href="ui_concepts.html#sec:Folding">15.1.1.20. Folding</a></li>
 <li><a href="ui_concepts.html#sec:Customizable_validation___severity">15.1.1.21. Customizable validation / severity</a></li>
 <li><a href="ui_concepts.html#sec:Proposals">15.1.1.22. Proposals</a></li>
 </ul>
 </li>
 <li><a href="ui_concepts.html#sec:Non_Eclipse_UI_Concepts">15.1.2. Non-Eclipse UI Concepts</a>
 <ul class="sectlevel4">
 <li><a href="ui_concepts.html#sec:Overlays">15.1.2.1. Overlays</a></li>
 <li><a href="ui_concepts.html#sec:Goto__Inferred__Type">15.1.2.2. Goto (Inferred) Type</a></li>
 <li><a href="ui_concepts.html#sec:Postfix_Completion">15.1.2.3. Postfix Completion</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="ui_concepts.html#_user-interface-resources">15.2. User Interface Resources</a>
 <ul class="sectlevel3">
 <li><a href="ui_concepts.html#_icons">15.2.1. Icons</a>
 <ul class="sectlevel4">
 <li><a href="ui_concepts.html#_eclipse-platform-icons">15.2.1.1. Eclipse Platform Icons</a></li>
 <li><a href="ui_concepts.html#_n4js-specific-icons">15.2.1.2. N4JS Specific Icons</a></li>
 <li><a href="ui_concepts.html#_high-resolution-icons">15.2.1.3. High Resolution Icons</a></li>
 </ul>
 </li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="formatting.html#_formatting">16. Formatting</a>
 <ul class="sectlevel2">
 <li><a href="formatting.html#sec:FmtObjective">16.1. Objective</a>
 <ul class="sectlevel3">
 <li><a href="formatting.html#sec:FmtFormatting_Comments">16.1.1. Formatting Comments</a></li>
 </ul>
 </li>
 <li><a href="formatting.html#sec:FmtArchitecture">16.2. Architecture</a>
 <ul class="sectlevel3">
 <li><a href="formatting.html#sec:Implementation_example">16.2.1. Implementation example</a></li>
 </ul>
 </li>
 <li><a href="formatting.html#sec:FmtFormatter_Implementation_Guidelines">16.3. Formatter Implementation Guidelines</a></li>
 <li><a href="formatting.html#sec:FmtConfiguration">16.4. Configuration</a></li>
 <li><a href="formatting.html#sec:FmtUI_Integration">16.5. UI Integration</a></li>
 <li><a href="formatting.html#sec:FmtUnit_Testing_with_Xpect">16.6. Unit Testing with Xpect</a></li>
 </ul>
 </li>
 <li><a href="external_libraries.html#_external-libraries">17. External Libraries</a>
 <ul class="sectlevel2">
 <li><a href="external_libraries.html#sec:Major_Components">17.1. Major Components</a>
 <ul class="sectlevel3">
 <li><a href="external_libraries.html#subsec:External_Resources">17.1.1. External Resources</a></li>
 <li><a href="external_libraries.html#subsec:External_Library_Workspace">17.1.2. External Library Workspace</a></li>
 <li><a href="external_libraries.html#subsec:External_Library_Preference_Store">17.1.3. External Library Preference Store</a></li>
 <li><a href="external_libraries.html#subsec:npm_Manager">17.1.4. Library Manager</a></li>
 <li><a href="external_libraries.html#subsec:External_Library_Builder_Helper">17.1.5. External Library Builder</a></li>
 <li><a href="external_libraries.html#subsec:External_Library_Xtext_Index_Persister">17.1.6. External Library Xtext Index Persister</a></li>
 <li><a href="external_libraries.html#subsec:External_Library_Preference_Page">17.1.7. External Library Preference Page</a></li>
 </ul>
 </li>
 <li><a href="external_libraries.html#sec:Headless_External_Library_Support">17.2. Headless External Library Support</a>
 <ul class="sectlevel3">
 <li><a href="external_libraries.html#_custom-npm-settings">17.2.1. Custom npm settings</a></li>
 </ul>
 </li>
 <li><a href="external_libraries.html#sec:lmFutureWork">17.3. Future Work</a>
 <ul class="sectlevel3">
 <li><a href="external_libraries.html#subsec:lmMultipleDependencyScope">17.3.1. Multiple Dependency Scope</a></li>
 <li><a href="external_libraries.html#subsec:lmRunTestsFromLibrary">17.3.2. Run Tests from TestLibrary</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="json_support.html#sec:JSON_Support">18. JSON Support</a>
 <ul class="sectlevel2">
 <li><a href="json_support.html#sec:JSON_Parser">18.1. JSON Parser</a>
 <ul class="sectlevel3">
 <li><a href="json_support.html#sec:JSON_Parser_Unicode_Escaping">18.1.1. Escaping Unicode Control Characters in String Literals</a></li>
 <li><a href="json_support.html#sec:JSON_Parser_Empty_Text">18.1.2. Empty Text</a></li>
 <li><a href="json_support.html#sec:JSON_Parser_Nested_Structures">18.1.3. Nested Structures</a></li>
 <li><a href="json_support.html#sec:JSON_Parser_Whitespace">18.1.4. Whitespace</a></li>
 <li><a href="json_support.html#sec:JSON_Parser_Comments">18.1.5. Comments</a></li>
 </ul>
 </li>
 <li><a href="json_support.html#sec:JSON_Language_Extensions">18.2. JSON Language Extensions</a>
 <ul class="sectlevel3">
 <li><a href="json_support.html#sec:JSON_Validator_Extensions">18.2.1. JSON Validator Extensions</a>
 <ul class="sectlevel4">
 <li><a href="json_support.html#sec:File_Specitic_Validator_Extensions">18.2.1.1. File-Specific Validator Extensions</a></li>
 <li><a href="json_support.html#sec:JSON_Declarative_JSON_Validator_Extensions">18.2.1.2. Declarative JSON Validator Extensions</a></li>
 </ul>
 </li>
 <li><a href="json_support.html#_json-resource-description-strategy">18.2.2. JSON Resource Description Strategy</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="jsdoc.html#_jsdoc">19. JSDoc</a>
 <ul class="sectlevel2">
 <li><a href="jsdoc.html#sec:Design_Rationale">19.1. Design Rationale</a>
 <ul class="sectlevel3">
 <li><a href="jsdoc.html#_general-design">19.1.1. General Design</a></li>
 <li><a href="jsdoc.html#sec:Type_Expressions">19.1.2. Type Expressions</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="docexporter.html#_docexporter">20. DocExporter</a>
 <ul class="sectlevel2">
 <li><a href="docexporter.html#sec:Specification_Exporter">20.1. Specification Exporter</a></li>
 </ul>
 </li>
 <li><a href="rename_refactoring.html#_rename-refactoring">21. Rename Refactoring</a>
 <ul class="sectlevel2">
 <li><a href="rename_refactoring.html#_rename-refactoring-ui-interaction">21.1. Rename Refactoring UI interaction</a></li>
 <li><a href="rename_refactoring.html#_renameelementprocessor-interaction">21.2. RenameElementProcessor interaction</a></li>
 </ul>
 </li>
 <li><a href="flow_graphs.html#chap:flowgraphs">22. Flow Graphs</a>
 <ul class="sectlevel2">
 <li><a href="flow_graphs.html#sec:flowgraphs_overview">22.1. Flow graphs overview</a>
 <ul class="sectlevel3">
 <li><a href="flow_graphs.html#_internal-graph">22.1.1. Internal graph</a></li>
 <li><a href="flow_graphs.html#_optimizations">22.1.2. Optimizations</a></li>
 <li><a href="flow_graphs.html#_api-for-client-analyses">22.1.3. API for client analyses</a>
 <ul class="sectlevel4">
 <li><a href="flow_graphs.html#_mapping-from-internal-to-ast-elements">22.1.3.1. Mapping from internal to AST elements</a></li>
 <li><a href="flow_graphs.html#_graph-visitor">22.1.3.2. Graph visitor</a></li>
 <li><a href="flow_graphs.html#_graph-explorer">22.1.3.3. Graph explorer</a></li>
 <li><a href="flow_graphs.html#_branch-walker">22.1.3.4. Branch walker</a></li>
 <li><a href="flow_graphs.html#_example-1-compute-string-for-each-path">22.1.3.5. Example 1: Compute string for each path</a></li>
 <li><a href="flow_graphs.html#_path-quantor">22.1.3.6. Path quantor</a></li>
 </ul>
 </li>
 <li><a href="flow_graphs.html#_control-flow-analyses">22.1.4. Control flow analyses</a>
 <ul class="sectlevel4">
 <li><a href="flow_graphs.html#_dead-code-analysis">22.1.4.1. Dead code analysis</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="flow_graphs.html#sec:dataflow">22.2. Dataflow</a>
 <ul class="sectlevel3">
 <li><a href="flow_graphs.html#_dataflow-graph">22.2.1. Dataflow graph</a></li>
 <li><a href="flow_graphs.html#_dataflow-analyses">22.2.2. Dataflow analyses</a>
 <ul class="sectlevel4">
 <li><a href="flow_graphs.html#_def-def-def-nothing-analysis">22.2.2.1. Def&#8594;Def / Def&#8594;Nothing analysis</a></li>
 <li><a href="flow_graphs.html#_def-use-decl-analysis">22.2.2.2. Def|Use&#8592;Decl analysis</a></li>
 </ul>
 </li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="publish_npms.html#sec:publish-npms-to-public">23. Publish npms</a>
 <ul class="sectlevel2">
 <li><a href="publish_npms.html#sec:publish-npms-n4js-maven">23.1. Publish n4js-libs to during  maven build</a></li>
 </ul>
 </li>
 <li><a href="appendix_a_hints.html#sec:Hints">Appendix A: Hints</a>
 <ul class="sectlevel2">
 <li><a href="appendix_a_hints.html#sec:XtextInjection">A.1. Xtext Injection</a>
 <ul class="sectlevel3">
 <li><a href="appendix_a_hints.html#sec:DI_MultipleInjectors_Singletons">A.1.1. Multiple Injectors and Singletons</a>
 <ul class="sectlevel4">
 <li><a href="appendix_a_hints.html#sec:DI_avoid_duplicate_singletons">A.1.1.1. Avoiding duplicate singletons</a>
 <ul class="sectlevel5">
 <li><a href="appendix_a_hints.html#sec:DI_binding_in_shared">A.1.1.1.1. Defining binding in the shared injector</a></li>
 <li><a href="appendix_a_hints.html#sec:DI_binding_in_custom">A.1.1.1.2. Defining binding in the custom injector</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="appendix_a_hints.html#sec:DI_Hints">A.1.2. Dependency Injection Hints</a>
 <ul class="sectlevel4">
 <li><a href="appendix_a_hints.html#sec:DI_custom_bundle">A.1.2.1. Use DI in custom bundle, use DI with extensions</a>
 <ul class="sectlevel5">
 <li><a href="appendix_a_hints.html#sec:DI_custom_bundle_problem">A.1.2.1.1. Problem</a></li>
 <li><a href="appendix_a_hints.html#sec:DI_custom_bundle_solution">A.1.2.1.2. Solution</a></li>
 </ul>
 </li>
 <li><a href="appendix_a_hints.html#sec:Access_Other_DSL_Injector">A.1.2.2. How do I get the Guice Injector of my language?</a>
 <ul class="sectlevel5">
 <li><a href="appendix_a_hints.html#sec:DSL_Injector_UI_context">A.1.2.2.1. UI context</a></li>
 <li><a href="appendix_a_hints.html#sec:DSL_Injector_Non_UI_context">A.1.2.2.2. Non UI context but with injection context</a></li>
 <li><a href="appendix_a_hints.html#sec:DSL_Injector_Non_UI_non_injection_context">A.1.2.2.3. Non UI context without injection context</a></li>
 </ul>
 </li>
 <li><a href="appendix_a_hints.html#sec:Cancel_Indicator">A.1.2.3. How do I get cancel indicators in different contexts?</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="appendix_a_hints.html#sec:Eclipse">A.2. Eclipse</a>
 <ul class="sectlevel3">
 <li><a href="appendix_a_hints.html#sec:Show_Xtext_Index">A.2.1. Show the current Xtext index</a></li>
 <li><a href="appendix_a_hints.html#sec:Plugin_spy">A.2.2. Plug-in spy</a></li>
 </ul>
 </li>
 <li><a href="appendix_a_hints.html#sec:Maven-hints">A.3. Maven</a>
 <ul class="sectlevel3">
 <li><a href="appendix_a_hints.html#how-to-check-for-maven-mojo-updates">A.3.1. How to check for Maven MOJO updates</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="appendix_b_module_loading.html#_module-loading">Appendix B: Module Loading</a>
 <ul class="sectlevel2">
 <li><a href="appendix_b_module_loading.html#sec:Dependency_Management">B.1. Dependency Management</a></li>
 <li><a href="appendix_b_module_loading.html#ecmascript-modules">B.2. ECMAScript Modules</a>
 <ul class="sectlevel3">
 <li><a href="appendix_b_module_loading.html#sec:ES5_Modules_Systems">B.2.1. ES5 Modules Systems</a></li>
 <li><a href="appendix_b_module_loading.html#sec:ES6_Modules">B.2.2. ES6 Modules</a></li>
 </ul>
 </li>
 <li><a href="appendix_b_module_loading.html#sec:ECMAScript_Module_Loaders">B.3. ECMAScript Module Loaders</a>
 <ul class="sectlevel3">
 <li><a href="appendix_b_module_loading.html#sec:ES6_Module_Loaders">B.3.1. ES6 Module Loaders</a></li>
 <li><a href="appendix_b_module_loading.html#sec:Polyfills_for_ES6_Module_Loaders">B.3.2. Polyfills for ES6 Module Loaders</a>
 <ul class="sectlevel4">
 <li><a href="appendix_b_module_loading.html#sec:es6_module_loader">B.3.2.1. es6-module-loader</a></li>
 <li><a href="appendix_b_module_loading.html#sec:SystemJS">B.3.2.2. SystemJS</a></li>
 <li><a href="appendix_b_module_loading.html#sec:Demo">B.3.2.3. Demo</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="appendix_b_module_loading.html#case-study-typescript">B.4. Case Study : TypeScript</a>
 <ul class="sectlevel3">
 <li><a href="appendix_b_module_loading.html#sec:ES6_Modules_Support">B.4.1. ES6 Modules Support</a></li>
 <li><a href="appendix_b_module_loading.html#sec:TypeScript_and_Module_Loading">B.4.2. TypeScript and Module Loading</a></li>
 </ul>
 </li>
 <li><a href="appendix_b_module_loading.html#sec:Cyclic_Dependencies">B.5. Cyclic Dependencies</a>
 <ul class="sectlevel3">
 <li><a href="appendix_b_module_loading.html#sec:Setup">B.5.1. Setup</a></li>
 <li><a href="appendix_b_module_loading.html#sec:Transpile_and_Execute">B.5.2. Transpile and Execute</a>
 <ul class="sectlevel4">
 <li><a href="appendix_b_module_loading.html#sec:Module_Format___AMD">B.5.2.1. Module Format = AMD</a></li>
 <li><a href="appendix_b_module_loading.html#sec:Module_Format___CommonJS">B.5.2.2. Module Format = CommonJS</a></li>
 <li><a href="appendix_b_module_loading.html#sec:Module_Format___SystemJS">B.5.2.3. Module Format = SystemJS</a></li>
 </ul>
 </li>
 <li><a href="appendix_b_module_loading.html#sec:Conclusion">B.5.3. Conclusion</a></li>
 </ul>
 </li>
 <li><a href="appendix_b_module_loading.html#system.register-as-transpilation-target">B.6. System.register as transpilation target</a>
 <ul class="sectlevel3">
 <li><a href="appendix_b_module_loading.html#sec:Introduction">B.6.1. Introduction</a>
 <ul class="sectlevel4">
 <li><a href="appendix_b_module_loading.html#sec:External_Transpilers">B.6.1.1. External Transpilers</a></li>
 <li><a href="appendix_b_module_loading.html#sec:Example_of_a_System_register_module">B.6.1.2. Example of a System.register module</a></li>
 </ul>
 </li>
 <li><a href="appendix_b_module_loading.html#sec:Structure_of_a_System_register_module">B.6.2. Structure of a System.register module</a></li>
 <li><a href="appendix_b_module_loading.html#_transpilation-hints">B.6.3. Transpilation Hints</a>
 <ul class="sectlevel4">
 <li><a href="appendix_b_module_loading.html#sec:Handling_Imports">B.6.3.1. Handling Imports</a></li>
 <li><a href="appendix_b_module_loading.html#sec:__exportFn__">B.6.3.2. &lt;&lt;exportFn&gt;&gt;</a></li>
 <li><a href="appendix_b_module_loading.html#sec:Handling_Exports">B.6.3.3. Handling Exports</a></li>
 </ul>
 </li>
 <li><a href="appendix_b_module_loading.html#sec:Examples_w__Circular_Dependencies">B.6.4. Examples w/ Circular Dependencies</a></li>
 <li><a href="appendix_b_module_loading.html#sec:N4JS_Examples_w__Circular_Dependencies">B.6.5. N4JS Examples w/ Circular Dependencies</a>
 <ul class="sectlevel4">
 <li><a href="appendix_b_module_loading.html#sec:Unresolved_Cyclic_Dependencies">B.6.5.1. Unresolved Cyclic Dependencies</a></li>
 <li><a href="appendix_b_module_loading.html#sec:Variables___Functions">B.6.5.2. Examples with Variables &amp; Functions</a></li>
 <li><a href="appendix_b_module_loading.html#sec:Classes">B.6.5.3. Examples with Classes</a></li>
 <li><a href="appendix_b_module_loading.html#sec:Examples_with_SubClassing">B.6.5.4. Examples with SubClassing</a></li>
 <li><a href="appendix_b_module_loading.html#sec:Miscellaneous">B.6.5.5. Miscellaneous</a></li>
 </ul>
 </li>
 <li><a href="appendix_b_module_loading.html#_resources">B.6.6. Resources</a></li>
 </ul>
 </li>
 <li><a href="appendix_b_module_loading.html#sec:CommonJS_as_transpilation_target">B.7. CommonJS as transpilation target</a>
 <ul class="sectlevel3">
 <li><a href="appendix_b_module_loading.html#_introduction-2">B.7.1. Introduction</a></li>
 <li><a href="appendix_b_module_loading.html#sec:Transpilation_Hints">B.7.2. Transpilation Hints</a>
 <ul class="sectlevel4">
 <li><a href="appendix_b_module_loading.html#sec:Import_Statements">B.7.2.1. Import Statements</a></li>
 <li><a href="appendix_b_module_loading.html#sec:Export_Statements">B.7.2.2. Export Statements</a></li>
 <li><a href="appendix_b_module_loading.html#sec:Tracking_Live_Bindings">B.7.2.3. Tracking Live Bindings</a></li>
 <li><a href="appendix_b_module_loading.html#sec:A_complete_example">B.7.2.4. A complete example</a></li>
 </ul>
 </li>
 <li><a href="appendix_b_module_loading.html#_resources-2">B.7.3. Resources</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li><a href="appendix_c_license.html#sec:License">Appendix C: License</a></li>
 <li><a href="appendix_d_acronyms.html#sec:Acronyms">Appendix D: Acronyms</a></li>
 <li><a href="appendix_e_bibliography_and_footnotes.html#_bibliography-and-footnotes">Appendix E: Bibliography and Footnotes</a></li>
 </ul>
 </div>
 </div>
 <div id="content"><div class="sect1">
 <h2 id="_execution"><a class="anchor" href="#_execution"></a><a class="link" href="#_execution">13. Execution</a></h2>
 <div class="sectionbody">
 <div class="admonitionblock warning">
 <table>
 <tr>
 <td class="icon">
 <i class="fa icon-warning" title=""></i>
 </td>
 <td class="content">
 This chapter may be outdated.
 </td>
 </tr>
 </table>
 </div>
 <div class="paragraph">
 <p>There are many different use cases for executing N4JS code:</p>
 </div>
 <div class="ulist">
 <ul>
 <li>
 <p>running project locally</p>
 </li>
 <li>
 <p>running tests in CI</p>
 </li>
 <li>
 <p>running application in the client</p>
 </li>
 <li>
 <p>running processor on the server</p>
 </li>
 </ul>
 </div>
 <div class="paragraph">
 <p>All those use cases may differ in their details, but can be divided into general phases:</p>
 </div>
 <div class="olist arabic">
 <ol class="arabic">
 <li>
 <p>execution environment preparation</p>
 </li>
 <li>
 <p>bootstrapping</p>
 </li>
 <li>
 <p>call to given n4js entry point</p>
 </li>
 <li>
 <p>shutdown (optional)</p>
 </li>
 </ol>
 </div>
 <div class="paragraph">
 <p>When N4JS execution is triggered, proper <em>Runner</em> (see <a href="#sec:Runners-introduction">Runners</a>) is selected. In some cases it is done automatically, in others user needs to make a choice. Runner is responsible for perform all required preparations, according to <a href="#sec:N4JS_Project_Execution_And_Linking_Model">N4JS Project Execution And Linking Model</a>. Then JS execution environment (e.g. NodeJS, IOJS, Chrome, JavaScriptCore) performs bootstrapping according to <a href="#sec:N4JS_Execution_And_Linking_File">N4JS Execution And Linking File</a>. As last step of bootstrap phase defend n4js entry point will be called which starts proper n4js execution phase. In some cases there may be shutdown phase, but that is highly dependent on use case and proceeding execution phases.</p>
 </div>
 <div class="sect2 language-n4js">
 <h3 id="sec:N4JS_Project_Execution_And_Linking_Model"><a class="anchor" href="#sec:N4JS_Project_Execution_And_Linking_Model"></a><a class="link" href="#sec:N4JS_Project_Execution_And_Linking_Model">13.1. N4JS Project Execution And Linking Model</a></h3>
 <div class="paragraph">
 <p>N4JS project is compiled to JavaScript language, that in turn can be executed in some JS execution environment, Those environments (e.g. NodeJS, IOJS, Chrome, JavaScriptCore) will differ between each other in terms of JS APIs they expose and way JS code has to be provided to them, or the way it is triggered. We introduced systematic way of describing those features in terms of N4JS projects (see Components and Projects <a href="#sec:N4_Components_and_IDE_Support">Components and IDE Support</a>). N4JS project will be of different <em>PojectType</em> that determines project purpose (see Package.json section <a href="project_model.html#sec:Package_json">Package.json File</a>. When we want to execute some N4JS project, we can divide its dependency graph into 4 general areas</p>
 </div>
 <div class="olist arabic">
 <ol class="arabic">
 <li>
 <p>User Space, e.g. user code</p>
 </li>
 <li>
 <p>System Space, e.g N4 Platform APIs</p>
 </li>
 <li>
 <p>Runtime Space, e.g. EcmaScript APIs</p>
 </li>
 <li>
 <p>Environment Space, e.g. execution environment APIs</p>
 </li>
 </ol>
 </div>
 <div class="paragraph">
 <p>Example of that kind of graph can bee seen on <a href="#fig:od_sampleProjectDependencyGraph">Sample Project Dependency Graph</a></p>
 </div>
 <div id="fig:od_sampleProjectDependencyGraph" class="imageblock center">
 <div class="content">
 <img src="chapters/14_execution/images/od_sampleProjectDependencyGraph.svg" alt="od sampleProjectDependencyGraph">
 </div>
 <div class="title">Figure 37. Sample Project Dependency Graph</div>
 </div>
 <div class="paragraph">
 <p>All dependencies are compile time dependency (as they are checked by the compiler), but <em>tend</em> to weaken, the lower in the dependency graph we are. <em>User Space</em> objects will have strong load time and run time dependency to each other and to the <em>System Space</em>. <em>System Space</em> have strong load time and run time dependency to each other and, only runtime dependency to <em>Runtime Space</em>. <em>Runtime Space</em> objects should not have any load time dependencies between each other. In some cases they may have weak runtime dependency to each other. In many cases those components are just api definitions that describe execution environment native apis, but may contain polyfills code. <em>Environment Space</em> has no dependency to other components, except the fact different <em>RuntimeEnvironemnt</em>s can extend each other (see <a href="#sec:N4_Components_and_IDE_Support">[sec:N4_Components_and_IDE_Support]</a>).</p>
 </div>
 <div class="paragraph">
 <p>Runner must configure JS execution environment in the way that all above areas of the dependency graph must be either</p>
 </div>
 <div class="ulist">
 <ul>
 <li>
 <p>provided by execution environment itself (runtime libraries APIs - <em>n4jsd</em> files)</p>
 </li>
 <li>
 <p>loaded by defined runtime environment (self initialisation code)</p>
 </li>
 <li>
 <p>available to load by environment explicitly (runtime libraries polyfills, system libraries)</p>
 </li>
 <li>
 <p>available to load by other implicitly (system libraries, user libraries and projects)</p>
 </li>
 </ul>
 </div>
 <div class="paragraph">
 <p>Testers, the same way as runners, must be able to execute n4js code. Main difference is that dependency graph for test case will be usually slightly bigger (dependencies to test libraries), and code that has to be triggered shifts a bit from given project to test library used in test code of tested project. Extending previously used example with test elements is shown in figure <a href="#fig:od_sampleTestProjectDependencyGraph2">Sample Test Project Dependency Graph</a>.</p>
 </div>
 <div id="fig:od_sampleTestProjectDependencyGraph2" class="imageblock center">
 <div class="content">
 <img src="chapters/14_execution/images/od_sampleTestProjectDependencyGraph.svg" alt="od sampleTestProjectDependencyGraph">
 </div>
 <div class="title">Figure 38. Sample Test Project Dependency Graph</div>
 </div>
 <div id="fig:runners-testers" class="imageblock center">
 <div class="content">
 <img src="chapters/14_execution/images/runners-testers.svg" alt="runners testers">
 </div>
 <div class="title">Figure 39. Runners and Testers</div>
 </div>
 <div class="sect3 language-n4js">
 <h4 id="subsec:N4JS_Execution_With_NodeJS"><a class="anchor" href="#subsec:N4JS_Execution_With_NodeJS"></a><a class="link" href="#subsec:N4JS_Execution_With_NodeJS">13.1.1. N4JS Execution With NodeJS</a></h4>
 <div class="paragraph">
 <p>This example shows in-depth details of N4JS code execution with NodeJS runner.</p>
 </div>
 <div class="paragraph">
 <p>In the workspace we have <code>Client</code> with <code>foo.n4js</code> that imports <code>bar.n4js</code> from <code>UserLib</code> that is also in the workspace.
 Those N4JS files use some ES5 APIs , e.g. <code>Math.random()</code> and <code>setTimeout()</code>. Those APIs are <code>Global</code> so there is
 no impicit import, still they make user projects depend on runtime library <code>n4js-runtime-es2015</code>.
 Assuming user selects <code>foo.n4js</code> file for execution, the NodeRunner in the IDE will:</p>
 </div>
 <div class="ulist">
 <ul>
 <li>
 <p>create working directory in temp folder, e.g. <code>/var/temp/N4JSNodeRun123/</code></p>
 </li>
 <li>
 <p>create <code>node_modules</code> folder inside working directory, to which projects will be linked</p>
 </li>
 <li>
 <p>generate script, e.g. <code>n4jsELF.js</code> that will be responsible for booting execution (see <a href="#sec:N4JS_Execution_And_Linking_File">N4JS Execution And Linking File</a>)</p>
 </li>
 <li>
 <p>runner will put <code>/var/temp/N4JSNodeRun123/node_modules</code> into <code>NODE_PATH</code></p>
 </li>
 <li>
 <p>execute <code>/var/temp/N4JSNodeRun123/n4jsELF.js</code> with NodeJS</p>
 </li>
 </ul>
 </div>
 <div class="paragraph">
 <p>For example with NodeJS environment if all projects from dependency graph are accessible in local file system, their
 paths would need to be put in NodeJS <em>NODE_PATH</em> environment variable. In addition to configuring execution environment
 <em>Runner</em> generates N4JS Elf file that is used by environment to bootstrap n4js execution
 (see <a href="#sec:N4JS_Execution_And_Linking_File">N4JS Execution And Linking File</a>).
 [[fig:od_sampleNodeProjectExecution]</p>
 </div>
 <div class="imageblock center">
 <div class="content">
 <img src="chapters/14_execution/images/od_sampleNodeProjectExecution.svg" alt="od sampleNodeProjectExecution">
 </div>
 <div class="title">Figure 40. Sample NodeJS Project Execution</div>
 </div>
 </div>
 </div>
 <div class="sect2 language-n4js">
 <h3 id="sec:N4JS_Execution_And_Linking_File"><a class="anchor" href="#sec:N4JS_Execution_And_Linking_File"></a><a class="link" href="#sec:N4JS_Execution_And_Linking_File">13.2. N4JS Execution And Linking File</a></h3>
 <div class="paragraph">
 <p>JS execution environment not only needs to know from where it needs to obtain code to execute, but also <em>what is the entry point to the code that is supposed to be executed</em> and <em>what code needs to be loaded before entry point is called</em>.</p>
 </div>
 <div class="paragraph">
 <p>All this information is generated by the runner based on the executed project dependency graph. The way this information
 is presented depends on concrete JS execution environment used, and on its configuration (e.g. user provided options, or
 configuration derived in other ways). But in either case file is generated with that information. Figure <a href="#fig:n4js_elf">N4JS ELF examples</a>
 shows examples how this information would look like for both testers and runners for both NodeJS or Chrome.</p>
 </div>
 <div id="fig:n4js_elf" class="imageblock center">
 <div class="content">
 <img src="chapters/14_execution/images/n4js_elf.svg" alt="n4js elf">
 </div>
 <div class="title">Figure 41. N4JS ELF examples</div>
 </div>
 <div class="paragraph">
 <p>First segment of the n4js elf is responsible for loading <em>RuntimeEnvironment</em> bootstrap code. Since <em>RuntimeEnvironment</em>s can extend each other, generated information would follow those dependencies. It is possible that <em>RuntimeEnvironment</em>s need to do some special work in regards of of provided <em>RuntimeLibraries</em>s, e.g. initiate initiate polyfills. That code can be either directly in <em>RuntimeEnvironment</em> init code, or its init code can call modules from provided runtime libraries.</p>
 </div>
 <div class="paragraph">
 <p>Second segment of the n4js elf is responsible for loading <em>RuntimeEnvironment</em> exec module. This is special module defined in package.json of the environment, that is used to call into user projects entry point directly, or (as in test case) call into runners of the test library.</p>
 </div>
 <div class="paragraph">
 <p>Last segment of the n4js elf is responsible for passing run/test data (generated by IDE/CLI) into initialised previously exec module.</p>
 </div>
 <div class="paragraph">
 <p>While first two segments are resolved from project dependencies and can be covered by generic approach on IDE/CLI side, last segment requires strong relation between given runner/tester and <em>RuntimeEnvironment</em> / <em>TestEnvironment</em>. While some generic approaches can be used, for the moment we don’t specify concrete convention there.</p>
 </div>
 <div class="sect3 language-n4js">
 <h4 id="subsec:NodeJS_Specific_ELF"><a class="anchor" href="#subsec:NodeJS_Specific_ELF"></a><a class="link" href="#subsec:NodeJS_Specific_ELF">13.2.1. NodeJS Specific ELF</a></h4>
 <div class="paragraph">
 <p>Concrete environments may need specific setup that is not common for other environemtns. For example for NodeJS runner
 needs to configure the node lookup paths for the module resolution. This is achieved by creating at runtime symlinks
 from <code>node_modules</code> pointing to concrete dependencies required during execution.</p>
 </div>
 </div>
 </div>
 <div class="sect2 language-n4js">
 <h3 id="sec:Runners-execution"><a class="anchor" href="#sec:Runners-execution"></a><a class="link" href="#sec:Runners-execution">13.3. Runners</a></h3>
 <div class="paragraph">
 <p>It is specified above, that <em>Runner</em> prepares concrete JS execution environment for executing given code and triggers execution process. What is not clear so far is how appropriate runner is selected for given project. In <a href="#_n4components">N4 Components</a> it was specified that N4JS projects do not depend directly on specific runners or JS execution environments. Instead, N4JS tooling should be able to select appropriate runner based on given project transitive dependencies. In this section we specify overall design of runners for both N4JS IDE and CLI tooling and how runners are selected for projects.</p>
 </div>
 <div class="paragraph">
 <p>INFO: In general any n4js code execution is governed by <em>runners</em> and <em>testers</em> depending on the use case.
 In this chapter <em>runners</em> are described in detail.
 Information from this chapter applies to <em>Testers</em>, unless stated otherwise in chapter dedicated to testing N4JS code (<a href="tests.html#_tests">Tests</a>), were we specify
 testing specific use cases.</p>
 </div>
 <div class="sect3">
 <h4 id="subsec:N4_Runtime_Environments_Convention"><a class="anchor" href="#subsec:N4_Runtime_Environments_Convention"></a><a class="link" href="#subsec:N4_Runtime_Environments_Convention">13.3.1. N4 Runtime Environments Convention</a></h4>
 <div class="paragraph">
 <p>Dependency between <em>Runner</em> and <em>Runtime Environment</em> crosses technical boundary between N4JS Projects (N4JS code) and N4JS tooling (IDE and CLI tools implemented with e.g. Java). We introduce convention to implement this dependency, yet letting N4JS projects and N4JS tools internals to be relatively independent.</p>
 </div>
 <div id="fig:cd_EnvironmentConvention" class="imageblock center">
 <div class="content">
 <img src="chapters/14_execution/images/cd_EnvironmentConvention.svg" alt="cd EnvironmentConvention">
 </div>
 <div class="title">Figure 42. Runtime Environments Convention</div>
 </div>
 <div class="paragraph">
 <p><a href="#fig:cd_EnvironmentConvention">Runtime Environments Convention</a> convention that is used to communicate run time configuration of the N4JS projects (grey colour) and N4JSIDE (pink colour). JS projects declare dependencies on provided list of <em>Runtime Libraries</em>. Each combination of those corresponds to one predefined <em>Runtime Environment</em> N4JS component. On N4JSIDE side there is separate list of <em>runtime environment</em>s maintained. Both lists correspond one to one to each other.</p>
 </div>
 </div>
 <div class="sect3 language-n4js">
 <h4 id="subsec:Passing_Information_from_IDE_to_Execution_Code_in_Runtime_Environment"><a class="anchor" href="#subsec:Passing_Information_from_IDE_to_Execution_Code_in_Runtime_Environment"></a><a class="link" href="#subsec:Passing_Information_from_IDE_to_Execution_Code_in_Runtime_Environment">13.3.2. Passing Information from IDE to Execution Code in Runtime Environment</a></h4>
 <div class="paragraph">
 <p>When launching an N4JS file, the IDE will compute some information on the containing N4JS project and its direct and indirect dependencies as well as the runtime environment in use. This information will be passed on to the execution module defined in the runtime environment, i.e. the code specified via property in the runtime environment’s package.json file. The information will be passed via a global variable <code>$executionData</code>. The value will be a Javascript object with the following properties:</p>
 </div>
 <div class="ulist">
 <ul>
 <li>
 <p><code>userSelection</code>: the module the user had selected when initiating the launch. This will usually be the <code>module to run</code>  , but in case of testing it will be the project, folder, or file the user had selected.</p>
 </li>
 <li>
 <p><code>projectNameMapping</code>: an object in which every key is the name of an API project among the direct or indirect dependencies of the project being run, and every value is the name of the corresponding implementation project being used. When running N4JS projects that do not make use of the API / implementation project technique, then this property will either hold an empty object or be undefined.</p>
 </li>
 <li>
 <p><code>testTree</code> (only when running tests): the test tree as defined in <a href="tests.html#_tests">Tests</a> containing information on the tests to be run, i.e. test classes, test methods, etc. The test tree will be encoded as JSON, so the value of this property will be of type string and should be passed to <code>JSON.parse()</code>.</p>
 </li>
 </ul>
 </div>
 <div class="paragraph">
 <p>All calculations described above are based on the workspace available. This includes library manager functionality, see <a href="../20_externalLibraries/externalLibraries.html#:External_Library_Workspace">External Library Workspace</a>.
 In specific setups, where workspace is not available runners provide helper utility <code>org.eclipse.n4js.runner.RunnerFileBasedShippedCodeConfigurationHelper.configureFromFileSystem()</code> that allows to configure given <code>RunConfiguration</code> using
 plain file system to the external libraries. Note that in order to do this in a way that allows to re-use all computation logic based on <a href="../12_n4components/n4components.html#:N4MFContainerManagement">N4Containers</a>,
 runners infrastructure provides its own subclasses of the few component types. Those specialized types are used only in scope of <code>RunnerFileBasedShippedCodeConfigurationHelper</code> and are not exposed to the rest of the system.</p>
 </div>
 <div class="paragraph">
 <p>Specific runners, e.g. the NodeJS or Chrome runner, may choose to provide more information via the execution data object.</p>
 </div>
 </div>
 <div class="sect3">
 <h4 id="subsec:Runners_Design"><a class="anchor" href="#subsec:Runners_Design"></a><a class="link" href="#subsec:Runners_Design">13.3.3. Runners Design</a></h4>
 <div class="paragraph">
 <p>As specified in section before N4JS projects will need to be executed on various JS execution environments, for which dedicated runners will be needed. While they will differ how they interact with concrete JS environment, they will have common parts when it comes to interaction with N4JS IDE or CLI. Those parts are provided in form of abstract <em>IDERunner</em> <em>CLIRunner</em> and <em>Runner</em> <em>components</em> (or bundles) that specific runners should use to interact with N4JS IDE or CLI.</p>
 </div>
 <div class="paragraph">
 <p>Runner by design consists of three parts:</p>
 </div>
 <div class="ulist">
 <ul>
 <li>
 <p><em>core</em> part (green colour) - contains most logic, resources (e.g. JS execution environment binary)</p>
 </li>
 <li>
 <p><em>IDE</em> part (blue colour) - responsible for working with N4JS IDE (enabling runner in ui, providing views)</p>
 </li>
 <li>
 <p><em>CLI</em> part (yellow colour) - responsible for working with N4JS CLI (get command line parameters, provide console output)</p>
 </li>
 </ul>
 </div>
 <div id="cd_RunnersIdeCli" class="imageblock center">
 <div class="content">
 <img src="chapters/14_execution/images/cd_RunnersIdeCli.svg" alt="cd RunnersIdeCli">
 </div>
 <div class="title">Figure 43. Runner for N4JS IDE and CLI tooling</div>
 </div>
 <div class="paragraph">
 <p>Specific runner is connected to running N4JS IDE or CLI via extension points. This is done either by using them directly, or by using types exposed by abstract runner component.</p>
 </div>
 </div>
 </div>
 <div class="sect2 language-n4js">
 <h3 id="sec:Legacy_Execution_Engine"><a class="anchor" href="#sec:Legacy_Execution_Engine"></a><a class="link" href="#sec:Legacy_Execution_Engine">13.4. Legacy Execution Engine</a></h3>
 <div class="paragraph">
 <p>Compilation of N4JS may target many platforms. For the moment it is hard to discuss what they will be exactly or if N4JSIDE will provide some integration or hooks to those platforms. On the other hand we want to have some execution environment for internal use to validate behaviour of compiled code. Since we know that V8 based platforms (e.g. Chrome, NodeJS) will be in our target platforms set we want to be able to execute compiled code on similar environment. As standalone V8 integration is quite challenging, we have decided to integrate in N4JSIDE NodeJS as execution environment. This is considered internal feature used for testing compilation of N4JS and N4JSIDE.</p>
 </div>
 </div>
 <div class="sect2 language-n4js">
 <h3 id="sec:Design"><a class="anchor" href="#sec:Design"></a><a class="link" href="#sec:Design">13.5. Design</a></h3>
 <div class="paragraph">
 <p>We provide NodeJS binaries for various OSes. Direct access to binaries is not exposed. Selection and institutionalization of the binary is done internally and is not configurable. Instead bundle containing binaries provides classes required to run code (in form of <code>String</code> or <code>File</code> with the code). Clients That want to do this may either use provided <code>Engine</code> class or can implement their own engine based on provided infrastructure. Main class that used in engine implementation is <code>EngineCommandBuilder</code>. This class is responsible for building proper command line commands that engine implementation must execute to run code with NodeJS.</p>
 </div>
 <div class="paragraph">
 <p><a href="#fig:cd_executionengine">NodeJS execution integration</a> shows the most important classes of the NodeJS integration.</p>
 </div>
 <div id="fig:cd_executionengine" class="imageblock center">
 <div class="content">
 <img src="chapters/14_execution/images/cd_executionengine.svg" alt="cd executionengine">
 </div>
 <div class="title">Figure 44. NodeJS execution integration</div>
 </div>
 <div class="sect3">
 <h4 id="sec:Usage_Outside_N4JSIDE"><a class="anchor" href="#sec:Usage_Outside_N4JSIDE"></a><a class="link" href="#sec:Usage_Outside_N4JSIDE">13.5.1. Usage Outside N4JSIDE</a></h4>
 <div class="paragraph">
 <p>In this use case we use provdied <code>Engine</code> class that allows to execute js code in form of <code>String</code> or <code>File</code> with the code. In return user receives <code>EngineOutput</code> object with two lists of strings containing standard output and error output of the node process, that were captured during execution.</p>
 </div>
 <div class="paragraph">
 <p>In this usage scenario execution api assumes valid JS code. User needs to ensure compilation of code prior to execution, if needed.</p>
 </div>
 <div class="paragraph">
 <p>That functionality is used in internal jUnit tests and in xpect tests of the compiler.</p>
 </div>
 <div class="sect4">
 <h5 id="sec:Use_Node_with_Maven"><a class="anchor" href="#sec:Use_Node_with_Maven"></a><a class="link" href="#sec:Use_Node_with_Maven">13.5.1.1. Use Node with Maven</a></h5>
 <div class="paragraph">
 <p>Note on maven usage. For maven based builds we need to ensure that binary resources are available and are unpacked. To do this in pom of the project that will be calling engine we must include following listing:</p>
 </div>
 <div class="listingblock">
 <div class="content">
 <pre class="highlight"><code class="language-xml" data-lang="xml">            &lt;plugin&gt;
                 &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
                 &lt;artifactId&gt;maven-dependency-plugin&lt;/artifactId&gt;
                 &lt;executions&gt;
                     &lt;execution&gt;
                         &lt;id&gt;unpack&lt;/id&gt;
                         &lt;phase&gt;process-test-classes&lt;/phase&gt;
                         &lt;goals&gt;
                             &lt;goal&gt;unpack&lt;/goal&gt;
                         &lt;/goals&gt;
                         &lt;configuration&gt;
                             &lt;artifactItems&gt;
                                 &lt;artifactItem&gt;
                                     &lt;groupId&gt;org.eclipse.n4js&lt;/groupId&gt;
                                     &lt;artifactId&gt;org.eclipse.n4js.js.engine&lt;/artifactId&gt;
                                     &lt;version&gt;0.0.1-SNAPSHOT&lt;/version&gt;
                                     &lt;overWrite&gt;true&lt;/overWrite&gt;
                                     &lt;outputDirectory&gt;
                                         ${project.build.directory}/classes
                                     &lt;/outputDirectory&gt;
                                 &lt;/artifactItem&gt;
                             &lt;/artifactItems&gt;
                         &lt;/configuration&gt;
                     &lt;/execution&gt;
                 &lt;/executions&gt;
             &lt;/plugin&gt;</code></pre>
 </div>
 </div>
 </div>
 </div>
 <div class="sect3">
 <h4 id="sec:Usage_Inside_N4JSIDE"><a class="anchor" href="#sec:Usage_Inside_N4JSIDE"></a><a class="link" href="#sec:Usage_Inside_N4JSIDE">13.5.2. Usage Inside N4JSIDE</a></h4>
 <div class="paragraph">
 <p>In Eclipse platfrom based environment we use custom implementation of the engine, <code>PlatformEngine</code>. This implementation unlike default <code>Platform</code> is non blocking implementation that forwards output to platform console and allows platform to control lifecycle of the running engine. Additionally this version uses its own implementation of the <code>ResourceUrlResolver</code>. It is required to properly resolve urls that point inside platform bundles.</p>
 </div>
 <div class="paragraph">
 <p>This scenario we assume that user will run N4JS files or JS files. We have created proper UI hooks that allow user to do this either from editor or as selection menu. Based on name of the file that user commands to execute we find proper compiled file (compiled with our ES5 compiler - it is not configurable). When found we execute this file in our execution engine. If it is not found, execution engine will write appropriate error to N4JSIDE console.</p>
 </div>
 </div>
 </div>
 <div class="sect2 langauge-n4js">
 <h3 id="sec:Runtime_Injection"><a class="anchor" href="#sec:Runtime_Injection"></a><a class="link" href="#sec:Runtime_Injection">13.6. Runtime Injection</a></h3>
 <div class="paragraph">
 <p>There is need to inject into runtime environment some special code, for example when compiling N4JS to ES5 (see N4JavaScriptSpecification,chapter N4 JS Compilation). To achieve this wee need to inject desired code when calling engine to run desired compiled code. Injection mechanism depends a lot on way we run engine. In this section injection of runtime is discussed based on NodeJs that is used as runtime environment.</p>
 </div>
 <div class="sect3">
 <h4 id="sec:Running_String_Code"><a class="anchor" href="#sec:Running_String_Code"></a><a class="link" href="#sec:Running_String_Code">13.6.1. Running String Code</a></h4>
 <div class="paragraph">
 <p>We allow code execution where code is provided in form of <code>String</code>. In this case we are calling nodejs with parameters . To enrich execution environment in this case we are appending special runtime code at the end of file. It is important to append it at the end, to avoid changing line numbers of original code and decrease other potential side effects. So actual invocation of nodejs looks like</p>
 </div>
 <div class="paragraph">
 <p>This mechanism assumes:</p>
 </div>
 <div class="olist arabic">
 <ol class="arabic">
 <li>
 <p>injected code starts with new line - this makes ASI mechanism to finish user last statement if it was not properly finished by user, otherwise just creates</p>
 </li>
 <li>
 <p>injected code does not have to be initiated manually - all exposed api is in named function declarations</p>
 </li>
 </ol>
 </div>
 <div class="paragraph">
 <p><em>Explanation</em></p>
 </div>
 <div class="paragraph">
 <p>In first assumption we make workaround for user code that does not contain new line or semicolon at the end of last statement. This kind of code is incorrect and would result in last statement of user code and first statement of injected code to be interpreted as one JS statement. In most cases that would be invalid code. By having new line as first character of injected code, we are taking advantage of JS AutomaticSemicolonInjection mechanism. If user code AST is not finished properly this mechanism will finish close user AST. If user AST is finished properly, ASI will just insert empty statement between user code and injection code. In both cases we end up with proper AST.</p>
 </div>
 <div class="paragraph">
 <p>Second assumption avoids need for further user code modifications, as injected does not have to be manually called. Instead we take advantage of variable and function hoisting mechanism of JS. This assures that even though user code is first in AST, JS environment will first initiate named functions therefore when user code calls injected code it is already defined in scope in which user code executes.</p>
 </div>
 </div>
 <div class="sect3">
 <h4 id="sec:Running_File_Code"><a class="anchor" href="#sec:Running_File_Code"></a><a class="link" href="#sec:Running_File_Code">13.6.2. Running File Code</a></h4>
 <div class="paragraph">
 <p>Second method of code execution is to execute provided file with user code. Normal way of doing that with NodeJS is to make call. But since we need to inject special code without rewriting files, we use different mechanism. Basically we are executing injected code and in the same scope using node api. Additionally we are attaching injected code to global scope in node, ensuring this way that required file is executed in scope which contains injected code. Putting this all together we are making following call:</p>
 </div>
 <div class="paragraph">
 <p>This mechanism assumes that injected code attaches all exposed API to global scope .</p>
 </div>
 </div>
 <div class="sect3">
 <h4 id="sec:Injection_Code_Example"><a class="anchor" href="#sec:Injection_Code_Example"></a><a class="link" href="#sec:Injection_Code_Example">13.6.3. Injection Code Example</a></h4>
 <div class="paragraph">
 <p>Following is simple example of properly formed injection code.</p>
 </div>
 <div class="listingblock">
 <div class="content">
 <pre class="highlight"><code class="language-n4js" data-lang="n4js">;
 function foo(){}
 function bar(){}
 function baz(){}

 (function(){
  GLOBAL.foo = foo;
  GLOBAL.bar = bar;
  GLOBAL.baz = baz;
 })();
 ;</code></pre>
 </div>
 </div>
 <div class="olist arabic">
 <ol class="arabic">
 <li>
 <p>first line is empty line to trigger ASI</p>
 </li>
 <li>
 <p>second line (optional) enters</p>
 </li>
 <li>
 <p>lines 3-5 are defining runtime api in current scope (in which user code provided as a string is executed)</p>
 </li>
 <li>
 <p>lines 6 (optional) is just a visual sugar</p>
 </li>
 <li>
 <p>lines 7-11 are adding runtime api to global scope (to expose it when runnig user file with code)</p>
 </li>
 <li>
 <p>lines 12-13 (optional) are there to separate injected code and invokation of user file (if running user provided file with code)</p>
 </li>
 </ol>
 </div>
 </div>
 </div>
 </div>
 </div>
 </div>
 <div id="footer">
 <div id="footer-text">
 Version 0.9<br>
 Last updated 2019-08-08 13:15:33 CEST
 </div>
 </div>
 <!-- ************* docinfo-footer *************************************************************** -->
 <div class="Grid social" style="color:#d5dfea">
   <div class="Cell Cell--2-12 m-Cell--withMargin">
     <h2>Quick Links</h2>
     <ul>
       <li><a href="../downloads.html">Download</a></li>
       <li><a href="../userguides/index.html">Documentation</a></li>
       <li><a href="https://github.com/eclipse/n4js/">Source</a></li>
       <li><a href="https://github.com/eclipse/n4js/issues">Issues</a></li>
     </ul>
   </div>
   <div class="Cell Cell--2-12 m-Cell--withMargin">
     <br/><br/>
     <ul>
       <li><a href="https://www.eclipse.org/forums/index.php/f/365/">Forum</a></li>
       <li><a href="http://n4js.blogspot.de/">Blog</a></li>
       <li><a href="https://dev.eclipse.org/mailman/listinfo/n4js-dev">Mailing List</a></li>
       <li><a href="https://projects.eclipse.org/projects/technology.n4js">Eclipse Project Page</a></li>
       <li><a href="https://twitter.com/n4jsdev">Tweets by n4jsdev</a></li>
     </ul>
   </div>
   <div class="Cell Cell--2-12 m-Cell--withMargin">
     <br/><br/>
     <ul>
       <li><a href="http://www.eclipse.org/">Eclipse Home</a></li>
       <li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
       <li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
       <li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
       <li><a href="http://www.eclipse.org/legal/">Legal</a></li>
     </ul>
   </div>
   <div style="clear: both; height: 0; overflow: hidden;"></div>
 </div>

 <!-- ************* UI Scripts ************* -->
 <script type="text/javascript" src="scripts/back-to-top.js"></script>

 <script type="text/javascript" src="scripts/treeview.js"></script>
 <script type="text/javascript" src="scripts/toc.js"></script>

 <!-- ************* Prism.js Syntax Highlighting ************* -->
 <script src="scripts/prism.js"></script>

 <script type="text/javascript">
 	// Add the 'toclist' id for search function
 	$(".toc2 > ul").attr('id', 'toclist');
 	// Generate a Search input form
 	$("#toclist > li:first-of-type").before('<input type="text" id="pagesearch" onkeyup="search()" placeholder="Search for section...">');
 	$("#toclist > li:first-of-type").before('<i id="clear" class="fa fa-times-circle-o"></i>');
 	$("#clear").click(function(){
 	    $("#pagesearch").val('');
 	    search();
 	    $('.toc2 > ul').treeView('collapseAll');
 	});
 	// intialize Treeview.js
 	$(".toc2 > ul").treeView();
 	// Initialize Scrollspy
 </script>
 <!-- ************* docinfo-footer *************************************************************** -->
 </body>
 </html>