github.com/bazelbuild/bazel-watcher@v0.25.2/README.md (about) 1 # Bazel watcher 2 3 [![Build status](https://badge.buildkite.com/7694a2e22dcb7ea2e2ec80bb7e8e0380c700079e761394096f.svg?branch=master)](https://buildkite.com/bazel/bazel-watcher-postsubmit) 4 5 Note: This is not an official Google product. 6 7 A source file watcher for [Bazel](https://Bazel.build) projects 8 9 Ever wanted to save a file and have your tests automatically run? How about 10 restart your webserver when one of the source files change? Look no further. 11 12 Install `ibazel` using one of the 3 methods [described below](#installation). Then: 13 14 ```bash 15 $ ibazel build //path/to/my:target 16 ``` 17 18 Hack hack hack. Save and your target will be rebuilt. 19 20 Right now this repo supports `build`, `test`, and `run`. 21 22 ## Installation 23 24 There are several ways to install iBazel, documented below. 25 26 ### Mac (Homebrew) 27 28 If you run a macOS you can install it from [homebrew](https://brew.sh). 29 30 ```sh 31 $ brew install ibazel 32 ``` 33 34 ### NPM 35 36 If you're a JS developer you can install it as a `devDependency` or by calling `npm install` directly in your project 37 38 ``` 39 $ npm install @bazel/ibazel 40 ``` 41 42 ### Linux 43 44 Packages are available for the following distributions: 45 46 * **Arch Linux**: [`aur/ibazel`][install/linux/archlinux/aur] 47 48 [install/linux/archlinux/aur]: https://aur.archlinux.org/packages/ibazel 49 50 ### Compiling yourself 51 52 You can, of course, build iBazel using Bazel. 53 54 ``` 55 $ git clone git@github.com:bazelbuild/bazel-watcher 56 $ cd bazel-watcher 57 $ bazel build //cmd/ibazel 58 ``` 59 60 Now copy the generated binary onto your path: 61 62 ```bash 63 $ export PATH=$PATH:$PWD/bazel-bin/cmd/ibazel/ibazel_ 64 ``` 65 66 ## Running a target 67 68 By default, a target started with `ibazel run` will be terminated and restarted 69 whenever it's notified of source changes. Alternatively, if the build rule for 70 your target contains `ibazel_notify_changes` in its `tags` attribute, then the 71 command will stay alive and will receive a notification of the source changes on 72 stdin. 73 74 ## Output Runner 75 76 iBazel is capable of producing and running commands from the output of Bazel 77 commands. If iBazel is run with the flag `--run_output` then it will check for 78 a `%WORKSPACE%/.bazel_fix_commands.json` and if present run any commands that 79 match the provided regular expressions. For example the commands defined by 80 the following file will match `buildozer` commands found in the output and 81 provide a prompt to run the command as well as invoke `bazel run //:gazelle` if 82 it detects a missing import for your go code. 83 84 ``` 85 [ 86 { 87 "regex": "^Check that imports in Go sources match importpath attributes in deps.$", 88 "command": "bazel", 89 "args": [ "run", "//:gazelle" ] 90 }, 91 { 92 "regex": "^buildozer '(.*)'\\s+(.*)$", 93 "command": "buildozer", 94 "args": [ "$1", "$2" ] 95 }, 96 { 97 "regex": "^(\\S+)/[\\w-]+\\.proto:\\d+:\\d+: Import \"\\S+\" was not found or had errors\\.$", 98 "command": "bazel", 99 "args": [ "run", "//:gazelle", "--", "proto/$1" ] 100 } 101 ] 102 ``` 103 104 Adding the flag `--run_output_interactive=false` will automatically run the 105 command without prompting for confirmation. The fields in 106 `.bazel_fix_commands.json` are: 107 108 * `regex`: a regular expression that will be matched against every line of 109 output. 110 * backslash `\` characters will need to be escaped once for the regex to be 111 parsed properly. 112 * `command`: a command that will be run from the workspace root. 113 * `args`: a list of arguments to provide to the command, substituting `$1` 114 with the first match group of `regex`, `$2` with the second, etc., and `$0` 115 for the entire match. 116 117 You can disable this feature by adding flag `--run_output=false` or you can 118 create a `.bazel_fix_commands.json` that contains an empty json array, `[]`. 119 This will additionally disable the notification providing usage instructions on 120 the first invocation of iBazel. 121 122 ### Disabling output runner 123 124 If you would like to remove the banner but don't wish to configure the output 125 runner, you can create an empty configuration file like this: 126 127 ```sh 128 echo "[]" > .bazel_fix_commands.json 129 ``` 130 131 You should no longer be prompted when iBazel starts up. 132 133 ## Profiling 134 135 iBazel has a `--profile_dev` flag which turns on a generated profile output file 136 about the build process and timing. To use it include this flag in the command line. For example, 137 138 ``` 139 ibazel --profile_dev=profile.json run devserver 140 ``` 141 142 The profile outfile is in concatenated JSON format. Events are outputted one per line. 143 144 ### Profiler events 145 146 | Event | Description | Attributes <font size=1>(* optional)</font> | 147 | ------------- | ------------- | ------------- | 148 | `IBAZEL_START` | Emitted when iBazel is started as part of the first iteration | `type`, `iteration`, `time`, `iBazelVersion`, `bazelVersion`, `maxHeapSize`, `committedHeapSize` | 149 | `SOURCE_CHANGE` | A source file change was detected | `type`, `iteration`, `time`, `targets`, `elapsed`, `change` | 150 | `GRAPH_CHANGE` | A build file change was detected | `type`, `iteration`, `time`, `targets`, `elapsed`, `changes`* | 151 | `RELOAD_TRIGGERED` | A livereload was triggered to any listening browsers | `type`, `iteration`, `time`, `targets`, `elapsed`, `changes`* | 152 | `RUN_START` | A run operation started | `type`, `iteration`, `time`, `targets`, `elapsed`, `changes`* | 153 | `RUN_FAILED` | A run operation failed | `type`, `iteration`, `time`, `targets`, `elapsed`, `changes`* | 154 | `RUN_DONE` | A run operation completed successfully | `type`, `iteration`, `time`, `targets`, `elapsed`, `changes`* | 155 | `BUILD_START` | A build operation started | `type`, `iteration`, `time`, `targets`, `elapsed`, `changes`* | 156 | `BUILD_FAILED` | A build operation failed | `type`, `iteration`, `time`, `targets`, `elapsed`, `changes`* | 157 | `BUILD_DONE` | A build operation completed successfully | `type`, `iteration`, `time`, `targets`, `elapsed`, `changes`* | 158 | `TEST_START` | A test operation started | `type`, `iteration`, `time`, `targets`, `elapsed`, `changes`* | 159 | `TEST_FAILED` | A test operation failed | `type`, `iteration`, `time`, `targets`, `elapsed`, `changes`* | 160 | `TEST_DONE` | A test operation completed successfully | `type`, `iteration`, `time`, `targets`, `elapsed`, `changes`* | 161 | `REMOTE_EVENT` | A remote event was received from the browser | `type`, `iteration`, `time`, `targets`, `elapsed`, `remoteType`, `remoteTime`, `remoteElapsed`, `remoteData` | 162 | `REMOTE_EVENT / PAGE_LOAD` | A remote event emitted by the profiler client-side script on the browser's `load` event. `remoteType` is `PAGE_LOAD`. | `type`, `iteration`, `time`, `targets`, `elapsed`, `remoteType`, `remoteTime`, `remoteElapsed`, `remoteData` | 163 164 ### Event attributes 165 166 | Attribute | Type | Description | 167 | ------------- | ------------- | ------------- | 168 | `type` | string | Event type. | 169 | `iteration` | string | Unique build iteration key. | 170 | `time` | integer | Time of event. | 171 | `targets` | string[] | List of targets that are being built (Note: this is a complete list and includes targets that were already built prior to an iteration). | 172 | `elapsed` | integer | Elapsed time in ms since the start of the iteration. | 173 | `change` | string | The file changed on a `SOURCE_CHANGE` or `GRAPH_CHANGE` event. | 174 | `changes` | string[] | A cumulative list of files changed during a build iteration. | 175 | `iBazelVersion` | string | Version of iBazel that generated this event. | 176 | `bazelVersion` | string | Version of bazel in use. | 177 | `maxHeapSize` | string | Max heap size as reported by Bazel. | 178 | `committedHeapSize` | string | Committed heap size as reported by Bazel. | 179 | `remoteType` | string | Sub-type for `REMOTE_EVENT` type. | 180 | `remoteTime` | number | Browser time for `REMOTE_EVENT` type. | 181 | `remoteElapsed` | number | Elapsed time in browser since `navigationStart` for `REMOTE_EVENT` type. | 182 | `remoteData` | string | Data sent from browser for `REMOTE_EVENT` type. This may be in escaped JSON format for some remote events. | 183 184 ### Example profile output file 185 186 You can find an example profile output JSON file [here](https://github.com/bazelbuild/bazel-watcher/blob/master/example.profile.json). Below is the file in pretty print JSON format: 187 188 ``` 189 { 190 "type": "IBAZEL_START", 191 "iteration": "4214114686684e0f", 192 "time": 1513706108351, 193 "iBazelVersion": "v0.2.0-dirty", 194 "bazelVersion": "release 0.8.1-homebrew", 195 "maxHeapSize": "3817MB", 196 "committedHeapSize": "1372MB" 197 } 198 { 199 "type": "RUN_START", 200 "iteration": "4214114686684e0f", 201 "time": 1513706109329, 202 "targets": [ 203 "//src:devserver" 204 ], 205 "elapsed": 978 206 } 207 { 208 "type": "RELOAD_TRIGGERED", 209 "iteration": "4214114686684e0f", 210 "time": 1513706114595, 211 "targets": [ 212 "//src:devserver" 213 ], 214 "elapsed": 6244 215 } 216 { 217 "type": "RUN_DONE", 218 "iteration": "4214114686684e0f", 219 "time": 1513706114595, 220 "targets": [ 221 "//src:devserver" 222 ], 223 "elapsed": 6244 224 } 225 { 226 "type": "SOURCE_CHANGE", 227 "iteration": "7e6f8e150e9a8367", 228 "time": 1513706129384, 229 "targets": [ 230 "//src:devserver" 231 ], 232 "change": "/Users/greg/google/gregmagolan/angular-bazel-example/src/hello-world/hello-world.component.ts" 233 } 234 { 235 "type": "RUN_START", 236 "iteration": "7e6f8e150e9a8367", 237 "time": 1513706129484, 238 "targets": [ 239 "//src:devserver" 240 ], 241 "elapsed": 100, 242 "changes": [ 243 "/Users/greg/google/gregmagolan/angular-bazel-example/src/hello-world/hello-world.component.ts" 244 ] 245 } 246 { 247 "type": "RELOAD_TRIGGERED", 248 "iteration": "7e6f8e150e9a8367", 249 "time": 1513706133947, 250 "targets": [ 251 "//src:devserver" 252 ], 253 "elapsed": 4563, 254 "changes": [ 255 "/Users/greg/google/gregmagolan/angular-bazel-example/src/hello-world/hello-world.component.ts" 256 ] 257 } 258 { 259 "type": "RUN_DONE", 260 "iteration": "7e6f8e150e9a8367", 261 "time": 1513706133947, 262 "targets": [ 263 "//src:devserver" 264 ], 265 "elapsed": 4563, 266 "changes": [ 267 "/Users/greg/google/gregmagolan/angular-bazel-example/src/hello-world/hello-world.component.ts" 268 ] 269 } 270 { 271 "type": "REMOTE_EVENT", 272 "iteration": "7e6f8e150e9a8367", 273 "time": 1513706134297, 274 "targets": [ 275 "//src:devserver" 276 ], 277 "elapsed": 4913, 278 "remoteType": "PAGE_LOAD", 279 "remoteTime": 1513706134294, 280 "remoteElapsed": 346, 281 "remoteData": "{\"pageLoadTime\":344,\"fetchTime\":9,\"connectTime\":0,\"requestTime\":6,\"responseTime\":6,\"renderTime\":325,\"navigationStart\":1513706133948,\"unloadEventStart\":1513706133962,\"unloadEventEnd\":1513706133962,\"redirectStart\":0,\"redirectEnd\":0,\"fetchStart\":1513706133952,\"domainLookupStart\":1513706133952,\"domainLookupEnd\":1513706133952,\"connectStart\":1513706133952,\"connectEnd\":1513706133952,\"secureConnectionStart\":0,\"requestStart\":1513706133955,\"responseStart\":1513706133955,\"responseEnd\":1513706133961,\"domLoading\":1513706133967,\"domInteractive\":1513706134222,\"domContentLoadedEventStart\":1513706134222,\"domContentLoadedEventEnd\":1513706134222,\"domComplete\":1513706134292,\"loadEventStart\":1513706134292}" 282 } 283 ``` 284 285 ## Remote events 286 287 Remote events require the client-side profiling script. If you are using the `ts_devserver` bazel rule, this script will automatically be included in the development bundle so you don't have to worry about including it. If you're not using `ts_devserver` for development mode, you can include the following script tag to pull in the client-side profiling script: 288 289 ``` 290 <script src="http://localhost:30000/profiler.js"></script> 291 ``` 292 293 The script is served by iBazel on port 30000 by default. If port 30000 is not available, iBazel will attempt to find another available port between 30001 and 30099. 294 295 Remote events in the profiler script are sent using the [Beacon API](https://developer.mozilla.org/en-US/docs/Web/API/Beacon_API). This API is available in Chrome 39, Firefox 31, Edge and Opera 26. It is not available in Internet Explorer or Safari. Browser compatability can be checked [here](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/sendBeacon#Browser_compatibility). 296 297 If your browser does not support the Beacon API, you will see the following error in the console when including the profiler script: `iBazel profiler disabled because Beacon API is not available`. 298 299 ## Custom remote events 300 301 When the profiler script is loaded, a `window.IBazelProfileEvent(eventType, data)` public API is made available for generating custom remote events. This function sends a custom REMOTE_EVENT to the iBazel profiler log. 302 303 | Param | Type | Description | 304 | ------------- | ------------- | ------------- | 305 | `eventType` | string | The event type that ends up in the 'remoteType' attribute of the REMOTE_EVENT. | 306 | `data` | any | Optional data associated with the event. This is converted to a string. If it is an object it will be converted to escaped JSON in the profiler log. | 307 308 ## Additional notes 309 310 ### Termination 311 312 SIGINT has to be sent twice to kill ibazel: once to terminate the subprocess, 313 and the second time for ibazel itself. Also, ibazel will exit on its own when a 314 bazel query fails, but it will stay alive when a build, test, or run fails. 315 We use an exit code of 3 for a signal termination, and 4 for a query failure. 316 These codes are not an API and may change at any point. 317 318 ### What about the `--watchfs` flag? 319 320 Bazel has a flag called `--watchfs` which, according to the bazel command-line 321 help does: 322 323 > If true, Bazel tries to use the operating system's file watch service for 324 > local changes instead of scanning every file for a change 325 326 Unfortunately, this option does not rebuild the project on save like the Bazel 327 watcher does, but instead queries the file system for a list of files that have 328 been invalidated since last build and will require reinspection by the Bazel 329 server. 330 331 ### Big thanks 332 333 * [Google](http://opensource.google.com) for cross-platform build/test CI instances. 334 * [Sauce Labs](https://saucelabs.com) for cross-browser testing. 335 336 Copyright 2017 The Bazel Authors. All right reserved.