Giter Club home page Giter Club logo

phonegap-cli's Introduction

PhoneGap CLI

Build Status  Build status codecov

PhoneGap command-line interface and Node.js library.

Command-line

Requirements

Install

$ npm install -g phonegap@latest

Getting Started

$ phonegap create my-app    # create a PhoneGap project
$ cd my-app                 # change to project directory
$ phonegap run ios          # build and install the app to iOS

Usage

Usage: phonegap [options] [commands]

Description:

  PhoneGap command-line tool.

Commands:

  create <path>        create a phonegap project
  build <platform>     build the project for specific platform
  install <platform>   install the project on a specific platform
  run <platform>       build and install the projectfor specific platform
  serve                serve a phonegap project
  local [command]      development on local system
  remote [command]     development in cloud with phonegap/build
  platform [command]   update a platform version
  help [command]       output usage information
  version              output version number
  analytics            turn analytics on or off, or view current status

Options:

  -d, --verbose        allow verbose output
  -v, --version        output version number
  -h, --help           output usage information

Platforms:

  keyword            | local environment | remote environment
  -------------------|-------------------|-------------------
  android            | ✔                 | ✔
  blackberry10       | ✔                 | ✖
  ios                | ✔                 | ✔
  wp8                | ✔                 | ✔


Examples:

  $ phonegap help create
  $ phonegap help remote build
  $ phonegap create path/to/my-app
  $ phonegap remote build android

Local Usage

Usage: phonegap local [command]

Description:

  Executes the command on the local system.

  This requires that platform SDK is correctly installed.

Commands:

  build <platform>     build a specific platform
  install <platform>   install a specific platform
  run <platform>       build and install a specific platform
  plugin <command>     add, remove, and list plugins

Examples:

  $ phonegap local build android
  $ phonegap local run android
  $ phonegap local plugin list

Remote Usage

Usage: phonegap remote [command]

Description:

  Executes the command remotely using the cloud-based PhoneGap/Build service.

Commands:

  login                login to PhoneGap/Build
  logout               logout of PhoneGap/Build
  build <platform>     build a specific platform
  install <platform>   install a specific platform
  run <platform>       build and install a specific platform

Examples:

  $ phonegap remote login
  $ phonegap remote build android
  $ phonegap remote run android

Node Library

Usage

var phonegap = require('phonegap');

App Templates

Templates allow you to create a new app from an existing app template. The nice part about templates is that they are simply a Cordova-compatible app. Any existing app can be a template.

You can list the available templates with:

$ phonegap template list

You can create a new project from a template with:

$ phonegap create my-app --template hello-world

Adding a New Template

Adding a new template is easy.

  1. Add your template to the package.json template section.

     // the key is your template name (e.g. hello-world)
     // the url is a HTTP URL to a .tar.gz.
     {
       "templates": {
         "hello-world": {
           "description": "Default hello world app for PhoneGap.",
           "url": "https://github.com/phonegap/phonegap-app-hello-world/archive/master.tar.gz"
         }
       }
     }
    
  2. Send us a pull request!

FAQ

phonegap: command not found

Problem

The PhoneGap CLI installs successfully but you do not have a command phonegap.

Reason

Depending on how node and npm were installed, your globally installed npm modules may not be in your PATH.

Solution

At the bottom of your npm install -g phonegap@latest installation log, you will see the following:

...
/usr/local/share/npm/bin/phonegap -> /usr/local/share/npm/lib/node_modules/phonegap/bin/phonegap.js
...

(Your path may be slightly different)

Open ~/.profile or ~/.bashrc, depending on what exists on your system, and add following line:

export PATH=$PATH:/usr/local/share/npm/bin

Open a new terminal tab or type the following command:

$ source ~/.profile
or
$ source ~/.bashrc

The command phonegap should now be available to you.

The provided path is not an Android project

Problem

You receive the following error message when building an Android project:

