platform-tools

A toolchain to build and compile native dependencies with and for Node.

TL;DR

Compile C/C++ and native node addons with Node.js. Under the hood this is shelling out to gcc, clang and cl.exe in a similar way make does. To mitigate gyp and autotools dependencies node users (eventually) could use this.

Assume a file exit_with_1.c

int main(int argc, char const* argv[]) {
  return 1;
}

The below would be an example of emulating with Node.js

gcc -c exit_with_1
gcc -o exit_with_1.o
./exit_with_1

const platform_tools = require('platform-tools')
const spawn = require('child_process').spawn

let out = 'exit_with_1'
// first compile without linking
platform_tools.compile('exit_with_1.c', {output: `${out}.o`}, () => {
  // then link the object file (here an easy case)
  platform_tools.link(`${out}.o`, {output: out}, () => {
    // now execute the compiled binary and expect the C-program to end
    // with code 1
    const cp = spawn(out, [], {shell: true});
    cp.on('close', (code) => {
      assert(code === 1), 'Compiled binary exit_with_1 must exit with code 1')
    })
  })
})

Implementation Status

| Method | implemented | | --- | --- | | .compile(source [,options, cb]) | yes | | .compileAddon(source [,options, cb]) | yes | | .link(object [,options, cb]) | yes | | .config(library [,options, cb]) | yes |

Overview

(TBD)

Also this makes it easier for libarary authors and users, since compilation output will either be stored into a user specified location or by default into the current working directories build/ directory (precisely `${process.cwd()}/build`)

Technical Overview

Rquirements:

• Node 4.5.0+
• the default compiler for your system

Windows Users

Mote: since this repo wants to purposely increase Windows native addon usabilty please share if you have a hard time. However ue to the Microsoft inherent SDK and compiler strategy we need to assume prerequisites of you.

• Windows SDK 10 standalone should be installed and in your %ProgramFiles(x86)%
• Visual Studio 2015 should be installed and in your %ProgramFiles(x86)%

For background: To accomplish unix-like command-line behavior, e.g. gcc source_file.c -o source.exe && ./source.exe we need to assume the location of the most basic C/C++ headers in various locations on your Windows installation. The cl.exe binary does not assume any search paths on it's own, if it is not run through Visual Studio. Although that being quite a quirk for embedders and library authors, Windows compiler support is as good as Unix'.

Platform

This module is currently tested on:

| Platform | 0.10 | 0.12 | 4.0 | 5.0 | 6.0 | | --- | --- | --- | --- | ---| ---|---| | Mac OS X | - | - | yes | yes| yes | | BSDs| - | - | yes | yes| yes | | Linux | - | - | yes | yes | yes | | Windows | - | - | yes | yes | yes |

Roadmap

• have more complex C/C++ files compile and link fully
• ~~make native addons build~~
• make node build
• make v8 build
• override values that the lib takes as assumption
• gyp-file integration (chop-off comments and trailing commas -> then done?)
• more sophisticated Windows search path fallbacks for not optimal installatons

API

PlatformTools

Kind: global class

• PlatformTools
  • .compile(source, cb) ⇒ Callback
  • .link(object, options, cb) ⇒ Callback
  • .config(lib, cb) ⇒ Callback
  • .compileAddon(addonSrcFile, options, cb) ⇒ Callback

platformTools.compile(source, cb) ⇒ Callback

Compiles a given source code file or array of files to the platforms object code.

Kind: instance method of PlatformTools

| Param | Type | Description | | --- | --- | --- | | source | String | Array.<String> | Path to source | | cb | function | Optional callback for completion |

platformTools.link(object, options, cb) ⇒ Callback

Links mutiple objects and libraries to a binary.

Kind: instance method of PlatformTools

| Param | Type | Description | | --- | --- | --- | | object | String | Array.<String> | Path for name of object code file | | options | Object | Options object | | cb | function | Optional callback |

platformTools.config(lib, cb) ⇒ Callback

Returns the necessary libraries to link against, similarly to pkg-config(1).

Kind: instance method of PlatformTools

| Param | Type | Description | | --- | --- | --- | | lib | String | Library to search dependencies against | | cb | function | Optional Callback upon completion |

platformTools.compileAddon(addonSrcFile, options, cb) ⇒ Callback

This method compiles node native addons end-to-end. Motivation behind this high level approach is past struggles with this technique, and especially different behaviors across platforms. Eventually this method should take care of all of the above. If the user has special cases, it is still possible to pass instructions via the options object and (item for roadmap) override certain common variables forcefully.

Kind: instance method of PlatformTools
Returns: Callback - returns optional callback

| Param | Type | Description | | --- | --- | --- | | addonSrcFile | String | Path to source file | | options | Object | Options object | | cb | function | |

License

MIT