Squashed '3rdparty/machinetalk-protobuf/' changes from 4e534c6..314b080

314b080 Merge pull request #62 from mhaberler/master
017ce0a Makefile: make template path configurable, depend on all moving parts
05de663 Merge pull request #60 from machinekit/ArcEye-patch-1
b30e223 Update asciidoc.mustache
a292fb0 Merge pull request #58 from strahlex/python-examples
31afa09 Update README.md
c123a4a add Python examples and install README
dc8c822 Merge pull request #57 from mhaberler/asciidoc-support
72d6749 scripts/asciidoc.mustache: a start - this is still markdown
522d981 Makefile: support different output formats
a2494ab Merge pull request #55 from strahlex/doc-fix
7864694 fix automatic build of documentation
e56f95d Merge pull request #51 from strahlex/preview-doc
59180cd added some documentation for preview.proto
5621140 Merge pull request #50 from strahlex/small-clean
3f5125c updated js bundle
860a798 types.proto: added generic full and incremental update
f2b21dd status.proto: fix case incosistency
8ecfe22 Merge pull request #49 from strahlex/js-bundle
e552450 added bundled JavaScript files for browser
0caef9c js: added scripts to create bundle with browserify
a52ae93 Merge pull request #46 from strahlex/doc
7efd4b5 Merge pull request #48 from bobvanderlinden/nodejs
a289f8b changed the way nodejs packages are created
fe0c77d generating single doc file with defined templated
57b2205 Merge pull request #32 from strahlex/unit-cleanup
773843b added machine unit fields
b449530 Merge pull request #36 from strahlex/python-setup
517a13e fix protojs paths and disabling of protojs
81a4623 added protobuf folder and module __init__ to git
d8e02cc added install rules for .proto and .h files
0ae22d8 create separate build directory to hold all ouputs
b3d8036 build C++, Python, Js, objects all with namespace directories
41ebbcc initial work for Python packaging
9b30785 Merge pull request #35 from strahlex/doc
9d8ad18 Merge pull request #38 from bobvanderlinden/fix-qeueue
126b476 fixed typo in INTERP_QEUEUE_WAIT to INTERP_QUEUE_WAIT
5c1a401 Merge pull request #37 from bobvanderlinden/python-environment
c5c2737 use python from environment
2de4ee6 Added documenation for status.proto
a38a012 Added doc generator
5900be6 Merge pull request #33 from strahlex/tool-table-offset
a4ca021 machinetalk-protobuf: replaced tool table offset fields
621f595 Merge pull request #31 from strahlex/python2_3
cae23c4 fix backwards compatibility with Python2
e653531 Merge pull request #29 from strahlex/origin-fix
f73e663 Merge pull request #30 from strahlex/emccmd-feedback
80dc355 added types for command feedback
f00172a OriginIndex: added ORIGIN_UNKNOWN field:
348d0a9 Merge pull request #23 from bobvanderlinden/unicode-fix
b8dda44 protoc-gen-depends: treat stdin/stdout as byte-streams, not as text-streams
c00f3a6 Merge pull request #21 from mhaberler/master
f2105a1 Update README.md
762b3ad Merge pull request #20 from mhaberler/master
10aad18 Update README.md
7724509 rtapicommand: add task creation flags

git-subtree-dir: 3rdparty/machinetalk-protobuf
git-subtree-split: 314b080

.gitignore