throw new Error('The provided path "' + project + '" is not an Android

Reason

The first time that you build for a platform, the framework is downloaded from Apache Cordova.

The framework is stored locally in your home directory, such as ~/.cordova/lib.

Sometimes the framework is corrupted during the download. It can exist for two know reasons:

  1. Your Android SDK environment is not properly configured.
  2. Unknown issue related to Apache's servers or the untar operation.

Solution

First, you must properly configure your Android environment by following the platform setup guide.

Next, you must delete the cached Cordova Android framework (x.x.x is your version):

~/.cordova/lib/android/cordova/x.x.x

Next, you can try to rebuild the project. Enabling verbose mode is sometimes helpful:

$ phonegap build android --verbose

Upgrading Cordova

There are a few steps that should be taken when upgrading to a new version of the cordova-cli.

  1. Update the package.json dependencies version for cordova.

     {
       "dependencies": {
         "cordova": "3.1.0"
       }
     }
    
  2. Update the package.json version.

     {
       "version": "3.1.0+cordova.0.15.0"
     }
    
  3. Run the tests.

     $ npm test
    
  4. Commit stating the version increment.

     $ git add package.json
     $ git commit -am "Version 3.1.0+cordova.0.15.0"
    
  5. Tag the version commit.

     $ git tag 3.1.0+cordova.0.15.0
    
  6. Update the PhoneGap Hello World App to match the new version.

  1. Manually test that the latest Hello World app is lazy-loaded.

     # Link the phonegap-cli for easier development (only need to do once).
    
     $ cd phonegap-cli/
     $ [sudo] npm link .
    
     # Manually test and verify hello world app is lazy-loaded.
    
     $ phonegap create my-app
     [phonegap] missing library phonegap/www/3.1.0
     [phonegap] downloading https://github.com/phonegap/phonegap-app-hello-world/archive/3.1.0.tar.gz...
     [phonegap] created project at /Users/mwbrooks/Development/sandbox/my-app
    
     $ cd my-app/
     $ phonegap run ios
    
  2. Push the git commit after the Hello World has been updated.

     $ git push phonegap master
    
  3. Publish the npm release.

     $ npm publish
    

Analytics

Please read our privacy policy for more information on the data we collect.

phonegap-cli's People

Contributors

adrivanhoudt avatar aharbick avatar anotheredward avatar brianleroux avatar carynbear avatar devgeeks avatar eliotsykes avatar filmaj avatar frederikbosch avatar gebeto avatar hermwong avatar hiddentao avatar hollyschinsky avatar imhotep avatar kt3k avatar lorinbeer avatar macdonst avatar maverickmishra avatar mwbrooks avatar nsriram avatar octavioturra avatar purplecabbage avatar qkdreyer avatar rodms10 avatar ryanstewart avatar shazron avatar silverma avatar stevengill avatar surajpindoria avatar timkim avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

phonegap-cli's Issues

$ phonegap remote [commands]

Usage

$ phonegap remote [command]

Description

This command is a bucket for all remote commands that interact with PhoneGap/Build.

When the the following is run:

$ phonegap remote

Then the remote usage information should be ouput.

$ phonegap remote login [options]

Implement the following command:

$ phonegap remote login [options]

This command is currently implement by phonegap-build-cli and can be directly called.

This is also an opportunity to begin removing the the CLI interface from the phonegap-build library.

App Command

Command

$ phonegap app
[phonegap] Open the PhoneGap app on your device
[phonegap] Select “Local Development”
[phonegap] Address: 192.168.0.10
[phonegap] Port: 8080

Related Issues

Issue #1: First Application

Implementation

This is a local webserver that serves up the assets. For now, it can be that dumb.

This command is analogous to $ cordova serve... at least on the outside.

$ phonegap remote logout

Implement the following command:

$ phonegap remote logout

This command is currently implement by phonegap-build-cli and can be directly called.

This is also an opportunity to begin removing the the CLI interface from the phonegap-build library.

Building to Multiple Platforms

Overview

The Cordova CLI supports building to multiple platforms:

$ cordova build android ios

Question

Do we want to offer this functionality to the PhoneGap CLI?

Approach

PhoneGap/Build already builds to all platforms.

Cordova CLI supports this functionality.

It would be trivial to add support, although require some refactoring of mwbrooks/phonegap-build-cli.

Reference

This is in reference to phonegap/node-phonegap-build#31

phonegap build remote hangs

probably should have a timeout and friendly error message. a way to check the health of phonegap build might be needed doing too

Cordova CLI: Donate Platform Support

Source Code

Detecting support of a platform SDK.

Contribution

The Cordova CLI needs to expose the ability to check whether a system supports a given platform SDK.

Currently, the check_requirements function does most of this, but is not exposed globally. However, there are a few considerations that should be addressed:

  • Android attempts to update the project. However, the phonegap-cli does not create platform projects until first build, which does not happen until the SDK is verified. So, this will need to be restructured.
  • BlackBerry has no detection. At the very least, it should check that bbwp is in the path.

Reference

#26 Added Platform Verification

Recipe Feature

What is a Recipe

A recipe is a template project. For example, a project based on TopCoat, Backbone, Angular.js, etc.

Usage

When creating a project, the user can add a --recipe <name> flag to create a project based on a specific recipe.

Review $ phonegap build local ios

Overview

$ cordova build local ios

Add Platform

???

Build Path

???

Does Build Command Run Installer?

???

$ cordova emulate ios

???

Review $ npm install -g phonegap

Goal

Review the installation process it fast and simple.

Cordova CLI

The Cordova CLI is exactly the opposite of the goal. It's a large installation that is not friendly to a [sudo] installation (which is the most common type that is setup by the Node OS X installer).

Add create command

$ phonegap create <path>

The command should call cordova create under the hood and generate an app using the phonegap-start template.

JavaScript API Documentation

Overview

The PhoneGap CLI exposes both a command-line interface and programmatic JavaScript interface.

Problem

It is tedious and error prone to mirror the function signatures and parameters in the README.md.

Investigate

Investigate generating the documentation to a webpage.

Declare help documentation in text files

Overview

To reduce to the amount of code and simplify the documentation, it would be nice to declare the help documentation in text files.

Structure

/doc/
/doc/cli/
/doc/cli/command.txt
/doc/cli/command.command.txt

Format

For now, we can just use plain-text (txt). Later on, if there is a need, we can use markdown (md).

Cleanup Remote Build Logic

Review lib/cli/remote.build.js and lib/phonegap/remote.build.js to move as much logic back to phonegap-build-cli as possible.

Hide $ phonegap app Command

Description

Soon we'll be starting work on the PhoneGap App and accepting beta users to test the application out.

Since the command $ phonegap app is specific to the PhoneGap App, it may be confusing to developers who are not in the beta program.

Hidden Not Removed

We're just removing the command from $ phonegap help.

You can still learn about the command with $ phonegap help app and run the command with $ phonegap app.

Future

If we generalize the command to support Ripple or Browser based development, we can re-add the command.

$ phonegap build <platform>

Implement the following command:

$ phonegap build <platform>

Description

Builds the project locally if the SDK is installed, otherwise uses PhoneGap/Build.

Implementation

This command should only contain the logic required to link the other two commands.

  • attempt phonegap local build <platform>
  • on error attempt phonegap remote build <platform>

Clean up Login Logic

Just a little house cleaning to ensure the lib/cli/remote.login.js and lib/phonegap/remote.login.js are doing as little as possible.

Review $ phonegap build local blackberry

Overview

$ cordova build local blackberry

Add Platform

Prompts for a number of SDK questions.

Many of these can be auto-detected and the settings should be stored globally.

Build Path

???

Does Build Command Run Installer?

???

$ cordova emulate android

???

Add / Remove / List Platforms

Overview

This is functionality of the Cordova CLI.

Question

Do we want to add this functionality to the PhoneGap CLI?

Do we want to provide a default platform?

Approach

We can store the platforms in .cordova/config.json to for local and remote support.

A default platform would be used when running phonegap build

Reference

This is in reference to a phonegap/node-phonegap-build#31

Update Remote Build to Support Merges Directory

Description

Projects are now created using a Cordova project structure (#17).

One feature of the Cordova project structure is the merges/ directory, which adds support for platform-specific files to replace files in www/.

Cordova has a prepare command that can be leveraged to preprocess the assets before compiling. We should be able to prepare the assets, before building remotely.

Update Global Configuration Director to ~/.config

Description

Currently:

~/.phonegap/

Problem

There is a high chance that Apache Cordova will need to use a global configuration directory as well. For backwards compatibility, we should adopt their directory.

PhoneGap/Build CLI

The PhoneGap/Build CLI has already adopted the ~/.cordova/ directory pattern with #28.

Decouple each command in the library

Current

Currently, each command is part of an class prototype. There are three reasons why it is implemented like this:

  • shared eventEmitter instance.
  • shared PhoneGapBuild instance.
  • commands invoke each other.

Problem

Referencing the instance is of PhoneGap gets messy when dealing with subcommands such as:

PhoneGap.prototype.remote.build;

Solution 1)

This could be solved by making remote a class instance of PhoneGap:

function PhoneGap() {
    this.emitter = new events.EventEmitter();
    this.remote = new Remote(this.emitter);
}

Pro

  • PhoneGap as a class is more testable because a new instance is created for each test.

Con

  • Abstracting the subcommands makes it more difficult to learn and maintain

Solution 2)

