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