Building the APK¶
Build yourself instead of download¶
AndroidAPS is not available as download due to regulation for medial devices. It is legal to build the app for your own use but you must not give a copy to others! See FAQ page for details.
## Important notes¶
- Please use Android Studio Version 3.5.1 or newer to build the apk.
- Windows 10 32-bit systems are not supported by Android Studio 3.5.1.
Configuration on demand is not supported by the current version of the Android Gradle plugin!
If your build fails with an error regarding “on demand configuration” you can do the following:
- Open the Preferences window by clicking File > Settings (on Mac, Android Studio > Preferences).
- In the left pane, click Build, Execution, Deployment > Compiler.
- Uncheck the Configure on demand checkbox.
- Click Apply or OK.
This article is divided into two parts.¶
- In the overview part there is an explanation on what steps are necessary to build the APK file.
- In the step by step walkthrough part you will find the screenshots of a concrete installation. Because the versions of Android Studio - the software development environment which we will use to build the APK - will change very quickly this will be not identical to your installation but it should give you a good starting point. Android Studio also runs on Windows, Mac OS X and Linux and there might be small differences in some aspects between each platform. If you find that something important is wrong or missing, please inform the facebook group “AndroidAPS users” or in the Gitter chats Android APS or AndroidAPSwiki so that we can have a look at this.
Overview¶
In general, the steps necessary to build the APK file:
- Install git
- Install and setup Android Studio.
- Use git to clone the source code from the central Github repository where the developers have put the actual code for the app.
- Open the cloned project in Android Studio as active project.
- Build the signed APK.
- Transfer the signed APK to your smartphone.
Step by step walkthrough¶
Detailed description of the steps necessary to build the APK file.
Install git (if you don’t have it)¶
Follow the manual on the git installation page.
Install Android Studio¶
The following screenshots have been taken from Android Studio Version 3.1.3. Your screen might look a bit different depending on the Android Studio version you use. But you should be able to find your way through. Help from the community is provided for example in the AndroidAPS Facebook group and other places.
Install Android Studio and setup during first start.
Select “Do not import settings” as you have not used it before.
Click “Next”.
Select “Standard” installation and click “Next”.
Select the theme for the user interface you like. (In this manual we used “Intellij”. Then click “Next”. This is just the color scheme. You can select any you like (i.e. “Darcula” for dark mode). This selection has no influence on building the APK.
Click “Next” on the “Verify Settings” dialog.
The Android emulator (to emulate the smartphone on your PC or Mac) is not used to build the APK. You can click “Finish” to finish the installation and read the documentation later on demand.
Android Studio is downloading a lot of software components it uses. You can click on the “Show Details” button to the what happens but that’s not important at all.
After the downloads are completed click the “Finish” button.
- Applause, applause you have now finished the Android Studio installation and can start cloning the source code. Maybe it’s time for a short break?
Set git path in preferences¶
Windows¶
Let Studio know where is git.exe located: File - Settings
In the next window: Version Control - Git
Choose correct path: .../Git/bin
Make sure update method “Merge” is selected.
Mac¶
- If you install git via homebrew there is no need to change any preferences. Just in case: They can be found here: Android Studio - Preferences.
Download code and additional components¶
- Use git clone in Android Studio as shown in screenshots below. Select “Check out project from Version Control” with “Git” as concrete version control system.
Fill in the URL to the main AndroidAPS repository (“https://github.com/MilosKozak/AndroidAPS”) and click “clone”.
Android Studio will start cloning. Don’t click “Background” as it goes fast and makes things more complicated at the moment.
Finish the checkout from version control with opening the project by clicking “Yes”.
Use the standard “default gradle wrapper” and click “OK”.
Read and close the “Tip of Day” screen of Android Studio by pressing “Close”.
- Excellent, you have your own copy of the source code and are ready to start the build.
- Now we are approaching our first error message. Fortunately, Android Studio will directly give us the solution for this.
Click “Install missing platform(s) and sync project” as Android Studio needs to install a missing platform.
Accept the license agreement by selecting “Accept” and clicking “Next”.
As it is said in the dialog please wait until the download is finished.
Now it’s finished. Please click “Finish”.
Aaaahhh, next error. But Android Studio suggests a similar solution. Click “Install Build Tools and sync project” as Android Studio needs to download missing Tools.
As it is said in the dialog please wait until the download is finished.
Now it’s finished. Please click “Finish”.
And another error to handle as Android Studio needs to download again a missing platform. Click “Install missing platform(s) and sync project”.
As it is said in the dialog please wait until the download is finished.
Now it’s finished. Please click “Finish”.
Click “Install Build Tools and sync project” as Android Studio needs to download missing Tools.
As it is said in the dialog please wait until the download is finished.
Now it’s finished. Please click “Finish”.
Yeah, the error messages are gone and the first gradle build is runing. Maybe it’s time to drink some water?
Android Studio recommends to update the gradle system. Never update gradle! This might lead to difficulties!
Please click “Don’t remind me again for this project”.
The build is running again.
Yeah, the first build is successful but we are not finished.
Generate signed APK¶
In the menu select “Build” and then “Generate Signed Bundle / APK...”. (The menu in Android Studio changed as of September 2018. In older versions select in the menu “Build” and then “Generate Signed APK...”.)
Signing means that you sign your generated app but in a digital way as a kind of digital fingerprint in the app itself. That is necessary because Android has a rule that it only accepts signed code to run for security reasons. For more information on this topic, follow the link here Security is a deep and complex topic and you don’t need this now.
In the following dialogue box select “APK” instead of “Android App Bundle” and click button “Next”.
Select “app” and click “Next”.
Click “Create new...” to start creating your keystore. A keystore in this case is nothing more than a file in which the information for signing is stored. It is encrypted and the information is secured with passwords. We suggest storing it in your home folder and remember the passwords but if you lose this information it’s not a big issue because then you just have to create a new one. Best practice is to store this information carefully.
- Fill in the information for the next dialog.
- Key store path: is the path to the keystore file. Do not save in same folder as projekt. You must use a different directory!
- The password fields below are for the keystore to double check for typing errors.
- Alias is a name for the key you need. You can leave the default or give it a fancy name you want.
- The password fields below the key are for the key itself. As always to double check for typing errors.
- You can let the validity at the default of 25 years.
- You only have to fill out first name and last name but feel free to complete the rest of information. Then click “OK”.
Fill in the information of the last dialog in this dialog and click “Next”.
Select “full” (or “fullRelease”) as flavour for the generated app. Select V1 “Jar Signature” (V2 is optional) and click “Finish”. The following information might be important for later use.
- ‘Release’ should be your default choice for “Build Type”, ‘Debug’ is just for people coding.
- Select the build type you want to build.
- full / fullRelease (i.e. recommendations automatically enacted in closed looping)
- openloop (i.e. recommendations given to user to manually enact)
- pumpcontrol (i.e. remote control for pump, no looping)
- nsclient (i.e. looping data of another user is displayed and careportal entries can be added)
In the event log you see that the Signed APK was generated successfully.
Click the “locate” link in the event log.
Transfer APK to smartphone¶
A file manager window opens. It might look a bit different on your system as I am using Linux. On Windows there will be the File Explorer and on Mac OS X the Finder. There you should see the directory with the generated APK file. Unfortunately this is the wrong place as “wear-release.apk” is not the signed “app” APK we are searching for.
Please change to the directory AndroidAPS/app/full/release to find the “app-full-release.apk” file. Transfer this file to your Android smartphone. You can do it on your preferred way, i.e.
- Bluetooth
- cloud upload (Google Drive or other cloud services)
- connect computer and phone by cable
- by mail (Note that some mail apps do not allow apk attachments, in this case use other transfer method.)
In this example Gmail is used as it is fairly simple. To install the self-signed app you need to allow Android on your smartphone to do this installation even if this file is received via Gmail which is normally forbidden. If you use something other please proceed accordingly.
In the settings of your smartphone there is an area “unknown apps install” where I have to give Gmail the right to install APK files which I get via Gmail.
Select “Allow from this source”. After the installation, you can disable it again.
The last step is to press on the APK file I got via Gmail and install the app. If the APK does not install and you have an older version of AndroidAPS on your phone that was signed with a different key then you will need to uninstall this first, remember to export your settings if so!
Yeah, you got it and can now start with configuring AndroidAPS for your use (CGMS, insulin pump) etc.
Identify receiver if using xDrip+¶
Rozwiązywanie problemów¶
See separate page troubleshooting Android Studio.