Creating an Android Project with Forcedroid

To create an app, use forcedroid in a terminal window or at a Windows command prompt. The forcedroid utility gives you two ways to create your app.

Specify the type of application you want, along with basic configuration data.
OR
Use an existing Mobile SDK app as a template. You still provide the basic configuration data.

You can use forcedroid in interactive mode with command-line prompts, or in script mode with command-line arguments. To see command usage information, type forcedroid without arguments.

Forcedroid Project Types

The forcedroid create command requires you to specify one of the following project types:

App Type	Architecture	Language
`native`	Native	Java
`native_kotlin` (or just press `RETURN`)	Native	Kotlin

To develop a native Android app in Java, specify native.

Using forcedroid create Interactively

To enter application options interactively at a command prompt, type forcedroid create. The forcedroid utility then prompts you for each configuration option. For example:

1$ forcedroid create
2Enter your application type (native, native_kotlin): <press RETURN>
3Enter your application name: testNative
4Enter the package name for your app (com.mycompany.myapp): com.bestapps.android
5Enter your organization name (Acme, Inc.): BestApps
6Enter output directory for your app (leave empty for the current directory): testNative

This command creates a native Kotlin Android app named “testNative” in the testNative\ subdirectory of your current directory.

Using forcedroid create in Script Mode

In script mode, you can use forcedroid without interactive prompts. For example, to create a native app written in Java:

1$ forcedroid create --apptype="native" --appname="package-test" --packagename="com.acme.mobile_apps" 
2    --organization="Acme Widgets, Inc." --outputdir="PackageTest"

Or, to create a native app written in Kotlin:

1$ forcedroid create --apptype="native_kotlin" --appname="package-test" --packagename="com.acme.mobile_apps" 
2    --organization="Acme Widgets, Inc." --outputdir="PackageTest"

Each of these calls creates a native app named “package-test” and places it in the PackageTest/ subdirectory of your current directory.

Creating an App from a Template

The forcedroid createWithTemplate command is identical to forcedroid create except that it asks for a GitHub repo URI instead of an app type. You set this URI to point to any repo directory that contains a Mobile SDK app that can be used as a template. Your template app can be any supported Mobile SDK app type. The script changes the template’s identifiers and configuration to match the values you provide for the other parameters.

Before you use createWithTemplate, it's helpful to know which templates are available. To find out, type forcedroid listtemplates. This command prints a list of templates provided by Mobile SDK. Each listing includes a brief description of the template and its GitHub URI. For example:

1Available templates:
2
31) Basic Kotlin application 
4forcedroid createwithtemplate --templaterepouri=AndroidNativeKotlinTemplate
52) Basic Java application
6forcedroid createwithtemplate --templaterepouri=AndroidNativeTemplate
73) Sample Kotlin Identity Provider application
8forcedroid createwithtemplate --templaterepouri=AndroidIDPTemplate

Once you've found a template's URI, you can plug it into the forcedroid command line. Here’s command-line usage information for forcedroid createWithTemplate:

1Usage:
2forcedroid createWithTemplate 
3    --templaterepouri=<Template repo URI> (e.g. https://github.com/forcedotcom/SalesforceMobileSDK-Templates/MobileSyncExplorerReactNative)] 
4    --appname=<Application Name> 
5    --packagename=<App Package Identifier> (e.g. com.mycompany.myapp) 
6    --organization=<Organization Name> (Your company's/organization's name) 
7    --outputdir=<Output directory> (Leave empty for current directory)]

For any template in the SalesforceMobileSDK-Templates repo, you can drop the path for templaterepouri—just the template name will do. For example:

1forcedroid createwithtemplate --templaterepouri=AndroidNativeKotlinTemplate

You can use forcedroid createWithTemplate interactively or in script mode. For example, here’s a script mode call:

1forcedroid createWithTemplate 
2--templaterepouri=SalesforceMobileSDK-Templates/AndroidIDPTemplate#v6.2.0 
3--appname=MyIDP-Android 
4-—packagename=com.mycompany.react 
5--organization="Acme Software, Inc." 
6-—outputdir=testWithTemplate

This call creates an Android identity provider app with the same source code and resources as the Android IdP sample app. Forcedroid places the new app in the testWithTemplate/ subdirectory of your current directory. It also changes the app name to “MyIDP-Android” throughout the project.

Checking the Forcedroid Version

To find out which version of forcedroid you’ve installed, run the following command:

1forcedroid version

Import and Build Your App in Android Studio

Open the project in Android Studio.
- From the Welcome screen, click Import Project (Eclipse ADT, Gradle, etc.).
  
  OR
- From the File menu, click File | New | Import Project....
Browse to your project directory and click OK.

Android Studio automatically builds your workspace. This process can take several minutes. When the status bar reports “Gradle build successful”, you’re ready to run the project.
Click Run <project_name>, or press SHIFT+F10. For native projects, the project name is the app name that you specified.
Android Studio launches your app in the emulator or on your connected Android device.

Building and Running Your App from the Command Line

After the command-line returns to the command prompt, the forcedroid script prints instructions for running Android utilities to configure and clean your project. Follow these instructions if you want to build and run your app from the command line.

Build the new application.
- Windows:
  1cd <your_project_directory> 2gradlew assembleDebug
- Mac:
  1cd <your_project_directory> 2./gradlew assembleDebug
When the build completes successfully, you can find your signed APK debug file in the project’s build/outputs/apk directory.
If you’re using an emulator that isn’t running, use the Android AVD Manager to start it. If you’re using a physical device, connect it.

Install the APK file on the emulator or device.

Windows:

1adb install <path_to_your_app>\build\outputs\apk\<app_name>.apk

Mac:

1./adb install <path_to_your_app>/build/outputs/apk/<app_name>.apk

If you can’t find your newly installed app, try restarting your emulator or device. For more information, search “Build your app from the command line” at developer.android.com.

How the Forcedroid Script Generates New Apps

The script downloads templates at runtime from a GitHub repo.
The forcedroid create command uses the default Kotlin template in the SalesforceMobileSDK-Templates GitHub repo.
Generated apps use Gradle.
The script uses npm at runtime to download Mobile SDK libraries. The settings.gradle file points to these libraries under node_modules.

Mobile SDK Development Guide