diff --git a/CocoaPods.md b/CocoaPods.md index 6bc2089e0e..57a40e1015 100644 --- a/CocoaPods.md +++ b/CocoaPods.md @@ -12,14 +12,14 @@ To work with such libraries, you need to wrap them as a custom NativeScript plug ## Install CocoaPods You need to install CocoaPods. If you haven't yet, you can do so by running: -``` +```bash $ sudo gem install cocoapods ``` > **NOTE:** All operations and code in this article are verified against CocoaPods 0.38.2. To check your current version, run the following command. -``` +```bash $ pod --version ``` @@ -33,8 +33,8 @@ sudo gem install cocoapods To start, create a project and add the iOS platform. ```bash -$ tns create MYCocoaPods -$ cd MYCocoaPods +$ tns create MYCocoaPodsApp +$ cd MYCocoaPodsApp $ tns platform add ios ``` @@ -42,17 +42,17 @@ $ tns platform add ios For more information about working with NativeScript plugins, click [here](PLUGINS.md). -``` +```bash cd .. mkdir my-plugin cd my-plugin ``` -Create a package.json file with the following content: +Create a `package.json` file with the following content: -``` +```json { - "name": "myplugin", + "name": "my-plugin", "version": "0.0.1", "nativescript": { "platforms": { @@ -72,18 +72,31 @@ my-plugin/ └── Podfile ``` +Podfile: +``` +pod 'GoogleMaps' +``` + +## Install the Plugin + Next, install the plugin: -``` +```bash tns plugin add ../my-plugin ``` -## Build the project +> **NOTE:** Installing CocoaPods sets the deployment target of your app to iOS 8, if not already set to iOS 8 or later. This change is required because CocoaPods are installed as shared frameworks to ensure that all symbols are available at runtime. -``` +## Build the Project + +```bash tns build ios ``` -This modifies the `MYCocoaPods.xcodeproj` and creates a workspace with the same name. +This modifies the `MYCocoaPodsApp.xcodeproj` and creates a workspace with the same name. + +> **IMPORTANT:** You will no longer be able to run the `xcodeproj` alone. NativeScript CLI will build the newly created workspace and produce the correct package. + +## Troubleshooting -> **IMPORTANT:** You will no longer be able to run the `xcodeproj` alone. NativeScript CLI will build the newly created workspace and produce the correct .ipa. \ No newline at end of file +In case of post-build linker errors, you might need to resolve missing dependencies to native frameworks required by the installed CocoaPod. For more information about how to create the required links, see the [build.xcconfig specification](PLUGINS.md#buildxcconfig-specification). diff --git a/Gruntfile.js b/Gruntfile.js index 536061fcab..b432c963b0 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -39,17 +39,17 @@ module.exports = function(grunt) { }, devlib: { - src: ["lib/**/*.ts", "!lib/common/node_modules/**/*.ts"], + src: ["lib/**/*.ts", "!lib/common/node_modules/**/*.ts", "!lib/common/messages/**/*.ts"], reference: "lib/.d.ts" }, devall: { - src: ["lib/**/*.ts", "test/**/*.ts", "!lib/common/node_modules/**/*.ts", "lib/common/test/unit-tests/**/*.ts", "definitions/**/*.ts", "!lib/common/test/.d.ts"], + src: ["lib/**/*.ts", "test/**/*.ts", "!lib/common/node_modules/**/*.ts", "!lib/common/messages/**/*.ts", "lib/common/test/unit-tests/**/*.ts", "definitions/**/*.ts", "!lib/common/test/.d.ts"], reference: "lib/.d.ts" }, release_build: { - src: ["lib/**/*.ts", "test/**/*.ts", "!lib/common/node_modules/**/*.ts"], + src: ["lib/**/*.ts", "test/**/*.ts", "!lib/common/node_modules/**/*.ts", "!lib/common/messages/**/*.ts"], reference: "lib/.d.ts", options: { sourceMap: false, @@ -61,7 +61,7 @@ module.exports = function(grunt) { tslint: { build: { files: { - src: ["lib/**/*.ts", "test/**/*.ts", "!lib/common/node_modules/**/*.ts", "lib/common/test/unit-tests/**/*.ts", "definitions/**/*.ts", "!**/*.d.ts"] + src: ["lib/**/*.ts", "test/**/*.ts", "!lib/common/node_modules/**/*.ts", "!lib/common/messages/**/*.ts", "lib/common/test/unit-tests/**/*.ts", "definitions/**/*.ts", "!**/*.d.ts"] }, options: { configuration: grunt.file.readJSON("./tslint.json") @@ -71,7 +71,7 @@ module.exports = function(grunt) { watch: { devall: { - files: ["lib/**/*.ts", 'test/**/*.ts', "!lib/common/node_modules/**/*.ts"], + files: ["lib/**/*.ts", 'test/**/*.ts', "!lib/common/node_modules/**/*.ts", "!lib/common/messages/**/*.ts"], tasks: [ 'ts:devall', 'shell:npm_test' @@ -184,6 +184,6 @@ module.exports = function(grunt) { "copy:package_to_qa_drop_folder" ]); grunt.registerTask("lint", ["tslint:build"]); - + grunt.registerTask("all", ["clean", "test", "lint"]); grunt.registerTask("default", "ts:devlib"); }; diff --git a/PLUGINS.md b/PLUGINS.md index abecd6009e..e811271028 100644 --- a/PLUGINS.md +++ b/PLUGINS.md @@ -6,8 +6,9 @@ Starting with NativeScript CLI 1.1.0, you can develop or use plugins in your Nat * [What Are NativeScript Plugins](#what-are-nativescript-plugins) * [Create a Plugin](#create-a-plugin) * [Directory Structure](#directory-structure) - * [Package.json Specification](#packagejson-specification) - * [Include.gradle Specification](#includegradle-specification) + * [`package.json` Specification](#packagejson-specification) + * [`include.gradle` Specification](#includegradle-specification) + * [`build.xcconfig` Specification](#buildxcconfig-specification) * [Install a Plugin](#install-a-plugin) * [Valid Plugin Sources](#valid-plugin-sources) * [Installation Specifics](#installation-specifics) @@ -21,11 +22,11 @@ Starting with NativeScript CLI 1.1.0, you can develop or use plugins in your Nat A NativeScript plugin is any npm package, published or not, that exposes a native API via JavaScript and consists of the following elements. -* A `package.json` file which contains the following metadata: name, version, supported runtime versions, dependencies and others. For more information, see the [Package.json Specification](#packagejson-specification) section. +* A `package.json` file which contains the following metadata: name, version, supported runtime versions, dependencies and others. For more information, see the [`package.json` Specification](#packagejson-specification) section. * One or more CommonJS modules that expose a native API via a unified JavaScript API. For more information about Common JS modules, see the [CommonJS Wiki](http://wiki.commonjs.org/wiki/CommonJS). -* `AndroidManifest.xml` and `Info.plist` which describe the permissions, features or other configurations required or used by your app for Android and iOS, respectively. -* (Optional) Native Android libraries and the native Android `include.gradle` configuration file which describes the native dependencies. For more information, see the [Include.gradle Specification](#includegradle-specification) section -* (Optional) Native iOS dynamic libraries. +* (Optional) `AndroidManifest.xml` and `Info.plist` which describe the permissions, features or other configurations required or used by your app for Android and iOS, respectively. +* (Optional) Native Android libraries and the native Android `include.gradle` configuration file which describes the native dependencies. For more information, see the [`include.gradle` Specification](#includegradle-specification) section. +* (Optional) Native iOS libraries and the native `build.xcconfig` configuration file which describes the native dependencies. For more information, see the [`build.xcconfig` Specification](#buildxcconfig-specification) section. The plugin must have the directory structure, described in the [Directory Structure](#directory-structure) section. @@ -35,11 +36,11 @@ If the NativeScript framework does not expose a native API that you need, you ca * The plugin must be a valid npm package. * The plugin must expose a built-in native API or a native API available via custom native libraries. -* The plugin must be written in JavaScript or TypeScript and must comply with the CommonJS specification. If written in TypeScript, make sure to include the compiled `JavaScript` file in your plugin. +* The plugin must be written in JavaScript and must comply with the CommonJS specification. If you are using a transpiler, make sure to include the transpiled JavaScript files in your plugin. * The plugin directory structure must comply with the specification described below. * The plugin must contain a valid `package.json` which complies with the specification described below. -* If the plugin requires any permissions, features or other configuration specifics, it must contain `AndroidManifest.xml` and `Info.plist` file which describe them. -* (Android-only) If the plugin depends on native libraries, it must contain a valid `include.gradle file`, which describes the dependencies. +* If the plugin requires any permissions, features or other configuration specifics, it must contain `AndroidManifest.xml` or `Info.plist` file which describe them. +* If the plugin depends on native libraries, it must contain a valid `include.gradle` or `build.xcconfig` file, which describes the dependencies. ### Directory Structure @@ -51,7 +52,7 @@ my-plugin/ ├── package.json └── platforms/ ├── android/ - │ └── res/ + │ ├── res/ │ └── AndroidManifest.xml └── ios/ └── Info.plist @@ -61,6 +62,7 @@ NativeScript plugins which consist of multiple CommonJS modules might have the f ``` my-plugin/ +├── index.js ├── package.json ├── MyModule1/ │ ├── index1.js @@ -70,20 +72,17 @@ my-plugin/ │ └── package.json └── platforms/ ├── android/ + │ ├── AndroidManifest.xml │ └── res/ - │ └── AndroidManifest.xml └── ios/ └── Info.plist - └── Podfile ``` * `index.js`: This file is the CommonJS module which exposes the native API. You can use platform-specific `*.platform.js` files. For example: `index.ios.js` and `index.android.js`. During the plugin installation, the NativeScript CLI will copy the platform resources to the `tns_modules` subdirectory in the correct platform destination in the `platforms` directory of your project.
Alternatively, you can give any name to this CommonJS module. In this case, however, you need to point to this file by setting the `main` key in the `package.json` for the plugin. For more information, see [Folders as Modules](https://nodejs.org/api/modules.html#modules_folders_as_modules). * `package.json`: This file contains the metadata for your plugin. It sets the supported runtimes, the plugin name and version and any dependencies. The `package.json` specification is described in detail below. * `platforms\android\AndroidManifest.xml`: This file describes any specific configuration changes required for your plugin to work. For example: required permissions. For more information about the format of `AndroidManifest.xml`, see [App Manifest](http://developer.android.com/guide/topics/manifest/manifest-intro.html).
During build, gradle will merge the plugin `AndroidManifest.xml` with the `AndroidManifest.xml` for your project. The NativeScript CLI will not resolve any contradicting or duplicate entries during the merge. After the plugin is installed, you need to manually resolve such issues. -* `platforms\android\include.gradle`: This file modifies the native Android configuration of your NativeScript project such as native dependencies, build types and configurations. For more information about the format of `include.gradle`, see [include.gradle file](#includegradle-specification). -* `platforms/android/res`: (Optional) This directory contains resources declared by the `AndroidManifest.xml` file. You can look at the folder structure [here](http://developer.android.com/guide/topics/resources/providing-resources.html#ResourceTypes). -* `platforms/ios/Info.plist`: This file describes any specific configuration changes required for your plugin to work. For example: required permissions. For more information about the format of `Info.plist`, see [About Information Property List Files](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/AboutInformationPropertyListFiles.html).
During the plugin installation, the NativeScript CLI will merge the plugin `Info.plist` with the `Info.plist` for your project. The NativeScript CLI will not resolve any contradicting or duplicate entries during the merge. After the plugin is installed, you need to manually resolve such issues. -* `platforms/ios/Podfile`: This file describes the dependency to the library that you want to use. For more information, see [the CocoaPods article](CocoaPods.md). +* `platforms\android\res`: (Optional) This directory contains resources declared by the `AndroidManifest.xml` file. You can look at the folder structure [here](http://developer.android.com/guide/topics/resources/providing-resources.html#ResourceTypes). +* `platforms\ios\Info.plist`: This file describes any specific configuration changes required for your plugin to work. For example, required permissions. For more information about the format of `Info.plist`, see [About Information Property List Files](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/AboutInformationPropertyListFiles.html).
During the plugin installation, the NativeScript CLI will merge the plugin `Info.plist` with the `Info.plist` for your project. The NativeScript CLI will not resolve any contradicting or duplicate entries during the merge. After the plugin is installed, you need to manually resolve such issues. NativeScript plugins which contain both native Android and iOS libraries might have the following directory structure. @@ -92,20 +91,28 @@ my-plugin/ ├── ... └── platforms/ ├── android/ - │ └── res/ - │ └── MyLibrary.jar - │ └── MyLibrary.aar - │ └── include.gradle + │ ├── res/ + │ ├── MyLibrary.jar + │ ├── MyLibrary.aar + │ ├── include.gradle │ └── AndroidManifest.xml └── ios/ - ├── MyiOSLibrary.framework - └── Info.plist + ├── MyiOSFramework.framework + ├── build.xcconfig + ├── Podfile + ├── Info.plist + ├── MyStaticiOSLibrary.a + └── include/ + └── MyStaticiOSLibrary/ + └── ... ``` -* `platforms\android`: This directory contains any native Android libraries packaged as `*.jar` and `*.aar` packages. These native libraries can reside in the root of this directory or in a user-created sub-directory. During the plugin installation, the NativeScript CLI will configure the Android project in `platforms\android` to work with the plugin. +* `platforms\android`: This directory contains any native Android libraries packaged as `*.jar` and `*.aar` packages. These native libraries can reside in the root of this directory or in a user-created sub-directory. During the plugin installation, the NativeScript CLI will configure the Android project in `platforms\android` to work with the plugin. * `platforms\android\res`: (Optional) This directory contains resources declared by the `AndroidManifest.xml` file. You can look at the folder structure [here](http://developer.android.com/guide/topics/resources/providing-resources.html#ResourceTypes). -* `platforms\ios`: This directory contains native iOS dynamic libraries (`.framework`). During the plugin installation, the NativeScript CLI will copy these files to `lib\iOS` in your project and will configure the Android project in `platforms\ios` to work with the library. -* `platforms\android\include.gradle`: This file modifies the native Android configuration of your NativeScript project such as native dependencies, build types and configurations. For more information about the format of `include.gradle`, see [include.gradle file](#includegradle-specification). +* `platforms\android\include.gradle`: This file modifies the native Android configuration of your NativeScript project such as native dependencies, build types and configurations. For more information about the format of `include.gradle`, see [`include.gradle` file](#includegradle-specification). +* `platforms\ios`: This directory contains native dynamic iOS Cocoa Touch Frameworks (`.framework`) and Cocoa Touch Static Libraries (`.a`). During the plugin installation, the NativeScript CLI will copy these files to `lib\iOS` in your project and will configure the iOS project in `platforms\ios` to work with the libraries. If the library is written in Swift, only APIs exposed to Objective-C are exposed to NativeScript. In case the plugin contains a Cocoa Touch Static Library (`.a`), you must place all public headers (`.h`) under `include\\`. Make sure that the static libraries are built at least for the following processor architectures - armv7, arm64, i386. +* `platforms\ios\build.xcconfig`: This file modifies the native iOS configuration of your NativeScript project such as native dependencies and configurations. For more information about the format of `build.xcconfig`, see [`build.xcconfig` file](#buildxcconfig-specification). +* `platforms\ios\Podfile`: This file describes the dependency to the library that you want to use. For more information, see [the CocoaPods article](CocoaPods.md). ### Package.json Specification @@ -113,7 +120,7 @@ Every NativeScript plugin should contain a valid `package.json` file in its root * It must comply with the [npm specification](https://docs.npmjs.com/files/package.json).
The `package.json` must contain at least `name` and `version` pairs. You will later use the plugin in your code by requiring it by its `name`. * It must contain a `nativescript` section which describes the supported NativeScript runtimes and their versions. This section can be empty. If you want to define supported platforms and runtimes, you can nest a `platforms` section. In this `platforms` section, you can nest `ios` and `android` key-value pairs. The values in these pairs must be valid runtime versions or ranges of values specified by a valid semver(7) syntax. -* If the plugin depends on other npm modules, it must contain a `dependencies` section as described [here](https://docs.npmjs.com/files/package.json#dependencies).
The NativeScript CLI will resolve the dependencies during the plugin installation. +* If the plugin depends on other npm modules, it must contain a `dependencies` section as described [here](https://docs.npmjs.com/files/package.json#dependencies).
The NativeScript CLI will resolve the dependencies during the plugin installation. #### Package.json Example @@ -141,16 +148,16 @@ Every NativeScript plugin, which contains native Android dependencies, should al * Any native dependencies should be available in [jcenter](https://bintray.com/bintray/jcenter) or from the Android SDK installed on your machine. > **IMPORTANT:** If you don't have an `include.gradle` file, at build time, gradle will create a default one containing all default elements. - + #### Include.gradle Example -``` +```gradle //default elements -android { - productFlavors { - "my-plugin" { - dimension "my-plugin" - } - } +android { + productFlavors { + "my-plugin" { + dimension "my-plugin" + } + } } //optional elements @@ -159,6 +166,14 @@ dependencies { } ``` +### Build.xcconfig Specification +Every NativeScript plugin, which contains native iOS dependencies, can also contain a [valid](https://pewpewthespells.com/blog/xcconfig_guide.html) `build.xcconfig` file in the root of its `platforms\ios` directory. This `build.xcconfig` file might contain native dependencies required to build the plugin properly. + +#### Build.xcconfig Example +``` +OTHER_LDFLAGS = $(inherited) -framework "QuartzCore" -l"sqlite3" +``` + ## Install a Plugin To install a plugin for your project, inside your project, run the following command. @@ -185,7 +200,7 @@ The NativeScript CLI takes the plugin and installs it to the `node_modules` dire If the NativeScript CLI detects any native iOS libraries in the plugin, it copies the library files to the `lib\ios` folder in your project and configures the iOS-specific projects in `platforms\ios` to work with the library. -Next, the NativeScript CLI runs a partial `prepare` operation for the plugin for all platforms configured for the project. During this operation, the CLI copies only the plugin to the `tns_modules` subdirectories in the `platforms\android` and `platforms\ios` directories in your project. If your plugin contains platform-specific `JS` files, the CLI copies them to the respective platform subdirectory and renames them by removing the platform modifier. +Next, the NativeScript CLI runs a partial `prepare` operation for the plugin for all platforms configured for the project. During this operation, the CLI copies only the plugin to the `tns_modules` subdirectories in the `platforms\android` and `platforms\ios` directories in your project. If your plugin contains platform-specific `JS` files, the CLI copies them to the respective platform subdirectory and renames them by removing the platform modifier. > **TIP:** If you have not configured any platforms, when you run `$ tns platform add`, the NativeScript CLI will automatically prepare all installed plugins for the newly added platform. @@ -202,7 +217,7 @@ The following is an example of a plugin `AndroidManifest`, project `AndroidManif ```XML - + @@ -211,7 +226,7 @@ The following is an example of a plugin `AndroidManifest`, project `AndroidManif - + @@ -229,10 +244,10 @@ The following is an example of a plugin `AndroidManifest`, project `AndroidManif - + - + - + @@ -259,7 +274,7 @@ The following is an example of a plugin `AndroidManifest`, project `AndroidManif ```XML - @@ -271,7 +286,7 @@ The following is an example of a plugin `AndroidManifest`, project `AndroidManif - @@ -300,7 +315,7 @@ To use a plugin inside your project, you need to add a `require` in your app. var myPlugin = require("myplugin"); ``` -This will look for a `myplugin` module with a valid `package.json` file in the `tns_modules` directory. Note that you must require the plugin with the value for the `name` key in the plugin `package.json` file. +This will look for a `myplugin` module with a valid `package.json` file in the `tns_modules` directory. Note that you must require the plugin with the value for the `name` key in the plugin `package.json` file. ## Remove a Plugin diff --git a/README.md b/README.md index a3ac6fd200..2753c76b65 100644 --- a/README.md +++ b/README.md @@ -570,3 +570,4 @@ This software is licensed under the Apache 2.0 license, quoted [--path ] [--appid ] [--copy-from ]` +Create from default JavaScript template | `$ tns create [--path ] [--appid ]` +Create from default TypeScript template | `$ tns create [--path ] [--appid --template typescript` OR `$ tns create [--path ] [--appid --template tsc` +Copy from existing project | `$ tns create [--path ] [--appid ] --copy-from ` +Create from custom template | `$ tns create [--path ] [--appid ] --template