Each command can exist as its own function. This keeps everything very clean and straightforward.

  • eventEmitter is a module used by all functions.
  • PhoneGapBuild is a module used by all functions.
  • invoke commands should be attached to module.exports.<name> for testable spies.

Pro

  • Clear and easy to understand / contribute
  • Less interconnected parts dependent on class structure

Con

  • PhoneGap object must become a singleton, which is less testable
    • phonegap.removeAllListeners() can help reset the object

CLI: Reimplement Command Lookup and Loading

Current

Currently, the commands are predefined in lib/cli.js and invoked by a lookup function in lib/cli/argv.js.

Problem

Predefining commands are unnecessary. No command should communicate with another command. So, on each run of the command-line tool only one command is invoked.

The lookup is error prone when dealing with subcommands such as phonegap remote build. For example, it will crash if you give a subcommand an unknown command.

Solution

The commands can be dynamically loaded upon request.

When a command does not exist, the unknown command can be invoked.

$ phonegap remote build <platform>

Implement the following command:

$ phonegap remote build <platform>

This command is currently implement by phonegap-build-cli and can be directly called.

This is also an opportunity to begin removing the the CLI interface from the phonegap-build library.

error on `npm install -g phonegap`

Some problem with flatiron.

npm ERR! peerinvalid The package flatiron does not satisfy its siblings' peerDependencies requirements!
npm ERR! peerinvalid Peer [email protected] wants flatiron@~0.1.9
npm ERR! peerinvalid Peer [email protected] wants flatiron@~0.1.9

