ATAK Development Environment
Setup
1
Prerequisites
The following tools should be installed before proceeding with the setup in this document:
Adoptium Java JDK 11 DO NOT USE ORACLE
Git 2.34.1 or later
Git Large File Storage (LFS) 3.0.2 or later
Git Client (optional)
Android Studio Dolphin or later
2
Testing an Existing Project
Let’s start with an existing plugin to demonstrate the mechanics of how to use Android Studio to
checkout, build, and deploy a plugin. This information will be repeated later for the plugin that
we will begin to modify. First familiarize yourself with the checkout process.
The URL you will use when cloning is here
3
Testing an Existing Project (Hello World)
Please note that if you have an issue with cloning you may need to take an extra step to enable
the credential helper in Android Studio stack overflow help Effectively you need to enable the
Credential Helper Settings > Version Control > Git In the bottom, enable Use credential helper if
disabled.
When the project opens up, it will not be able to build initially. The next step is critical. We need to
add information into the local.properties file at the root of the plugin project and add the
following lines. Each of the <> entries needs to be replaced. Once completed, select File → Sync
Project with Gradle Files.
sdk.dir=<directory-path-to-the-sdk>
takrepo.url=https://artifacts.tak.gov/artifactory/maven
takrepo.user=<username>
takrepo.password=<password>
takdev.plugin=.
4
Additional File [temporary]
Download the appropriate Javadoc for the version being developed against. In this example
we are pulling down the javadoc from here. The jar file needs to be placed in the root of the
plugin directory. This is the case for each plugin you have.
If you need a specific version other than the latest, you can download it from the atak-civ
SDK repo.
5
Ways to run Android Applications
There are two ways to run Android applications.
Each one has advantages and disadvantages.
You only need to set up one.
Physical device
Emulator
6
Configure a Physical Device
Make sure phone has Android API 21 or later.
Connect your device to the laptop, using a USB cable.
Enable USB debugging
Open Settings app
Scroll to bottom and select About phone
Scroll to bottom and tap Build number seven times
Return to previous screen and click Developer options
Enable USB debugging
7
Configure an Emulator
Select Tools → AVD Manager or on newer Android Studio releases Tools → Device Manager
followed by Create Device
8
New Virtual Device
Click Create Virtual Device…
9
Configure an Emulator
Select Pixel 5 then click Next
10
Configure an Emulator
Select the x86 Images tab
Click Download next to API 30 (R - ABI x86_64)
Accept the license agreement and click Next
A er the download completes, click Finish
ATAK will run on anything above API 21 but it is recommended to run a newer version of Android.
11
Configure an Emulator
Once downloaded, select the API 30 image and click Next
Name your emulator.
Click on Show Advanced Settings and scroll down to adjust the VM Heap and Storage if they
are less than the values below.
VM heap: 512 MB
Internal Storage: 2048 MB
Click Finish
You may get a warning about installing HAXM if running on Windows or Mac. At the time of
these instructions, installing HAXM from Android Studio does not work. Install the latest
release from the HAXM Github
12
Configure an Emulator
To open the emulator, click the play button
A phone should appear and boot up to the Android home screen
13
Verify the system is set up properly (VM and Physical
Devices) 1/2
In the main development window, go under Build → Select Build Variant and select
civDebug
Under the app pull down, select Edit Configuration and make sure Launch Options
indicates Nothing as well as under Installation Options indicates Always Install with
Package Manager. Both of these options are important
14
Verify the system is set up properly (VM and Physical
Devices) 2/2
Close the window and apply changes.
Press the play button.
Now go under the root of the plugin folder and go to /app/build/outputs/atak-apks/sdk/
using your favorite file browser. The single apk in this directory is the ATAK application that
needs to be installed.
You can drag and drop this file over to the running VM to install it or if you are on a
physical device you can use either ADB or drag and drop it onto the device and double
click on it using the device file browser.
15
Install the Javadocs
On the Project panel, select Project view from the drop-down at the top
Under External Libraries, right-click on Gradle:com.atakmap.app.civ.common:api:X.X.X.X
and select library property
Select the + button and navigate to the plugin directory and select atak-javadoc.jar
Note: If you do not see any JavaDocs when hovering over existing methods, you might need
to turn on Quick Documentation:
Navigate to File→Settings and select Editor → Code editing
Check Show quick documentation on mouse move
16
Running ATAK
Click on the ATAK icon in either the VM or on the physical device. (Note: If it crashes
immediately - continue on to the next screen)
Accept all permissions. View and Agree to the EULA.
Once running hit play on your plugin development screen which will compile and load your
plugin. ATAK will prompt you to load the plugin.
Each time you hit the play button in your plugin IDE environment while ATAK is running, it
will prompt you to load the new plugin. This will unload the previous version and load the
new version. Resource management is critical. So anything you register should be
unregistered during unloading; oncreate, onstart, onpause, onresume, onstop,
and ondestroy should be considered.
17
ATAK (Running)
18
Install ATAK - Troubleshooting Tips
Problem Potential Solution(s)
Out of space error. Check your emulator advanced settings to see if your
heap is set to 512 MB, and internal storage to 2048 MB.
ATAK keeps crashing. This is possibly due to the fact that ATAK makes use of a
significant amount of OpenGL capability that your
system might not support in emulation.
Click on the three dots at the bottom of the
emulator options.
Navigate to Advanced…
Try out a few shader options from the dropdowns,
and restart the emulator.
If none of those work you may need to upgrade
graphics drivers or run with a real hardware
device.
19
Install ATAK - Troubleshooting Tips
If the apk fails to install, execute the following command in the current directory to install
the apk, substituting the actual name of the ATAK apk for <atakApk>:
Windows
C:\Users\%USERNAME%\AppData\Local\Android\Sdk\platform-tools\adb.exe install <atakApk>
Mac
/Users/${USER}/Library/Android/sdk/platform-tools/adb install <atakApk>
20
Install ATAK - Troubleshooting Tips
If ATAK crashes repeatedly, execute the following commands, which will create a file on the
emulator to instruct ATAK not to use OpenGL
Windows
cd C:\Users\%USERNAME%\AppData\Local\Android\Sdk\platform-tools
adb.exe shell
cd sdcard/atak/
touch opengl.broken
exit
Mac
cd /Users/${USER}/Library/Android/sdk/platform-tools
adb shell
cd sdcard/atak/
touch opengl.broken
exit
21
Install ATAK - Troubleshooting Tips
If ATAK still crashes, has garbled display text, or just displays a black screen, follow these
instructions to adjust the renderer settings.
Click the icon on the emulator controls
Select Settings in the dialog
Select the Advanced tab
Change OpenGL ES renderer to ANGLE
(D3D11) or Swi Shader
Change OpenGL ES API level to Renderer
maximum
Restart your emulator (using the X
button in the emulator controls)
22
Create a New Project
We always start a new project from the plugin template.
Pull down the PluginTemplate as a zip from here
Unzip the file and rename the PluginTemplate directory to the name of your plugin.
In the root of the directory, rename the file template.local.properties to local.properties
and modify the file appropriately
23
Create a New Project
Open Android Studio
Select open project
Navigate to location that the Plugin Template was unzipped
Open the root of the project
Setup the local.properties just as before.
Begin development!
24
