Skip to content

Commit 88a042b

Browse files
author
Iva Koevska
committed
First draft
1 parent 3bef0fb commit 88a042b

File tree

1 file changed

+383
-3
lines changed

1 file changed

+383
-3
lines changed

‎README.md

Lines changed: 383 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,385 @@
1-
nativescript-cli
1+
Telerik NativeScript Command-Line Interface
22
================
3-
[![Build Status](https://travis-ci.org/NativeScript/nativescript-cli.svg?branch=build)](https://travis-ci.org/NativeScript/nativescript-cli)
3+
[![Build Status](https://travis-ci.org/NativeScript/nativescript-cli.svg?branch=build)][2]
44

5-
Command-line interface for building NativeScript projects
5+
*Create, build, and run native apps for iOS and Android using JavaScript*
6+
7+
The Telerik NativeScript CLI lets you create, build, and deploy NativeScript-based projects on iOS and Android devices.
8+
9+
* [What is NativeScript](#what-is-nativescript "Quick overview of Telerik NativeScript, the JavaScript framework for cross-platform development of native iOS and Android apps")
10+
* [Supported Platforms](#supported-platforms "The mobile platforms you can target with NativeScript")
11+
* [System Requirements](#system-requirements "The hardware and software requirements for setting up and working with the Telerik NativeScript CLI")
12+
* [Installation](#installation "How to configure and install the Telerik NativeScript CLI")
13+
* [Quick Start](#quick-start "Get started with the Telerik NativeScript CLI")
14+
* [How to Contribute](#how-to-contribute "")
15+
* [License](#license)
16+
17+
What is NativeScript
18+
===
19+
20+
> Telerik NativeScript is currently available as a private preview. To sign up for the NativeScript Insiders program, visit <a href="http://www.telerik.com/nativescript-insiders-signup" target="_blank">http://www.telerik.com/nativescript-insiders-signup</a>.
21+
22+
Telerik NativeScript is a cross-platform JavaScript framework that lets you develop native iOS and Android apps from a single code base. The framework provides JavaScript access to the native APIs, user interface, and rendering engines of iOS and Android. By using JavaScript or TypeScript, you can create one project that builds into an iOS or Android app with completely native user experience.
23+
24+
To learn more about Telerik NativeScript, you can check the following resources:
25+
26+
* [The Telerik NativeScript web page][4]
27+
* [NativeScript - a Technical Overview][9]
28+
* [Development with NativeScript][3]
29+
* [Announcing NativeScript - cross-platform framework for building native mobile applications][11]
30+
* [The Telerik NativeScript Documentation Wiki][6]
31+
* [The Telerik NativeScript API Reference][7]
32+
* [The Telerik NativeScript FAQ][8]
33+
* [On NativeScript for Android][10]
34+
35+
[Back to Top][1]
36+
37+
Supported Platforms
38+
===
39+
40+
With the Telerik NativeScript CLI, you can target the following mobile platforms.
41+
42+
* Android 4.2 or later
43+
* iOS 7.0 or later
44+
45+
[Back to Top][1]
46+
47+
System Requirements
48+
===
49+
50+
You can install and run the Telerik NativeScript CLI on Windows or OS X.
51+
52+
* [Windows](#widnows)
53+
* [OS X](#os-x)
54+
55+
## Windows
56+
57+
> On Windows systems, you can develop, build, and deploy NativeScript projects that target Android.
58+
59+
* Windows Vista or later
60+
* Node.js 0.10.22 or later
61+
* (Optional) Chocolatey
62+
* JDK 6 or later
63+
* Apache Ant 1.8 or later
64+
* Android SDK 19 or later
65+
66+
If you have installed Chocolatey, you can complete these steps to set up JDK, Apache Ant, and Android SDK.
67+
68+
1. Run a Windows command prompt.
69+
1. To install JDK, run the following command.
70+
71+
```Shell
72+
choco install java
73+
```
74+
1. If not present, create the following environment variable.
75+
76+
```
77+
JAVA_HOME=Path to the jdk* install folder
78+
```
79+
80+
For example: JAVA_HOME=C:\Program Files\Java\jdk1.8.0_11
81+
1. To install Apache Ant, run the following command.
82+
83+
```Shell
84+
choco install ant
85+
```
86+
1. If not present, add the following file path to the `PATH` system environment variable.
87+
88+
```
89+
Path to the bin directory in the Apache Ant installation folder
90+
```
91+
92+
For example: PATH=...;...;C:\tools\apache-ant-1.9.4\bin
93+
1. To install the Android SDK, run the following command.
94+
95+
```Shell
96+
choco install android-sdk
97+
```
98+
1. If not present, add the following file path to the `PATH` system environment variable.
99+
100+
```
101+
Path to tools directory in the Android SDK installation folder
102+
Path to platform-tools directory in the Android SDK installation folder
103+
```
104+
105+
For example: PATH=...;...;%localappdata%\Android\android-sdk\tools;%localappdata%\Android\android-sdk\platform-tools
106+
1. To update the Android SDK to 19 or later, run the following command.
107+
108+
```Shell
109+
android update sdk
110+
```
111+
1. Select all packages for the Android 19 SDK and any other SDKs that you want to install and click **Install**.
112+
113+
## OS X
114+
115+
> On OS X systems, you can develop, build, and deploy NativeScript projects that target iOS and Android.
116+
117+
* OS X Mavericks
118+
* Node.js 0.10.22 or later
119+
* For iOS development
120+
* iOS 7.0 SDK or later
121+
* Xcode 5 or later
122+
* Xcode command-line tools
123+
* For Android development
124+
* JDK 6 or later
125+
* Apache Ant 1.8 or later
126+
* Android SDK 19 or later
127+
128+
If you want to develop for Android, verify that you have added the following paths in `/etc/paths`.
129+
130+
```
131+
Path to the bin subdirectory in the Apache Ant installation directory
132+
Path to the tools subdirectory in the Android SDK installation directory
133+
```
134+
135+
For example:
136+
```
137+
~/ant/apache-ant-1.9.4/bin
138+
/Applications/Android Studio.app/sdk/tools
139+
/Applications/Android Studio.app/sdk/platform-tools
140+
```
141+
142+
[Back to Top][1]
143+
144+
Installation
145+
===
146+
147+
The Telerik NativeScript CLI is available for installing as an npm package.
148+
149+
In the command prompt, run the following command.
150+
151+
```Shell
152+
npm install nativescript -g
153+
```
154+
155+
[Back to Top][1]
156+
157+
Quick Start
158+
===
159+
160+
* [The Commands](#the-commands)
161+
* [Create Project](#create-project)
162+
* [Add Platforms](#add-platforms)
163+
* [Develop Your Project](#develop-your-project)
164+
* [Prepare for Build](#prepare-for-build)
165+
* [Build Your Project](#build-your-project)
166+
* [Deploy Your Project](#deploy-your-project)
167+
* [Emulate Your Project](#emulate-your-project)
168+
169+
## The Commands
170+
171+
Run `tns help` to list all available commands. Run or `tns <Command> help` to view more information about a selected command.
172+
173+
* `help` lists all available commands.
174+
* `create <App name> [--path <Directory>] [--appid <App ID>] [--copy-from <Directory>]` creates a new project with the specified settings.
175+
* `platform list` lists the current target platforms for your project.
176+
* `platform add <Platform>` adds a new target platform to your project.
177+
* `platform remove <Platform>` removes the selected platform from the target platforms of the project.
178+
* `prepare <Platform>` copies cross-platform and platform-specific content to the subdirectory for the selected target platform.
179+
* `build <Platform>` builds the project for the selected target platform.
180+
* `emulate <Platform>` builds the project for the selected target platform and runs it in the native emulator, if configured.
181+
* `deploy <Platform> [--device <Device ID>]` deploys an already built application on connected device.
182+
* `run <Platform>` executes `prepare`, `build`, and `deploy`.
183+
* `list-devices` lists connected devices.
184+
* `feature-usage-tracking` configures anonymous feature usage tracking.
185+
186+
[Back to Top][1]
187+
188+
## Create Project
189+
190+
To create a new hybrid project from the default template, run the following command.
191+
192+
```Shell
193+
tns create MyApp
194+
```
195+
196+
The Telerik NativeScript creates a new project based on the JavaScript built-in template and sets the application identifier to `com.telerik.myapp`.
197+
198+
The CLI places the project in a new directory in the current directory. The newly created directory has the following structure.
199+
200+
```
201+
MyApp/
202+
|-- app/
203+
|-- |-- app/
204+
|-- |-- App_Resources/
205+
|-- |-- |-- Android/
206+
|-- |-- `-- iOS/
207+
|-- |-- tns_modules/
208+
|-- |-- |-- application/
209+
|-- |-- |-- camera/
210+
|-- |-- |-- console/
211+
|-- |-- |-- file-system/
212+
|-- |-- |-- globals/
213+
|-- |-- |-- http/
214+
|-- |-- |-- image-source/
215+
|-- |-- |-- local-settings/
216+
|-- |-- |-- location/
217+
|-- |-- |-- promises/
218+
|-- |-- |-- text/
219+
|-- |-- |-- timer/
220+
|-- |-- `-- utils/
221+
|-- |-- LICENSE
222+
|-- |-- package.json
223+
|-- `-- README.md
224+
|-- hooks/
225+
|-- platforms/
226+
|-- tns_modules/
227+
`-- .tnsproject
228+
```
229+
230+
[Back to Top][1]
231+
232+
## Add Platforms
233+
234+
After you have created your project, you can start adding target platforms to it. To be able to build your project into an application package for a selected target platform, you need to add the platform to your project. Currently, you can target Android and iOS with your NativeScript projects.
235+
236+
Navigate to the directory that contains your newly created project and run the following commands.
237+
238+
```Shell
239+
tns platform add android
240+
tns platform add ios
241+
```
242+
243+
`platform add` creates the `android` and the `ios` subdirectories in the `platforms` directory. These subdirectories have the platform-specific project structure required for native development with the platform.
244+
245+
```
246+
...
247+
platforms/
248+
|-- android/
249+
|-- |-- assets/
250+
|-- |-- gen/
251+
|-- |-- libs/
252+
|-- |-- node_modules/
253+
|-- |-- res/
254+
|-- |-- src/
255+
|-- |-- .project
256+
|-- |-- AndroidManifest.xml
257+
|-- |-- build.xml
258+
|-- |-- local.properties
259+
|-- |-- proguard-project.txt
260+
|-- `-- project.properties
261+
|-- ios/
262+
|-- |-- libTNSBridge.a
263+
|-- |-- node_modules
264+
`-- |-- MyApp/
265+
`-- MyApp.xcodeproj
266+
...
267+
```
268+
269+
[Back to Top][1]
270+
271+
## Develop Your Project
272+
273+
Develop your project in the `app` directory in the root of the project. Avoid making changes to the platform-specific subdirectories in `platforms`. The Telerik NativeScript CLI overrides such changes during the `prepare` operation.
274+
275+
You can use platform-specific files to provide customized functionality and design for each target platform. To indicate that a file is platform-specific, make sure that the file name is in the following format: `name.ios.extension` or `name.android.extension`. For example: `main.ios.js` or `main.android.js`. You can develop shared functionality or design in common files. To indicate that a file is common, make sure that the file name does not contain a `.android.` or `.ios.` string.
276+
277+
[Back to Top][1]
278+
279+
## Prepare for Build
280+
281+
When you run `build`, the Telerik NativeScript CLI uses the resources from the platform-specific subdirectory in the `platforms` directory. To populate the platform-specific subdirectory with the correct application assets, you need to run `prepare`.
282+
283+
```Shell
284+
tns prepare android
285+
tns prepare ios
286+
```
287+
288+
`prepare <Platform>` takes content from `app`, analyzes it and copies it to the platform-specific subdirectory in `platforms`. This operation copies common content and platform-specific content that applies only to the selected platform. This ensures that your Android or iOS application will contain the correct assets.
289+
290+
Keep in mind that `prepare` overrides any changes made to the platform-specific subdirectory in `platforms`. To develop platform-specific functionality and design for your native apps, use platform-specific files in the `app` directory.
291+
292+
> **IMPORTANT:** Always run `prepare <Platform>` before running `build <Platform>` or `deploy <Platform>`. This ensures that the Telerik NativeScript CLI will build an application package that contains your latest code and resources.
293+
294+
[Back to Top][1]
295+
296+
## Build Your Project
297+
298+
After you have prepared your project, you can build it for your target mobile platforms.
299+
300+
```Shell
301+
tns build android
302+
tns build ios
303+
```
304+
305+
The Telerik NativeScript CLI calls the SDK for the selected target platform and uses it to build your app locally.
306+
307+
When you build for Android, the Telerik NativeScript CLI saves the application package as an `APK` in `platforms` -> `android` -> `bin`.
308+
309+
When you build for iOS, the Telerik NativeScript CLI saves the application package as an `IPA` in `platforms` -> `ios` -> `build` -> `device`.
310+
311+
> **IMPORTANT:** To build your app for iOS, you need to configure a valid pair of certificate and provisioning profile for code signing your application package. For more information, see [iOS Code Signing - A Complete Walkthrough](http://seventhsoulmountain.blogspot.com/2013/09/ios-code-sign-in-complete-walkthrough.html).
312+
313+
[Back to Top][1]
314+
315+
## Deploy Your Project
316+
317+
You can test your work in progress on connected Android or iOS devices.
318+
319+
To verify that the Telerik NativeScript CLI recognizes your connected devices, run the following command.
320+
321+
```Shell
322+
tns list-devices
323+
```
324+
325+
The Telerik NativeScript CLI lists all connected physical devices and running virtual Android devices managed by the Android Virtual Device manager.
326+
327+
After you have listed the available devices, you can deploy your app on all devices from the selected target platform.
328+
329+
330+
```Shell
331+
tns deploy android
332+
tns deploy ios
333+
```
334+
335+
The Telerik NativeScript CLI calls the SDK for the selected target platform and uses it to build your app locally. After the build is complete, the Telerik NativeScript CLI downloads and installs the application package on your connected devices. The app does not run automatically on the device.
336+
337+
> **IMPORTANT:** To deploy your app on iOS devices, you need to configure a valid pair of certificate and provisioning profile for code signing your application package. For more information, see [iOS Code Signing - A Complete Walkthrough](http://seventhsoulmountain.blogspot.com/2013/09/ios-code-sign-in-complete-walkthrough.html).
338+
339+
[Back to Top][1]
340+
341+
## Emulate Your Project
342+
343+
If you do not have any physical devices on which to test your app or if you have not configured any certificates and provisioning profiles for iOS, you can run your app in the native emulator of your target platform.
344+
345+
```Shell
346+
tns emulate android
347+
tns emulate ios
348+
```
349+
350+
This operation launches the native device emulator for the selected target platform and runs your project in the virtual device.
351+
352+
For Android, the Telerik NativeScript CLI runs your app in the earliest created virtual device. Before running your app in the Android native emulator, make sure that you have configured at least one virtual device in the Android Virtual Device manager.
353+
354+
For iOS, the Telerik NativeScript CLI runs your app in the iOS Simulator.
355+
356+
[Back to Top][1]
357+
358+
How to Contribute
359+
===
360+
361+
To learn how to log a bug that you just discovered, click [here](CONTRIBUTING.md#report-an-issue).
362+
363+
To learn how to suggest a new feature or improvement, click [here](CONTRIBUTING.md#request-a-feature).
364+
365+
To learn how to contribute to the code base, click [here](CONTRIBUTING.md#contribute-to-the-code-base).
366+
367+
[Back to Top][1]
368+
369+
License
370+
===
371+
372+
This software is licensed under the Apache 2.0 license, quoted <a href="LICENSE" target="_blank">here</a>.
373+
374+
[Back to Top][1]
375+
376+
[1]: #telerik-nativescript-command-line-interface
377+
[2]: https://travis-ci.org/NativeScript/nativescript-cli
378+
[3]: http://docs.telerik.com/platform/appbuilder/nativescript/index
379+
[4]: http://www.telerik.com/nativescript
380+
[6]: https://github.com/nativescript/docs/wiki
381+
[7]: https://github.com/nativescript/docs
382+
[8]: http://www.telerik.com/nativescript/faq
383+
[9]: http://developer.telerik.com/featured/nativescript-a-technical-overview/
384+
[10]: http://developer.telerik.com/featured/nativescript-android/
385+
[11]: http://blogs.telerik.com/valentinstoychev/posts.aspx/14-06-12/announcing-nativescript---cross-platform-framework-for-building-native-mobile-applications

0 commit comments

Comments
 (0)