README

EMANATOR

Deploy your HTML5 web or desktop applications with ease. Emanator can help you create custom project integration processes to deploy HTML5 web applications as well as standalone desktop applications using NWJS.

In addition to being an exceptionally useful tool for day-to-day utilities, emanator offers following application build targets:

Windows
- Portable ZIP archive (Nodejs)
- Portable ZIP archive (NWJS)
- InnoSetup 6 EXE installer (NWJS)
Linux
- Portable ZIP archive (Nodejs)
- Portable ZIP archive (NWJS)
Mac OS
- Portable ZIP archive (Nodejs)
- Portable ZIP archive (NWJS)
- DMG disk image installer

Some of the key features of the Emanator include:

Task-driven approach to create sequential or parallel execution pipelines.
Async-oriented environment
Instant access to modules included with the Emanator (see below), while also being able to use local node_modules included within your project (if any)
Convenient shell access as well as utility functions allowing you to download, extract, compress and perform variety of other operations usually needed in build processes.

Installation

Emanator requires minimum Nodejs 14. You can install emanator as follows:

Via NPM: npm install -g emanator

Via Github:

git clone https://github.com/aspectron/emanator
cd emanator
npm link

Installing via Github allows you to stay on top of latest changes in the master branch.

Command Line Flags

--version - Prints currently installed version of the emanator.
--clean - Erase temporary folders and cache before starting the build process
--serve - Starts HTTP server serving current folder as static files. When --serve is specified, you can use --port=8080 to bind the server to a specific port (default 8080) and --host=* (or --host=0.0.0.0) to bind the server to all interfaces.

Windows-specific Flags

--innosetup - build InnoSetup installer
--nopackage - skip archival process if forced in the Emanator constructor options
--sign - sign the InnoSetup installer with your PFK

EMANATE Scripts

Emanate script should be located in the root of your project with the file named EMANATE or .emanate.

Before invoking the Emanate script, Emanator preloads various modules and invokes the script inside of an async function. This wrapping provides instant access to various preloaded modules as well as removes the requirement to define custom async wrapper (typically done in async Nodejs applications).

Prerequisites

Documentation on this site assumes that you are running under unix-compatible OS (i.e have acces to bash shell). If you are running Windows, it is recommended to install MSys2, Git for Windows or similar suites.

A barebone EMANATE script

const E = new Emanator();
const version = E.flags.version || 'v14.8.8';
const folder = `node-${version}-${E.PLATFORM_ARCH}`;
const file = `${folder}.${E.NODE_ARCHIVE_EXTENSION}`;
await E.download(`https://nodejs.org/dist/${version}/${file}`, E.TEMP);
await E.decompress(path.join(E.TEMP,file), E.HOME);
await E.spawn([`${path.join(E.HOME,folder,'bin',E.BINARY('node')}`,``],{ cwd });

Emanator node_module handling

When running Emanate scripts, Emanator adds a local node_modules folder as the first entry in the require() search path. Subsequently, before performing a standard require() module search/resolution, modules will be searched for in a local node_modules.

Globals

`flags`

flags is a javascript object generated from command line arguments as follows:

presence of a simple flag with -- prefix such as --some-option will be treated as a boolean
presence of an assignment such as --version=1.5 will be available as a string Example: emanate --optimize --version=1.5 will yield the following flags object:

{
    "optimize" : true,
    "version" : "1.5"
}

`argv`

argv is an array of command-line arguments supplied to the Emanator when running emanate scripts. For example: running emanate build package will yield argv as ['build','package']

External Modules

fs - Global fs object is a composite of the Nodejs fs module as well as fs-extra module. In addition to integrated fs module functions, fs-extra brings in the following methods: https://github.com/jprichardson/node-fs-extra#methods
mkdirp - mkdirp module for recursive directory create
colors - Emanator allows the use of ansi terminal colors via the colors module - https://github.com/Marak/colors.js

Native Modules

process
os
path

Native Functions

exec(command[, options][, callback])
execSync(command[, options])
execFile(file[, args][, options][, callback])
_spawn(command[, args][, options]) (alias for native child_process.spawn())
setInterval
clearInterval
setTimer
clearTimer

Emanator Interface

