Page tree
Skip to end of metadata
Go to start of metadata

This guide explains how to use Smartface CLI Tool.

About 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 for CLI tool.

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 it's 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 it's download page.

Scroll down to "SDK Tools Only" under "Other Download Options" section.

Installation instruction are here.

 Node.js

nodejs 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 the interactive 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 installgit.

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 it's Environment variable correctly.

Smartface Installation

The command for installation is :

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 here.

It will be solved as in the below image :

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 here
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 :

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 :

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 same 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 :

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.

If you already downloaded the project, you will get the This sample directory already exists. error as in below.

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 Demo that 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.

 

Once you logged 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

When you are trying to get Android publish, you will see the following options :

Once you make all your selections, the publish process will start and an apk file will be produced. The location of the apk file to be published will be displayed in the terminal.

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 thePackageProfiles.xml file.

iOS-Publish

The steps for iOS publish is also similar with Android.

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 it's 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”