Updated README.md to reflect the state of the repository
diff --git a/README.md b/README.md index 57dbd06..89ebc11 100644 --- a/README.md +++ b/README.md
@@ -1,363 +1,7 @@ -Mojo +Mojo Testing ==== -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. +This directory contains the contents of upstream Mojo's testing/ directory. - -## 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. +At the moment, it is not meant to be built alone. Instead, it should be pulled +into a repository which componentizing Mojo (through either Jiri or gclient).