isabella232 / manticore-native

A runtime to expose Javascript classes, logic and code to native components on Mac/PC/Phones/RPis

Manticore

A cross platform Javascript runtime environment, built specifically for native mobile development and enabled by code generation.

• Bidirectional invocation - JavaScript calling native callbacks and vice versa
• True object portability across the native boundary - not just primitive types, and no "frozen" types requiring synchronization
• Asynchronous Javascript methods (e.g. Promises) exposed in native-friendly ways
• The ability to completely hide the fact that it's "Javascript all the way down" from your code consumers

Code Portability

If you wrote a single library in JavaScript, here are all the platforms where Manticore could help you compile it into native code:

Platform	Version	Native	Distro	Version	CI Status
iOS	7.0+	Obj C	CocoaPods	none
MacOS	10.9+	Obj C	CocoaPods	none
Android	API 19+	Java	JCenter	none
Windows	XP (.Net4)	C#	NuGet	none
Windows	7,8,Vista (v8 )	C#	NuGet	none
Windows	8.1, 8.1 Phone, 10 (jint)	C#	NuGet	none	CI not running
codegen	0.12	JS	npm	none

How It Works

Pre-Compilation: Generating Native Classes

The manticore-gen script generates native interface shims in a target language (Objective-C, Java, and C# currently) -- code to interact with the proper Manticore runtime and Javascript engine for that platform. The generator reads class and type information from the JSDoc comments in the JavaScript, stores it as JSON, and uses DustJS templates to render the native code.

As such, there is a different template for each language, which you can customize or replace.

For more information, see the README in lib/manticore-gen.

Pre-Compilation: Generating Runtime JavaScript

Manticore provides scripts to combine all the source JavaScript code (and its dependencies) into one large file, using (among other things) browserify and folderify. This is the implementation code, for which the native shims are the interface.

For more information, see the README in lib/mantify.

Initialization: Launching Manticore-Powered Code

Manticore launches a native JavaScript environment and loads the unified JavaScript file into it.

For more information, see the runtime documentation or complete example projects.

Runtime: Crossing the Boundary

The Manticore runtime provides the boilerplate code that's used for each method and field of the underlying JavaScript: native calls that dive into the JavaScript layer and convert types back and forth. For primitive types this conversion is "simple." For other Manticore or non-native types, the objects returned are still the same thin shims over JavaScript -- where all calls to properties and methods will be sent. This means there is no "synchronization" of values or events or anything - there is only one truth, and it lives in the JavaScript environment.

License

Manticore (manticore-native) is available under the Apache 2.0 License. See LICENSE.txt.

Contributing

See CONTRIBUTING.md.

Isn't There a Project That Already Does This?

If you're referring to Apache Cordova, Adobe PhoneGap, React Native, or SWIG, see Comparisons.md, summarized in this table:

	Cordova / PhoneGap	React Native	SWIG	Manticore
TL;DR	Webviews everywhere	Learn once, run "anywhere"	C++ wrappers everywhere	JS wrappers everywhere
You write common code in	HTML / CSS / JS	JSX / JS	C++	JS / ES6
Hardware access provided by	Plugins	Plugins	(Native)	(Native)
main()defined in	JS	JSX / JS	(Native)	(Native)
UI managed by	Cordova library	OS-specific modules	(Native)	(Native)
Runs on iOS	Yes	Yes		Yes
Runs on MacOS			Yes	Yes
Runs on Android	Yes	Yes	Yes	Yes
Runs on Windows Phone	Yes		Yes	Yes
Runs on Windows XP and up			Yes	Yes
Runs in web browsers	Yes			Yes
Runs on Windows Phone (8.1)			Yes	Yes
Runs on ChromeOS / Chrome Apps			?	Yes
Runs in Node.js			Yes	Yes
Compatible with Cordova / PhoneGap	-	No	?	Yes
Compatible with React Native	No	-	?	Yes

Help

Where-to-post summary:

• How do I? -- StackExchange
• I got this error, why? -- StackExchange
• I got this error and I'm sure it's a bug -- file an issue
• I have an idea/request -- file an issue