npm ERR! System Darwin 12.3.0
npm ERR! command "node" "/usr/local/bin/npm" "install" "-g" "phonegap"
npm ERR! cwd /Users/brianl/Desktop
npm ERR! node -v v0.8.12
npm ERR! npm -v 1.2.18
npm ERR! code EPEERINVALID
npm ERR!
npm ERR! Additional logging details can be found in:
npm ERR! /Users/brianl/Desktop/npm-debug.log
npm ERR! not ok code 0

Add Platform Support Verification

Overview

The global commands of the PhoneGap CLI must detect whether the system has the platform SDK installed. The command will then execute locally or remotely.

Cordova Public Interface

At the moment, Cordova CLI does not publicly expose an interface to check the platform support.

Solution

The Cordova CLI implementation is minimal.

A short-term action can be to implement the verification functions within the PhoneGap CLI.

A long-term action can be to expose the verification functions in the Cordova CLI.

CLI Consumes Main Library

At the moment, the CLI cheats in some respects:

  • var cordova = require('cordova');
  • var qrcode = require('qrcode-terminal');
  • var config = require('../common/config');

Additionally, it must awkwardly pass the phonegap object around. The PhoneGap object has been updated to include a global instance under lib/main.js, which is exposed as the npm main entry point.

The CLI should be updated to only use the lib/main.js. This is a good exercise for the library.

Clean up Logout Logic

Just a little house cleaning to ensure the lib/cli/remote.logout.js and lib/phonegap/remote.logout.js are doing as little as possible.

$ phonegap local build <platform>

Implement the following command:

$ phonegap local build <platform>

Description

Builds the application locally using the system's installed SDK.

Implementation

This command should leverage cordova-cli under the hood. Currently, the Cordova CLI is hardcoded to use the Cordova distribution, so contributions will need to be made to support alternative Cordova distributions.

Command Interface

Overview

The PhoneGap Command Line tool should support building an application both locally and remotely.