const E = new Emanator(__dirname, {
    type : 'NWJS',
    guid : 'c5072045-6d98-44d8-9aa5-e9be6c79bd01',
    group : 'MyWindowsStartMenuGroup',
    ident : 'my-app',
    title : 'My App',
    banner : 'my app',
    git : 'git@github.com:my-org/my-app',
    author : "My Inc.",
    url : "http://my-site.com",
    archive : true,
    production: true,
    nwjs : { version : '0.46.2', ffmpeg : true },
    resources : 'resources/setup',
    skipDirCreation:true,
    manifest:manifest=>{
        return manifest;
    }
});

In most emanator scripts, Emanator class is instantiated as a capital letter E.

Option Object

type - should contain one of the following reserved project types: NODE, NWJS, UTIL, DOC; if used for utility purposes, can contain any user-defined type.
guid - should contain a project GUID that will be used to identify the applicaton on Windows. For example: c5012045-6a98-44d8-9a85-e9be6379bd01
group - My Software Group Windows Start Menu folder in which your application will reside
ident - Application identifier my-app
title - My App Title
banner - my app banner (ascii banner displayed at startup)
git - git@github.com:my-org/my-app
author - "My Inc."
url - http://my-site.com,
archive
production
nwjs - should contain required NWJS installer version. For example: nwjs : { version : '0.46.2', ffmpeg : true }. If ffmpeg property is set to true Emanator will download and overwrite ffmpeg shared libraries included as a part of NWJS with GPL-licensed ffmpeg libraries.
resources - should point to resource folder containing resources needed by Installers (images, icons etc)
manifest - can be set to a custom function receiving and returning the project manifest data. The function has the following signature: (manifest) => { return manifest; }. This function is useful to modify project manifest (for example, include extra node module dependencies) during the build process.

Emanator task pipeline

Emanator offers creation of multiple inter-dependent tasks that can be executed asynchronously if various integration stages are independent of one another.

`task(name [, dependencies], handler)`

name - task name
[dependencies] - an array of tasks that should be completed before this task starts
handler - a function that will be executed when dependent tasks are complete

Declare a custom task.

Task handler function can have one of the following signatures:

Promise function() you can return a promise that should be resolved upon task completion.
void function(callback) you can invoke the supplied callback, in which case you must not return a promise.

`run([name])`

name - task name

Run a specific task with its dependencies.

Control functions

`manifest_read_sync()`

Read the project manifest file (package.json) synchronously, making the contents accessible as an object under E.pkg property. This is useful when contents of the package.json are required before execution of a pipeline.

Constants

ident- project identifier (used in archive file and folder names)
type- project type. Currently used NODE,NWJS,UTIL
PROJECT_VERSION - version of the project used to initialize the Emanator object.
PLATFORM- target platform identifier: windows, linux, darwin
ARCH - target architexture identifier: x64, arm7
PLATFORM_ARCH
BINARY_EXT - set to '.exe' on Windows, otherwise an empty string ''
WINCMD_EXT - set to '.cmd' on Windows, otherwise an empty string ''
PLATFORM_PATH_SEPARATOR - platform-specific path delimiter (/ on Unix-compatible OS, '' on Windows)
DMG_APP_NAME
DMG_APP_NAME_ESCAPED
NODE_VERSION - currently running Node version
NWJS_VERSION - project-configured NWJS version
NPM - npm script location
HOME - absolute path to the current user home folder
NWJS_ARCHIVE_EXTENSION - OS-specific archive extension used in NWJS releases
NODE_ARCHIVE_EXTENSION - OS-specific archive extension used in Nodejs releases

Functions

`BINARY(filename)`

Return Value:

Unix: returns filename unchanged
Windows: appends .exe to the filename

`download(url, folder)`

Downloads a file at the destination URL to a folder. Downloaded filename is derived from the URL.

`extract(from,to)`

Extracts archive to the destination folder based on file extension.

TAR files:

Uses tar to extract. (Requires unix compatibility layer on Windows)

ZIP files:

Windows: uses AdmZip (no progress)
Unix: uses unzip

`spawn(command[, args][, options])`

command <string> The command to run.
args <string[]> List of string arguments.
options <Object>
Returns: Promise (child process termination)

Spawns a child process. Returns a promise that will be resolved upon the child process termination.

This function is an async wrapper of the native Nodejs Child Process spawn() function with following differences:

