Standalone function refactor (#44)

Carol Hansen · web-flow · commit 74918ab1ea3d · 2017-06-15T15:05:41.000-05:00
skel with standalone function and new structure
diff --git a/Makefile b/Makefile
@@ -25,8 +25,8 @@ clean:
 	rm -rf lib/binding
 	rm -rf build
 	# remove remains from running 'make coverage'
-	rm *.profraw
-	rm *.profdata
+	rm -f *.profraw
+	rm -f *.profdata
 	@echo "run 'make distclean' to also clear node_modules, mason_packages, and .mason directories"
 
 distclean: clean
diff --git a/README.md b/README.md
@@ -23,8 +23,20 @@ This repository itself can be cloned and edited to your needs.
 ```
 git clone git@github.com:mapbox/node-cpp-skel.git
 cd node-cpp-skel
-make # build binaries
+
+# Build binaries. This looks to see if there were changes in the C++ code. This does not reinstall deps.
+make
+
+# Run tests
 make test
+
+# Cleans your current builds and removes potential cache
+make clean
+
+# Cleans everything, including the things you download from the network in order to compile (ex: npm packages).
+# This is useful if you want to nuke everything and start from scratch.
+# For example, it's super useful for making sure everything works for Travis, production, someone else's machine, etc
+make disclean
 ```
 
 Note: by default the build errors on compiler warnings. To disable this do:
@@ -33,6 +45,7 @@ Note: by default the build errors on compiler warnings. To disable this do:
 WERROR=false make
 ```
 
+To build from scratch
 
 # Code coverage
 
@@ -53,13 +66,30 @@ If you're developing on macOS and have Xcode installed, you can also type `make
 
 # Usage
 
+### Standalone sync function
 ```javascript
-var HelloWorld = require('./path/to/lib/index.js');
-var HW = new HelloWorld();
+var module = require('./path/to/lib/index.js');
+var check = module.hello();
+
+console.log(check); // => world
+```
+
+### Object
+```javascript
+var module = require('./path/to/lib/index.js');
+var HW = new module.HelloWorld();
 var hi = HW.wave();
+
 console.log(hi); // => howdy world!
 ```
 
+# Add Custom Code
+`node-cpp-skel` was designed to make adding custom code simple and scalable, to form to whatever use-case you may need. Here's how!
+
+- Create a dir in `./src` to hold your custom code. See `./src/standalone` as an example.
+- Add your new method or class to `./src/module.cpp`
+- Add your new file-to-be-compiled to the list of target sources in `./binding.gyp`
+
 # Publishing Binaries
 
 It's a good idea to publish pre-built binaries of your module if you want others to be able to install it properly on their own systems, which can very likely not have a compiler like `gcc` or `clang`. Node-pre-gyp does a lot of the heavy lifting for us (like detecting which system you are building on and deploying to s3) but you'll need a few things configured to get started.
diff --git a/binding.gyp b/binding.gyp
@@ -28,7 +28,16 @@
       'target_name': '<(module_name)',
       'product_dir': '<(module_path)',
       'dependencies': [ 'action_before_build' ],
-      'sources': [ './src/hello_world.cpp' ],
+      # "make" only watches files specified here, and will sometimes cache these files after the first compile.
+      # This cache can sometimes cause confusing errors when removing/renaming/adding new files. 
+      # Running "make clean" helps to prevent this "mysterious error by cache" scenario
+      # This also is where the benefits of using a glob come into play...
+      # See: https://github.com/mapbox/node-cpp-skel/pull/44#discussion_r122050205
+      'sources': [ 
+        './src/module.cpp',
+        './src/standalone/hello.cpp',
+        './src/hello_world.cpp'
+      ],
       'include_dirs': [
         '<!(node -e \'require("nan")\')'
       ],
diff --git a/lib/hello_world.js b/lib/hello_world.js
diff --git a/lib/index.js b/lib/index.js
@@ -1 +1,4 @@
-module.exports = require('./hello_world.js');
+"use strict";
+
+var MODULE = module.exports = require('./binding/module.node');
+MODULE.version = require('../package.json').version;
diff --git a/package.json b/package.json
@@ -26,7 +26,7 @@
     "tape": "^4.5.1"
   },
   "binary": {
-    "module_name": "hello_world",
+    "module_name": "module",
     "module_path": "./lib/binding/",
     "host": "https://mapbox-node-binary.s3.amazonaws.com",
     "remote_path": "./{name}/v{version}/{configuration}/{toolset}/",
diff --git a/src/hello_world.cpp b/src/hello_world.cpp
@@ -274,10 +274,4 @@ NAN_MODULE_INIT(HelloWorld::Init)
     const auto fn = Nan::GetFunction(fnTp).ToLocalChecked();
     constructor().Reset(fn);
     Nan::Set(target, whoami, fn);
-}
-
-/*
- * This creates the module, started up with NAN_MODULE_INIT.
- * The naming/casing of the first argument is reflected in lib/hello_world.js
- */
-NODE_MODULE(HelloWorld, HelloWorld::Init);
+}
diff --git a/src/hello_world.hpp b/src/hello_world.hpp
@@ -32,6 +32,7 @@ class HelloWorld: public Nan::ObjectWrap
         // constructor
         // This includes a Default Argument
         // If a paramter value is passed in, it takes priority over the default arg
