Smartface CLI Tool

This Node.js CLI tool handles various tasks of the Smartface Framework, including the publishing process to create native iOS and Android apps from JavaScript code. You can use any platform to develop native mobile apps. Other features will be integrated in the future, such as Android and iOS emulator, drag & drop interface integration and possibly more.

Requirements

For Debian or Ubuntu

Certain libraries must be installed to publish for Android. Run the command below from your terminal:

sudo apt-get install -y lib32z1 lib32ncurses5 lib32bz2-1.0 lib32stdc++6

For All Platforms

These requirements are for all platforms like Linux, Mac OSX and Windows systems.

Java SE Development Kit 7u79

You need to install Java 1.7 JDK to publish for Android. You can find more information from its download page.

Android Tools (Optional)

If you want to immediately publish the output to a device or a running emulator instance, you also need to install Android Tools. You can find more information from its download page. Scroll down to SDK Tools Only under Other Download Options section. Installation instruction are here.

Node.js

Node.js version 0.12 or greater is required for the current release.

Warning: Issue with Node.js 4.x version with the interactive mode

There is a bug with Node.js version 4.x that currently leads to a crash when trying to go back by using ESC key in theinteractive mode. Please use the tool with version 0.12 if you plan on using the interactive mode, which is what we would recommend for new users. Nvm can be used to install and manage multiple versions of Node.js on Mac OSX and Linux environments. Npm is used to install dependencies, any recent installation that includes Node.js version 0.12 should be sufficient.

git (Optional)

If you want to download sample projects, you must install git. It should also be visible from your shell environment. You can check this through your command line. For Mac OSX or Linux

which git

For Windows

where git.exe

If you installed Git but do not see it when you use the command above in Windows, you need to make sure that you set its Environment variable correctly.

Smartface Installation

npm install smartface -g

“Sudo” Issue When Installing Smartface

In Linux and Unix systems, when installing global modules for Node.js, you may run into a problem where you may be asked to install with super user privileges by using the sudo command. You can learn how to fix this issue from https://docs.npmjs.com/getting-started/fixing-npm-permissions.

Usage

This tool creates publish output for both Android and iOS for Smartface Cloud projects. The output is apk file for Android and Xcode project file for iOS. You can publish your project by using either interactive mode or parameters which are below. You can find a sample project workspace at https://github.com/SmartfaceIO/smfc-empty-workspace Easiest way to start using the CLI tool is via the interactive mode:

smfc -i

More details about the interactive mode are explained below. You can get the help screen by executing the below command:

smfc -h

You will see the following screen:

  Smartface Command-Line Interface, version 0.0.36

Usage: smfc [options] Smartface Command-Line Interface Options: -h, --help General Help -v, --version Print smfc's version. -i, --interactive Smartface Command-Line Interface in interactive mode --help= General help --task= Task to execute --projectRoot= Target project's root folder --licenseFile= Your Smartface license file path --java= Java 1.7 path --inputApk= Smartface Android Player apk for ARM architecture --inputApkx86= Smartface Android Player apk for x86 architecture --inputZip= Smartface iOS Player project zip --profile= Android options for architecture and package profiles --maxJavaMemory= Maximum amount of memory to be consumed by Java --logLevel= Log Level --logFile= Log to a specific file. --logStdOut= Log to console. You can get detailed information about a CLI parameter by running smfc --help=. For example, you can run

smfc --help=task

And you will see the following screen:

Smartface Command-Line Interface, version 0.0.36

Option: –task Task to execute Example: –task=Android-publish Description: Task to execute More detailed information is provided in the below sections on how to use the CLI parameters.

First Time User

If you have not used the tool before, here is the most basic workflow that you can try. Here are the steps to follow:

• Open your terminal.
• Run smfc -i.
• Choose Sample Projects and then choose Blank Workspace to download.
• Choose Exit.
• Type in your terminal cd , obviously you need to change it to the path where the project was downloaded.
• Run smfc -i.
• Follow the steps for Android-publish or iOS-publish described below.

Interactive Mode

When you type smfc -i or smfc --interactive from your terminal, the interface below will appear:

  Smartface Command-Line Interface, version 0.0.36  
  ( You can enter 'escape' at any time to back. )

» task ? Which task that you want to be run (Use arrow keys) Check Environment & Dependencies ❯ Login Android-publish iOS-publish Sample Projects Exit If you want to use this interface for a specific project, first cd $your_project and then call smfc -i. Once you do this, the CLI tool will provide sane defaults for your project, and in most cases there will be no need for you to change the defaults. When you go through all the steps for publish processes via the interactive mode, the resulting command that can be used to build from the command line is displayed on the screen.

Check Environment & Dependencies

You can check if you are missing any dependencies by choosing this selection. Something similar to the following will appear, depending on your platform and setup:

  Smartface Command-Line Interface, version 0.0.36  
  ( You can enter 'escape' at any time to back. )

