1Protocol Buffers - Google's data interchange format 2=================================================== 3 4[![Build status](https://storage.googleapis.com/protobuf-kokoro-results/status-badge/linux-javascript.png)](https://fusion.corp.google.com/projectanalysis/current/KOKORO/prod:protobuf%2Fgithub%2Fmaster%2Fubuntu%2Fjavascript%2Fcontinuous) [![Build status](https://storage.googleapis.com/protobuf-kokoro-results/status-badge/macos-javascript.png)](https://fusion.corp.google.com/projectanalysis/current/KOKORO/prod:protobuf%2Fgithub%2Fmaster%2Fmacos%2Fjavascript%2Fcontinuous) 5 6Copyright 2008 Google Inc. 7 8This directory contains the JavaScript Protocol Buffers runtime library. 9 10The library is currently compatible with: 11 121. CommonJS-style imports (eg. `var protos = require('my-protos');`) 132. Closure-style imports (eg. `goog.require('my.package.MyProto');`) 14 15Support for ES6-style imports is not implemented yet. Browsers can 16be supported by using Browserify, webpack, Closure Compiler, etc. to 17resolve imports at compile time. 18 19To use Protocol Buffers with JavaScript, you need two main components: 20 211. The protobuf runtime library. You can install this with 22 `npm install google-protobuf`, or use the files in this directory. 23 If npm is not being used, as of 3.3.0, the files needed are located in binary subdirectory; 24 arith.js, constants.js, decoder.js, encoder.js, map.js, message.js, reader.js, utils.js, writer.js 252. The Protocol Compiler `protoc`. This translates `.proto` files 26 into `.js` files. The compiler is not currently available via 27 npm, but you can download a pre-built binary 28 [on GitHub](https://github.com/protocolbuffers/protobuf/releases) 29 (look for the `protoc-*.zip` files under **Downloads**). 30 31 32Setup 33===== 34 35First, obtain the Protocol Compiler. The easiest way is to download 36a pre-built binary from [https://github.com/protocolbuffers/protobuf/releases](https://github.com/protocolbuffers/protobuf/releases). 37 38If you want, you can compile `protoc` from source instead. To do this 39follow the instructions in [the top-level 40README](https://github.com/protocolbuffers/protobuf/blob/master/src/README.md). 41 42Once you have `protoc` compiled, you can run the tests by typing: 43 44 $ cd js 45 $ npm install 46 $ npm test 47 48 # If your protoc is somewhere else than ../src/protoc, instead do this. 49 # But make sure your protoc is the same version as this (or compatible)! 50 $ PROTOC=/usr/local/bin/protoc npm test 51 52This will run two separate copies of the tests: one that uses 53Closure Compiler style imports and one that uses CommonJS imports. 54You can see all the CommonJS files in `commonjs_out/`. 55If all of these tests pass, you know you have a working setup. 56 57 58Using Protocol Buffers in your own project 59========================================== 60 61To use Protocol Buffers in your own project, you need to integrate 62the Protocol Compiler into your build system. The details are a 63little different depending on whether you are using Closure imports 64or CommonJS imports: 65 66Closure Imports 67--------------- 68 69If you want to use Closure imports, your build should run a command 70like this: 71 72 $ protoc --js_out=library=myproto_libs,binary:. messages.proto base.proto 73 74For Closure imports, `protoc` will generate a single output file 75(`myproto_libs.js` in this example). The generated file will `goog.provide()` 76all of the types defined in your .proto files. For example, for the unit 77tests the generated files contain many `goog.provide` statements like: 78 79 goog.provide('proto.google.protobuf.DescriptorProto'); 80 goog.provide('proto.google.protobuf.DescriptorProto.ExtensionRange'); 81 goog.provide('proto.google.protobuf.DescriptorProto.ReservedRange'); 82 goog.provide('proto.google.protobuf.EnumDescriptorProto'); 83 goog.provide('proto.google.protobuf.EnumOptions'); 84 85The generated code will also `goog.require()` many types in the core library, 86and they will require many types in the Google Closure library. So make sure 87that your `goog.provide()` / `goog.require()` setup can find all of your 88generated code, the core library `.js` files in this directory, and the 89Google Closure library itself. 90 91Once you've done this, you should be able to import your types with 92statements like: 93 94 goog.require('proto.my.package.MyMessage'); 95 96 var message = proto.my.package.MyMessage(); 97 98If unfamiliar with Closure or it's compiler, consider reviewing Closure documentation 99https://developers.google.com/closure/library/docs/tutorial 100https://developers.google.com/closure/library/docs/closurebuilder 101https://developers.google.com/closure/library/docs/depswriter 102At a high level, closurebuilder.py can walk dependencies, and compile your code, and all dependencies for Protobuf into a single .js file. Using depsbuilder.py to generate a dependency file can also be considered for non-production dev environments. 103 104CommonJS imports 105---------------- 106 107If you want to use CommonJS imports, your build should run a command 108like this: 109 110 $ protoc --js_out=import_style=commonjs,binary:. messages.proto base.proto 111 112For CommonJS imports, `protoc` will spit out one file per input file 113(so `messages_pb.js` and `base_pb.js` in this example). The generated 114code will depend on the core runtime, which should be in a file called 115`google-protobuf.js`. If you are installing from `npm`, this file should 116already be built and available. If you are running from GitHub, you need 117to build it first by running: 118 119 $ gulp dist 120 121Once you've done this, you should be able to import your types with 122statements like: 123 124 var messages = require('./messages_pb'); 125 126 var message = new messages.MyMessage(); 127 128The `--js_out` flag 129------------------- 130 131The syntax of the `--js_out` flag is: 132 133 --js_out=[OPTIONS:]output_dir 134 135Where `OPTIONS` are separated by commas. Options are either `opt=val` or 136just `opt` (for options that don't take a value). The available options 137are specified and documented in the `GeneratorOptions` struct in 138[src/google/protobuf/compiler/js/js_generator.h](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/compiler/js/js_generator.h#L53). 139 140Some examples: 141 142- `--js_out=library=myprotos_lib.js,binary:.`: this contains the options 143 `library=myprotos.lib.js` and `binary` and outputs to the current directory. 144 The `import_style` option is left to the default, which is `closure`. 145- `--js_out=import_style=commonjs,binary:protos`: this contains the options 146 `import_style=commonjs` and `binary` and outputs to the directory `protos`. 147 `import_style=commonjs_strict` doesn't expose the output on the global scope. 148 149API 150=== 151 152The API is not well-documented yet. Here is a quick example to give you an 153idea of how the library generally works: 154 155 var message = new MyMessage(); 156 157 message.setName("John Doe"); 158 message.setAge(25); 159 message.setPhoneNumbers(["800-555-1212", "800-555-0000"]); 160 161 // Serializes to a UInt8Array. 162 var bytes = message.serializeBinary(); 163 164 var message2 = MyMessage.deserializeBinary(bytes); 165 166For more examples, see the tests. You can also look at the generated code 167to see what methods are defined for your generated messages. 168