A local build will require the platform SDK to be properly installed.

A remote build will require a PhoneGap/Build account.

Local and Remote Projects

When it comes to the CLI design, there are two camps of opinions. One group would like the CLI to provide two separate commands: phonegap and phonegap-build. The other camp would like graceful degradation from local to remote.

I prefer to think about the workflow instead of the implementation.

Terminology

We will use local and remote instead of referencing PhoneGap/Build. In the world of PhoneGap, the word "build" can exist as a verb (to compile) and noun (PG/Build). To avoid confusion, the noun "build" is replaced with remote.

Venn Diagram

Managing a local project has a certain set of tasks:

  • create a project
  • build a project
  • serve a project
  • install to emulator
  • install to device

Managing a remote project has a certain set of tasks:

  • create a project locally
  • create a project remotely
  • build a project
  • manage keys
  • manage collaborators
  • manages apps

While some commands overlap, others do not.

Scenarios

  • Developer may only build a project locally
  • Developer may only build a project remotely
  • Developer may both build a project locally and remotely
  • Developer may use different strategy for each project (depending on PhoneGap version)

Goal

The CLI tool should be extensible to offer a complete experience for both local and remote projects.

Strategy

For clear distinction of what environment a command affects, the commands should be grouped under the environment.

When a common command exists in both environments then it can become a global command. The global command must smartly invoke the proper environment's command. If it cannot do this, then it should not be a global command.

Discarded Strategies

Two Separate Command-Line Tools

$ phonegap create my-app
$ phonegap build android

$ phonegap-build create my-app
$ phonegap-build build android
$ phonegap-build collaborator add mwbrooks

An original draft experimented with two separated commands: phonegap and phonegap-build. Both tools would attempt to use a common command-line interface and add additional commands as desired.

The Good

  • Isolates environment commands to each environment
  • Developer must explicitly think about the environment for the command

The Bad

  • There are not universal (global) commands.
  • Developer must learn two command-line tools.
  • Command parity breakdown.
    • As programmers we know that it will be difficult to keep parity between separate interfaces.
    • Inevitably, the same commands will not match in result.

Unified Interferface

$ phonegap create my-app
$ phonegap build android
$ phonegap build android --local
$ phonegap build android --remote
$ phonegap collaborator add mwbrooks

Both local and remote commands are defined by the phonegap binary in the global command space. A [options] flag is used to define a --local or --remote action.

The Good

  • There is one command-line tool.
  • There are universal (global) commands.
  • Developer can opt-out of the auto-environment selector with a flag.

The Bad

  • Command environment is ambiguous
    • Some commands run locally
    • Some commands run remotely
    • Some commands run locally and remotely

Command Line Interface

$ phonegap create my-app

$ phonegap build android
$ phonegap local build android
$ phonegap remote build android

$ phonegap remote collaborator add mwbrooks

Update create command to use Cordova's create

Current State

Currently $ phonegap create <path> uses the phonegap-build-cli create function.

Why use Cordova

In order to add local commands with cordova-cli, the project must match that defined by cordova-cli.

Blocker

This issue is a blocker to #9 - Adding local build functionality.

Events required by all commands

Description

Every command in the phonegap library should support the following events:

  • log(str, [str, ...]) for progress logging.
  • warn(str, [str, ...]) for warning messages.
  • error(e) when an error occurs.
  • complete([data]) when command completes successfully.
  • login(callback) when authentication is required.

Naming Conventions

I'm totally open to any naming convention.

I use log, warn, and error because they match node.js console naming.

The alternative to complete could be end, which matches many node libraries. However, I feel end does not naturally imply a success state, which complete does. shrugs If you've got an opinion on this, chime in (even if the thread is closed) and we can refactor away.

Event Scope

At the moment, all events are scoped to the command. Most of the events above could be placed on the global phonegap object to DRY up the client's code. For now, I'll do baby-steps and just add all of the events to each command. Again, chime in if you have an opinion.

Review $ phonegap build local android

Overview

$ cordova build local android

Add Platform

Silently added the platform.

Build Path

my-project/platforms/android/bin/

Does Build Command Run Installer?

Does not install to an emulator or device.

$ cordova emulate android

Installs to the first connected device or emulator.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.