┌───────────────────────────────────┐ ├───┐ │ │ √ ├── Environments ─────────────┤ ├───┘ │ ├──── √ Node.js v0.12.2 │ ├──── √ Java 1.7 1.7.0_79 │ ├──── √ Git 2.3.2 │ └───────────────────────────────────┘

Samples

At the moment only a blank workspace sample is included. But more will be included soon. They will be downloaded to your $HOME/Smartface/Samples/ folder.

  »  sample projects
? Select one of available projects for installing (Use arrow keys)
❯ Blank Workspace 

If you already downloaded the project, you will get the This sample directory already exists. error. You can move or delete the project and try again.

Login

If you already own a Smartface license, you can choose to use your license instead of the default Smartface Demothat comes with the installation. You will be asked to enter your email and password. We will not save your credentials for security reasons, but the downside is that you will need to enter your credentials everytime you run the smfc -i command. But you can trigger publish action many times until you exit from the interactive application.

  »  login
? Email   : ******* 
? password: *******

Once you log in successfully, you will be returned to the main list. When you run a publish command, your login information will be used to fetch your licenses, and you can choose which license you wish to use.

Android-publish

You will see the following options (not all at once but one by one):

  »  project root
? Enter project root folder (.../Smartface/Samples/smfc-empty-workspace) 
  »  profiles
? select profiles (Press  to select)
 ──────────────
❯◯ ARM - Default
 ──────────────
 ◯ x86 - Default
  »  license
? select license (Use arrow keys)
❯ Smartface Demo 

Once you make all your selections, the publish process will start and an apk file will be produced. Each publish process is placed in a timestamped folder to prevent collisions. There are two default profiles, ARM and x86. You can add more profiles by editing the PackageProfiles.xml file. The location of the apk file to be published will be displayed in the terminal.

iOS-publish

You will see the following options (not all at once but one by one):

  »  project root
? Enter project root folder (.../Smartface/Samples/smfc-empty-workspace) 
  »  license
? select license (Use arrow keys)
❯ Smartface Demo 

Once you make all your selections, the publish process will start and a zip file that contains the Xcode project will be produced. The location of the zip file to be published will be displayed in the terminal.

Advanced Usage

The CLI tool can be called with numerous parameters to control its input.

Required Parameters

If you want to publish your project, you must use these arguments

• task Task that will be run. Supported tasks: ‘Android-publish‘, ‘iOS-publish‘

Example task

--task=$(TASK) , --task=Android-publish

• projectRoot Your project root folder. You can also use relative paths.

Example projectRoot

--projectRoot=$(PROJECT_ROOT) , --projectRoot=../smfc-sample

Optional parameters

You can use optional parameters.

• licenseFile Your license file path

Example licenseFile

--licenseFile=$(LICENSE) , --licenseFile=/home/Smartface/license.xml

• java Java 1.7 will be needed for the apk file operations. If you do not set this parameter, the tool will try to find Java 1.7, and use that version if it can find one.

Example java

--java=$(JAVA) , --java=/usr/bin/java

• inputApk Smartface Player apk for ARM. You can set one of the arm-players of Smartface.

Example inputApk

--inputApk=$(INPUT_APK) , --inputApk=/home/Smartface/SmartfacePlayer.apk

• inputApkx86 Smartface Player apk for x86. You can set one of the x86-players of Smartface.

Example inputApkx86

--inputApkx86=$(INPUT_APK_x86) , --inputApkx86=/home/Smartface/SmartfacePlayer-x86.apk

• inputZip Smartface Player zip file for iOS. You can set one of the iOS-players of Smartface.

Example inputZip

--inputZip=$(INPUT_ZIP) , --inputZip=/home/Smartface/SmartfacePlayer.zip

• profile ARM or x86 profiles that will be published. * means all profiles

Example profile

--profile=$(PROFILE) , --profile=arm:Default,hdpi;x86:*

• maxJavaMemory Java to be used max memory while running.

Example maxJavaMemory

--maxJavaMemory=$(MAX_JAVA_MEM) , --maxJavaMemory=512m

• logLevel Verbosity level of logging Available options are ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF

Example logLevel

--logLevel=$(LOG_LEVEL) , --logLevel=debug

• logFile You can log to a specific file. Relative paths can be used.

Example logFile

--logFile=$(LOG_FILE) , --logFile=../smfc-sample/log/some.log

• logStdOut You can display logs on the console. If logLevel is set to OFF, there will be no output on the console.

Example logStdOut

--logStdOut=$(LOG_STDOUT) , --logStdOut=true

Example Usage

iOS Publish

smfc --task=iOS-publish --projectRoot=../smfc-sample

smfc --task=iOS-publish --projectRoot=../smfc-sample --logLevel=debug --logFile=../smfc-sample/log/ios.log

Android Publish

smfc --task=Android-publish --projectRoot=../smfc-sample

smfc --task=Android-publish --projectRoot=../smfc-sample --logLevel=debug --logFile=../smfc-sample/log/android.log --maxJavaMemory=512m --profile="arm:Default;x86:hdpi"