.. _`Cross Compiling Node.js Applications`:

####################################
Cross Compiling Node.js Applications
####################################

A cross compiler allows for creating executable code for a target platform other than the one on which
the compiler is running (the host machine).

This section provides an overview of how you can cross-compile a Node.js
project on a host machine and run it on a target platform.

To cross-compile a node project, all the development needs to be done on the
cross-compiling host machine.

Dependencies on the host machine
*********************************
	- Node.js LTS 12.16.3 or later (Node.js LTS 12.x version)
	- npm (node package manager) version 5.6.0 or later (typically included with a Node.js install)
	- Python 2.7 (v3.x.x is not supported)
	- make
  - An OpenSplice RTE cross compiling build installed
    
    Such installer typically have a name such as,
  
    Pnnn-VortexOpenSpliceRTE-6.x.x-HDE-<host-info>-RTS-<target-info>-installer.run

    Example installer:

      P748-VortexOpenSpliceRTE-6.x.x-HDE-x86.linux-gcc4.8-glibc2.19-RTS-armv7at2_vfp_neon.WRlinux7_gcc-glibc_small-installer.run

Cross-compile Node.js application
**********************************
1. On the host machine, start a command shell. Setup OSPL environment variables by running release.com or release.bat

2. Create a node project folder, if not created:

      mkdir <project_name>

      cd <project_name>

      npm init

3. Set CC to <C cross compiler>

      Example: *export CC=arm-wrs-linux-gnueabi-gcc*

4. Set CXX to <C++ cross compiler>

      Example: *export CXX=arm-wrs-linux-gnueabi-g++*

5. Change directory to your Node.js project folder

6. Cross-compile the Node.js DCPS api package to your project by executing following command (on linux):

.. code-block:: bash
  
    npm --target_arch=<target_arch_name> install $OSPL_HOME/tools/nodejs/vortexdds-x.y.z.tgz

7. Run the following command to cross-compile your Node.js application dependencies:

.. code-block:: bash

      npm --target_arch=<target_arch_name> install


Compile IDL file into XML document
**********************************
The Node.js DCPS API package has a runtime dependency on *idlpp*. The *idlpp* is the Vortex OpenSplice IDL Pre-processor.
It will be unavailable on the target machine.
In order to eliminate the dependency on *idlpp*, you need to compile idl files to generate xml documents.

There are two ways of doing this:

  1. Invoke the 'compile-idl' script provided by the Node.js DCPS API package

  (OR)

  2. Directly invoke the idlpp command to compile an idl file


.. _InvokeScript:

Invoke 'compile-idl' script to generate XML
===========================================

The 'compile-idl' script provided by the Node.js DCPS API package will compile ALL the idl files of the 
current working directory into xml documents and put them in the same directory path of the source idl files.

A generated file will be named as '<idl_file_name>.idl.xml' file. For example, for 'Chat.idl' file 
the generated xml file will be 'Chat.idl.xml'.

You will need to re-run this script if you change the idl file or add any new idl file(s) into your project directory.

This script will ignore all the idl files inside the 'node_modules' directory.

.. note::

    If you get any error when running the provided Node.js script, or if you do not want to compile all of the idl files in your 
    project directory, you can directly invoke the idlpp command to compile an idl file and write the result to an xml file 
    (see :ref:`InvokeIDLPP`).

  
Steps to run 'compile-idl' script:

1. Change directory to your Node.js application folder

2. Edit your application's 'package.json' file to add a script entry for "cidl" : "compile-idl":

  **Example: package.json file**

  .. code-block:: json

      {
        ...
        "name": "pingpong",
        "version": "1.0.0",
        "scripts": {
          "cidl": "compile-idl"
        },
        "author": ""
        ...
      }


3. Run the script:

    npm run cidl


.. _InvokeIDLPP:

Invoke IDLPP to generate XML
============================

IDLPP can be directly invoked to compile an idl file and write the result to an xml file.

This option may be preferred IF it is not desirable to compile all of the idl files in your project directory.

It is also an alternative option IF errors are encountered while attempting to run the "compile-idl" script in :ref:`InvokeScript` section.

On Linux host machine, follow the steps below to generate xml from an idl file:

1. Open a Linux terminal and change directory to the location of the idl file that you need to compile

2. Run the 'idlpp -l pythondesc' command for your idl file.

    Example:

      idlpp -l pythondesc idl_file_name.idl > idl_file_name.idl.xml

.. note::

    The name of the xml file to be generated must be the same as the source idl file name.


Copy Node.js application into target platform
**********************************************
After you cross-compile your Node.js application and generate xml from idl file, copy your Node.js application directory (containing all the 
sub-directories, cross-compiled dependencies and the generated xml file(s)) into the target platform.


On the target platform
**********************

Prerequisites
=============
- Install OpenSplice RTS

    Follow the instructions provided for installing OpenSplice on the target platform. If you have a problem running OpenSplice 
    on the target platform, please contact customer support for more information.

- Install Node.js

  + Install Node.js for the target platform from `https://nodejs.org/en/download/ <https://nodejs.org/en/download/>`_.

  (or)

  + Cross-compile Node.js source if Node.js install fails:

      If the installed Node.js does not work on target platform, you can cross-compile the Node.js source code on
      the host machine.

      Following section gives the instructions of how you can cross-compile Node.js source code for the target platform.

How to cross-compile Node.js for target platform if Node.js install fails
-------------------------------------------------------------------------

  Steps to cross-compile Node.js source on the host machine:

  1. Download Node.js source code from `https://nodejs.org/en/download/ <https://nodejs.org/en/download/>`_.

  2. Extract and cd to the source directory.
  
      Example:
        
          cd node-v12.16.3

  3. Set CC to <C cross compiler>

  4. Set CXX to <C++ cross compiler>

  5. Run the configure script to set up things for cross compilation:

  .. code-block:: bash

    ./configure --dest-cpu=<target_platform> --cross-compiling --dest-os=<target_os>
    
  
  Example:

  .. code-block:: bash

    ./configure --dest-cpu=arm --cross-compiling --dest-os=linux

      
  6. Run '*make*'
  

  This should generate executable node for the target platform inside the 'out/Release' directory.

  
.. note::

    If you get errors about 'icupkg' while building node source, you can try adding '--without-intl' and '--without-snapshot' flags
    to the configure line and make again.

    .. code-block:: bash

        ./configure --dest-cpu=<target_platform> --cross-compiling --dest-os=<target_os>
        --without-intl --without-snapshot



Run cross-compiled Node.js application on the target
====================================================
1. On target platform, setup OSPL environment variables by running release.com or release.bat

    .. code-block:: bash
      
        source ./release.com


2. Change directory to your Node.js application folder

3. Start the node application