OLD | NEW |
| (Empty) |
1 Contributing | |
2 ============ | |
3 | |
4 [sky_sdk](https://github.com/domokit/sky_sdk) is generated from the | |
5 [mojo repository](https://github.com/domokit/mojo) using | |
6 [deploy_sdk.py](https://github.com/domokit/mojo/blob/master/sky/tools/deploy_sdk
.py) | |
7 Static files (including this README.md) are located under | |
8 [sky/sdk](https://github.com/domokit/mojo/tree/master/sky/sdk). Pull | |
9 requests and issue reports are glady accepted at the | |
10 [mojo repository](https://github.com/domokit/mojo)! | |
11 | |
12 Sky | |
13 === | |
14 | |
15 Sky is an experimental, high-performance UI framework for mobile apps. Sky helps | |
16 you create apps with beautiful user interfaces and high-quality interactive | |
17 design that run smoothly at 120 Hz. | |
18 | |
19 Sky consists of two components: | |
20 | |
21 1. *The Sky engine.* The engine is the core of the system. Written in C++, the | |
22 engine provides the muscle of the Sky system. The engine provides | |
23 several primitives, including a soft real-time scheduler and a hierarchical, | |
24 retained-mode graphics system, that let you build high-quality apps. | |
25 | |
26 2. *The Sky framework.* The [framework](packages/sky/lib/framework) makes it | |
27 easy to build apps using Sky by providing familiar user interface widgets, | |
28 such as buttons, infinite lists, and animations, on top of the engine using | |
29 Dart. These extensible components follow a functional programming style | |
30 inspired by [React](http://facebook.github.io/react/). | |
31 | |
32 We're still iterating on Sky heavily, which means the framework and underlying | |
33 engine are both likely to change in incompatible ways several times, but if | |
34 you're interested in trying out the system, this document can help you get | |
35 started. | |
36 | |
37 Examples | |
38 -------- | |
39 | |
40 Sky uses Dart and Sky applications are | |
41 [Dart Packages](https://www.dartlang.org/docs/tutorials/shared-pkgs/). | |
42 Application creation starts by creating a new directory and | |
43 adding a [pubspec.yaml](https://www.dartlang.org/tools/pub/pubspec.html): | |
44 | |
45 pubspec.yaml for your app: | |
46 ```yaml | |
47 name: your_app_name | |
48 dependencies: | |
49 sky: any | |
50 ``` | |
51 | |
52 Once the pubspec is in place, create a `lib` directory (where your dart code | |
53 will go), ensure that the 'dart' and 'pub' executables are on your $PATH and | |
54 run the following: | |
55 | |
56 `pub get && pub run sky:init`. | |
57 | |
58 Currently the Sky Engine assumes the entry point for your application is a | |
59 `main` function located inside a `main.sky` file at the root of the package. | |
60 `.sky` is an html-like format: | |
61 ``` | |
62 <sky> | |
63 <script> | |
64 import 'package:your_app_name/main.dart'; | |
65 | |
66 void main() { | |
67 new HelloWorldApp(); | |
68 } | |
69 </script> | |
70 </sky> | |
71 ``` | |
72 | |
73 The rest of the application then goes inside the `lib` directory of the package | |
74 thus `lib/main.dart` would be: | |
75 | |
76 ```dart | |
77 import 'package:sky/framework/fn.dart'; | |
78 | |
79 class HelloWorldApp extends App { | |
80 UINode build() { | |
81 return new Text('Hello, world!'); | |
82 } | |
83 } | |
84 ``` | |
85 | |
86 Execution starts in `main`, which creates the `HelloWorldApp`. The framework | |
87 then marks `HelloWorldApp` as dirty, which schedules it to build during the next | |
88 animation frame. Each animation frame, the framework calls `build` on all the | |
89 dirty components and diffs the virtual `UINode` hierarchy returned this frame | |
90 with the hierarchy returned last frame. Any differences are then applied as | |
91 mutations to the physical hierarchy retained by the engine. | |
92 | |
93 Skip down to "Running a Sky application" to learn how to load and run this | |
94 example on your device. | |
95 | |
96 For examples, please see the [examples directory](examples/). | |
97 | |
98 Services | |
99 -------- | |
100 | |
101 Sky apps can access services from the host operating system using Mojo IPC. For | |
102 example, you can access the network using the `network_service.mojom` interface. | |
103 Although you can use these low-level interfaces directly, you might prefer to | |
104 access these services via libraries in the framework. For example, the | |
105 `fetch.dart` library wraps the underlying `network_service.mojom` in an | |
106 ergonomic interface: | |
107 | |
108 ```dart | |
109 import 'package:sky/framework/net/fetch.dart'; | |
110 | |
111 main() async { | |
112 Response response = await fetch('example.txt'); | |
113 print(response.bodyAsString()); | |
114 } | |
115 ``` | |
116 | |
117 Set up your computer | |
118 -------------------- | |
119 | |
120 1. Install the Dart SDK: | |
121 - https://www.dartlang.org/tools/download.html | |
122 | |
123 2. Install the ``adb`` tool from the Android SDK: | |
124 - https://developer.android.com/sdk/installing/index.html | |
125 | |
126 3. Install the Sky SDK: | |
127 - ``git clone https://github.com/domokit/sky_sdk.git`` | |
128 | |
129 4. Ensure that $DART_SDK is set to the path of your Dart SDK and 'adb' | |
130 (inside 'platform-tools' in the android sdk) is in your $PATH. | |
131 | |
132 Set up your device | |
133 ------------------ | |
134 | |
135 Currently Sky requires an Android device running the Lollipop (or newer) version | |
136 of the Android operating system. | |
137 | |
138 1. Enable developer mode on your device by visiting ``Settings > About phone`` | |
139 and tapping the ``Build number`` field five times. | |
140 | |
141 2. Enable ``USB debugging`` in ``Settings > Developer options``. | |
142 | |
143 3. Using a USB cable, plug your phone into your computer. If prompted on your | |
144 device, authorize your computer to access your device. | |
145 | |
146 Running a Sky application | |
147 ------------------------- | |
148 | |
149 The `sky` pub package includes a `sky_tool` script to assist in running | |
150 Sky applications inside the `SkyDemo.apk` harness. The sky_tool script expects | |
151 to be run from the root directory of your application pub package. To run | |
152 one of the examples in this SDK, try: | |
153 | |
154 1. ``cd examples/stocks`` | |
155 | |
156 2. ``pub get`` to set up a copy of the sky package in the app directory. | |
157 | |
158 3. ``./packages/sky/sky_tool start`` to start the dev server and upload your | |
159 app to the device. | |
160 (NOTE: add a ``--install`` flag to install SkyDemo.apk if not already | |
161 installed on the device.) | |
162 | |
163 4. Use ``adb logcat`` to view any errors or Dart print() output from the app. | |
164 ``adb logcat -s chromium`` can be used to filter only adb messages from | |
165 `SkyDemo.apk` (which for | |
166 [legacy reasons](https://github.com/domokit/mojo/issues/129) still uses the | |
167 android log tag 'chromium'). | |
168 | |
169 Measuring Performance | |
170 --------------------- | |
171 | |
172 Sky has support for generating trace files compatible with | |
173 [Chrome's about:tracing](https://www.chromium.org/developers/how-tos/trace-event
-profiling-tool). | |
174 | |
175 `packages/sky/sky_tool start_tracing` and `packages/sky/sky_tool stop_tracing` | |
176 are the commands to use. | |
177 | |
178 Due to https://github.com/domokit/mojo/issues/127 tracing currently | |
179 requires root access on the device. | |
180 | |
181 Debugging | |
182 --------- | |
183 | |
184 Dart's [Observatory](https://www.dartlang.org/tools/observatory/) | |
185 (VM Debugger & Profiler) support in Sky is | |
186 [in progress](https://codereview.chromium.org/1107803002) and should | |
187 be released shortly after Dart Summit 2015. | |
188 | |
189 Building a standalone MyApp | |
190 --------------------------- | |
191 | |
192 Although it is possible to bundle the Sky Engine in your own app (instead of | |
193 running your code inside SkyDemo.apk), right now doing so is difficult. | |
194 | |
195 There is one example of doing so if you're feeling brave: | |
196 https://github.com/domokit/mojo/tree/master/sky/apk/stocks | |
197 | |
198 Eventually we plan to make this much easier and support platforms other than | |
199 Android, but that work is yet in progress. | |
200 | |
201 Adding Services to MyApp | |
202 ------------------------ | |
203 | |
204 [Mojo IPC](https://github.com/domokit/mojo) is an inter-process-communication | |
205 system designed to provide cross-thread, cross-process, and language-agnostic | |
206 communication between applications. Sky uses Mojo IPC to make it possible | |
207 to write UI code in Dart and yet depend on networking code, etc. written in | |
208 another language. Services are replicable, meaning that Dart code | |
209 written to use the `network_service` remains portable to any platform | |
210 (iOS, Android, etc.) by simply providing a 'natively' written `network_service`. | |
211 | |
212 Embedders of the Sky Engine and consumers of the Sky Framework can use this | |
213 same mechanism to expose not only existing services like the | |
214 [Keyboard](https://github.com/domokit/mojo/blob/master/mojo/services/keyboard/pu
blic/interfaces/keyboard.mojom) | |
215 service to allow Sky Framework Dart code to interface with the underlying | |
216 platform's Keyboard, but also to expose any additional non-Dart business logic | |
217 to Sky/Dart UI code. | |
218 | |
219 As and example, [SkyApplication](https://github.com/domokit/mojo/blob/master/sky
/shell/org/domokit/sky/shell/SkyApplication.java) | |
220 exposes a mojo `network_service` (required by Sky Engine C++ code) | |
221 [SkyDemoApplication](https://github.com/domokit/mojo/blob/master/sky/apk/demo/or
g/domokit/sky/demo/SkyDemoApplication.java) | |
222 additionally exposes `keyboard_service` and `sensor_service` for use by the Sky | |
223 Framework from Dart. | |
OLD | NEW |