README.md - mojo - Git at Google

 Mojo
 ====

 Mojo is a collection of interprocess communication technologies, protocols
 and a runtime for creating applications and services that are composable while
 being loosely coupled. It simplifies the creation of fully asynchronous
 component-based systems and provides guarantees so that components made by
 different vendors and in different programming languages can interoperate.


 ## Set-up and code check-out

 The instructions below only need to be done once. Note that a simple "git clone"
 command is not sufficient to build the source code because this repo uses the
 gclient command from depot_tools to manage most third party dependencies.

 1. [Download
    depot_tools](http://www.chromium.org/developers/how-tos/install-depot-tools)
    and make sure it is in your path.
 2. [Googlers only] Install Goma in ~/goma.
 3. Create a directory somewhere for your checkout (preferably on an SSD), cd
    into it, and run the following commands:


 ```
 $ fetch mojo # append --target_os=android to include Android build support.
 $ cd src

 # Or install-build-deps-android.sh if you plan to build for Android.
 $ ./build/install-build-deps.sh

 $ mojo/tools/mojob.py gn
 ```

 The `fetch mojo` command does the following:
 - creates a directory called 'src' under your checkout directory
 - clones the repository using git clone
 - clones dependencies with gclient sync

 `install-build-deps.sh` installs any packages needed to build, then
 `mojo/tools/mojob.py gn` runs `gn args` and configures the build directory,
 out/Debug.

 If the fetch command fails, you will need to delete the src directory and start
 over.

 ### <a name="configure-android"></a>Adding Android bits in an existing checkout

 If you configured your set-up for Linux and now wish to build for Android, edit
 the `.gclient` file in your root Mojo directory (the parent directory to src.)
 and add this line at the end of the file:

 ```
 target_os = [u'android',u'linux']
 ```

 Bring in Android-specific build dependencies:
 ```
 $ build/install-build-deps-android.sh
 ```

 Pull down all of the packages with this command:
 ```
 $ gclient sync
 ```

 ## Update your checkout

 You can update your checkout like this. The order is important. You must do the
 `git pull` first because `gclient sync` is dependent on the current revision.

 ```
 # Fetch changes from upstream and rebase the current branch on top
 $ git pull --rebase
 # Update all modules as directed by the DEPS file
 $ gclient sync
 ```

 You do not need to rerun `gn gen out/Debug` - ninja does so automatically each
 time you build. You might need to rerun `mojo/tools/mojob.py gn` if the GN
 flags have changed.

 ## <a name="buildmojo"></a>Build Mojo

 ### Linux

 Build Mojo for Linux by running:

 ```
 $ ninja -C out/Debug -j 10
 ```

 You can also use the `mojob.py` script for building. This script automatically
 calls ninja and sets -j to an appropriate value based on whether Goma (see the
 section on Goma below) is present. You cannot specify a target name with this
 script.

 ```
 mojo/tools/mojob.py gn
 mojo/tools/mojob.py build
 ```

 Run a demo:
 ```
 out/Debug/mojo_shell mojo:spinning_cube
 ```

 Run the tests:
 ```
 mojo/tools/mojob.py test
 ```

 Run the benchmarks:
 ```
 mojo/devtools/common/mojo_benchmark mojo/tools/data/benchmarks
 ```

 Create a release build:
 ```
 mojo/tools/mojob.py gn --release
 mojo/tools/mojob.py build --release
 mojo/tools/mojob.py test --release
 ```

 ### Android

 To build for Android, first make sure that your checkout is [configured](#configure-android) to build
 for Android. After that you can use the mojob script as follows:
 ```
 $ mojo/tools/mojob.py gn --android
 $ mojo/tools/mojob.py build --android
 ```

 The result will be in out/android_Debug. If you see javac compile errors,
 [make sure you have an up-to-date JDK](https://code.google.com/p/chromium/wiki/AndroidBuildInstructions#Install_Java_JDK)

 ### Goma (Googlers only)

 If you're a Googler, you can use Goma, a distributed compiler service for
 open-source projects such as Chrome and Android. If Goma is installed in the
 default location (~/goma), it will work out-of-the-box with the `mojob.py gn`,
 `mojob.py build` workflow described above.

 You can also manually add:
 ```
 use_goma = true
 ```

 at the end of the file opened through:
 ```
 $ gn args out/Debug
 ```

 After you close the editor `gn gen out/Debug` will run automatically. Now you
 can dramatically increase the number of parallel tasks:
 ```
 $ ninja -C out/Debug -j 1000
 ```

 ### Official builds

 Official builds for android generate a signed Mojo Shell intended for
 distribution. You normally should not need to produce one. If you have any
 questions, reach out to [etiennej@chromium.org](mailto:etiennej@chromium.org).

 ## Run Mojo Shell

 Devtools `mojo_run` is a universal shell runner abstracting away the differences
 between running on Linux and Android.

 Having built Mojo as described above, a demo app can be run as follows:

 ```
 mojo/devtools/common/mojo_run https://core.mojoapps.io/spinning_cube.mojo  # Linux
 mojo/devtools/common/mojo_run https://core.mojoapps.io/spinning_cube.mojo --android  # Android
 ```

 ### Development server

 Whenever `mojo_run` is run, a development server is set up according to [the
 config file](mojoconfig). The server runs on your machine, serving the locally
 built apps, but appears to the shell under the `https://core.mojoapps.io` host.

 You can ignore the config file and skip spawning the local server (for example,
 in order to use apps at the actual https://core.mojoapps.io web host) by passing
 `--no-config-file` to `mojo_run`.

 ### More examples

 Some applications can be run directly from the source tree. The development
 server serves the `src` directory, allowing to refer to these apps. For
 instance, this command serves a dart Mojo app from the source at
 `examples/dart/device_info/main.dart`:

 ```sh
 mojo/devtools/common/mojo_run https://core.mojoapps.io/examples/dart/device_info/lib/main.dart [--android]
 ```

 Some applications implement ViewProvider and are run embedded in a view. To run
 these, you can pass the app url using the `--embed` flag:

 ```sh
 mojo/devtools/common/mojo_run --embed mojo:moterm_example_app [--android]
 ```

 which is a shorthand for:

 ```sh
 mojo/devtools/common/mojo_run "mojo:launcher mojo:moterm_example_app"
 ```

 For additional information on `mojo_run` refer to the built-in help and the
 [documentation](mojo/devtools/common/docs/mojo_run.md).
 You can also request more information on what the tool is doing for you by
 passing the `--verbose` flag.

 ### <a name="debugging"></a>Debugging, tracing, profiling

 Devtools `mojo_debug` allows you to interactively inspect a running shell,
 collect performance traces and attach a gdb debugger.

 For additional information refer to the built-in help and the
 [documentation](mojo/devtools/common/docs/mojo_debug.md).

 ### Android set-up

 #### Adb

 For the Android tooling to work, you will need to have `adb` in your PATH. For
 that, you can either run:
 ```
 source build/android/envsetup.sh
 ```

 each time you open a fresh terminal, or add something like:
 ```
 export PATH="$PATH":$MOJO_DIR/src/third_party/android_tools/sdk/platform-tools
 ```

 to your ~/.bashrc file, $MOJO_DIR being a path to your Mojo checkout.

 #### Device

 **The device has to be running Android 5.0 (Lollipop) or newer.**

 Many features useful for development (ie. streaming of the shell stdout when
 running shell on the device) will not work unless the device is rooted and
 running a userdebug build. For Googlers, [follow the instructions at this
 link](http://go/mojo-internal-build-instructions).

 ### Running manually on Linux

 If you wish to, you can also run the Linux Mojo shell directly with no wrappers:
 ```
 ./out/Debug/mojo_shell out/Debug/spinning_cube.mojo
 ```

 ## Contribute

 With git you should make all your changes in a local branch. Once your change is
 committed, you can delete this branch.

 Create a local branch named "mywork" and make changes to it.
 ```
   cd src
   git new-branch mywork
   vi ...
 ```
 Commit your change locally. (this doesn't commit your change to the SVN or Git
 server)

 ```
   git commit -a
 ```

 Fix your source code formatting.

 ```
 $ git cl format
 ```

 Upload your change for review.

 ```
 $ git cl upload
 ```

 Respond to review comments.

 See [Contributing code](http://www.chromium.org/developers/contributing-code)
 for more detailed git instructions, including how to update your CL when you get
 review comments. There's a short tutorial that might be helpful to try before
 making your first change: [C++ in Chromium
 101](http://dev.chromium.org/developers/cpp-in-chromium-101-codelab).

 To land a change after receiving LGTM:
 ```
 $ git cl land
 ```

 ## Monitoring

 Our [waterfall](http://build.chromium.org/p/client.mojo/waterfall) continuously
 builds and tests the code. Don't break the build!

 ### Benchmarks

 One of the bots, [Mojo Linux
 Perf](http://build.chromium.org/p/client.mojo/builders/Mojo%20Linux%20Perf) runs
 a [suite of benchmarks](mojo/tools/data/benchmarks) and uploads the results to
 the [performance dashboard](https://chromeperf.appspot.com/). You can browse the
 results [here](https://chromeperf.appspot.com/report), putting `mojo_benchmarks`
 as the "test suite".

 Automated alerts about performance regressions are sent to
 [mojo-perf-alerts@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/mojo-perf-alerts).

 For examples of interesting sets of graphs see:

  - [app
    startup](https://chromeperf.appspot.com/report?sid=4848464df5ca8467770d80b309740ef56fbff00e773c2c53816fd8bff1fda1e0)
  - [ipc
    performance](https://chromeperf.appspot.com/report?sid=9abc20b46f6f8d908b0f07847f1d42eab54c7025a098336e6dc2d3e2030d66f8)

 ## Development Tools

 These are some helpful tools for use during development.

 ### Atom IDE plugins

 Here are some useful plugins for Atom IDE during Mojo development.

  - `language-mojom`: provides syntax highlighting for `*.mojom` files.
  - `clang-format`: auto-formats C and C++ code in the editor (make sure to configure the path to the executable in the plugin settings).

 ### Vim plugins

 The `//tools/vim` directory contains the following plugins, refer to each script for installation instructions.

  - `mojom`: provides syntax highlighting for `*.mojom` files.
  - `clang_format.vim`: binds keyboard shortcuts to invoke `clang-format`.
  - `filetypes.vim`: provides syntax highlighting for `*.gyp`, `*.gypi`, and `DEPS` files.
  - `ninja-build.vim`: binds keyboard shortcuts to invoke the `ninja` build tool.

 ### Address Sanitizer (ASAN)

 Use ASAN to help find misuse of heap memory such as use-after-free errors.

 ```
 $ mojo/tools/mojob.py gn --asan
 $ mojo/tools/mojob.py build --asan
 ```

 Use `//tools/valgrind/asan/asan_symbolize.py` to decode stack traces when ASAN detects an error at runtime.

 This tool is not supported on Android.

 ### Android Stack Parser

 Use `//mojo/devtools/common/android_stack_parser/stack` to decode stack traces from Mojo programs running on Android.

 Make sure to include the lines containing `Caching mojo app XXX at YYY` which are printed while the program starts up so that the stack tool can locate the necessary symbols on the host machine.
	Mojo
	====

	Mojo is a collection of interprocess communication technologies, protocols
	and a runtime for creating applications and services that are composable while
	being loosely coupled. It simplifies the creation of fully asynchronous
	component-based systems and provides guarantees so that components made by
	different vendors and in different programming languages can interoperate.


	## Set-up and code check-out

	The instructions below only need to be done once. Note that a simple "git clone"
	command is not sufficient to build the source code because this repo uses the
	gclient command from depot_tools to manage most third party dependencies.

	1. [Download
	depot_tools](http://www.chromium.org/developers/how-tos/install-depot-tools)
	and make sure it is in your path.
	2. [Googlers only] Install Goma in ~/goma.
	3. Create a directory somewhere for your checkout (preferably on an SSD), cd
	into it, and run the following commands:



	```
	$ fetch mojo # append --target_os=android to include Android build support.
	$ cd src

	# Or install-build-deps-android.sh if you plan to build for Android.
	$ ./build/install-build-deps.sh

	$ mojo/tools/mojob.py gn
	```

	The `fetch mojo` command does the following:
	- creates a directory called 'src' under your checkout directory
	- clones the repository using git clone
	- clones dependencies with gclient sync

	`install-build-deps.sh` installs any packages needed to build, then
	`mojo/tools/mojob.py gn` runs `gn args` and configures the build directory,
	out/Debug.

	If the fetch command fails, you will need to delete the src directory and start
	over.

	### <a name="configure-android"></a>Adding Android bits in an existing checkout

	If you configured your set-up for Linux and now wish to build for Android, edit
	the `.gclient` file in your root Mojo directory (the parent directory to src.)
	and add this line at the end of the file:

	```
	target_os = [u'android',u'linux']
	```

	Bring in Android-specific build dependencies:
	```
	$ build/install-build-deps-android.sh
	```

	Pull down all of the packages with this command:
	```
	$ gclient sync
	```

	## Update your checkout

	You can update your checkout like this. The order is important. You must do the
	`git pull` first because `gclient sync` is dependent on the current revision.

	```
	# Fetch changes from upstream and rebase the current branch on top
	$ git pull --rebase
	# Update all modules as directed by the DEPS file
	$ gclient sync
	```

	You do not need to rerun `gn gen out/Debug` - ninja does so automatically each
	time you build. You might need to rerun `mojo/tools/mojob.py gn` if the GN
	flags have changed.

	## <a name="buildmojo"></a>Build Mojo

	### Linux

	Build Mojo for Linux by running:

	```
	$ ninja -C out/Debug -j 10
	```

	You can also use the `mojob.py` script for building. This script automatically
	calls ninja and sets -j to an appropriate value based on whether Goma (see the
	section on Goma below) is present. You cannot specify a target name with this
	script.

	```
	mojo/tools/mojob.py gn
	mojo/tools/mojob.py build
	```

	Run a demo:
	```
	out/Debug/mojo_shell mojo:spinning_cube
	```

	Run the tests:
	```
	mojo/tools/mojob.py test
	```

	Run the benchmarks:
	```
	mojo/devtools/common/mojo_benchmark mojo/tools/data/benchmarks
	```

	Create a release build:
	```
	mojo/tools/mojob.py gn --release
	mojo/tools/mojob.py build --release
	mojo/tools/mojob.py test --release
	```

	### Android

	To build for Android, first make sure that your checkout is [configured](#configure-android) to build
	for Android. After that you can use the mojob script as follows:
	```
	$ mojo/tools/mojob.py gn --android
	$ mojo/tools/mojob.py build --android
	```

	The result will be in out/android_Debug. If you see javac compile errors,
	[make sure you have an up-to-date JDK](https://code.google.com/p/chromium/wiki/AndroidBuildInstructions#Install_Java_JDK)

	### Goma (Googlers only)

	If you're a Googler, you can use Goma, a distributed compiler service for
	open-source projects such as Chrome and Android. If Goma is installed in the
	default location (~/goma), it will work out-of-the-box with the `mojob.py gn`,
	`mojob.py build` workflow described above.

	You can also manually add:
	```
	use_goma = true
	```

	at the end of the file opened through:
	```
	$ gn args out/Debug
	```

	After you close the editor `gn gen out/Debug` will run automatically. Now you
	can dramatically increase the number of parallel tasks:
	```
	$ ninja -C out/Debug -j 1000
	```

	### Official builds

	Official builds for android generate a signed Mojo Shell intended for
	distribution. You normally should not need to produce one. If you have any
	questions, reach out to [etiennej@chromium.org](mailto:etiennej@chromium.org).

	## Run Mojo Shell

	Devtools `mojo_run` is a universal shell runner abstracting away the differences
	between running on Linux and Android.

	Having built Mojo as described above, a demo app can be run as follows:

	```
	mojo/devtools/common/mojo_run https://core.mojoapps.io/spinning_cube.mojo # Linux
	mojo/devtools/common/mojo_run https://core.mojoapps.io/spinning_cube.mojo --android # Android
	```

	### Development server

	Whenever `mojo_run` is run, a development server is set up according to [the
	config file](mojoconfig). The server runs on your machine, serving the locally
	built apps, but appears to the shell under the `https://core.mojoapps.io` host.

	You can ignore the config file and skip spawning the local server (for example,
	in order to use apps at the actual https://core.mojoapps.io web host) by passing
	`--no-config-file` to `mojo_run`.

	### More examples

	Some applications can be run directly from the source tree. The development
	server serves the `src` directory, allowing to refer to these apps. For
	instance, this command serves a dart Mojo app from the source at
	`examples/dart/device_info/main.dart`:

	```sh
	mojo/devtools/common/mojo_run https://core.mojoapps.io/examples/dart/device_info/lib/main.dart [--android]
	```

	Some applications implement ViewProvider and are run embedded in a view. To run
	these, you can pass the app url using the `--embed` flag:

	```sh
	mojo/devtools/common/mojo_run --embed mojo:moterm_example_app [--android]
	```

	which is a shorthand for:

	```sh
	mojo/devtools/common/mojo_run "mojo:launcher mojo:moterm_example_app"
	```

	For additional information on `mojo_run` refer to the built-in help and the
	[documentation](mojo/devtools/common/docs/mojo_run.md).
	You can also request more information on what the tool is doing for you by
	passing the `--verbose` flag.

	### <a name="debugging"></a>Debugging, tracing, profiling

	Devtools `mojo_debug` allows you to interactively inspect a running shell,
	collect performance traces and attach a gdb debugger.

	For additional information refer to the built-in help and the
	[documentation](mojo/devtools/common/docs/mojo_debug.md).

	### Android set-up

	#### Adb

	For the Android tooling to work, you will need to have `adb` in your PATH. For
	that, you can either run:
	```
	source build/android/envsetup.sh
	```

	each time you open a fresh terminal, or add something like:
	```
	export PATH="$PATH":$MOJO_DIR/src/third_party/android_tools/sdk/platform-tools
	```

	to your ~/.bashrc file, $MOJO_DIR being a path to your Mojo checkout.

	#### Device

	The device has to be running Android 5.0 (Lollipop) or newer.

	Many features useful for development (ie. streaming of the shell stdout when
	running shell on the device) will not work unless the device is rooted and
	running a userdebug build. For Googlers, [follow the instructions at this
	link](http://go/mojo-internal-build-instructions).

	### Running manually on Linux

	If you wish to, you can also run the Linux Mojo shell directly with no wrappers:
	```
	./out/Debug/mojo_shell out/Debug/spinning_cube.mojo
	```

	## Contribute

	With git you should make all your changes in a local branch. Once your change is
	committed, you can delete this branch.

	Create a local branch named "mywork" and make changes to it.
	```
	cd src
	git new-branch mywork
	vi ...
	```
	Commit your change locally. (this doesn't commit your change to the SVN or Git
	server)

	```
	git commit -a
	```

	Fix your source code formatting.

	```
	$ git cl format
	```

	Upload your change for review.

	```
	$ git cl upload
	```

	Respond to review comments.

	See [Contributing code](http://www.chromium.org/developers/contributing-code)
	for more detailed git instructions, including how to update your CL when you get
	review comments. There's a short tutorial that might be helpful to try before
	making your first change: [C++ in Chromium
	101](http://dev.chromium.org/developers/cpp-in-chromium-101-codelab).

	To land a change after receiving LGTM:
	```
	$ git cl land
	```

	## Monitoring

	Our [waterfall](http://build.chromium.org/p/client.mojo/waterfall) continuously
	builds and tests the code. Don't break the build!

	### Benchmarks

	One of the bots, [Mojo Linux
	Perf](http://build.chromium.org/p/client.mojo/builders/Mojo%20Linux%20Perf) runs
	a [suite of benchmarks](mojo/tools/data/benchmarks) and uploads the results to
	the [performance dashboard](https://chromeperf.appspot.com/). You can browse the
	results [here](https://chromeperf.appspot.com/report), putting `mojo_benchmarks`
	as the "test suite".

	Automated alerts about performance regressions are sent to
	[mojo-perf-alerts@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/mojo-perf-alerts).

	For examples of interesting sets of graphs see:

	- [app
	startup](https://chromeperf.appspot.com/report?sid=4848464df5ca8467770d80b309740ef56fbff00e773c2c53816fd8bff1fda1e0)
	- [ipc
	performance](https://chromeperf.appspot.com/report?sid=9abc20b46f6f8d908b0f07847f1d42eab54c7025a098336e6dc2d3e2030d66f8)

	## Development Tools

	These are some helpful tools for use during development.

	### Atom IDE plugins

	Here are some useful plugins for Atom IDE during Mojo development.

	- `language-mojom`: provides syntax highlighting for `*.mojom` files.
	- `clang-format`: auto-formats C and C++ code in the editor (make sure to configure the path to the executable in the plugin settings).

	### Vim plugins

	The `//tools/vim` directory contains the following plugins, refer to each script for installation instructions.

	- `mojom`: provides syntax highlighting for `*.mojom` files.
	- `clang_format.vim`: binds keyboard shortcuts to invoke `clang-format`.
	- `filetypes.vim`: provides syntax highlighting for `.gyp`, `.gypi`, and `DEPS` files.
	- `ninja-build.vim`: binds keyboard shortcuts to invoke the `ninja` build tool.

	### Address Sanitizer (ASAN)

	Use ASAN to help find misuse of heap memory such as use-after-free errors.

	```
	$ mojo/tools/mojob.py gn --asan
	$ mojo/tools/mojob.py build --asan
	```

	Use `//tools/valgrind/asan/asan_symbolize.py` to decode stack traces when ASAN detects an error at runtime.

	This tool is not supported on Android.

	### Android Stack Parser

	Use `//mojo/devtools/common/android_stack_parser/stack` to decode stack traces from Mojo programs running on Android.

	Make sure to include the lines containing `Caching mojo app XXX at YYY` which are printed while the program starts up so that the stack tool can locate the necessary symbols on the host machine.