options object can contain stdout property referencing a function that will receive process stdout output.
First element of the arguments parameter must be the porocess filename.

Options:

stdout :

Example:

await E.spawn(['node','-v'])

async exec(file[,arguments][,options]) - executes file with arguments, returns stdout captured from process execution
async copy(source, destination,options) - https://github.com/jprichardson/node-fs-extra/blob/HEAD/docs/copy.md
async move(source, destination, options) - moves file
async remove() - removes file or folder (recursively)
async emptyDir() - delete all directory contents - https://github.com/jprichardson/node-fs-extra/blob/HEAD/docs/emptyDir.md
async mkdirp(path) - creates folders in the supplied path
async ensureDir() - https://github.com/jprichardson/node-fs-extra/blob/HEAD/docs/ensureDir.md
addToPath(path) - add supplied path to the current process.env.PATH list.

Folders

Property	Description
`RELEASE`	`<emanator>/<org>/`
`TOOLS`	`<emanator>/tools/`
`DEPS`	`<emanator>/deps/`
`SETUP`	`<project>/setup/<platform>-<arch>`
`ROOT`	comprised of `<emanator>/<org>/<project>` if git URL is configured, `<emanator>/<ident>` if not.
`TEMP`	`<emanator>/<org>/temp/`
`DMG`	`<emanator>/<org>/DMG/`
`REPO`	default:`<project>` production:`<repo>`

<emanator> - default location: <home-folder>/emanator
<project> - project root, location of the EMANATE file
<org> - organization, derived from the git property
<ident> - ident property supplied to the Emanator() constructor
<platform> - target platform name: windows, linux, darwin
<arch> - target architecture: x64, arm7

Nodejs Integration Pipeline

init
manifest-read
create-folders
manifest-write
npm-install
npm-update
node-modules
node-binary
origin

NWJS Integration Pipeline

init
manifest-read
create-folders
manifest-write
npm-install
npm-update
nwjs-sdk-download
nwjs-ffmpeg-download
nwjs-download
nwjs-sdk-unzip
nwjs-ffmpeg-unzip
nwjs-unzip
unlink-nwjs-app
nwjs-copy
nwjs-ffmpeg-copy
nwjs-cleanup
node-modules
node-binary
origin

Modules

`7z`

Provides interface to the 7z archiver - functions for compression and decompression using 7z

exec7zArchive(folder, archive[, options]) - create 7z archive from a folder
- folder - source folder to archive from
- archive - archive filename
- options - Can contain following options: level compression level (must be a numeric value in range of 1..9); silent set to true to enable running 7z in silent mode (--bb0).
createSFX(options) - create .EXE Self-extracting archive (SFX)
- options can contain the following properties:
  - script
  - elevate
  - title
  - folder
  - wait
  - args

Usage no npm install needed!

README

EMANATOR

Installation

Command Line Flags

Windows-specific Flags

EMANATE Scripts

Prerequisites

A barebone EMANATE script

Emanator node_module handling

Globals

flags

argv

External Modules

Native Modules

Native Functions

Emanator Interface

Option Object

Emanator task pipeline

task(name [, dependencies], handler)

run([name])

Control functions

manifest_read_sync()

Constants

Functions

BINARY(filename)

download(url, folder)

extract(from,to)

TAR files:

ZIP files:

spawn(command[, args][, options])

Folders

Nodejs Integration Pipeline

NWJS Integration Pipeline

Modules

7z

ares

docker

gcc

git

go

npm

nwjc

nwjs

Utility functions

log

getDirFiles

zipFolder

getConfig

asyncMap

fileHash

whereis

glob

iterateFolder

replicateFile

matchFiles

Platform targets

Linux

Windows

Mac OS

`flags`

`argv`

`task(name [, dependencies], handler)`

`run([name])`

`manifest_read_sync()`

`BINARY(filename)`

`download(url, folder)`

`extract(from,to)`

`spawn(command[, args][, options])`

`7z`

`ares`

`docker`

`gcc`

`git`

`go`

`npm`

`nwjc`

`nwjs`

`log`

`getDirFiles`

`zipFolder`

`getConfig`

`asyncMap`

`fileHash`

`whereis`

`glob`

`iterateFolder`

`replicateFile`

`matchFiles`