diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index badc104676e58..efe4b8cf2c714 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,7 @@ -Contributing to Sky Engine -========================== +Contributing to Sky +=================== + +[![Build Status](https://travis-ci.org/domokit/sky_engine.svg)](https://travis-ci.org/domokit/sky_engine) Getting the code ---------------- diff --git a/README.md b/README.md index 5be497b55d1c5..92cf674101f9d 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,14 @@ Sky === -[![Build Status](https://travis-ci.org/domokit/sky_engine.svg)](https://travis-ci.org/domokit/sky_engine) - Sky is a new way to build high performance, cross platform mobile apps. More specifically, Sky is a rendering engine, a scripting engine, an (optional) framework, and a (optional) set of Material Design widgets. Sky is optimized for today's, and tomorrow's, mobile devices. We are focused on low-latency input, high frame rates, and we are purely mobile first. -For information about using the latest stable release of Sky, please -see the [Sky SDK README](sky/sdk/README.md). + - For information about using Sky to build apps, please see + [Getting Started with Sky](sky/sdk/README.md). -For information about contributing to Sky, please see -[CONTRIBUTING.md](CONTRIBUTING.md). + - For information about contributing to Sky, please see + [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/sky/sdk/README.md b/sky/sdk/README.md index daae838b09bbe..e92a57e5339a6 100644 --- a/sky/sdk/README.md +++ b/sky/sdk/README.md @@ -1,50 +1,14 @@ -Contributing -============ - -This SDK is generated from the -[Sky repository](https://github.com/domokit/sky_engine) using -[deploy_sdk.py](https://github.com/domokit/sky_engine/blob/master/sky/tools/deploy_sdk.py). -Static files (including this README.md) are located under -[sky/sdk](https://github.com/domokit/sky_engine/tree/master/sky/sdk). - -Pull -requests and issue reports are gladly accepted at the -[Sky repository](https://github.com/domokit/sky_engine)! - -Sky -=== - -Sky is an experimental, high-performance UI framework for mobile apps. Sky helps -you create apps with beautiful user interfaces and high-quality interactive -design that run smoothly at 120 Hz. - -Sky consists of two components: - -1. *The Sky engine.* The engine is the core of the system. Written in C++, the - engine provides the muscle of the Sky system. The engine provides - several primitives, including a soft real-time scheduler and a hierarchical, - retained-mode graphics system, that let you build high-quality apps. - -2. *The Sky framework.* The [framework](packages/sky/lib/framework) makes it - easy to build apps using Sky by providing familiar user interface widgets, - such as buttons, infinite lists, and animations, on top of the engine using - Dart. These extensible components follow a functional programming style - inspired by [React](http://facebook.github.io/react/). - -We're still iterating on Sky heavily, which means the framework and underlying -engine are both likely to change in incompatible ways several times, but if -you're interested in trying out the system, this document can help you get -started. - -Examples --------- - -Sky uses Dart and Sky applications are -[Dart Packages](https://www.dartlang.org/docs/tutorials/shared-pkgs/). -Application creation starts by creating a new directory and +Getting Started with Sky +======================== + +Sky apps are written in Dart. To get started, we need to set up Dart SDK: + + - Install the [Dart SDK](https://www.dartlang.org/downloads/). + - Ensure that `$DART_SDK` is set to the path of your Dart SDK. + +Once we have the Dart SDK, we can creating a new directory and adding a [pubspec.yaml](https://www.dartlang.org/tools/pub/pubspec.html): - pubspec.yaml for your app: ```yaml name: your_app_name dependencies: @@ -52,20 +16,23 @@ dependencies: ``` Once the pubspec is in place, create a `lib` directory (where your dart code -will go), ensure that the 'dart' and 'pub' executables are on your $PATH and +will go) ensure that the 'dart' and 'pub' executables are on your $PATH and run the following: -`pub get && pub run sky:init`. + - `mkdir lib` + - `pub get && pub run sky:init` Currently the Sky Engine assumes the entry point for your application is a -`main` function in a Dart file inside your package: +`main` function in `lib/main.dart`: ```dart import 'package:sky/widgets/basic.dart'; class HelloWorldApp extends App { Widget build() { - return new Text('Hello, world!'); + return new Center( + child: new Text('Hello, world!') + ); } } @@ -78,63 +45,25 @@ Execution starts in `main`, which instructs the framework to run a new instance of the `HelloWorldApp`. The framework then calls the `build()` function on `HelloWorldApp` to create a tree of widgets, some of which might be other `Components`, which in turn have `build()` functions that generate -more widgets iteratively to create the widget hierarchy. - -Later, if a `Component` changes state, the framework calls that component's -`build()` function again to create a new widget tree. The framework diffs the -new widget tree against the old widget tree and any differences are applyed -to the underlying render tree. - - * To learn more about the widget system, please see the - [widgets tutorial](lib/widgets/README.md). - * To learn how to run Sky on your device, please see the - [Running a Sky application](#running-a-sky-application) section in this - document. - * To dive into examples, please see the [examples directory](example/). - -Services --------- - -Sky apps can access services from the host operating system using Mojo IPC. For -example, you can access the network using the `network_service.mojom` interface. -Although you can use these low-level interfaces directly, you might prefer to -access these services via libraries in the framework. For example, the -`fetch.dart` library wraps the underlying `network_service.mojom` in an -ergonomic interface: - -```dart -import 'package:sky/mojo/net/fetch.dart'; - -main() async { - Response response = await fetchBody('example.txt'); - print(response.bodyAsString()); -} -``` - -Set up your computer --------------------- +more widgets iteratively to create the widget hierarchy. To learn more about +the widget system, please see the [widgets tutorial](lib/widgets/README.md). -1. Install the Dart SDK: - - https://www.dartlang.org/tools/download.html - -2. Install the `adb` tool from the Android SDK: - - https://developer.android.com/sdk/installing/index.html - -3. Ensure that `$DART_SDK` is set to the path of your Dart SDK and `adb` - (inside `platform-tools` in the android sdk) is in your `$PATH`. - -Set up your device ------------------- +Setup your Android device +------------------------- Currently Sky requires an Android device running the Lollipop (or newer) version of the Android operating system. -1. Enable developer mode on your device by visiting `Settings > About phone` + - Install the `adb` tool from the [Android SDK](https://developer.android.com/sdk/installing/index.html) + and ensure that `adb (inside `platform-tools` in the Android SDK) is in your + `$PATH`. + + - Enable developer mode on your device by visiting `Settings > About phone` and tapping the `Build number` field five times. -2. Enable `USB debugging` in `Settings > Developer options`. + - Enable `USB debugging` in `Settings > Developer options`. -3. Using a USB cable, plug your phone into your computer. If prompted on your + - Using a USB cable, plug your phone into your computer. If prompted on your device, authorize your computer to access your device. Running a Sky application @@ -142,73 +71,32 @@ Running a Sky application The `sky` pub package includes a `sky_tool` script to assist in running Sky applications inside the `SkyDemo.apk` harness. The `sky_tool` script -expects to be run from the root directory of your application pub package. To -run one of the examples in this SDK, try: +expects to be run from the root directory of your application's package (i.e., +the same directory that contains the `pubspec.yaml` file). To run your app, +follow these instructions: -1. `cd example/stocks` - -2. `pub get` to set up a copy of the sky package in the app directory. - -3. `./packages/sky/sky_tool start` to start the dev server and upload your + - `./packages/sky/sky_tool start` to start the dev server and upload your app to the device. (NOTE: add a `--install` flag to install `SkyDemo.apk` if it is not already installed on the device.) -4. Use `adb logcat` to view any errors or Dart `print()` output from the app. + - Use `adb logcat` to view any errors or Dart `print()` output from the app. `adb logcat -s sky` can be used to filter only adb messages from `SkyDemo.apk`. -Measuring Performance ---------------------- - -Sky has support for generating trace files compatible with -[Chrome's about:tracing](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool). - -`packages/sky/sky_tool start_tracing` and `packages/sky/sky_tool stop_tracing` -are the commands to use. + Building a standalone APK + ------------------------- -Due to https://github.com/domokit/mojo/issues/127 tracing currently -requires root access on the device. + Although it is possible to build a standalone APK containing your application, + doing so right now is difficult. If you're feeling brave, you can see how we + build the `Stocks.apk` in [example/stocks](example/stocks). Eventually we plan + to make this much easier and support platforms other than Android, but that work + still in progress. Debugging --------- Sky uses [Observatory](https://www.dartlang.org/tools/observatory/) for debugging and profiling. While running your Sky app using `sky_tool`, you can -access Observatory by navigating your web browser to http://localhost:8181/. - -Building a standalone MyApp ---------------------------- - -Although it is possible to bundle the Sky Engine in your own app (instead of -running your code inside SkyDemo.apk), right now doing so is difficult. - -There is one example of doing so if you're feeling brave: -https://github.com/domokit/sky_engine/tree/master/sky/sdk/example/stocks - -Eventually we plan to make this much easier and support platforms other than -Android, but that work is yet in progress. - -Adding Services to MyApp ------------------------- - -[Mojo IPC](https://github.com/domokit/mojo) is an inter-process-communication -system designed to provide cross-thread, cross-process, and language-agnostic -communication between applications. Sky uses Mojo IPC to make it possible -to write UI code in Dart and yet depend on networking code, etc. written in -another language. Services are replicable, meaning that Dart code -written to use the `network_service` remains portable to any platform -(iOS, Android, etc.) by simply providing a 'natively' written `network_service`. - -Embedders of the Sky Engine and consumers of the Sky Framework can use this -same mechanism to expose not only existing services like the -[Keyboard](https://github.com/domokit/mojo/blob/master/mojo/services/keyboard/public/interfaces/keyboard.mojom) -service to allow Sky Framework Dart code to interface with the underlying -platform's Keyboard, but also to expose any additional non-Dart business logic -to Sky/Dart UI code. - -As an example, [SkyApplication](https://github.com/domokit/sky_engine/blob/master/sky/shell/org/domokit/sky/shell/SkyApplication.java) -exposes a mojo `network_service` (required by Sky Engine C++ code) -[SkyDemoApplication](https://github.com/domokit/sky_engine/blob/master/sky/apk/demo/org/domokit/sky/demo/SkyDemoApplication.java) -additionally exposes `keyboard_service` and `sensor_service` for use by the Sky -Framework from Dart. +access Observatory by navigating your web browser to +[http://localhost:8181/](http://localhost:8181/). diff --git a/sky/tools/big_red_button.py b/sky/tools/big_red_button.py index 3c0d90702f256..ba110f5850991 100755 --- a/sky/tools/big_red_button.py +++ b/sky/tools/big_red_button.py @@ -84,7 +84,6 @@ def main(): run(sky_engine_root, [ 'sky/tools/deploy_sdk.py', '--non-interactive', - '--commit', sky_sdk_root ]) # tag for version? @@ -104,4 +103,4 @@ def main(): if __name__ == '__main__': - sys.exit(main()) \ No newline at end of file + sys.exit(main()) diff --git a/sky/tools/deploy_sdk.py b/sky/tools/deploy_sdk.py index dcedc66d1ac06..665a17e4f4274 100755 --- a/sky/tools/deploy_sdk.py +++ b/sky/tools/deploy_sdk.py @@ -86,7 +86,6 @@ def main(): parser.add_argument('--build-dir', action='store', type=str, default=os.path.join(SRC_ROOT, DEFAULT_REL_BUILD_DIR)) parser.add_argument('--non-interactive', action='store_true') - parser.add_argument('--commit', action='store_true') args = parser.parse_args() build_dir = os.path.abspath(args.build_dir) @@ -95,8 +94,6 @@ def main(): print 'Building SDK from %s into %s' % (build_dir, sdk_root) start_time = datetime.now() - should_commit = args.commit - def sdk_path(rel_path): return os.path.join(sdk_root, rel_path) @@ -120,22 +117,6 @@ def src_path(rel_path): subprocess.check_call([src_path('tools/licenses.py'), 'credits'], stdout=license_file) - if should_commit: - # Kinda a hack to make a prettier build dir for the commit: - script_path = os.path.relpath(os.path.abspath(__file__), SRC_ROOT) - rel_build_dir = os.path.relpath(build_dir, SRC_ROOT) - revision = git_revision() - commit_url = "https://github.com/domokit/mojo/commit/%s" % revision - pattern = """Autogenerated from %s -Using %s and build output from %s. -""" - commit_message = pattern % (commit_url, script_path, rel_build_dir) - subprocess.check_call(['git', 'add', '.'], cwd=sdk_root) - subprocess.check_call([ - 'git', 'commit', - '-m', commit_message - ], cwd=sdk_root) - time_delta = datetime.now() - start_time print 'SDK built at %s in %ss' % (sdk_root, time_delta.total_seconds())