diff --git a/README.md b/README.md index 2d27145292..03d3b51cb2 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -

+


Nativescript Logo
@@ -8,14 +8,12 @@

-

The NativeScript CLI lets you create, build, and deploy NativeScript-based projects on iOS and Android devices.

+

The NativeScript CLI lets you create, build, and deploy NativeScript-based apps on iOS and Android devices.

-
Master Branch

-Build Status -Waffle.io - NativeScript CLI +Build Status

Get it using: `npm install -g nativescript` @@ -31,15 +29,11 @@ Get it using: `npm install -g nativescript` * [Quick Start](#quick-start "Get started with the NativeScript CLI") * [The Commands](#the-commands) * [Create Project](#create-project) - * [Add Platforms](#add-platforms) * [Develop Your Project](#develop-your-project) - * [Prepare for Build](#prepare-for-build) * [Build Your Project](#build-your-project) - * [Deploy Your Project](#deploy-your-project) * [Run Your Project](#run-your-project) * [Extending the CLI](#extending-the-cli) * [Troubleshooting](#troubleshooting) -* [Known Issues](#known-issues) * [How to Contribute](#how-to-contribute) * [How to Build](#how-to-build) * [Get Help](#get-help) @@ -52,13 +46,11 @@ NativeScript is a cross-platform JavaScript framework that lets you develop nati To learn more about NativeScript, you can check the following resources: -* [The NativeScript web page][4] -* [NativeScript - a Technical Overview][9] -* [Development with NativeScript][3] -* [Announcing NativeScript - cross-platform framework for building native mobile applications][11] -* The NativeScript [Documentation repo][6] and [Documentation portal][7] -* [The NativeScript FAQ][8] -* [On NativeScript for Android][10] +* [The NativeScript web page][2] +* [NativeScript - a Technical Overview][7] +* [Announcing NativeScript - cross-platform framework for building native mobile applications][8] +* The NativeScript [Documentation repo][3] and [Documentation portal][4] +* [The NativeScript FAQ][6] [Back to Top][1] @@ -83,7 +75,7 @@ Supported Platforms With the NativeScript CLI, you can target the following mobile platforms. * Android 4.2 or a later stable official release -* iOS 7.0 or later stable official release +* iOS 9.0 or later stable official release [Back to Top][1] @@ -167,11 +159,8 @@ Quick Start * [The Commands](#the-commands) * [Create Project](#create-project) -* [Add Platforms](#add-platforms) * [Develop Your Project](#develop-your-project) -* [Prepare for Build](#prepare-for-build) * [Build Your Project](#build-your-project) -* [Deploy Your Project](#deploy-your-project) * [Run Your Project](#run-your-project) ## The Commands @@ -185,14 +174,15 @@ Run `tns help` to view all available commands in the browser. Run `tns help -``` - -Where `` is the complete path to the directory that contains your existing project. You can use any NativeScript project, created with the Telerik AppBuilder clients. - The NativeScript CLI creates a new project and sets the application identifier to `org.nativescript.myapp`. The CLI places the project in a new directory in the current directory. The newly created directory has the following structure. @@ -223,67 +205,14 @@ The CLI places the project in a new directory in the current directory. The newl ``` MyApp/ ├── app -│ ├── app.css -│ ├── app.js -│ ├── bootstrap.js -│ ├── main-page.js -│ ├── main-page.xml │ ├── App_Resources -│ │ └── ... -│ └── tns_modules -│ └── ... +│ └── ... └── platforms └── ... ``` -* The `app` directory is the **development space for your application**. You should modify all common and platform-specific code within this directory. When you run `prepare `, the NativeScript CLI copies relevant content to the platform-specific folders for each target platform. -* The `platforms` directory is created empty. When you add a target platform to your project, the NativeScript CLI creates a new subdirectory with the platform name. The subdirectory contains the ready-to-build resources of your app. When you run `prepare `, the NativeScript CLI copies relevant content from the `app` directory to the platform-specific subdirectory for each target platform. - -[Back to Top][1] - -## Add Platforms - -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 first. Currently, you can target Android and iOS with your NativeScript projects. - -Navigate to the directory that contains your newly created project and run the following commands. - -```Shell -tns platform add android -tns platform add ios -``` - -`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 native SDKs for the platform. - -``` -... -platforms/ -|-- android/ -|-- |-- assets/ -|-- |-- gen/ -|-- |-- libs/ -|-- |-- node_modules/ -|-- |-- res/ -|-- |-- src/ -|-- |-- .project -|-- |-- AndroidManifest.xml -|-- |-- build.xml -|-- |-- local.properties -|-- |-- proguard-project.txt -|-- `-- project.properties -|-- ios/ -|-- |-- libTNSBridge.a -|-- |-- node_modules -`-- |-- MyApp/ - `-- MyApp.xcodeproj -... -``` - -For more information about the structure of Android native projects, see [Android Projects](http://developer.android.com/tools/projects/index.html#ApplicationProjects). - -For more information about the structure of iOS native projects, see [Code Organization in Xcode Projects](http://akosma.com/2009/07/28/code-organization-in-xcode-projects/). - -> **TIP:** The NativeScript team provides experimental support for the latest versions of iOS and Android. You can choose which platform runtime to use in your project by running `tns platform add @`
To list all available versions for android, run $ npm view tns-android versions
To list only experimental versions for android, run $ npm view tns-android dist-tags -To list all available versions for ios, run $ npm view tns-ios versions
To list only experimental versions for ios, run $ npm view tns-ios dist-tags +* The `app` directory is the **development space for your application**. You should modify all common and platform-specific code within this directory. When you run `prepare `, the NativeScript CLI prepares relevant content to the platform-specific folders for each target platform. +* The `platforms` directory is created empty. When you add a target platform to your project, the NativeScript CLI creates a new subdirectory with the platform name. The subdirectory contains the ready-to-build resources of your app. When you run `prepare `, the NativeScript CLI prepares relevant content from the `app` directory to the platform-specific subdirectory for each target platform. [Back to Top][1] @@ -297,12 +226,12 @@ To list all available versions for ios, run $ npm view tns-ios versions
To l For more information about working with NativeScript, see the following resources. -* [The NativeScript Documentation Wiki][6] -* [The NativeScript API Reference][7] +* [The NativeScript Documentation Wiki][3] +* [The NativeScript API Reference][5] ### Development in `app` -The `app` directory in the root of the project is the development space for your project. **Place all your common and platform-specific code in this directory.** When you run `prepare `, the NativeScript CLI copies relevant content to the platform-specific folders for each target platform. +The `app` directory in the root of the project is the development space for your project. **Place all your common and platform-specific code in this directory.** In the `app` directory, 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`. @@ -310,13 +239,11 @@ You can develop shared functionality or design in common files. To indicate that ### Development in `platforms` -> **IMPORTANT:** Avoid editing files located in the `platforms` subdirectory because the NativeScript CLI overrides such files during the `prepare ` using the contents of the `app` directory. +> **IMPORTANT:** Avoid editing files located in the `platforms` subdirectory because the NativeScript CLI overrides such files. ### Modifying Configuration Files -The NativeScript CLI respects any platform configuration files placed inside `app/App_Resources`. Those files are respectively `app/App_Resources/AndroidManifest.xml` for Android and `app/App_Resources/Info.plist` for iOS. - -Additionaly, you can modify `app/App_Resources/build.xcconfig` and `app/App_Resources/app.gradle` for adding/removing additional build properties for iOS and Android, respectively. +The NativeScript CLI respects any platform configuration files placed inside `app/App_Resources`. ### Modifying Entitlements File (iOS only) @@ -326,24 +253,9 @@ You can always override the generated entitlements file, by pointing to your own [Back to Top][1] -## Prepare for Build - -When you run `build`, the 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`. - -```Shell -tns prepare android -tns prepare ios -``` - -`prepare ` takes content from `app`, analyzes it and copies it to the platform-specific subdirectory in `platforms`. This operation copies common and relevant platform-specific content that applies to the selected platform. This ensures that your Android or iOS application contain only the correct assets. - -Keep in mind that `prepare` overrides changes made to the platform-specific subdirectory in `platforms`. For more information, see [Development in platforms](#development-in-platforms). - -[Back to Top][1] - ## Build Your Project -After you have prepared your project, you can build it for your target mobile platforms. +You can build it for your target mobile platforms. ```Shell tns build android @@ -352,66 +264,25 @@ tns build ios The NativeScript CLI calls the SDK for the selected target platform and uses it to build your app locally. -When you build for Android, the NativeScript CLI saves the application package as an `APK` in `platforms` → `android` → `bin`. - When you build for iOS, the NativeScript CLI will either build for a device, if there's a device attached, or for the native emulator if there are no devices attached. To trigger a native emulator build when a device is attached, set the `--emulator` flag. -The native emulator build is saved as an `APP` in `platforms` → `ios` → `build` → `emulator`. The device build is saved as an `IPA` in `platforms` → `ios` → `build` → `device`. - > **IMPORTANT:** To build your app for an iOS device, you must configure a valid certificate and provisioning profile pair, and have that pair present on your system 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). [Back to Top][1] -## Deploy Your Project +## Run Your Project You can test your work in progress on connected Android or iOS devices. To verify that the NativeScript CLI recognizes your connected devices, run the following command. ```Shell -tns device -``` - -The NativeScript CLI lists all connected physical devices and running Android Virtual Devices. - -After you have listed the available devices, you can deploy your app on all devices from the selected target platform. - - -```Shell -tns deploy android -tns deploy ios +tns devices ``` -The NativeScript CLI calls the SDK for the selected target platform and uses it to build your app locally. After the build is complete, the NativeScript CLI downloads and installs the application package on your connected devices. +The NativeScript CLI lists all connected physical devices and running emulators/simulators. -On Android devices, the app runs automatically. - -On iOS devices, the app does not run automatically. To run the app, tap the app icon. - -> **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). - -[Back to Top][1] - -## Emulate Your Project - -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. - -```Shell -tns run android --emulator -tns run ios --emulator -``` - -This operation calls the SDK for the selected target platform, builds your app locally, launches the native device emulator for the selected target platform, and runs your project on the virtual device. - -For Android, the NativeScript CLI runs your app in the earliest created virtual device or the currently running Android 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. - -For iOS, the NativeScript CLI runs your app in the iOS Simulator. - -[Back to Top][1] - -## Run Your Project - -You can quickly run your app on connected devices, including all running Android Virtual Devices. The following command is shorthand for `prepare`, `build`, and `deploy`. +After you have listed the available devices, you can quickly run your app on connected devices by executing: ```Shell tns run android @@ -442,21 +313,7 @@ tns doctor This command prints warnings about current configuration issues and provides basic information about how to resolve them. -If addressing the configuration issues does not resolve your problem, you can [report an issue](https://github.com/NativeScript/nativescript-cli/blob/master/CONTRIBUTING.md#report-an-issue) or [post in the NativeScript forums](https://discourse.nativescript.org/). - -[Back to Top][1] - -Known Issues -=== - -* You cannot synchronize changes to apps on Android 4.3 devices and on some Samsung devices using the `run android` command.
**Workaround:** Upgrade to a later version of Android to be able to use the `livesync` command. If you need to develop for Android 4.3 devices, re-build and re-deploy your app to get your latest changes on device. - -* On macOS systems with configured firewall or web proxy, when you run a command, the operation might not release the command line and you might not be able to run other commands until you break the current operation.
If you have enabled feature usage tracking for the NativeScript CLI, but you have not authenticated with the firewall or web proxy on your macOS system, the NativeScript CLI might not release the command line after you run a command. To continue working with the NativeScript CLI, you need to break the current operation by pressing `Ctrl+C`.
**Workaround:** Authenticate with the firewall or web proxy. - 1. Close the terminal. - 1. Run Safari. - 1. Attempt to open a web page. - 1. Provide your authentication credentials for accessing the Internet. - 1. Run the terminal and continue working with the NativeScript CLI. +If addressing the configuration issues does not resolve your problem, you can [report an issue](https://github.com/NativeScript/nativescript-cli/blob/master/CONTRIBUTING.md#report-an-issue) or [ask the community](https://stackoverflow.com/questions/tagged/nativescript). [Back to Top][1] @@ -487,7 +344,7 @@ To use the locally built CLI instead `tns` you can call `PATH_TO_CLI_FOLDER/bin/ Get Help === -Please, use [github issues](https://github.com/NativeScript/nativescript-cli/issues) strictly for [reporting bugs](CONTRIBUTING.md#report-an-issue) or [requesting features](CONTRIBUTING.md#request-a-feature). For general NativeScript questions and support, check out [Stack Overflow](https://stackoverflow.com/questions/tagged/nativescript) or ask our experts in the [NativeScript community Slack channel](http://developer.telerik.com/wp-login.php?action=slack-invitation). +Please, use [github issues](https://github.com/NativeScript/nativescript-cli/issues) strictly for [reporting bugs](CONTRIBUTING.md#report-an-issue) or [requesting features](CONTRIBUTING.md#request-a-feature). For general NativeScript questions and support, check out [Stack Overflow](https://stackoverflow.com/questions/tagged/nativescript) or ask our experts in the [NativeScript community Slack channel](https://www.nativescript.org/slack-invitation-form). [Back to Top][1] @@ -499,23 +356,10 @@ This software is licensed under the Apache 2.0 license, quoted