+        // HelloWorld --> class
         HelloWorld(std::string name="hello");
 
     private:
diff --git a/src/module.cpp b/src/module.cpp
@@ -0,0 +1,19 @@
+#include <nan.h>
+#include "standalone/hello.hpp"
+#include "hello_world.hpp"
+
+// "target" is a magic var that nodejs passes into modules scope
+// When you write things to target, they become available to call from js
+static void init(v8::Local<v8::Object> target) {
+
+    // expose hello method
+    Nan::SetMethod(target, "hello", standalone::hello);
+    
+    // expose hello_world class
+    HelloWorld::Init(target);
+
+    // add more methods below that youd like to use in node.js-world
+    // then create a .cpp and .hpp file in /src for each new method
+}
+
+NODE_MODULE(module, init)
diff --git a/src/standalone/hello.cpp b/src/standalone/hello.cpp
@@ -0,0 +1,14 @@
+#include "hello.hpp"
+
+namespace standalone {
+
+  // "hello" is a Standalone function because it's not a class.
+  // If this function was not defined within a namespace, it would be in the global scope.
+  NAN_METHOD(hello) {
+
+    // "info" comes from the NAN_METHOD macro, which returns differently
+    // according to the version of node
+    info.GetReturnValue().Set(Nan::New<v8::String>("world").ToLocalChecked());
+  
+  }
+}
diff --git a/src/standalone/hello.hpp b/src/standalone/hello.hpp
@@ -0,0 +1,30 @@
+#pragma once
+#include <nan.h>
+// carrots, ex: <nan.h> --> look for header in global
+// quotes, ex: "hello.hpp" --> look for header in location relative to this file
+
+/*
+
+  Namespace is an organizational method that helps to clearly show where a method is coming from.
+  Namespaces are generally a great idea in C++ because they help us scale things. C++ has no notion of scoped modules,
+  so all of the code you write in any file could potentially conflict with other classes/functions/etc. 
+  Namespaces help to differentiate pieces of your code.
+ 
+  The convention In this skeleton is to name the namespace to match the name of the subdirectory where it lives.
+  So in this case, the namespace is called "standalone" because this method lives within the "standalone" subdirectory.
+  If there is another "hello" function used for another example, the compiler will know the difference between the two:
+ 
+  standalone::hello
+       
+       VS
+
+  potato::hello
+
+*/
+namespace standalone {
+
+	// hello, custom sync method tied to module.cpp
+	// method's logic lives in hello.cpp
+	NAN_METHOD(hello);
+
+}
diff --git a/test/hello.test.js b/test/hello.test.js
@@ -0,0 +1,9 @@
+var test = require('tape');
+var module = require('../lib/index.js');
+
+test('prints world', function(t) {
+  var check = module.hello();
+  t.equal(check, 'world', 'returned world');
+  t.end();
+});
+
diff --git a/test/hello_world.test.js b/test/hello_world.test.js
@@ -1,11 +1,11 @@
 var test = require('tape');
-var HelloWorld = require('../lib/index.js');
-var HW = new HelloWorld();
+var module = require('../lib/index.js');
+var HW = new module.HelloWorld();
 
 test('HellowWorld error - throw exception during construction', function(t) {
   var never = '';
   try {
-    var HWuhoh = new HelloWorld('uhoh');
+    var HWuhoh = new module.HelloWorld('uhoh');
     never = 'neverland';
   } catch (err) {
       t.ok(err, 'expected error');
@@ -17,7 +17,7 @@ test('HellowWorld error - throw exception during construction', function(t) {
 test('HellowWorld error - throw type error during construction', function(t) {
   var never = '';
   try {
-    var HWuhoh = new HelloWorld(24);
+    var HWuhoh = new module.HelloWorld(24);
     never = 'neverland';
   } catch (err) {
       t.ok(err, 'expected error');
@@ -30,7 +30,7 @@ test('HellowWorld error - throw type error during construction', function(t) {
 test('HellowWorld error - invalid constructor', function(t) {
   var never = '';
   try {
-    var HWuhoh = HelloWorld();
+    var HWuhoh = module.HelloWorld();
     never = 'neverland';
   } catch (err) {
       t.ok(err, 'expected error');
@@ -43,7 +43,7 @@ test('HellowWorld error - invalid constructor', function(t) {
 test('HellowWorld success - valid constructor', function(t) {
   var never = '';
   try {
-    var HWyay = new HelloWorld('hello');
+    var HWyay = new module.HelloWorld('hello');
     never = 'neverland';
   } catch (err) {
       if (err) throw err;