@@ -1,3 +1,3 @@
-objects/*
-js/*.js
+build
+node_modules
 

.npmignore

@@ -0,0 +1,6 @@
+*
+!js
+!build/js/**
+!package.json
+!README*
+!LICENSE*

Makefile

@@ -24,37 +24,35 @@ else
 endif
 ECHO := @echo
 
+DESTDIR := /usr/local
 # all protobuf definitions live here
-PROTODIR := proto
+NAMESPACEDIR := machinetalk/protobuf
+SRCDIR := src
+SRCDIRINV := $(shell realpath --relative-to=$(SRCDIR) .)
+PROTODIR := $(SRCDIR)/$(NAMESPACEDIR)
 
+BUILDDIR := build
 
 # generated C++ headers + source files
-CXXGEN   := generated
+CXXGEN   := $(BUILDDIR)/cpp
 
 # generated Python files
-PYGEN    := python
+PYGEN    := $(BUILDDIR)/python
 
-# disable protobuf.js per default
-PROTOBUFJS := 0
+# generated Documentation files
+# default to asciidoc template
+# for mk-docs formatting, pass in TEMPLATE pointing to the mk-docs template
+TEMPLATE := $(SRCDIRINV)/scripts/asciidoc.mustache
+DOCFORMAT := asciidoc
+DOCEXT := asciidoc
+#DOCFORMAT := markdown
+#DOCEXT := md
 
-# directory for ProtoBuf.js generated files
-PROTOBUFJS_GEN := js
-
-# the proto2js compiler
-PROTOJS := $(shell which proto2js)
+DOCGEN := $(BUILDDIR)/doc
 
 # pkg-config
 PKG_CONFIG := $(shell which pkg-config)
 
-# proto2js options - namespace
-#PROTOBUFJS_OPT := -commonjs=pb
-# http://en.wikipedia.org/wiki/Asynchronous_module_definition
-#PROTOBUFJS_OPT := -amd
-PROTOBUFJS_OPT := -class
-
-# protobuf namespace; all protos except nanopb.proto
-JSNAMESPACE := =pb
-
 # the set of all proto specs generated files depend on
 PROTO_SPECS := $(wildcard $(PROTODIR)/*.proto)
 
@@ -66,67 +64,71 @@ GPBINCLUDE :=  $(shell $(PKG_CONFIG) --variable=includedir protobuf)
 DESCDIR    :=  $(GPBINCLUDE)/google/protobuf
 
 # object files generated during dependency resolving
-OBJDIR := objects
+OBJDIR := $(BUILDDIR)/objects
 
 # search path for .proto files
 # see note on PBDEP_OPT below
 vpath %.proto  $(PROTODIR):$(GPBINCLUDE):$(DESCDIR)/compiler
 
 # machinetalk/proto/*.proto derived Python bindings
-PROTO_PY_TARGETS += $(subst $(PROTODIR)/, \
-	$(PYGEN)/, \
-	$(patsubst %.proto, %_pb2.py, $(PROTO_SPECS)))
+PROTO_PY_TARGETS := ${PROTO_SPECS:$(SRCDIR)/%.proto=$(PYGEN)/%_pb2.py}
+PROTO_PY_EXTRAS := $(PYGEN)/setup.py $(PYGEN)/machinetalk/__init__.py $(PYGEN)/machinetalk/protobuf/__init__.py
 
 # generated C++ includes
-PROTO_CXX_INCS := $(subst $(PROTODIR)/, \
-	$(CXXGEN)/,  \
-	$(patsubst %.proto, %.pb.h, $(PROTO_SPECS)))
+PROTO_CXX_INCS := ${PROTO_SPECS:$(SRCDIR)/%.proto=$(CXXGEN)/%.pb.h}
 
 # generated C++ sources
-PROTO_CXX_SRCS  :=  $(subst $(PROTODIR)/, \
-	$(CXXGEN)/, \
-	$(patsubst %.proto, %.pb.cc, $(PROTO_SPECS)))
+PROTO_CXX_SRCS  :=  ${PROTO_SPECS:$(SRCDIR)/%.proto=$(CXXGEN)/%.pb.cc}
 
+# generated doc file
+DOC_TARGET := $(DOCGEN)/machinetalk-protobuf.$(DOCEXT)
 
 # ---- generate dependcy files for .proto files
 #
 # the list of .d dep files for .proto files:
-PROTO_DEPS :=  $(patsubst %,$(OBJDIR)/%,$(patsubst %.proto,%.d,$(PROTO_SPECS)))
+PROTO_DEPS :=  ${PROTO_SPECS:$(SRCDIR)/%.proto=$(OBJDIR)/%.d}
+
 #
 # options to the dependency generator protoc plugin
 PBDEP_OPT :=
 #PBDEP_OPT += --debug
 PBDEP_OPT += --cgen=$(CXXGEN)
 PBDEP_OPT += --pygen=$(PYGEN)
-PBDEP_OPT += --jsgen=$(PROTOBUFJS_GEN)
 # this path must match the vpath arrangement exactly or the deps will be wrong
 # unfortunately there is no way to extract the proto path in the code
 # generator plugin
-PBDEP_OPT += --vpath=$(PROTODIR)
+PBDEP_OPT += --vpath=$(SRCDIR)
 PBDEP_OPT += --vpath=$(GPBINCLUDE)
 PBDEP_OPT += --vpath=$(DESCDIR)/compiler
 
-$(OBJDIR)/$(PROTODIR)/%.d: $(PROTODIR)/%.proto
+
+GENERATED += \
+	$(PROTO_CXX_SRCS)\
+	$(PROTO_CXX_INCS) \
+	$(PROTO_PY_TARGETS) \
+	$(PROTO_PY_EXTRAS)
+
+$(OBJDIR)/%.d: $(SRCDIR)/%.proto
 	$(ECHO) "protoc create dependencies for $<"
-	@mkdir -p $(OBJDIR)/$(PROTODIR)
+	@mkdir -p $(OBJDIR)/
 	$(Q)$(PROTOC) \
-	--plugin=protoc-gen-depends=scripts/protoc-gen-depends \
-	--proto_path=$(PROTODIR)/ \
-	--proto_path=$(GPBINCLUDE)/ \
-	--depends_out="$(PBDEP_OPT)":$(OBJDIR)/$(PROTODIR)/ \
-	 $<
+		--plugin=protoc-gen-depends=scripts/protoc-gen-depends \
+		--proto_path=$(SRCDIR)/ \
+		--proto_path=$(GPBINCLUDE)/ \
+		--depends_out="$(PBDEP_OPT)":$(OBJDIR)/ \
+		 $<
 
 #---------- C++ rules -----------
 #
 # generate .cc/.h from proto files
 # for command.proto, generated files are: command.pb.cc	command.pb.h
-$(CXXGEN)/%.pb.cc $(CXXGEN)/%.pb.h: %.proto
+$(CXXGEN)/%.pb.cc $(CXXGEN)/%.pb.h: $(SRCDIR)/%.proto
 	$(ECHO) "protoc create $@ from $<"
 	@mkdir -p $(CXXGEN)
 	$(Q)$(PROTOC) $(PROTOCXX_FLAGS) \
-	--proto_path=$(PROTODIR)/ \
+	--proto_path=$(SRCDIR)/ \
 	--proto_path=$(GPBINCLUDE)/ \
-	--cpp_out=$(CXXGEN)/ \
+	--cpp_out=$(CXXGEN) \
 	$<
 
 # ------------- Python rules ------------
@@ -135,61 +137,58 @@ $(CXXGEN)/%.pb.cc $(CXXGEN)/%.pb.h: %.proto
 # adapt here if using one of the accelerated methods
 #
 # generate Python modules from proto files
-$(PYGEN)/%_pb2.py: %.proto
+$(PYGEN)/%_pb2.py: $(SRCDIR)/%.proto
 	$(ECHO) "protoc create $@ from $<"
 	@mkdir -p $(PYGEN)
 	$(Q)$(PROTOC) $(PROTOC_FLAGS) \
-	--proto_path=$(PROTODIR)/ \
-	--proto_path=$(GPBINCLUDE)/ \
-	--python_out=$(PYGEN)/ \
-	$<
-
-# ------------- ProtoBuf.js rules ------------
-#
-# see https://github.com/dcodeIO/ProtoBuf.js
-#
-# generate Javascript modules from proto files
-#=$(filter-out %/butterfly.ngc,$(call GLOB,../nc_files/*))
-
-$(PROTOBUFJS_GEN)/%.js: %.proto
-	$(ECHO) $(PROTOJS)" create $@ from $<"
-	@mkdir -p $(PROTOBUFJS_GEN)
-	$(Q)$(PROTOJS) 	$< \
-	$(PROTOBUFJS_OPT)$(JSNAMESPACE) \
-	> $@
-
-# nanopb.proto needs different opts - no namespace argument
-$(PROTOBUFJS_GEN)/nanopb.js: $(PROTODIR)/nanopb.proto
-	$(ECHO) $(PROTOJS)" create $@ from $<"
-	@mkdir -p $(PROTOBUFJS_GEN)
-	$(Q)$(PROTOJS) 	$< \
-	$(PROTOBUFJS_OPT) \
-	> $@
-
-# generated Javasript sources
-# everything is namespace pb except nanopb.proto
-PROTO_PROTOBUFJS_SRCS  :=  $(subst $(PROTODIR)/, \
-	$(PROTOBUFJS_GEN)/, \
-	$(filter-out $(PROTODIR)/nanopb.js, $(patsubst %.proto, %.js, $(PROTO_SPECS))))
-
-
-GENERATED += $(PROTO_PY_TARGETS) \
-	$(PROTO_CXX_SRCS)\
-	$(PROTO_CXX_INCS)
-
+		--proto_path=$(SRCDIR)/ \
+		--proto_path=$(GPBINCLUDE)/ \
+		--python_out=$(PYGEN)/ \
+		$<
 
-ifeq ($(PROTOBUFJS),1)
-GENERATED += $(PROTO_PROTOBUFJS_SRCS) $(PROTOBUFJS_GEN)/nanopb.js
-endif
+$(PYGEN)/%.py: python/%.py
+	cp "$<" "$@"
 
 # force create of %.proto-dependent files and their deps
 Makefile: $(GENERATED) $(PROTO_DEPS)
 -include $(PROTO_DEPS)
 
+# ------------- protoc-gen-doc rules ------------
+#
+# see https://github.com/estan/protoc-gen-doc
+#
+# generate $(DOCFORMAT) files from proto files
+$(DOC_TARGET): $(wildcard $(SRCDIR)/*.proto) $(TEMPLATE) Makefile
+#doc_base:
+	$(ECHO) "protoc create $@ from *.proto"
+	@mkdir -p $(DOCGEN)
+	$(Q)cd $(SRCDIR); \
+	$(PROTOC) $(PROTOC_FLAGS) \
+	--proto_path=./ \
+	--proto_path=$(GPBINCLUDE)/ \
+	--doc_out=$(TEMPLATE),$(SRCDIRINV)/$@:./ \
+	$(NAMESPACEDIR)/*.proto
+
+all: $(GENERATED) $(PROTO_DEPS)
+
 ios_replace:
 	sh scripts/ios-replace.sh $(CXXGEN)
 
-all:  $(PROTO_DEPS) $(GENERATED)
+docs: $(PROTO_DEPS) $(DOC_TARGET)
 
 clean:
-	rm -rf $(OBJDIR) $(CXXGEN) $(PYGEN) $(PROTO_PROTOBUFJS_SRCS)
+	rm -rf build
+
+install_proto: $(PROTO_SPECS)
+	mkdir -p $(DESTDIR)/include/$(NAMESPACEDIR)
+	for proto in $(PROTO_SPECS); do \
+		install -m 0644 $$proto $(DESTDIR)/include/$(NAMESPACEDIR); \
+	done
+
+install_cpp: $(PROTO_CXX_INCS)
+	mkdir -p $(DESTDIR)/include/$(NAMESPACEDIR)
+	for headerfile in $(PROTO_CXX_INCS); do \
+		install -m 0644 $$headerfile $(DESTDIR)/include/$(NAMESPACEDIR); \
+	done
+
+install: install_proto install_cpp

README.md

@@ -5,8 +5,92 @@ Protobuf declarations for machinekit messages
 
 This repo is integrated into github.com/machinekit/machinekit as a git subtree.
 
-To change message definitions, send a PR against this repo, then update the subtree in the machinekit repo.
+To change/add to message definitions:
 
+* send a PR against this repo
+* add a new remote in your machinekit repo referring to here
+* update the subtree in your machinekit repo like so
 
+```
+git remote add machinetalk-protobuf git://github.com/machinekit/machinetalk-protobuf.git
+git fetch machinetalk-protobuf
+git subtree merge --prefix=src/machinetalk/proto machinetalk-protobuf/master --squash
+```
 
+Now create a PR against the machinekit repo.
 
+## Python
+
+### Installation
+
+To use the Machinetalk protobuf Python modules in your projects, use:
+
+```sh
+cd python
+python setup.py build
+sudo python setup.py install
+```
+
+### Usage
+See [examples](python/examples). 
+
+## JavaScript (NPM/NodeJS)
+
+### Installation
+
+To use machinetalk protobuf definitions in your npm-based projects, use:
+
+```sh
+npm install --save machinetalk-protobuf
+```
+
+### Usage
+
+See [examples](js/examples). If you want to try these examples, be sure to first run `npm install` in this repository.
+
+#### Encoding
+
+```js
+var machinetalkProtobuf = require('machinetalk-protobuf');
+var messageContainer = {
+  type: machinetalkProtobuf.message.ContainerType.MT_PING
+};
+var encodedMessageContainer = machinetalkProtobuf.message.Container.encode(messageContainer);
+```
+This results in a buffer that starts with `0x08 0xd2 0x01`.
+
+#### Decoding
+
+```js
+var machinetalkProtobuf = require('machinetalk-protobuf');
+var encodedBuffer = new Buffer([0x08, 0xd2, 0x01]);
+var decodedMessageContainer = machinetalkProtobuf.message.Container.decode(encodedBuffer);
+```
+This results in a messageContainer like the one defined in [Encoding](#Encoding).
+
+## JavaScript (Browser)
+
+### CDN usage
+```html
+<script src="//cdn.rawgit.com/machinekit/machinetalk-protobuf/VERSION/dist/machinetalk-protobuf.js"></script>
+```
+With `VERSION` replaced by [a valid tag](https://github.com/machinekit/machinetalk-protobuf/releases) or just `master` for testing
+the latest master build.
+
+### Encoding
+
+```js
+var messageContainer = {
+  type: machinetalk.protobuf.message.ContainerType.MT_PING
+};
+var encodedMessageContainer = machinetalk.protobuf.message.Container.encode(messageContainer);
+```
+This results in a buffer that starts with `0x08 0xd2 0x01`.
+
+#### Decoding
+
+```js
+var encodedBuffer = new ArrayBuffer([0x08, 0xd2, 0x01]);
+var decodedMessageContainer = machinetalk.protobuf.message.Container.decode(encodedBuffer);
+```
+This results in a messageContainer like the one defined in [Encoding](#Encoding).