generate-evb


Goal

To help you automate the process of generating an 'Enigma Virtual Box' project file (*.evb) as part of your normal build
stage.

Overview

Enigma Virtual Box (EVB) is a tool that lets you package a Windows
executable with all of the data and dependencies it needs in-order to run (dll files, assets, registry entries
etc.). The tool takes care of all the virtualization, so you usually don't need to change your code in any way. The
packaged executable can read/execute files that were packed with it as if they were really in the file system and not
virtualized (e.g. if you packed ./images/logo.png, you can read the file from that path).

To create a packaged executable you need to create a project file that describes what needs to be packaged along with
some other virtualization attributes. The tool offers only a GUI for creating the project and there's no built-in
support for recursively packing an entire directory. In other words, if files were changed in one of the packed folders,
you have to update the project manually using the GUI.

We offer an alternative. You can use generate-evb in your node build script, to pack an entire directory structure. To
update the project file, you just re-run your build script. You can also wrap your code in a gulp/grunt task if you
wish.

Usage

Start by installing generate-evb locally:
``sh
npm install generate-evb --save-dev
`

Load the generateEvb function:
`javascript
var generateEvb = require('generate-evb');
`

The signature of generateEvb is:
`javascript
generateEvb(projectName, inputExe, outputExe, path2Pack, options);
`
Where:
- projectName (String) - the file path to which we want to save the generated evb file (e.g. build/myProject.evb)
- inputExe (String) - the input executable file path. Enigma packs the files from path2Pack into a copy of this
executable
- outputExe (String) - the output executable file path. Enigma saves the packed file to this path
- path2Pack (String) - the path to the directory with the content that we want to pack into the copy of inputExe
- options (Object) - optional
- filter (Function) - optional, this function is called with the following parameters: fullPath (String), name
(String), isDir (Boolean) for each directory and file in path2Pack. The function should return true for any file
or directory you want to pack, and false for anything else
- templatePath (Object) - optional, will default to the templates in the generate-evb/templates
- project (String) - path to a project template
- dir (String) - path to a directory template
- file (String) - path to a file template
- evbOptions (Object) - optional:
- deleteExtractedOnExit (Boolean) - same as Enigma's "File Options > Delete Extracted On Exit". defaults to
true
- compressFiles (Boolean) - same as Enigma's "File Options > Compress Files". defaults to true
- shareVirtualSystem (Boolean) - same as Enigma's "Options Tab > Share virtual system to child processes".
defaults to false
- mapExecutableWithTemporaryFile (Boolean) - same as Enigma's "Options Tab > Map executable files using
temporary file". defaults to true
- allowRunningOfVirtualExeFiles (Boolean) - same as Enigma's "Options Tab > Allow running of virtual
executable files". defaults to true

Usage example

Let's say that we want to pack a Node.js project into node.exe. Our copy of node.exe is located at
C:/Program Files (x86)/nodejs/node.exe, so that will be our inputExe. The Node.js project is located at ../foo
(all paths can be relative or absolute), so that's our path2Pack. We want to save the packaged executable to
build/node.exe so that will be our outputExe. And we will save the evb project to build/packedNode.evb, so that's
the projectName.

So our script will look like this:

`javascript
var generateEvb = require('generate-evb');

generateEvb('build/packedNode.evb', 'C:/Program Files (x86)/nodejs/node.exe', 'build/node.exe', '../foo');
`
After we run this script we'll have the evb project file at build/packedNode.evb.

To pack it, we can either open the project in enigmavb.exe (Enigma's GUI) and click on Process, or we can use
enigmavbconsole.exe (Enigma's CLI) to pack it (example below).

Here's an example of packing the evb project using Node.js:
`javascript
var fs = require('fs');
var child_process = require('child_process');

// Change the following paths to the actual paths used in your project
var evbCliPath = 'C:/Program Files (x86)/Enigma Virtual Box/enigmavbconsole.exe';
var projectName = 'build/packedNode.evb';
var inputExe = 'C:/Program Files (x86)/nodejs/node.exe';
var outputExe = 'build/node.exe';

child_process.execFile(evbCliPath, [projectName], function (err, stdout, stderr) {
var success = false;
if (!err) {
// Sanity check (change this to what works for you):
// Check if the output file exists and if it's bigger than the input file
if (fs.existsSync(outputExe)) {
success = fs.statSync(outputExe).size > fs.statSync(inputExe).size;
}

if (!success) {
err = new Error('Failed to pack EVB project!\nEVB stdout:\n' + stdout + '\nEVB stderr:\n' + stderr);
}
}
if (err) {
throw err;
}
});
`

If path2Pack contains some files or directories you don't want to pack, you should provide a filter function. This is
especially true, if path2Pack contains inputExe (this is common when packing an Electron
app). Here's an example of how to filter out all png files:

`javascript
var generateEvb = require('generate-evb');

generateEvb('build/packedNode.evb', 'C:/Program Files (x86)/nodejs/node.exe', 'build/node.exe', '../foo', {
filter: function (fullPath, name, isDir) {
var pngRegexp = /.*\.png$/i;
// Any directory or any file that isn't a png file, is approved
return isDir || !pngRegexp.test(name);
}
});
`

Customization

You can customize the generated project using options.evbOptions. If an option/setting you are looking for is not
available there (e.g. you want to add virtual registry entries), you can use custom templates.
The default template files are located at generate-evb/templates.
Before you change them, copy the templates to a location outside of node_modules.

The templates are xml files that are pretty descriptive, so for most options it should be easy to figure our what needs
changing. If you can't find the option, I suggest that you generate the project file using the default options and
use enigmavb.exe (Enigma's GUI) to change the options as you see fit. Then you should do a diff between the before
and after, so you will see what options need changing. Then you can go back to the templates copy, and modify
accordingly.

To make generateEvb use the updated templates just pass it the optional options.templatePath object. We will use the
default templates for any missing template, so you don't have to replace all of them.

Alternatives

enigmavirtualbox is a Node.js module and CLI, that offers the
following capabilities:
- Download and install EVB
- Generate a project file (currently this is very limited and not customizable)
- Pack the project file

You can use this module along with generate-evb, where enigmavirtualbox takes care of installing, packing and
generate-evb` takes care of generating the project file.

Problems?

If you encounter a bug, please file an issue.

Suggestions and PRs are welcome :)