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